M-Bus telegrams

The telegram decoder of the M-Bus module: it finds the frames of EN 13757-2 in a stream of bytes, builds the requests of a master, and decodes the variable data structure of EN 13757-3 (the answer of a meter) to json. C_PROT_MBUS_M is built on it. A gate that reads M-Bus some other way, or a tool that decodes captured telegrams, can use it directly.

Source code:

• mbus_telegram.h

• mbus_telegram.c

Nothing here logs, and nothing keeps state. A function that fails returns -1, 0 or NULL, and writes the reason into the why buffer it is given. The caller logs that reason, because only the caller knows which peer sent the bytes. A meter that answers garbage is a warning about that meter, not an error of the decoder.

How it was checked. The decoder was compared, record by record, with libmbus’s decoding of the 78 real telegrams in libmbus’s test collection. 893 of the 909 records are equal. The other 16 differ on purpose:

• a BCD with a digit in error is null here, where libmbus makes up a number;

• a “date of” VIFE (6F, the date of a maximum) is a date here, where libmbus reads a temperature of 41 million °C;

• a date that was never set is null;

• a date with a field out of its range (an hour 31, a year 127) is null. This one came after the comparison: since then, storage 510 of the Landis+Gyr T230 (a type F date with every year bit set, a slot never written) is null here and 2027-01-01T00:00 in libmbus;

• the fixed data structure (CI 73) is not decoded.

The module’s test (tests/c/mbus_telegram) keeps six of those telegrams.

mbus_parse_frame()¶

mbus_parse_frame() finds the frame that starts at bf[0]: an E5, a short frame (10 C A CS 16), a control frame or a long frame (68 L L 68 C A CI data CS 16).

int mbus_parse_frame(
    const uint8_t *bf,
    size_t len,
    mbus_frame_t *frame,
    char *why,
    size_t why_size
);

Parameters

Returns

• The length of the frame (> 0).

• 0 when bf holds the start of a frame and more bytes are needed.

• -1 when bf does not start with a valid frame: a bad start byte, the two lengths differ, a bad checksum or stop byte. The link layer cannot resynchronise inside a broken frame, so the caller drops what it holds.

Bytes after the frame are not looked at: the caller decides whether they are the next frame or noise.

Example

mbus_frame_t frame;
char why[256];
int r = mbus_parse_frame(priv->rx, priv->rx_len, &frame, why, sizeof(why));
if(r == 0) {
    return 0;   // wait for more bytes
}
if(r < 0) {
    gobj_log_warning(gobj, 0,
        "function",     "%s", __FUNCTION__,
        "msgset",       "%s", MSGSET_PROTOCOL,
        "msg",          "%s", "M-Bus bad frame",
        "why",          "%s", why,
        NULL
    );
    priv->rx_len = 0;
    return -1;
}
// frame.type is MBUS_FRAME_ACK, _SHORT, _CONTROL or _LONG

mbus_build_short_frame()¶

mbus_build_short_frame() builds a short frame, the shape of every request of a master that carries no data: SND_NKE, REQ_UD2.

size_t mbus_build_short_frame(uint8_t *bf, size_t size, uint8_t c, uint8_t a);

Parameters

Returns

5, the length written, or 0 when size is less than that.

Example

uint8_t bf[MBUS_FRAME_MAX_LENGTH];
size_t n = mbus_build_short_frame(bf, sizeof(bf), MBUS_C_REQ_UD2|MBUS_C_FCB, 1);
// 10 7B 01 7C 16

mbus_build_long_frame()¶

mbus_build_long_frame() builds a long frame: the SND_UD of a master (a selection, a write), or the RSP_UD of a meter in a test.

size_t mbus_build_long_frame(
    uint8_t *bf,
    size_t size,
    uint8_t c,
    uint8_t a,
    uint8_t ci,
    const uint8_t *data,
    size_t data_len
);

Parameters

Returns

The length written, or 0 when data_len is more than a frame carries or size is too small.

Example

