dlms-cosem-rs

IEC 62056 · Blue Book 18 · Green Book 12

The whole of DLMS/COSEM that runs on a CPU, in one Rust crate.

The protocol a smart electricity, gas, water or heat meter speaks to the system that reads it — the object model, the application layer and the transports — with no sockets, no clock and no async runtime in the core. The same code drives a head-end under Tokio, a WASM decoder in a browser, and meter firmware on a Cortex-M.

pre-release Not yet published to crates.io — build it from the repository. The API is being made right rather than kept stable.

Read a register

The session hands you bytes and takes bytes back. Where they go is yours.

let mut session: ClientSession<_> = ClientSession::new(
    ClientConfig { client_sap: 0x10, ..Default::default() },
    RustCryptoProvider::new(KeyRing::default()),
);

let mut request = [0u8; 512];
let n = session.associate_request(&mut request)?;
// ... send request[..n] over HDLC, TCP, CoAP, whatever you have,
//     and feed the answer back:
session.handle_associate_response(&response)?;

let n = session.get_request(
    AttributeDescriptor::new(3, ACTIVE_ENERGY_IMPORT_TOTAL, 2),
    None,
    &mut request,
)?;

let mut scratch = [0u8; 512];
if let Response::Data(value) = session.handle_response(&answer, &mut scratch)? {
    println!("meter reads {:?} Wh", value.as_u64());
}

Decrypt a meter's push

The Austrian, Luxembourg and Dutch customer interfaces emit a ciphered DataNotification with no association and nothing to correlate. That is a listener, not a session.

let mut listener = NotificationListener::new(
    RustCryptoProvider::new(KeyRing::default()),
    SingleMeterKeys::new(meter_title, KeyRing::new(guek, gak)),
    // What the listener *requires*. A push is unsolicited, so nothing negotiated
    // this: the only statement about how a frame should have been protected is
    // this one.
    SecurityPolicy::authenticated_encrypted(SecuritySuite::Suite0),
);

let mut scratch = [0u8; 512];
if let Ok(push) = listener.handle(frame, &mut scratch) {
    for field in push.body.as_structure().into_iter().flat_map(|s| s.iter()) {
        println!("{:?}", field);
    }
}

Why another one

Every existing DLMS stack gives up at least two of these. This one is meant to give up none.

Permissively licensed

MIT or Apache-2.0. The reference implementation is GPL-2 or commercial; the nearest other Rust one is GPL-3.

no_std, alloc optional

The full codec, HDLC, the wrapper, both engines and suite 0 build for thumbv7em-none-eabihf with no allocator at all.

Sans-I/O

A whole ciphered association runs as a unit test in microseconds, and the server is fuzzed as a state machine rather than as a parser.

Client and server

From one object model. cosem does not depend on xdlms: the model says what a meter is, the application layer says how to ask it.

Panic-free from the network

A release build for two bare-metal targets contains no panic symbols at all — measured on object code with LTO off, so the library stands on its own. CI fails if one appears.

Replay is rejected, not documented

Every ciphered APDU spends an invocation counter that is never accepted twice. A recorded “open the breaker” is refused the second time.

What is in the box

LayerWhat it does
codecA bounds-checked cursor. Every error carries the byte offset it happened at.
axdrData borrowed from the input, so a load profile decodes without allocating. Compact arrays, delta types, COSEM date-times with their wildcards intact.
ber, acseAARQ / AARE / RLRQ / RLRE: application context, authentication mechanism, system titles, conformance.
xdlmsEvery APDU tag. GET / SET / ACTION / ACCESS, block transfer, general block transfer with its streaming window and retry, push, exceptions, the four protection wrappers — and short-name Read / Write behind the sn feature.
securitySuites 0–2 at both key widths, glo-/ded-/general ciphering, HLS-GMAC, invocation counters with a real replay window, AES key wrap — behind a swappable provider.
cosem102 interface classes as a registry, OBIS, access rights in both shapes, profile buffers with every compression undone.
transportHDLC with a resynchronising frame finder, segmentation and a link machine; the TCP/UDP wrapper; the P1 customer interface.
client, serverSans-I/O state machines with block transfer both ways, every batched service, both referencing modes, and both halves of push.

What it does not claim

Interoperability has not been tested. Almost every green test is this crate agreeing with itself. The exceptions are the NIST and RFC cipher vectors, the published xDLMS Initiate encodings and CRC-16's own check values — real independent evidence, but a narrow slice of the protocol. Until it has been run against another implementation this crate says “verified against the standard's own vectors”, never “conformant”.

The status page lists what is built, what is not, and why — including the parts deliberately refused rather than guessed at.