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 (one row per input frame; record fields use namespaced columns)
m-bus-parser-cli parse -d "..." -t csv

# Colored, semantically grouped 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

Naming and interoperability

The canonical JSON, YAML, CSV, table, Mermaid, Python, and WebAssembly outputs share one vocabulary:

• JSON/YAML member names and annotation identifiers use snake_case.
• Link-layer functions use the M-Bus mnemonics (RSP_UD, REQ_UD2, SND_NKE). Record functions, quantities, and data codings use the terms from the M-Bus application-layer tables, such as Instantaneous value, Volume flow, and 6-digit BCD.
• unit is a single case-sensitive UCUM expression when one is available, such as W, Cel, or m3.h-1.
• Complete temporal values use ISO 8601 notation. The parser does not invent a timezone when a meter does not transmit one.
• Each record value contains a kind and at most one parsed value. Exact decimals, text, and complete temporal values use strings; finite floats use JSON numbers; partial temporal values use a compact component object.
• Raw binary values use uppercase hexadecimal and fields containing them end in _hex. Record bytes live only in header_hex and data_hex.

There is no common JSON schema shared by M-Bus parsers. These rules retain the protocol vocabulary used by M-Bus and libmbus while keeping the structured formats predictable. The xml format deliberately retains libmbus's established XML vocabulary and unit symbols for compatibility. Formats whose names end in -legacy retain their historical contracts.

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