uint8_t sel[MBUS_SECONDARY_ADDRESS_SIZE];
mbus_build_secondary_address(sel, "12345678", "KAM", -1, -1, why, sizeof(why));
size_t n = mbus_build_long_frame(bf, sizeof(bf),
    MBUS_C_SND_UD, MBUS_ADDRESS_SELECTED, MBUS_CI_SELECT_SECONDARY,
    sel, sizeof(sel)
);
// 68 0B 0B 68 53 FD 52 78 56 34 12 2D 2C FF FF 0D 16

mbus_build_secondary_address()¶

mbus_build_secondary_address() encodes the 8 bytes that select a meter by its secondary address: identification (4 BCD bytes, least significant first), manufacturer, version, medium.

int mbus_build_secondary_address(
    uint8_t out[MBUS_SECONDARY_ADDRESS_SIZE],
    const char *id,
    const char *manufacturer,
    int version,
    int medium,
    char *why,
    size_t why_size
);

Parameters

Returns

0, or -1 when a field is not valid.

Example

uint8_t sel[MBUS_SECONDARY_ADDRESS_SIZE];
char why[256];
if(mbus_build_secondary_address(sel, "1234ffff", NULL, -1, mbus_medium_code("water"),
        why, sizeof(why)) < 0) {
    // why: "secondary address id must be digits or F: '...'"
}
// FF FF 34 12 FF FF FF 07

mbus_decode_user_data()¶

mbus_decode_user_data() decodes the user data of a meter’s long frame (RSP_UD) to json.

json_t *mbus_decode_user_data(
    const mbus_frame_t *frame,
    BOOL *more_follows,
    char *why,
    size_t why_size
);

Parameters

Returns

The json, yours to decref, or NULL with the reason in why.

It refuses the fixed data structure (CI 73/77), the other CIs, records encrypted (security modes 5, 7, 8, 9, 10 and 13 of the configuration field), and a record that does not fit in the telegram.

The id of a record says what the record is, and stays the same from one reading to the next:

<quantity>[:max|:min|:error][@s<n>][@t<n>][@u<n>][~<vife>...][#<n>]

Values come in one unit per quantity, already scaled:

So a consumer that reads energy never has to ask whether the meter counted it in GJ. A month or a year is no fixed number of seconds, so a duration the meter counts in months or years is another quantity, with _months in its name (a year is 12 months):

{"storage_interval":        {"value": 900, "unit": "s"},
 "storage_interval_months": {"value": 24,  "unit": "month"}}

The one quantity with no fixed unit is custom, a plain text VIF: its unit is the text the meter sends.

Dates come as text: "2026-10-23" (type G), "2026-10-23T14:05" (type F), "2026-10-23T14:05:30" (type I) or "14:05:30" (type J). Identity numbers come as text too (fabrication_number). These have "value": null: a real that is NaN or +-Inf (json has no number for them; the other records of the telegram are decoded), a BCD with a digit in error, a date marked invalid, never set, or with a field out of its range (year 0-99, month 1-12, day 1-31, hour 0-23, minute and second 0-59), and a record that carries a record-error VIFE (it also has "error": "no data available", or whatever the code says). Manufacturer data (after DIF 0F) comes as mfr_data in hex.

Example

BOOL more;
char why[256];
json_t *jn = mbus_decode_user_data(&frame, &more, why, sizeof(why));
if(!jn) {
    // why: "records encrypted (security mode 5): not decoded"
    return -1;
}
json_t *jn_volume = json_object_get(json_object_get(jn, "records"), "volume");
double m3 = json_number_value(json_object_get(jn_volume, "value"));
JSON_DECREF(jn)

A record id is a key: read it with json_object_get(), never as a kw path.

mbus_medium_name()¶

mbus_medium_name() gives the name of a medium code, the one a header carries as medium.

const char *mbus_medium_name(int medium);

Parameters

Returns

A static name, or NULL for a code that has none:

and the rest of the codes in EN 13757-3 (steam, compressed_air, cooling_outlet, pressure, smoke_detector, valve, waste_water, ...).

Example

const char *name = mbus_medium_name(0x07);  // "water"

mbus_medium_code()¶

mbus_medium_code() gives the code of a medium name: the reverse of mbus_medium_name().

int mbus_medium_code(const char *name);

Parameters

Returns

The code, or -1 for a name it does not know (or an empty one).

Example

int medium = mbus_medium_code("gas");   // 3