Wireformat Messages

Overview

Cerulion uses ROS2-compatible message definitions for type-safe communication between nodes. Whether you need to send sensor readings, camera frames, or robot state, these messages work seamlessly with both local (zero-copy) and network transport. Message definitions are automatically parsed from .msg files and compiled into zero-copy Rust types at build time.

use cerulion_core_v2::prelude::*;

// Create a timestamped pose
let mut pose_stamped = PoseStamped::new();
pose_stamped.set_header(header);
pose_stamped.set_pose(pose);

Primitive Types

Numeric Types
Variable-Length Types
Array Types

ROS2 Type	Rust Type	Size
`bool`	`bool`	1 byte
`int8` / `byte`	`i8`	1 byte
`uint8` / `char`	`u8`	1 byte
`int16`	`i16`	2 bytes
`uint16`	`u16`	2 bytes
`int32`	`i32`	4 bytes
`uint32`	`u32`	4 bytes
`int64`	`i64`	8 bytes
`uint64`	`u64`	8 bytes
`float32`	`f32`	4 bytes
`float64`	`f64`	8 bytes

ROS2 Type	Rust Type
`string`	`String`
`bytes`	`Vec<u8>`

Variable-length types use a 4-byte length prefix followed by data.

Syntax	Rust Type
`T[N]`	`[T; N]`
`T[]`	`Vec<T>`

Examples:

float64[9] → [f64; 9]
float64[36] → [f64; 36]
uint8[] → Vec<u8>

Nested Types

Any message type can reference another message type:

Syntax	Description	Example
`pkg/MsgType`	Message from another package	`geometry_msgs/Point`
`MsgType`	Message in same package	`Quaternion`

Available Message Packages

builtin_interfaces

Core time primitives used throughout the system.

Message	Fields	Description
Time	`int32 sec`, `uint32 nanosec`	Point in time relative to clock epoch
Duration	`int32 sec`, `uint32 nanosec`	Time duration (can be negative)

let mut stamp = Time::new();
stamp.set_sec(1704067200);
stamp.set_nanosec(500_000_000);

std_msgs

Standard message types and building blocks.

Message	Key Fields	Description
Header	`stamp: Time`, `frame_id: string`	Standard metadata for stamped data
Bool	`data: bool`	Single boolean value
String	`data: string`	String wrapper
Int8/16/32/64	`data: intN`	Signed integer wrappers
UInt8/16/32/64	`data: uintN`	Unsigned integer wrappers
Float32/64	`data: floatN`	Float wrappers
ColorRGBA	`r, g, b, a: float32`	RGBA color
Empty	(none)	Empty message for signals

let mut header = Header::new();
header.set_stamp(stamp);
header.set_frame_id("base_link");

geometry_msgs

Geometric primitives for robotics.

Message	Fields	Description
Point	`x, y, z: float64`	3D point position
Point32	`x, y, z: float32`	3D point (single precision)
Vector3	`x, y, z: float64`	3D vector
Quaternion	`x, y, z, w: float64`	Orientation quaternion
Pose	`position: Point`, `orientation: Quaternion`	Position + orientation
Pose2D	`x, y, theta: float64`	2D pose
PoseStamped	`header: Header`, `pose: Pose`	Timestamped pose
PoseArray	`header: Header`, `poses: Pose[]`	Array of poses
PoseWithCovariance	`pose: Pose`, `covariance: float64[36]`	Pose with 6x6 uncertainty
Transform	`translation: Vector3`, `rotation: Quaternion`	3D transform
TransformStamped	`header`, `child_frame_id`, `transform`	Stamped transform
Twist	`linear: Vector3`, `angular: Vector3`	Linear + angular velocity
TwistStamped	`header: Header`, `twist: Twist`	Timestamped velocity
TwistWithCovariance	`twist: Twist`, `covariance: float64[36]`	Velocity with uncertainty
Accel	`linear: Vector3`, `angular: Vector3`	Linear + angular acceleration
Wrench	`force: Vector3`, `torque: Vector3`	Force + torque
Inertia	`m: float64`, `com: Vector3`, `ixx,ixy,...`	Mass + inertia tensor
Polygon	`points: Point32[]`	2D polygon

// Simple point
let mut point = Point::new();
point.set_x(1.0);
point.set_y(2.0);
point.set_z(3.0);

// Velocity command
let mut twist = Twist::new();
let mut linear = Vector3::new();
linear.set_x(1.0);
twist.set_linear(linear);

sensor_msgs

Sensor data types.

