BB.Message behaviour (bb v0.16.0)

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.

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{
  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{...}