BB.Message behaviour (bb v0.31.2)

Message envelope and behaviour for payload types.

Messages in BB are wrapped in a standard envelope containing timing, coordinate frame, and payload data.

The :robot field identifies the publishing robot module and is filled in automatically by BB.PubSub.publish/3 just before dispatch. It is nil on freshly-constructed messages that have not yet been published, and lets subscribers that listen to more than one robot attribute each delivered message to its source.

The :arm_epoch field carries the robot's arm epoch as it stood when the message was sent, and is nil on everything else. BB.Actuator's send functions stamp it — deliberately at send time rather than in new/3, so a command built while disarmed and sent after arming carries the epoch it was actually sent under. BB.Actuator.Server refuses a command whose epoch is missing or belongs to an earlier arming session, which is what stops a command outliving the arming session that authorised it. See BB.Safety.epoch/1.

Usage

Use the use BB.Message macro to define a payload type:

defmodule MyPayload do
  defstruct [:value]

  use BB.Message,
    schema: [
      value: [type: :float, required: true]
    ]
end

{:ok, msg} = MyPayload.new(:base_link, value: 1.5)

The macro will:

Validate struct fields match schema keys at compile time
Implement the schema/0 callback
Generate a new/2 helper function

Note: defstruct must be defined before use BB.Message.

Summary

Types

t()

Callbacks

schema()

Returns a compiled Spark.Options schema for this payload type

Functions

new(payload_module, frame_id, attrs)

Create a new message with validated payload.

new!(payload_module, frame_id, attrs)

Like new/3 but raises on validation error.

schema(message)

Get the payload schema from a message.

Types

t()

@type t() :: %BB.Message{
  arm_epoch: BB.Safety.Controller.epoch() | nil,
  frame_id: atom(),
  monotonic_time: integer(),
  node: node(),
  payload: struct(),
  robot: module() | nil,
  wall_time: integer()
}

Callbacks

schema()

@callback schema() :: Spark.Options.t()

Returns a compiled Spark.Options schema for this payload type

Functions

new(payload_module, frame_id, attrs)

@spec new(module(), atom(), keyword()) :: {:ok, t()} | {:error, term()}

Create a new message with validated payload.

Validates the attributes against the payload module's schema, then wraps the resulting struct in a message envelope. The envelope is stamped with the current monotonic time, wall-clock time, and the local node name, so messages remain interpretable across nodes and after recording.

Examples

alias BB.Message.Geometry.Pose
alias BB.Math.Transform

{:ok, msg} = BB.Message.new(Pose, :end_effector, [
  transform: Transform.identity()
])

new!(payload_module, frame_id, attrs)

@spec new!(module(), atom(), keyword()) :: t()

Like new/3 but raises on validation error.

Examples

msg = BB.Message.new!(Pose, :end_effector, [
  transform: Transform.identity()
])

schema(message)

@spec schema(t()) :: Spark.Options.t()

Get the payload schema from a message.

Examples

BB.Message.schema(msg)  #=> %Spark.Options{...}