Message Types Reference

All message payloads in BB PubSub. Messages are wrapped in BB.Message:

%BB.Message{
  timestamp: integer(),   # System.monotonic_time(:nanosecond)
  frame_id: atom(),       # Coordinate frame (typically joint/link name)
  payload: struct()       # One of the message types below
}

Note on timestamps: The timestamp is monotonic time in nanoseconds (System.monotonic_time(:nanosecond)), not wall-clock time. This means:

Timestamps are suitable for ordering events and measuring durations
They cannot be converted to wall-clock/UTC time
They are only meaningful within a single BEAM VM instance

Sensor Messages

JointState

State of one or more joints.

Module: BB.Message.Sensor.JointState

Fields:

Field	Type	Required	Description
`names`	`[atom]`	Yes	Joint names
`positions`	`[float]`	No	Positions in radians (revolute) or metres (prismatic)
`velocities`	`[float]`	No	Velocities in rad/s or m/s
`efforts`	`[float]`	No	Efforts in Nm or N

Published to: [:sensor, joint_name]

Example:

JointState.new!(
  names: [:shoulder, :elbow],
  positions: [0.5, 1.2],
  velocities: [0.1, 0.0]
)

BatteryState

Battery status information.

Module: BB.Message.Sensor.BatteryState

Fields:

Field	Type	Required	Description
`voltage`	`float`	Yes	Battery voltage in volts
`current`	`float`	No	Current draw in amps
`percentage`	`float`	No	Charge percentage (0.0-1.0)
`present`	`boolean`	No	Whether battery is present

Published to: [:sensor, :battery] or custom path

IMU

Inertial measurement unit data.

Module: BB.Message.Sensor.IMU

Fields:

Field	Type	Required	Description
`orientation`	`Quaternion`	No	Orientation quaternion
`angular_velocity`	`Vec3`	No	Angular velocity in rad/s
`linear_acceleration`	`Vec3`	No	Linear acceleration in m/s²

Published to: [:sensor, :imu] or custom path

LaserScan

2D laser range finder data.

Module: BB.Message.Sensor.LaserScan

Fields:

Field	Type	Required	Description
`angle_min`	`float`	Yes	Start angle in radians
`angle_max`	`float`	Yes	End angle in radians
`angle_increment`	`float`	Yes	Angle between measurements
`ranges`	`[float]`	Yes	Range measurements in metres
`intensities`	`[float]`	No	Intensity values

Published to: [:sensor, :lidar] or custom path

Range

Single distance measurement.

Module: BB.Message.Sensor.Range

Fields:

Field	Type	Required	Description
`range`	`float`	Yes	Measured distance in metres
`min_range`	`float`	No	Minimum valid range
`max_range`	`float`	No	Maximum valid range
`radiation_type`	`atom`	No	`:ultrasound` or `:infrared`

Published to: [:sensor, sensor_name]

Image

Camera image data.

Module: BB.Message.Sensor.Image

Fields:

Field	Type	Required	Description
`height`	`integer`	Yes	Image height in pixels
`width`	`integer`	Yes	Image width in pixels
`encoding`	`string`	Yes	Pixel encoding (e.g., "rgb8", "mono8")
`data`	`binary`	Yes	Raw image data

Published to: [:sensor, :camera] or custom path

Actuator Messages

BeginMotion

Published when an actuator starts moving.

Module: BB.Message.Actuator.BeginMotion

Fields:

Field	Type	Required	Description
`initial_position`	`float`	Yes	Starting position
`target_position`	`float`	Yes	Target position
`expected_arrival`	`integer`	Yes	Expected completion time (monotonic ms)
`command_id`	`reference`	No	Correlation ID
`command_type`	`atom`	No	`:position`, `:velocity`, `:effort`, `:trajectory`

Published to: [:actuator, actuator_name]

Used by: OpenLoopPositionEstimator for position feedback without encoders.

EndMotion

Published when an actuator completes a motion.

Module: BB.Message.Actuator.EndMotion

Fields:

Field	Type	Required	Description
`final_position`	`float`	Yes	Achieved position
`command_id`	`reference`	No	Correlation ID

Published to: [:actuator, actuator_name]

Actuator Command Messages

Commands sent to actuators.

Command.Position

Position target command.

Module: BB.Message.Actuator.Command.Position

Fields:

Field	Type	Required	Description
`target`	`float`	Yes	Target position

Published to: [:actuator, actuator_name]

Command.Velocity

Velocity command.

Module: BB.Message.Actuator.Command.Velocity

Fields:

Field	Type	Required	Description
`velocity`	`float`	Yes	Target velocity

Command.Effort

Effort (torque/force) command.

Module: BB.Message.Actuator.Command.Effort

Fields:

Field	Type	Required	Description
`effort`	`float`	Yes	Target effort

Command.Trajectory

Multi-point trajectory command.

Module: BB.Message.Actuator.Command.Trajectory

Fields:

Field	Type	Required	Description
`points`	`[TrajectoryPoint]`	Yes	Trajectory waypoints

Command.Hold

Hold current position.

Module: BB.Message.Actuator.Command.Hold

No additional fields.

Command.Stop

Stop motion immediately.

Module: BB.Message.Actuator.Command.Stop

No additional fields.

Geometry Messages

Geometric primitives used as components in other messages.

Point3D

3D point.

Module: BB.Message.Geometry.Point3D

Fields:

Field	Type	Required	Description
`x`	`float`	Yes	X coordinate
`y`	`float`	Yes	Y coordinate
`z`	`float`	Yes	Z coordinate

Pose

Position and orientation.

Module: BB.Message.Geometry.Pose

Fields:

Field	Type	Required	Description
`position`	`Point3D`	Yes	Position
`orientation`	`Quaternion`	Yes	Orientation

Twist

Linear and angular velocity.

Module: BB.Message.Geometry.Twist

Fields:

Field	Type	Required	Description
`linear`	`Vec3`	Yes	Linear velocity (m/s)
`angular`	`Vec3`	Yes	Angular velocity (rad/s)

Accel

Linear and angular acceleration.

Module: BB.Message.Geometry.Accel

Fields:

Field	Type	Required	Description
`linear`	`Vec3`	Yes	Linear acceleration (m/s²)
`angular`	`Vec3`	Yes	Angular acceleration (rad/s²)

Wrench

Force and torque.

Module: BB.Message.Geometry.Wrench

Fields:

Field	Type	Required	Description
`force`	`Vec3`	Yes	Force (N)
`torque`	`Vec3`	Yes	Torque (Nm)

System Messages

StateMachine.Transition

Robot state machine transition.

Published to: [:state_machine]

Fields:

Field	Type	Description
`from`	`atom`	Previous state
`to`	`atom`	New state

Safety.HardwareError

Hardware error report.

Published to: [:safety, :error]

Fields:

Field	Type	Description
`path`	`[atom]`	Path to component
`error`	`term`	Error details

Creating Messages

All message types support new/1 and new!/1:

# Returns {:ok, message} or {:error, reason}
{:ok, msg} = JointState.new(names: [:shoulder], positions: [0.5])

# Raises on validation error
msg = JointState.new!(names: [:shoulder], positions: [0.5])

Message Wrapper

Messages are wrapped in BB.Message:

%BB.Message{
  payload: %JointState{...},
  timestamp: ~U[2025-01-18 12:00:00Z],
  frame_id: "shoulder"
}

Create wrapped messages:

BB.Message.new(JointState, :shoulder, names: [:shoulder], positions: [0.5])

← Previous Page Error Types Reference

Next Page → Telemetry Events Reference