Behaviour for state estimators in the BB framework.

Estimators consume one or more input message streams and publish derived state. The same contract covers within-sensor fusion (e.g. an AHRS algorithm combining gyro and accelerometer from a single IMU into orientation) and cross-sensor fusion (e.g. an EKF combining IMU and wheel odometry into a base pose).

Estimators are declared inline in the DSL using the estimator entity, which may nest inside either a sensor (single-input form, frame inherited) or a link (cross-sensor form, frame = link).

Usage

The use BB.Estimator macro sets up your module as an estimator callback module. Your module is NOT a GenServer - the framework provides a wrapper GenServer (BB.Estimator.Server) that delegates to your callbacks and routes returned messages to the appropriate pubsub paths.

Required Callbacks

• init/1 - Initialise estimator state from resolved options
• handle_input/2 - Consume an input message and optionally emit outputs

Optional Callbacks

• handle_options/2 - React to parameter changes at runtime
• handle_info/2, handle_call/3, handle_cast/2, handle_continue/2, terminate/2 - Standard GenServer-style callbacks
• options_schema/0 - Define accepted configuration options

Reply Shape

Unlike sensors and controllers, estimators emit messages by returning them from their callbacks rather than calling BB.publish/3 directly. Each callback that can emit messages accepts a {:reply, outputs, state} reply, where outputs is a list of {output_name, %BB.Message{}} tuples.

• output_name is either an atom matching an output :name block on the estimator, or the conventional :out atom for single-output estimators.
• Returning an empty list emits nothing - useful for accumulators that consume many inputs before producing one output.

Init Context

The framework injects an :estimator_context option carrying a BB.Estimator.Context struct alongside the existing :bb option. The context provides the target frame, the static transforms from each input's source frame to the target frame, and the estimator's full path.

defmodule MyEstimator do
  use BB.Estimator,
    options_schema: [
      gain: [type: :float, default: 0.1, doc: "Filter gain"]
    ]

  @impl BB.Estimator
  def init(opts) do
    gain = Keyword.fetch!(opts, :gain)
    context = Keyword.fetch!(opts, :estimator_context)
    {:ok, %{gain: gain, transforms: context.transforms}}
  end

  @impl BB.Estimator
  def handle_input(%BB.Message{} = msg, state) do
    out_msg = compute(msg, state)
    {:reply, [out: out_msg], state}
  end
end

Single vs Multi-Input Dispatch

For single-input estimators (sensor-nested, or link-nested with one declared input), handle_input/2 receives a single %BB.Message{}. For multi-input estimators, it receives a map of %{input_name => %BB.Message{}} keyed by the input declaration name, populated by the framework when the driver input arrives.

Auto-injected Options

The :bb and :estimator_context options are auto-injected by the framework and should NOT appear in options_schema/0. The :bb option contains %{robot: module, path: [atom]}.