Behaviour and API for actuators in the BB framework.

This module serves two purposes:

1. Behaviour - Defines callbacks for actuator implementations
2. API - Provides functions for sending commands to actuators

Behaviour

Actuators receive position/velocity/effort commands and drive hardware. They must implement the init/1 and disarm/1 callbacks.

Usage

The use BB.Actuator macro sets up your module as an actuator callback module. Your module is NOT a GenServer - the framework provides a wrapper GenServer (BB.Actuator.Server) that delegates to your callbacks.

Required Callbacks

• init/1 - Initialise actuator state from resolved options
• handle_command/2 - Act on an inbound command
• disarm/1 - Make hardware safe (called without GenServer state)

Optional Callbacks

• handle_options/2 - React to parameter changes at runtime
• handle_call/3, handle_cast/2, handle_info/2 - Standard GenServer-style callbacks, for the driver's own traffic
• handle_continue/2, terminate/2 - Lifecycle callbacks
• options_schema/0 - Define accepted configuration options

Options Schema

If your actuator accepts configuration options, pass them via :options_schema:

defmodule MyServoActuator do
  use BB.Actuator,
    options_schema: [
      channel: [type: {:in, 0..15}, required: true, doc: "PWM channel"],
      controller: [type: :atom, required: true, doc: "Controller name"]
    ]

  @impl BB.Actuator
  def init(opts) do
    channel = Keyword.fetch!(opts, :channel)
    bb = Keyword.fetch!(opts, :bb)
    {:ok, %{channel: channel, bb: bb}}
  end

  @impl BB.Actuator
  def disarm(opts) do
    MyHardware.disable(opts[:controller], opts[:channel])
    :ok
  end

  @impl BB.Actuator
  def handle_command(%BB.Message{payload: %Command.Position{} = cmd}, state) do
    MyHardware.write(state.channel, cmd.position)
    {:noreply, state}
  end
end

For actuators that don't need configuration, omit :options_schema:

defmodule SimpleActuator do
  use BB.Actuator

  @impl BB.Actuator
  def init(opts) do
    {:ok, %{bb: opts[:bb]}}
  end

  @impl BB.Actuator
  def handle_command(_message, state), do: {:noreply, state}

  @impl BB.Actuator
  def disarm(_opts), do: :ok
end

Parameter References

Options can reference parameters for runtime-adjustable configuration:

actuator :motor, {MyMotor, max_effort: param([:motion, :max_effort])}

When the parameter changes, handle_options/2 is called with the new resolved options. Override it to update your state accordingly.

Auto-injected Options

The :bb option is automatically provided and should NOT be included in your options_schema. It contains %{robot: module, path: [atom]}.

Safety Registration

Safety registration is automatic - the framework registers your module with BB.Safety using the resolved options. You don't need to call BB.Safety.register manually.

API

Supports both pubsub delivery (for orchestration, logging, replay) and direct GenServer delivery (for time-critical control paths).

Delivery Methods

• Pubsub (set_position/4, etc.) - Commands published to [:actuator | path]. Enables logging, replay, and multi-subscriber patterns.

• Direct (set_position!/4, etc.) - Commands sent directly via BB.Process.cast. Lower latency for time-critical control.

• Synchronous (set_position_sync/5, etc.) - Commands sent via BB.Process.call. Returns acknowledgement or error.

All three converge on handle_command/2. Which transport a caller chose is not something a driver has to know about, and choosing one cannot skip the checks BB.Actuator.Server applies on the way in.

Addressing

Every function accepts either the actuator's unique name or its full path through the topology. Names are resolved against the robot with BB.Robot.actuator_path/2, so the two are interchangeable:

BB.Actuator.set_position(MyRobot, :shoulder_servo, 1.57)
BB.Actuator.set_position(MyRobot, [:base_link, :shoulder, :shoulder_servo], 1.57)

Naming an actuator the robot doesn't have raises ArgumentError rather than publishing to a topic nothing is listening on.

Examples

# Pubsub delivery (for kinematics/orchestration)
BB.Actuator.set_position(MyRobot, :shoulder_servo, 1.57)

# Direct delivery (for time-critical control)
BB.Actuator.set_position!(MyRobot, :shoulder_servo, 1.57)

# Synchronous with acknowledgement
{:ok, :accepted} = BB.Actuator.set_position_sync(MyRobot, :shoulder_servo, 1.57)