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
• 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
• 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_cast({:command, msg}, state) do
    # Handle actuator commands
    {: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 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. Actuators receive commands via handle_info/2.

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

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

Examples

# Pubsub delivery (for kinematics/orchestration)
BB.Actuator.set_position(MyRobot, [:base_link, :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)