@spec default_command_payloads() :: [module()]

The command payloads an actuator accepts unless it says otherwise.

These are the payload types BB.Actuator's own API can produce, so they are the set every driver is expected to understand — or at least to ignore gracefully.

@spec follow_trajectory(module(), target(), [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

@spec follow_trajectory!(module(), target(), [keyword() | map()], keyword()) :: :ok

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

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

Send a trajectory command and wait for acknowledgement.

@spec hold(module(), target(), 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

@spec hold!(module(), target(), keyword()) :: :ok

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

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

Send a hold command and wait for acknowledgement.

@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.

@spec set_effort(module(), target(), 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

@spec set_effort!(module(), target(), number(), keyword()) :: :ok

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

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

Send an effort command and wait for acknowledgement.

@spec set_position(module(), target(), number(), keyword()) :: :ok | {:error, term()}

Send a position command.

Under the default delivery: :pubsub the command is published to [:actuator | path] for whoever is watching the topic, and delivered to the actuator itself by a call, so the caller learns whether the joint is actually moving. An actuator refuses a command it doesn't accept, or any command at all while the robot is disarmed.

The publication records that a command was issued; the return value says whether it was accepted. A refused command still appears on the topic.

Runs in the caller's process, so a driver must not call this from inside its own handle_command/2 - it would be waiting on itself.

Options

• :delivery - :pubsub (default) publishes the command and waits for the actuator to accept it; :direct casts to the actuator and returns at once, publishing nothing. Use :direct for control paths where the round trip costs more than knowing the outcome is worth
• :velocity - Velocity hint (rad/s or m/s)
• :duration - Duration hint (milliseconds)
• :command_id - Correlation ID for feedback tracking
• :timeout - How long to wait for the actuator, in milliseconds (default 5000). Unused under :direct, which waits for nothing

Returns

• :ok - Command accepted
• {:error, reason} - Command refused, reason being a BB.Error struct

Under delivery: :pubsub, exits if the actuator isn't running or doesn't answer within :timeout, like any other GenServer.call/3.

Commanding several joints

This is an ordinary blocking call, so several joints cost several round trips and how they overlap is yours to choose:

[shoulder: 1.57, elbow: 0.5]
|> Enum.map(fn {joint, position} ->
  Task.async(fn -> BB.Actuator.set_position(MyRobot, joint, position) end)
end)
|> Task.await_many()

Three things to know before reaching for that:

• Task.async/1 links. From a long-lived process - a controller loop - use Task.Supervisor.async_nolink/3 instead, or an actuator that has died takes the caller down with it.
• Task.await_many/2 applies one deadline to the whole set and kills the stragglers when it expires. It isn't "collect as they land".
• Each command publishes from inside its own task, so observers see the commands interleaved rather than in the order you listed them.

BB.Motion.send_positions/3 already does this for the joints of one motion.

Examples

:ok = BB.Actuator.set_position(MyRobot, [:base_link, :shoulder, :servo], 1.57)

case BB.Actuator.set_position(MyRobot, :servo, 1.57, velocity: 0.5) do
  :ok -> :moving
  {:error, error} -> Logger.error(Exception.message(error))
end

@spec set_velocity(module(), target(), number(), keyword()) :: :ok

Send a velocity command via pubsub.

Options

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

@spec set_velocity!(module(), target(), number(), keyword()) :: :ok

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

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

Send a velocity command and wait for acknowledgement.

@spec stop(module(), target(), keyword()) :: :ok

Send a stop command via pubsub.

Options

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

@spec stop!(module(), target(), keyword()) :: :ok

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

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

Send a stop command and wait for acknowledgement.

@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.