@spec cancel(module()) :: :ok | {:error, :no_execution}

Cancel the currently executing command.

Stops the command server with :cancelled reason. Awaiting callers will receive the result from the command's result/1 callback.

@spec category_availability(module()) :: %{
  required(atom()) => {non_neg_integer(), pos_integer()}
}

Get the availability of each command category.

Returns a map of category names to {current_count, limit} tuples.

@spec check_allowed(module(), [robot_state()]) ::
  :ok | {:error, BB.Error.State.NotAllowed.t()}

Check if the robot is in one of the allowed states.

Reads directly from ETS for fast concurrent access.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec execute(module(), atom(), map()) :: {:ok, pid()} | {:error, term()}

Execute a command with the given goal.

Returns {:ok, pid} where pid is the command server process. Use BB.Command.await/2 or BB.Command.yield/2 to get the result.

Examples

{:ok, cmd} = Runtime.execute(MyRobot, :navigate, %{target: pose})
{:ok, result} = BB.Command.await(cmd)

# Or with timeout
case BB.Command.yield(cmd, 5000) do
  nil -> still_running()
  {:ok, result} -> handle_result(result)
  {:error, reason} -> handle_error(reason)
end

Errors

• {:error, %StateError{}} - Robot not in allowed state
• {:error, {:unknown_command, name}} - Command not found
• Other errors are returned through BB.Command.await/2

@spec executing?(module()) :: boolean()

Check if any command is currently executing.

Reads directly from ETS for fast concurrent access.

@spec executing?(module(), atom()) :: boolean()

Check if a specific category has commands executing.

@spec executing_commands(module()) :: [map()]

Get information about all currently executing commands.

@spec get_robot(module()) :: BB.Robot.t()

Get the static robot struct (topology).

@spec get_robot_state(module()) :: BB.Robot.State.t()

Get the robot state (ETS-backed joint positions/velocities).

@spec operational_state(module()) :: atom()

Get the actual operational state, without backwards compatibility translation.

Unlike state/1, this returns the actual operational state regardless of whether commands are executing. Use this when you need to know the true operational context (e.g., :idle, :recording, :reacting).

Reads directly from ETS for fast concurrent access.

@spec positions(module()) :: %{required(atom()) => float()}

Get all joint positions as a map.

Reads directly from ETS for fast concurrent access. Returns a map of joint names to their current positions (in radians for revolute joints, metres for prismatic joints).

Positions are updated automatically by the Runtime when sensors publish JointState messages.

Examples

iex> BB.Robot.Runtime.positions(MyRobot)
%{pan_joint: 0.0, tilt_joint: 0.0}

@spec simulation_mode(module()) :: simulation_mode()

Get the simulation mode for a robot.

Returns nil if running in hardware mode, or the simulation mode atom (e.g., :kinematic, :external) if running in simulation.

Starts the runtime for a robot module.

@spec state(module()) :: robot_state()

Get the current robot state machine state.

Returns :disarmed if the robot is not armed (via BB.Safety), otherwise returns the internal operational state.

For backwards compatibility:

• When operational_state is :idle but commands are executing, returns :executing
• Custom operational states (e.g., :recording) are returned directly

Reads directly from ETS for fast concurrent access.

@spec transition(module(), robot_state()) :: {:ok, robot_state()} | {:error, term()}

Transition the robot to a new state.

@spec transition_operational_state(module(), reference(), atom()) ::
  :ok | {:error, term()}

Transition the operational state during command execution.

This is called by BB.Command.transition_state/2 to change the robot's operational state mid-execution. Only the command with the matching execution_id can trigger a transition.

@spec velocities(module()) :: %{required(atom()) => float()}

Get all joint velocities as a map.

Reads directly from ETS for fast concurrent access. Returns a map of joint names to their current velocities (in rad/s for revolute joints, m/s for prismatic joints).

Velocities are updated automatically by the Runtime when sensors publish JointState messages.

Examples

iex> BB.Robot.Runtime.velocities(MyRobot)
%{pan_joint: 0.0, tilt_joint: 0.0}

Returns the via tuple for process registration.