Search documentation of bb

# BB.Robot.State (bb v0.8.0)

View Source

ETS-backed mutable state for robot instances.

This module manages joint positions, velocities, and computed transforms for robot instances. Each robot instance has its own ETS table for concurrent read access.

## State Structure

For each joint, the following state is stored:

- `position`: current joint position (radians for revolute, meters for prismatic)
- `velocity`: current joint velocity (rad/s or m/s)

## Usage

    # Create state for a robot instance
    {:ok, state} = BB.Robot.State.new(robot)

    # Set/get joint positions
    :ok = BB.Robot.State.set_joint_position(state, :shoulder, 0.5)
    pos = BB.Robot.State.get_joint_position(state, :shoulder)

    # Get all joint positions as a map
    positions = BB.Robot.State.get_all_positions(state)

    # Clean up when done
    :ok = BB.Robot.State.delete(state)

# Summary

## Types

t()

## Functions

delete(state)

Delete a state table and free resources.

find_schema_for_parameter(state, path)

Find the schema that applies to a given parameter path.

get_all_positions(state)

Get all joint positions as a map.

get_all_velocities(state)

Get all joint velocities as a map.

get_chain_positions(state, target_link)

Get the positions of joints along a path from root to a target link.

get_joint_position(state, joint_name)

Get the current position of a joint.

get_joint_velocity(state, joint_name)

Get the current velocity of a joint.

get_parameter(state, path)

Get a parameter value by path.

get_parameter_schema(state, path)

Get the registered schema for a path prefix.

get_robot_state(state)

Get the current robot state machine state.

list_parameters(state, prefix \\ [])

List all parameters, optionally filtered by path prefix.

new(robot)

Create a new state table for a robot.

register_parameter_schema(state, path, schema)

Register a parameter schema for a component path.

reset(state)

Reset all joints to their default positions (0.0).

set_joint_position(state, joint_name, position)

Set the position of a joint.

set_joint_velocity(state, joint_name, velocity)

Set the velocity of a joint.

set_parameter(state, path, value)

Set a parameter value by path.

set_parameters(state, params)

Set multiple parameters atomically.

set_positions(state, positions)

Set multiple joint positions at once.

set_robot_state(state, state)

Set the robot state machine state.

set_velocities(state, velocities)

Set multiple joint velocities at once.

# Types

# t()

    @type t() :: %BB.Robot.State{robot: BB.Robot.t(), table: :ets.table()}

# Functions

# delete(state)

    @spec delete(t()) :: :ok

Delete a state table and free resources.

# find_schema_for_parameter(state, path)

    @spec find_schema_for_parameter(t(), [atom()]) ::
      {:ok, [atom()], Spark.Options.t()} | {:error, :not_found}

Find the schema that applies to a given parameter path.

Searches for the longest matching schema prefix.

# get_all_positions(state)

    @spec get_all_positions(t()) :: %{required(atom()) => float()}

Get all joint positions as a map.

## Examples

    iex> positions = BB.Robot.State.get_all_positions(state)
    %{shoulder: 0.0, elbow: 0.5, wrist: -0.3}

# get_all_velocities(state)

    @spec get_all_velocities(t()) :: %{required(atom()) => float()}

Get all joint velocities as a map.

# get_chain_positions(state, target_link)

    @spec get_chain_positions(t(), atom()) :: [{atom(), float()}]

Get the positions of joints along a path from root to a target link.

Returns a list of {joint_name, position} tuples in traversal order.

# get_joint_position(state, joint_name)

    @spec get_joint_position(t(), atom()) :: float() | nil

Get the current position of a joint.

Returns `nil` if the joint doesn't exist.

# get_joint_velocity(state, joint_name)

    @spec get_joint_velocity(t(), atom()) :: float() | nil

Get the current velocity of a joint.

Returns `nil` if the joint doesn't exist.

# get_parameter(state, path)

    @spec get_parameter(t(), [atom()]) :: {:ok, term()} | {:error, :not_found}

Get a parameter value by path.

Returns `{:ok, value}` if the parameter exists, `{:error, :not_found}` otherwise.

# get_parameter_schema(state, path)

    @spec get_parameter_schema(t(), [atom()]) ::
      {:ok, Spark.Options.t()} | {:error, :not_found}

Get the registered schema for a path prefix.

Returns `{:ok, schema}` if found, `{:error, :not_found}` otherwise.

# get_robot_state(state)

    @spec get_robot_state(t()) :: atom()

Get the current robot state machine state.

Returns the state atom (e.g., `:disarmed`, `:idle`, `:executing`).

# list_parameters(state, prefix \\ [])

    @spec list_parameters(t(), [atom()]) :: [{[atom()], map()}]

List all parameters, optionally filtered by path prefix.

Returns a list of `{path, metadata}` tuples where metadata includes the current value and schema information if registered.

# new(robot)

    @spec new(BB.Robot.t()) :: {:ok, t()}

Create a new state table for a robot.

Returns `{:ok, state}` on success.

# register_parameter_schema(state, path, schema)

    @spec register_parameter_schema(t(), [atom()], Spark.Options.t()) :: :ok

Register a parameter schema for a component path.

The schema is stored and used for validation and metadata.

# reset(state)

    @spec reset(t()) :: :ok

Reset all joints to their default positions (0.0).

# set_joint_position(state, joint_name, position)

    @spec set_joint_position(t(), atom(), float()) :: :ok

Set the position of a joint.

# set_joint_velocity(state, joint_name, velocity)

    @spec set_joint_velocity(t(), atom(), float()) :: :ok

Set the velocity of a joint.

# set_parameter(state, path, value)

    @spec set_parameter(t(), [atom()], term()) :: :ok

Set a parameter value by path.

This is a low-level function that does not validate or notify. Use `BB.Parameter.set/3` for the validated, notifying version.

# set_parameters(state, params)

    @spec set_parameters(t(), [{[atom()], term()}]) :: :ok

Set multiple parameters atomically.

This is a low-level function that does not validate or notify.

# set_positions(state, positions)

    @spec set_positions(t(), %{required(atom()) => float()}) :: :ok

Set multiple joint positions at once.

## Examples

    :ok = BB.Robot.State.set_positions(state, %{
      shoulder: 0.5,
      elbow: -0.3,
      wrist: 0.0
    })

# set_robot_state(state, state)

    @spec set_robot_state(t(), atom()) :: :ok

Set the robot state machine state.

# set_velocities(state, velocities)

    @spec set_velocities(t(), %{required(atom()) => float()}) :: :ok

Set multiple joint velocities at once.