# `BB.Actuator`
[🔗](https://github.com/beam-bots/bb/blob/main/lib/bb/actuator.ex#L5)

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)

# `disarm`

```elixir
@callback disarm(opts :: keyword()) :: :ok | {:error, term()}
```

Make the hardware safe.

Called with the opts provided at registration. Must work without GenServer state.
This callback is required for actuators since they control physical hardware.

# `handle_call`
*optional* 

```elixir
@callback handle_call(request :: term(), from :: GenServer.from(), state :: term()) ::
  {:reply, reply :: term(), new_state :: term()}
  | {:reply, reply :: term(), new_state :: term(),
     timeout() | :hibernate | {:continue, term()}}
  | {:noreply, new_state :: term()}
  | {:noreply, new_state :: term(),
     timeout() | :hibernate | {:continue, term()}}
  | {:stop, reason :: term(), new_state :: term()}
  | {:stop, reason :: term(), reply :: term(), new_state :: term()}
```

Handle synchronous calls.

Same semantics as `c:GenServer.handle_call/3`.

# `handle_cast`
*optional* 

```elixir
@callback handle_cast(request :: term(), state :: term()) ::
  {:noreply, new_state :: term()}
  | {:noreply, new_state :: term(),
     timeout() | :hibernate | {:continue, term()}}
  | {:stop, reason :: term(), new_state :: term()}
```

Handle asynchronous casts.

Same semantics as `c:GenServer.handle_cast/2`.

# `handle_continue`
*optional* 

```elixir
@callback handle_continue(continue_arg :: term(), state :: term()) ::
  {:noreply, new_state :: term()}
  | {:noreply, new_state :: term(),
     timeout() | :hibernate | {:continue, term()}}
  | {:stop, reason :: term(), new_state :: term()}
```

Handle continue instructions.

Same semantics as `c:GenServer.handle_continue/2`.

# `handle_info`
*optional* 

```elixir
@callback handle_info(msg :: term(), state :: term()) ::
  {:noreply, new_state :: term()}
  | {:noreply, new_state :: term(),
     timeout() | :hibernate | {:continue, term()}}
  | {:stop, reason :: term(), new_state :: term()}
```

Handle all other messages.

Same semantics as `c:GenServer.handle_info/2`.

# `handle_options`
*optional* 

```elixir
@callback handle_options(new_opts :: keyword(), state :: term()) ::
  {:ok, new_state :: term()} | {:stop, reason :: term()}
```

Handle parameter changes at runtime.

Called when a referenced parameter changes. The `new_opts` contain all options
with the updated parameter value(s) resolved.

Return `{:ok, new_state}` to update state, or `{:stop, reason}` to shut down.

# `init`

```elixir
@callback init(opts :: keyword()) ::
  {:ok, state :: term()}
  | {:ok, state :: term(), timeout() | :hibernate | {:continue, term()}}
  | {:stop, reason :: term()}
  | :ignore
```

Initialise actuator state from resolved options.

Called with options after parameter references have been resolved.
The `:bb` key contains `%{robot: module, path: [atom]}`.

Return `{:ok, state}` or `{:ok, state, timeout_or_continue}` on success,
`{:stop, reason}` to abort startup, or `:ignore` to skip this actuator.

# `options_schema`
*optional* 

```elixir
@callback options_schema() :: Spark.Options.t()
```

Returns the options schema for this actuator.

The schema should NOT include the `:bb` option - it is auto-injected.
If this callback is not implemented, the module cannot accept options
in the DSL (must be used as a bare module).

# `terminate`
*optional* 

```elixir
@callback terminate(reason :: term(), state :: term()) :: term()
```

Clean up before termination.

Same semantics as `c:GenServer.terminate/2`.

# `follow_trajectory`

```elixir
@spec follow_trajectory(module(), [atom()], [keyword() | map()], keyword()) :: :ok
```

Send a trajectory command via pubsub.

## Waypoint Structure

Each waypoint should be a keyword list or map with:
- `position` - Position (radians or metres)
- `velocity` - Velocity (rad/s or m/s)
- `acceleration` - Acceleration (rad/s² or m/s²)
- `time_from_start` - Time from trajectory start (milliseconds)

## Options

- `:repeat` - Number of repetitions: positive integer or `:forever` (default 1)
- `:command_id` - Correlation ID for feedback tracking

# `follow_trajectory!`

```elixir
@spec follow_trajectory!(module(), atom(), [keyword() | map()], keyword()) :: :ok
```

Send a trajectory command directly to an actuator (bypasses pubsub).

# `follow_trajectory_sync`

```elixir
@spec follow_trajectory_sync(
  module(),
  atom(),
  [keyword() | map()],
  keyword(),
  timeout()
) ::
  {:ok, :accepted | {:accepted, map()}} | {:error, term()}
```

Send a trajectory command and wait for acknowledgement.

# `hold`

```elixir
@spec hold(module(), [atom()], keyword()) :: :ok
```

Send a hold command via pubsub.

Instructs the actuator to actively maintain its current position.

## Options

- `:command_id` - Correlation ID for feedback tracking

# `hold!`

```elixir
@spec hold!(module(), atom(), keyword()) :: :ok
```

Send a hold command directly to an actuator (bypasses pubsub).

# `hold_sync`

