yule_log

A streaming ULOG parser written in Rust.

Features

Memory Efficient: A stream-oriented design allows yule_log handle arbitrarily large files in real time without fully loading them into memory.
Derive API: Map LoggedData messages directly into your structs using the optional macros feature.
Complete coverage: Supports all ULog message types.
Binary fidelity: Can parse and re-emit a ULog file byte-for-byte identical to the original.
Safe and robust: Full Rust type safety with comprehensive error handling.

🌟Derive API

The macros feature provides a serde-like experience, allowing ULOG data to be mapped directly into your own structs.

With this feature, there is no need to manually track subscription names, msg_ids, or field indices, the macros handle all of that for you automatically. The stream-oriented nature of the underlying parser is fully preserved.

User guide

1. Enable the feature in Cargo.toml

yule_log = { version="0.3.0", features = ["macros"] }

2. Map subscriptions to structs

Define one struct for each ULOG subscription you want to map, and annotate it with: #[derive(ULogData)].

Example:

#[derive(ULogData)]
 pub struct VehicleLocalPosition {
  pub timestamp: u64,
  pub x: f32,
  pub y: f32,
  pub z: f32,
  pub extra_field: Option<f32>,
 }

In most cases, no extra config is needed—just name your struct and fields to match the names used in the ULOG. Only include the fields you need.

The macros will infer the ULOG names by converting your struct and field names to snake case.

⚠️You can override the default mapping if needed: #[yule_log(subscription_name = "...", multi_id = N)]. By default, struct fields will be validated against the ULOG file, and any missing fields will cause an error. This can be overriden by making a field an Option<T>, as shown above for extra_field.

3. List all subscriptions in an enum

Declare an enum where each variant wraps one of your ULogData structs, and annotate it with: #[derive(ULogMessages)].

#[derive(ULogMessages)]
 pub enum LoggedMessages {
  VehicleLocalPosition(VehicleLocalPosition),
  ActuatorOutputs(ActuatorOutputs),
 }

This enum will then become your interface to the data.

⚠️ Raw ULOG messages can be captured by annotating an enum variant as follows:

  #[yule_log(forward_other)]
  Other(yule_log::model::msg::UlogMessage),

4. Iterate through mapped messages

The derive macro will generate a ::stream() method on your enum, allowing the messages to be easily retrieved.

Full example:

use std::fs::File;
use std::io::BufReader;
use yule_log::model::msg::UlogMessage;

use yule_log::{ULogData, ULogMessages};

#[derive(ULogMessages)]
pub enum LoggedMessages {
    VehicleLocalPosition(VehicleLocalPosition),
    ActuatorOutputs(ActuatorOutputs),

    #[yule_log(forward_other)]
    Other(yule_log::model::msg::UlogMessage),
}

#[derive(ULogData)]
pub struct VehicleLocalPosition {
    pub timestamp: u64,
    pub x: f32,
    pub y: f32,
    pub z: f32,
}

#[derive(ULogData)]
#[yule_log(multi_id = 1)]
pub struct ActuatorOutputs {
    pub timestamp: u64,
    pub output: Vec<f32>,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let reader = BufReader::new(File::open("sample.ulg")?);

    let stream = LoggedMessages::stream(reader)?;

    for msg_res in stream {
        let msg = msg_res?;

        match msg {
            LoggedMessages::VehicleLocalPosition(v) => {
                println!("VehicleLocalPosition: {}: x={} y={} z={}",
                         v.timestamp, v.x, v.y, v.z);
            }
            LoggedMessages::ActuatorOutputs(a) => {
                println!("ActuatorOutputs: {}: {:?}", 
                         a.timestamp, a.output);
            }
            LoggedMessages::Other(msg) => {
                if let UlogMessage::Info(info) = msg {
                    println!("INFO: {info}");
                }
            }
        }
    }

    Ok(())
}

Low Level API

For those requiring complete control over the parsing process, the original low level API is still available.