Behaviour for controllers in the BB framework.

Controllers manage hardware communication (I2C buses, serial ports, etc.) and are typically shared by multiple actuators. They run at the robot level and are supervised by BB.ControllerSupervisor.

Usage

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

Required Callbacks

• init/1 - Initialise controller state from resolved options

Optional Callbacks

• disarm/1 - Make hardware safe (only for controllers with active hardware)
• 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 controller accepts configuration options, pass them via :options_schema:

defmodule MyI2CController do
  use BB.Controller,
    options_schema: [
      bus: [type: :string, required: true, doc: "I2C bus name"],
      address: [type: :integer, required: true, doc: "I2C device address"]
    ]

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

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

defmodule SimpleController do
  use BB.Controller

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

Parameter References

Options can reference parameters for runtime-adjustable configuration:

controller :i2c, {MyI2CController, bus: param([:hardware, :i2c_bus])}

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

If your controller manages hardware that needs to be made safe when disarmed, implement the optional disarm/1 callback:

defmodule MyController do
  use BB.Controller, options_schema: [bus: [type: :string, required: true]]

  @impl BB.Controller
  def init(opts), do: {:ok, %{}}

  @impl BB.Controller
  def disarm(opts), do: disable_hardware(opts[:bus])
end

When disarm/1 is implemented, the framework automatically registers your controller with BB.Safety.