Message	Key Fields	Description
Image	`header`, `height`, `width`, `encoding`, `data[]`	Uncompressed image
CompressedImage	`header`, `format`, `data[]`	Compressed image (JPEG/PNG)
CameraInfo	`header`, `height`, `width`, K/D/R/P matrices	Camera calibration
Imu	`header`, `orientation`, `angular_velocity`, `linear_acceleration`	IMU data
LaserScan	`header`, angles, ranges, `ranges[]`, `intensities[]`	2D lidar scan
PointCloud2	`header`, `height`, `width`, `fields[]`, `data[]`	3D point cloud
PointField	`name`, `offset`, `datatype`, `count`	Point cloud field descriptor
JointState	`header`, `name[]`, `position[]`, `velocity[]`, `effort[]`	Robot joint states
NavSatFix	`header`, `status`, `latitude`, `longitude`, `altitude`	GPS fix
Range	`header`, `radiation_type`, `field_of_view`, `range`	Distance sensor
Temperature	`header`, `temperature`, `variance`	Temperature reading
BatteryState	`header`, `voltage`, `current`, `charge`, `percentage`	Battery status
Joy	`header`, `axes[]`, `buttons[]`	Joystick input

// Create an RGB image
let pixel_data = vec![0u8; 640 * 480 * 3];

let mut image = Image::new();
image.set_height(480);
image.set_width(640);
image.set_encoding("rgb8");
image.set_step(640 * 3);
image.set_data(pixel_data);

nav_msgs

Navigation messages.

Message	Key Fields	Description
Odometry	`header`, `child_frame_id`, `pose`, `twist` + covariances	Robot odometry
Path	`header`, `poses: PoseStamped[]`	Planned path
OccupancyGrid	`header`, `info: MapMetaData`, `data[]`	2D occupancy map
MapMetaData	`map_load_time`, `resolution`, `width`, `height`, `origin`	Map metadata
GridCells	`header`, `cell_width`, `cell_height`, `cells[]`	Grid cell list

shape_msgs

Shape primitives.

Message	Fields	Description
Mesh	`triangles[]`, `vertices[]`	Triangle mesh
MeshTriangle	`vertex_indices: uint32[3]`	Single triangle
Plane	`coef: float64[4]`	Plane equation (ax+by+cz+d=0)
SolidPrimitive	`type`, `dimensions[]`, `polygon`	Box/sphere/cylinder/cone

diagnostic_msgs

System diagnostics.

Message	Fields	Description
DiagnosticArray	`header`, `status[]`	Array of diagnostic statuses
DiagnosticStatus	`level`, `name`, `message`, `hardware_id`, `values[]`	Single diagnostic
KeyValue	`key`, `value`	Key-value pair

Usage Examples

Creating and Populating Messages

use cerulion_core_v2::prelude::*;

// Simple fixed-size message
let mut point = Point::new();
point.set_x(1.0);
point.set_y(2.0);
point.set_z(3.0);

// Direct field access (for fixed types)
assert_eq!(point.x, 1.0);

// Nested messages
let mut stamp = Time::new();
stamp.set_sec(1704067200);
stamp.set_nanosec(500_000_000);

let mut header = Header::new();
header.set_stamp(stamp);
header.set_frame_id("base_link");

// Composing complex messages
let mut orientation = Quaternion::new();
orientation.set_w(1.0); // Identity quaternion

let mut pose = Pose::new();
pose.set_position(point);
pose.set_orientation(orientation);

let mut pose_stamped = PoseStamped::new();
pose_stamped.set_header(header);
pose_stamped.set_pose(pose);

Working with Arrays

use cerulion_core_v2::prelude::*;

// Dynamic array of nested types
let mut poses = Vec::new();
for i in 0..10 {
    let mut p = Pose::new();
    let mut pos = Point::new();
    pos.set_x(i as f64);
    p.set_position(pos);
    poses.push(p);
}

let mut pose_array = PoseArray::new();
pose_array.set_poses(poses);

// Fixed-size arrays (covariance matrices)
let mut imu = Imu::new();
// 3x3 covariance matrix stored as row-major array
let orientation_cov = [
    0.01, 0.0, 0.0,  // row 1
    0.0, 0.01, 0.0,  // row 2
    0.0, 0.0, 0.01,  // row 3
];
imu.set_orientation_covariance(orientation_cov);

Building Custom Message Types

Workspace Structure

my-workspace

msg

custom_msgs

RobotState.msg

SensorData.msg

nodes

Cargo.toml

Step 1: Create a `.msg` File

# msg/custom_msgs/RobotState.msg

# Custom robot state message
std_msgs/Header header
string robot_name
geometry_msgs/Pose pose
geometry_msgs/Twist velocity
float64[6] joint_positions
float64[] sensor_readings
uint8 status
bool is_active

Step 2: Message Syntax Rules

# Comments start with #
fieldtype fieldname [default_value]

