m-bus-parser

For contributing see CONTRIBUTING.md, for change history see CHANGELOG.md.

An open-source parser (decoder/deserializer) for the wired and wireless M-Bus protocol, written in Rust.

M-Bus (Meter-Bus) is a European standard (EN 13757-2 physical and link layer, EN 13757-3 application layer) for remote reading of water, gas, electricity, and heat meters. — Wikipedia

• Try it live: maebli.github.io/m-bus-parser
• Spec: m-bus.com/documentation · OMS specification

Features

• Parses wired M-Bus (EN 13757-2/-3) and wireless M-Bus (wMBus) frames
• Eight harmonized output formats: table, json, yaml, csv, mermaid, xml, annotated, and annotated-text
• A versioned canonical schema with exact decimal values, provenance, partial-decode diagnostics, and stable error codes
• Responsive, Unicode-aware tables for narrow terminals and browser cards
• AES-128 decryption for encrypted wMBus frames (mode 5 / mode 7)
• no_std compatible — runs on embedded targets (manufacturer lookup and output formats require std)
• Available as a Rust library, CLI, WebAssembly (npm) and Python bindings

Deployments

Web app (WebAssembly)

Paste a hex frame at maebli.github.io/m-bus-parser and get instant output in any format, including a rendered Mermaid diagram. Frames can be shared via URL.

Source: wasm/

CLI

cargo install m-bus-parser-cli

Source: cli/

Python bindings

pip install pymbusparser

Source: python/

CLI Usage

m-bus-parser-cli parse [OPTIONS]

Options:
  -d, --data <DATA>      Raw M-Bus frame as a hex string
  -f, --file <FILE>      File containing a hex frame
  -t, --format <FORMAT>  table, json, yaml, csv, mermaid, xml, annotated, annotated-text
  -k, --key <KEY>        AES-128 decryption key (32 hex characters)
      --width <WIDTH>    Table width (auto-detected on an interactive terminal)
      --no-enrichment    Omit manufacturer enrichment

Input hex is strict: use compact hexadecimal or complete byte tokens separated by whitespace, colons, or hyphens.

68 3D 3D 68 ...      (space-separated)
683D3D68...          (plain hex)
0x68:0x3D:0x3D:0x68  (prefixed byte tokens)

Table output (default)

The table automatically selects a wide, compact, or vertical-card layout and never exceeds the detected terminal width. Use --width 44 to request an exact maximum explicitly.

Other formats

# JSON
m-bus-parser-cli parse -d "..." -t json

# YAML
m-bus-parser-cli parse -d "..." -t yaml

# CSV
m-bus-parser-cli parse -d "..." -t csv

# Mermaid diagram source (renders in the web app)
m-bus-parser-cli parse -d "..." -t mermaid

# Wired-compatible and wireless XML
m-bus-parser-cli parse -d "..." -t xml

# Byte annotations as JSON or human-readable text
m-bus-parser-cli parse -d "..." -t annotated
m-bus-parser-cli parse -d "..." -t annotated-text

# With AES-128 decryption key
m-bus-parser-cli parse -d "..." -k "000102030405060708090A0B0C0D0E0F"

Library Usage

Add to Cargo.toml:

[dependencies]
m-bus-parser = { version = "0.4", features = ["std", "serde"] }

Parse a wired frame

use m_bus_parser::{Address, WiredFrame, Function};
use m_bus_parser::mbus_data::MbusData;
use m_bus_parser::user_data::parse_application_layer;

let frame_bytes: Vec<u8> = vec![
    0x68, 0x4D, 0x4D, 0x68, 0x08, 0x01, 0x72, 0x01,
    // ... rest of frame
];

let frame = WiredFrame::try_from(frame_bytes.as_slice())?;

if let WiredFrame::LongFrame { function, address, data } = frame {
    let application_layer = parse_application_layer(data)?;
    if let Some(records) = application_layer.data_records() {
        for record in records {
            println!("{:?}", record?.value());
        }
    }
}

Parse application-layer data records

When the link and transport headers have already been removed, parse the DIF/VIF records directly:

use m_bus_parser::user_data::parse_data_records;

let data = [0x03, 0x13, 0x15, 0x31, 0x00];
for record in parse_data_records(&data) {
    let record = record?;
    println!("value: {:?}", record.value());
    println!("value information: {:?}", record.value_information());
}

Decode and render with typed APIs

use m_bus_parser::{
    DecodeOptions, OutputFormat, RenderOptions, decode_hex, render_hex,
};

let hex = "68 3D 3D 68 08 01 72 ...";
let decoded = decode_hex(hex, &DecodeOptions::default())?;
println!("schema v{}: {}", decoded.schema_version, decoded.protocol);

let table = render_hex(
    hex,
    OutputFormat::Table,
    &RenderOptions {
        table_width: Some(72),
        ..RenderOptions::default()
    },
)?;

serialize_mbus_data remains as a string compatibility wrapper. New code should use the typed APIs so invalid input and unsupported options remain machine-readable OutputError values.

no_std usage

The core parsing types are no_std compatible. Disable default features:

[dependencies]
m-bus-parser = { version = "0.4", default-features = false }

An embedded example (Cortex-M) is in examples/cortex-m/.

Output Formats

Protocol Coverage

Frame types

CI field types

Implemented

• ResponseWithVariableDataStructure (CI: 0x72, 0x76, 0x7A)
• ResponseWithFixedDataStructure (CI: 0x73)
• ApplicationLayerShortTransport (CI: 0x7D)
• ApplicationLayerLongTransport (CI: 0x7E)
• ExtendedLinkLayerI (CI: 0x8A)
• ResetAtApplicationLevel

Not yet implemented

Returns ApplicationLayerError::Unimplemented for: SendData, SelectSlave, SynchronizeSlave, baud-rate commands, ExtendedLinkLayerII/III, COSEM/OBIS data, and various transport/network layer types.

Most common value information unit codes are supported. Contributions for additional CI types and VIF codes are welcome.

Frame Structure

Wireless Link Layer

Wired Link Layer (Long Frame)

Application Layer

Value Information Block

Related Projects