Quickstart
This guide walks you through creating your first MCAP recording with Cerulion Core.
Step 1: Define Your Message Type
First, define a message type to record:
use cerulion_core::prelude::*;
#[derive(Copy, Clone, Debug)]
#[repr(C)]
struct SensorData {
temperature: f32,
timestamp: u64,
}
Step 2: Create an MCAP Recorder
Create a recorder that writes to a file:
use std::sync::Arc;
// Create MCAP recorder
let recorder = Arc::new(
McapRecorder::create("sensor_log.mcap", None, None)?
);
The recorder is wrapped in Arc so it can be shared across multiple publishers/subscribers. This ensures all messages are written to the same file.
Step 3: Create Publisher and Enable Logging
Create a publisher and enable MCAP logging:
// Create publisher
let mut publisher = Publisher::<SensorData>::create("sensors/temperature")?;
// Enable MCAP logging
publisher.enable_mcap_logging(recorder.clone());
Step 4: Send Messages
Messages are automatically logged when sent:
// Send messages - automatically logged to MCAP
let data = SensorData {
temperature: 23.5,
timestamp: 1234567890,
};
publisher.send(data)?;
println!("Message sent and logged!");
Once logging is enabled, all messages sent via publisher.send() are automatically logged to the MCAP file. No additional code needed.
Step 5: Verify the Recording
After your program completes, verify the MCAP file was created:
# List topics in MCAP file
mcap info sensor_log.mcap
# Expected output:
# Channels:
# sensors/temperature: SensorData (1 messages)
Complete Example
Here’s the complete program:
use cerulion_core::prelude::*;
use std::sync::Arc;
#[derive(Copy, Clone, Debug)]
#[repr(C)]
struct SensorData {
temperature: f32,
timestamp: u64,
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create MCAP recorder
let recorder = Arc::new(
McapRecorder::create("sensor_log.mcap", None, None)?
);
// Create publisher
let mut publisher = Publisher::<SensorData>::create("sensors/temperature")?;
// Enable MCAP logging
publisher.enable_mcap_logging(recorder.clone());
// Send messages (automatically logged)
for i in 0..10 {
let data = SensorData {
temperature: 20.0 + (i as f32) * 0.5,
timestamp: i as u64,
};
publisher.send(data)?;
println!("Sent: temp={:.1}°C", data.temperature);
}
println!("Recording saved to sensor_log.mcap");
Ok(())
}
Reading MCAP Files
Use the MCAP CLI tools to inspect and analyze your recordings:
# Show file information
mcap info sensor_log.mcap
# Extract messages to JSON
mcap extract sensor_log.mcap --output messages.json
# View message contents
cat messages.json | jq
MCAP files are self-contained and include schemas, metadata, and message data. They can be read by any MCAP-compatible tool or library.
Next Steps