# Examples:
float64 x                    # Simple primitive
string name                  # Variable-length string
uint8[] data                 # Dynamic array
float64[9] covariance        # Fixed array (9 elements)
geometry_msgs/Pose pose      # Nested type from another package
Header header                # Nested type (std_msgs implied)
uint8 STATUS_OK=1            # Constants

Step 3: Build Process

Step 4: Use Your Custom Message

use your_workspace::custom_msgs::RobotState;

let mut state = RobotState::new();
state.set_robot_name("arm_01");
state.set_status(1);
state.set_is_active(true);
state.set_joint_positions([0.0, 0.5, 1.0, 0.0, -0.5, 0.0]);
state.set_sensor_readings(vec![1.2, 3.4, 5.6]);

Generated Type Patterns

Fixed-Size Messages
Variable-Size Messages

Messages with only primitive fields:

// Generated from Point.msg
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Default)]
pub struct Point {
    pub x: f64,
    pub y: f64,
    pub z: f64,
}

impl Point {
    pub fn new() -> Self {
        Self::default()
    }
    pub fn set_x(&mut self, value: f64) -> &mut Self { ... }
}

// View is just a reference (zero-copy)
pub type PointView<'a> = &'a Point;

Zero-copy transport enabled

Messages with strings or dynamic arrays:

// Generated from Image.msg
#[derive(Debug, Clone, Default)]
pub struct Image {
    pub header: Header,
    pub height: u32,
    pub width: u32,
    pub encoding: String,
    pub is_bigendian: u8,
    pub step: u32,
    pub data: Vec<u8>,
}

impl Image {
    pub fn new() -> Self {
        Self::default()
    }
    pub fn wire_size(&self) -> usize { ... }
}

// View wraps buffer for reading
pub struct ImageView<'a> {
    buffer: &'a [u8],
}

Requires serialization for network transport

Wire Format

All primitives use little-endian byte order.

Variable-Length Encoding

Strings and dynamic arrays include a 4-byte length prefix:

Array Encoding

Fixed arrays (T[N]) have no length prefix — size is known at compile time.

Primitive Sizes

Type	Wire Size
`bool`	1 byte
`int8/uint8`	1 byte
`int16/uint16`	2 bytes
`int32/uint32/float32`	4 bytes
`int64/uint64/float64`	8 bytes

Message Traits

All generated messages implement these traits:

pub trait Message {
    const SCHEMA_HASH: u64;
    fn wire_size(&self) -> usize;
    fn write_to_buffer(&self, buffer: &mut [u8]);
}

// Additional trait for fixed-size messages
pub trait FixedMessage: Message {
    const WIRE_SIZE: usize;
}

Fixed-size messages implementing FixedMessage can use zero-copy shared memory transport, achieving sub-microsecond latency.

Best Practices

Use fixed arrays for known sizes

float64[9] is more efficient than float64[]. Fixed arrays are stored inline and enable zero-copy transport.

Prefer nested types over duplicating fields

Compose from existing messages rather than duplicating fields. This ensures consistency and enables better tooling support.

Include Header for timestamps

Most sensor data should include a std_msgs/Header for timing and frame information.

Use covariance matrices for uncertainty

Include 6x6 covariance for pose (float64[36]) or 3x3 for orientation (float64[9]) when uncertainty information is available.

Place variable data last

Put dynamic arrays and strings at the end of message definitions for better serialization performance.

Cerulion

Overview

Primitive Types

Nested Types

Available Message Packages

Usage Examples

Creating and Populating Messages

Working with Arrays

Building Custom Message Types

Workspace Structure

Step 1: Create a `.msg` File

Step 2: Message Syntax Rules

Step 3: Build Process

Step 4: Use Your Custom Message

Generated Type Patterns

Wire Format

Variable-Length Encoding

Array Encoding

Primitive Sizes

Message Traits

Best Practices

Next Steps

Pub/Sub

Architecture

Cerulion

​Overview

​Primitive Types

​Nested Types

​Available Message Packages

​Usage Examples

​Creating and Populating Messages

​Working with Arrays

​Building Custom Message Types

​Workspace Structure

​Step 1: Create a .msg File

​Step 2: Message Syntax Rules

​Step 3: Build Process

​Step 4: Use Your Custom Message

​Generated Type Patterns

​Wire Format

​Variable-Length Encoding

​Array Encoding

​Primitive Sizes

​Message Traits

​Best Practices

​Next Steps

Pub/Sub

Architecture

Overview

Primitive Types

Nested Types

Available Message Packages

Usage Examples

Creating and Populating Messages

Working with Arrays

Building Custom Message Types

Workspace Structure

Step 1: Create a `.msg` File

Step 2: Message Syntax Rules

Step 3: Build Process

Step 4: Use Your Custom Message

Generated Type Patterns

Wire Format

Variable-Length Encoding

Array Encoding

Primitive Sizes

Message Traits

Best Practices

Next Steps