Behaviour and API for sensors in the BB framework.

This module serves two purposes:

1. Behaviour - Defines callbacks for sensor implementations
2. API - Provides functions for working with sensors

Behaviour

Sensors read from hardware or other sources and publish messages. They can be attached at the robot level, to links, or to joints.

Usage

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

Required Callbacks

• init/1 - Initialise sensor state from resolved options

Optional Callbacks

• disarm/1 - Make hardware safe (only for sensors 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 sensor accepts configuration options, pass them via :options_schema:

defmodule MyTemperatureSensor do
  use BB.Sensor,
    options_schema: [
      bus: [type: :string, required: true, doc: "I2C bus name"],
      address: [type: :integer, required: true, doc: "I2C device address"],
      poll_interval_ms: [type: :pos_integer, default: 1000, doc: "Poll interval"]
    ]

  @impl BB.Sensor
  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 sensors that don't need configuration, omit :options_schema:

defmodule SimpleSensor do
  use BB.Sensor

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

Parameter References

Options can reference parameters for runtime-adjustable configuration:

sensor :temp, {MyTempSensor, poll_interval: param([:sensors, :poll_rate])}

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

Most sensors don't require safety callbacks since they only read data. If your sensor controls hardware that needs to be disabled on disarm (e.g., a spinning LIDAR), implement the optional disarm/1 callback:

defmodule MyHardwareSensor do
  use BB.Sensor

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

  @impl BB.Sensor
  def disarm(opts), do: stop_hardware(opts)
end

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