BB.Robot.State (bb v0.4.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.