Crate falcon_mdf 

falcon_mdf

A high-performance Rust library for reading ASAM MDF v4 (MF4) measurement data files.

Overview

falcon_mdf provides a clean, ergonomic API for reading MF4 files, which are commonly used in the automotive industry for storing measurement and calibration data. The library focuses on:

• Performance: Zero-copy access via memory mapping, lazy data decoding
• Modularity: Clear separation between I/O, parsing, and data model layers
• Extensibility: Version-aware design for easy support of different MF4 versions
• Usability: High-level API that hides format complexity

Quick Start

use falcon_mdf::Mf4File;

// Open an MF4 file
let file = Mf4File::open("measurement.mf4")?;

// Print file information
println!("MF4 Version: {}", file.version());
println!("Channels: {}", file.channel_count());

// List all channels
for channel in file.channels() {
    println!("  {} [{}]", channel.name, channel.unit);
}

// Read data from a channel
if let Some(channel) = file.find_channel("VehicleSpeed") {
    let signal = file.signal(channel)?;
    let values = signal.values_f64()?;
    println!("Speed values: {:?}", &values[..5.min(values.len())]);
}

Architecture

The crate is organized into several layers:

• I/O Layer (io): Abstraction over file access (mmap vs buffered)
• Block Layer (blocks): Low-level MF4 block structures and parsing
• Parser Layer (parser): Version-aware parsing and block iteration
• Model Layer (model): High-level, user-friendly data types
• File API (Mf4File): Main entry point for users
• Bus Layer (bus): Frames out of bus-logged groups, uninterpreted
• Streaming (stream): Bounded windows of a channel, for large groups
• CAN databases (candb): Payloads decoded to named physical signals

Performance Tips

• Use memory-mapped I/O (default with mmap feature) for large files
• Use iterators instead of values_f64() for very large signals
• The file structure is parsed eagerly, but sample data is read lazily

Supported Versions

Currently supports MF4 versions 4.0, 4.1, and 4.2. The architecture is designed to easily add support for future versions.

Design

Repeated lookups are kept off the hot path by three index structures:

• Block caching via cache::BlockCache for CC/TX/SI blocks
• Channel indexing via channels_db::ChannelsDB for name lookups
• Lazy data loading via data_index::DataBlockIndex

The implementation is idiomatic Rust throughout, leveraging:

• Arc<T> for shared block ownership
• Zero-copy memory mapping via memmap2
• Type-safe enums instead of magic numbers
• Parallel parsing with rayon

Re-exports

pub use blocks::conversion::Conversion;

pub use blocks::conversion::TableEntry;

pub use blocks::UnfinalizedFlags;

pub use bus::BusSignal;

pub use bus::BusSignals;

pub use bus::CanFrame;

pub use bus::CanFrames;

pub use cache::BlockCache;

pub use cache::CacheStats;

pub use candb::CanDatabase;

pub use candb::DecodedSignal;

pub use candb::IdMatching;

pub use candb::MessageDef;

pub use candb::Multiplexing;

pub use candb::SignalDef;

pub use channels_db::ChannelLocation;

pub use channels_db::ChannelsDB;

pub use channels_db::MastersDB;

pub use channels_db::SearchMode;

pub use error::Mf4Error;

pub use error::Result;

pub use eth::EthFrame;

pub use eth::EthFrames;

pub use export::write_csv;

pub use export::write_hdf5;

pub use export::write_mat;

pub use export::write_mat73;

pub use export::write_mat_v4;

pub use export::write_asc;

pub use export::write_asc_frames;

pub use export::write_parquet;

pub use export::write_parquet_with;

pub use export::ParquetCompression;

pub use flexray::FlexRayFrame;

pub use flexray::FlexRayFrames;

pub use inspect::BlockInfo;

pub use inspect::BlockMap;

pub use inspect::Gap;

pub use lin::LinFrame;

pub use lin::LinFrames;

pub use model::Attachment;

pub use model::CanopenDate;

pub use model::CanopenTime;

pub use model::Channel;

pub use model::ChannelGroup;

pub use model::ChannelHierarchyNode;

pub use model::DataGroup;

pub use model::EncryptionInfo;

pub use model::Event;

pub use model::FileStatistics;

pub use model::Metadata;

pub use model::RecordingTime;

pub use model::ReductionKind;

pub use model::SampleReduction;

pub use model::Signal;

pub use model::SignalValues;

pub use model::UnreadableReason;

pub use model::ValueKind;

pub use multi_ops::ChannelSelector;

pub use multi_ops::StackedSeries;

pub use multi_ops::TimeAlignment;

pub use parser::Mf4Version;

pub use scramble::scramble_file;

pub use scramble::ScrambleReport;

pub use stream::AlignedSignalChunks;

pub use stream::SignalChunks;

pub use stream::SignalsChunks;

pub use time_ops::InterpolationMode;

pub use time_ops::Raster;

pub use time_ops::SignalSeries;

pub use write::Mf4Writer;

pub use write::WriteChannel;

pub use write::WriteCodec;

pub use write::WriteGroup;

Modules

arxml

Reading an AUTOSAR ARXML database into a CanDatabase.

blocks

MF4 block type definitions and parsers.

bus

Frame extraction from bus-logged channel groups.

cache

Block caching infrastructure for efficient MF4 parsing.

candb

A CAN database, and the decoder that turns frame payloads into signals.

channels_db

Channel database for efficient channel lookup.

data_index

Data block indexing for lazy data access.

dbc

Reading a DBC file into a CanDatabase.

error

Error types and Result aliases for the falcon_mdf crate.

eth

Ethernet frames out of bus-logged groups.

export

Export of decoded channels to formats other tools read.

flexray

FlexRay frames out of bus-logged groups.

inspect

Every block in a file, in address order.

io

I/O abstraction layer for reading MF4 files.

ldf

Reading a LIN Description File (LDF) database into a CanDatabase.

lin

LIN frames out of bus-logged groups.

mdf3

Reading MDF 3.x files.

model

High-level, version-agnostic data model.

multi_ops

Operations that span several channels or several measurements: Mf4File::filter, concatenate and stack.

parser

Parser module for MF4 files.

prelude

Prelude module for convenient imports.

scramble

Anonymising a measurement by replacing its text, byte for byte.

stream

Block-by-block signal reading, for files too large to materialise.

time_ops

Time-domain operations on measurement signals: slicing (cut) and re-gridding (resample).

view

Bounded viewer reads. Only a record chunk and the requested output are retained; compressed input additionally needs one inflated MDF data block.

write

Creation of MF4 files from scratch.

Structs

Mf4File

The main interface for reading MF4 files.

OpenOptions

Configuration options for opening MF4 files.