```elixir
@spec hold_sync(module(), atom(), keyword(), timeout()) ::
  {:ok, :accepted | {:accepted, map()}} | {:error, term()}
```

Send a hold command and wait for acknowledgement.

# `publish_begin_motion`

```elixir
@spec publish_begin_motion(module(), [atom()], keyword()) :: :ok
```

Publish a `BeginMotion` message for the actuator at `path`, converting
the supplied motor-space values into joint-space before publishing.

The driver builds the message in motor-space (the only coordinate space
it knows about); this helper looks up the joint above the actuator,
resolves its transmission against the current parameter store, applies
`BB.Transmission.unapply_to_payload/2`, and publishes the joint-space
message to `[:actuator | path]`.

`path` is the actuator's full path (i.e. the `:bb.path` injected into
driver opts). `opts` is the keyword list accepted by
`BB.Message.Actuator.BeginMotion`'s schema, with `:initial_position`,
`:target_position`, `:peak_velocity`, and `:acceleration` in
motor-space.

# `set_effort`

```elixir
@spec set_effort(module(), [atom()], number(), keyword()) :: :ok
```

Send an effort (torque/force) command via pubsub.

## Options

- `:duration` - Duration (milliseconds), nil = until stopped
- `:command_id` - Correlation ID for feedback tracking

# `set_effort!`

```elixir
@spec set_effort!(module(), atom(), number(), keyword()) :: :ok
```

Send an effort command directly to an actuator (bypasses pubsub).

# `set_effort_sync`

```elixir
@spec set_effort_sync(module(), atom(), number(), keyword(), timeout()) ::
  {:ok, :accepted | {:accepted, map()}} | {:error, term()}
```

Send an effort command and wait for acknowledgement.

# `set_position`

```elixir
@spec set_position(module(), [atom()], number(), keyword()) :: :ok
```

Send a position command via pubsub.

The command is published to `[:actuator | path]` where subscribers can
receive it via `handle_info({:bb, path, message}, state)`.

## Options

- `:velocity` - Velocity hint (rad/s or m/s)
- `:duration` - Duration hint (milliseconds)
- `:command_id` - Correlation ID for feedback tracking

## Examples

    BB.Actuator.set_position(MyRobot, [:base_link, :shoulder, :servo], 1.57)
    BB.Actuator.set_position(MyRobot, [:shoulder, :servo], 1.57, velocity: 0.5)

# `set_position!`

```elixir
@spec set_position!(module(), atom(), number(), keyword()) :: :ok
```

Send a position command directly to an actuator (bypasses pubsub).

Uses `BB.Process.cast` for fire-and-forget delivery. The actuator receives
the command via `handle_cast({:command, message}, state)`.

## Options

Same as `set_position/4`.

# `set_position_sync`

```elixir
@spec set_position_sync(module(), atom(), number(), keyword(), timeout()) ::
  {:ok, :accepted | {:accepted, map()}} | {:error, term()}
```

Send a position command and wait for acknowledgement.

Uses `BB.Process.call` for synchronous delivery. Returns the actuator's
response or raises on timeout.

## Options

Same as `set_position/4`, plus:
- Fifth argument is timeout in milliseconds (default 5000)

## Returns

- `{:ok, :accepted}` - Command accepted
- `{:ok, :accepted, map()}` - Command accepted with additional info
- `{:error, reason}` - Command rejected

# `set_velocity`

```elixir
@spec set_velocity(module(), [atom()], number(), keyword()) :: :ok
```

Send a velocity command via pubsub.

## Options

- `:duration` - Duration (milliseconds), nil = until stopped
- `:command_id` - Correlation ID for feedback tracking

# `set_velocity!`

```elixir
@spec set_velocity!(module(), atom(), number(), keyword()) :: :ok
```

Send a velocity command directly to an actuator (bypasses pubsub).

# `set_velocity_sync`

```elixir
@spec set_velocity_sync(module(), atom(), number(), keyword(), timeout()) ::
  {:ok, :accepted | {:accepted, map()}} | {:error, term()}
```

Send a velocity command and wait for acknowledgement.

# `stop`

```elixir
@spec stop(module(), [atom()], keyword()) :: :ok
```

Send a stop command via pubsub.

## Options

- `:mode` - `:immediate` (default) or `:decelerate`
- `:command_id` - Correlation ID for feedback tracking

# `stop!`

```elixir
@spec stop!(module(), atom(), keyword()) :: :ok
```

Send a stop command directly to an actuator (bypasses pubsub).

# `stop_sync`

```elixir
@spec stop_sync(module(), atom(), keyword(), timeout()) ::
  {:ok, :accepted | {:accepted, map()}} | {:error, term()}
```

Send a stop command and wait for acknowledgement.

# `to_joint_space`

```elixir
@spec to_joint_space(module(), [atom()], BB.Message.t()) :: BB.Message.t()
```

Translate a motor-space outbound message into joint-space using the
transmission of the joint above the actuator at `actuator_path`.

Convenient for callers that build a message in motor-space and then
publish it on a topic of their own choosing — e.g. a controller
publishing `JointState` on a sensor topic. Performs a fresh
transmission resolution against the current parameter store on every
call, so it stays correct across runtime parameter changes without
the caller needing to subscribe.

Returns the message unchanged when the joint has no transmission.

---

*Consult [api-reference.md](api-reference.md) for complete listing*