spodes-rs
A pure-Rust implementation of the DLMS/COSEM stack for electricity metering, following IEC 62056 (the DLMS Green Book) and the Russian companion profiles СТО 34.01-5.1-006-2023 and Р 1323565.1 (GOST cryptography).
The crate covers the whole stack — COSEM object model, A-XDR encoding, HDLC and TCP/UDP transport, the xDLMS application services, and the full security model including the GOST suite — and provides blocking client and server drivers on top. Every wire format and every cryptographic primitive is validated byte-for-byte against the reference test vectors of the standards.
Features
- COSEM object model — 31 interface classes (Data, Register, Extended / Demand register, Register activation, Profile generic, Clock, Script table, Schedule, Special days table, Association LN, Security setup, Disconnect control, Limiter, Push / TCP-UDP / IPv4 / IPv6 setup, and more), all versions.
- 38 typed attribute structs — strongly-typed structs for IEC 62056-6-2
(Blue Book) type definitions, replacing generic
CosemDataType. - A-XDR / BER serialization of the common COSEM data types.
- Transport — an HDLC data-link layer (IEC 62056-46) over any byte medium and a wrapper layer (IEC 62056-47) for TCP/UDP.
- xDLMS services (LN referencing, IEC 62056-5-3):
- GET / SET / ACTION — normal, block transfer (with datablocks) and WITH-LIST;
- ACSE association (AARQ / AARE) and release (RLRQ / RLRE);
- structured InitiateRequest / InitiateResponse;
- DataNotification and EventNotification;
- ExceptionResponse and ConfirmedServiceError;
- general block transfer (GBT);
- glo-/ded-ciphering and general-glo-/ded-/general-ciphering / general-signing.
- Security (IEC 62056-5-3 §5.3 and Р 1323565.1):
- security suites 0, 1, 2 and the GOST suite;
- protection policies (none / authentication / encryption / both);
- authentication mechanisms 0..10, including the GOST HLS mechanisms (Streebog, Kuznyechik-CMAC, GOST 34.10 signatures);
- AES-GCM APDU protection, ECDSA and GOST 34.10 signatures;
- ECDH and GOST VKO key agreement with the NIST SP 800-56A and GOST KDFs.
- Timeouts and retries — configurable per-request timeouts and automatic retries for transient errors in the client session.
- Optional logging —
tracingsupport behind a feature flag.
Quick start
Add the crate to your Cargo.toml:
[]
= { = "https://github.com/gvtret/spodes-rs" }
# or with optional features:
# spodes-rs = { git = "...", features = ["tracing"] }
Creating a COSEM object
use Data;
use InterfaceClass;
use ObisCode;
use CosemDataType;
let object = new;
assert_eq!;
assert_eq!;
Creating a Register with ScalerUnit
use Register;
use ObisCode;
use ScalerUnit;
use CosemDataType;
let register = new;
// value = 1234567 × 10^(-2) = 12345.67 kWh
BER serialization
use CosemDataType;
let value = Structure;
let mut buf = Vecnew;
value.serialize_ber.unwrap;
// buf contains the A-XDR encoded bytes
let = deserialize_ber.unwrap;
assert!;
assert_eq!;
Typed attributes (IEC 62056-6-2)
The crate provides strongly-typed structs for all COSEM type definitions:
use *;
use ObisCode;
// Action item for script tables and register monitors
let action = ActionItem ;
let cd: CosemDataType = action.into; // Convert to CosemDataType
let back = try_from.unwrap; // Convert back
// Schedule table entry
let entry = ScheduleTableEntry ;
// Access rights for Association LN
let access = AccessRight ;
Client session with timeouts and retries
use ClientSession;
use Wrapper;
use MemoryTransport;
use Duration;
let transport = new;
let wrapper = new;
// Configure with timeouts and retries
let mut session = builder
.request_timeout
.max_retries
.retry_delay
.build;
// GET request
let response = session.get.unwrap;
// SET request
use CosemDataType;
session.set.unwrap;
// ACTION request
session.action.unwrap;
Server dispatcher
use Data;
use Register;
use RequestDispatcher;
use ObisCode;
use ScalerUnit;
use CosemDataType;
let mut dispatcher = new;
// Register objects
dispatcher.add;
dispatcher.add;
// Dispatch incoming request APDU
let request_apdu = vec!;
let response_apdu = dispatcher.dispatch.unwrap;
Clock object
use ;
use ObisCode;
use DateTime;
let clock = new;
assert_eq!; // hour
Activity calendar with typed structs
use ;
use ObisCode;
let season = SeasonProfile ;
let week = WeekProfile ;
let day = DayProfile ;
Push setup
use ;
use ObisCode;
use ;
use CosemDataType;
let config = PushSetupConfig ;
let mut push = new;
push.invoke_method.unwrap;
Examples
Runnable examples
# Client/server session
# Security and authentication
# Push notifications
# Transport
# COSEM object usage
# СПОДУС concentrator
Client session with AARQ/AARE and ciphering
use ;
use acse;
use Wrapper;
use MemoryTransport;
use Duration;
let transport = new;
let wrapper = new;
// Build session with timeouts and retries
let mut session = builder
.request_timeout
.max_retries
.retry_delay
.build;
// Associate with LLS (password authentication)
let response = session.associate_lls.unwrap;
// Check association state
assert!;
assert_eq!;
GOST ciphering (Kuznyechik)
use ;
// Create a GOST security context
let ctx = SecurityContext ;
// Encrypt an APDU
let plaintext = b"C001C100";
let ciphered = gost_protect.unwrap;
// Decrypt an APDU
let = gost_unprotect.unwrap;
assert_eq!;
assert_eq!;
Raw APDU support
use ClientSession;
use RawApdu;
// Create and send a raw APDU (for manufacturer-specific extensions)
let raw = new;
let response = session.send_raw.unwrap;
println!;
// Send raw bytes without any parsing
let reply = session.send_raw_bytes.unwrap;
Request dispatcher with access rights
use Data;
use Register;
use AssociationLn;
use RequestDispatcher;
use ObisCode;
use ScalerUnit;
use CosemDataType;
let mut dispatcher = new;
// Register objects
dispatcher.add;
dispatcher.add;
// Set association for access rights checking
// dispatcher.set_association(association_ln);
// Dispatch incoming request APDU
let response_apdu = dispatcher.dispatch.unwrap;
СПОДУС — ИВКЭ concentrator
The spodus module implements the СПОДУС profile
(СТО 34.01-5.1-013-2023): a data-concentrator (ИВКЭ) that speaks СПОДЭС as a
DLMS client to the meters, aggregates their data, and serves it upstream to the
head-end (ИВК) as a DLMS server, with transparent pass-through to an individual
meter by its direct_id.
Feature flags
| Feature | Default | Description |
|---|---|---|
gost |
yes | GOST cryptographic primitives (Kuznyechik, Streebog, GOST 34.10) |
nist |
yes | NIST cryptographic primitives (AES-GCM, ECDSA, ECDH) |
tracing |
no | Optional tracing logging support |
[]
= { = "...", = false, = ["nist"] }
Standards
- IEC 62056-5-3 (DLMS/COSEM application layer, the "Green Book")
- IEC 62056-6-2 (COSEM interface classes)
- IEC 62056-46 / IEC 62056-47 (HDLC and TCP/UDP transport)
- СТО 34.01-5.1-006-2023 (Rosseti companion profile)
- Р 1323565.1 (GOST cryptographic profile: suites, HLS mechanisms 8/9/10, GOST 34.10 / 34.11 / 34.12, VKO / KDF_TREE)
Testing
MSRV
The minimum supported Rust version is 1.85. This is tested in CI.
Versioning
This project follows Semantic Versioning. Notable changes
are recorded in CHANGELOG.md. Releases are cut by pushing a
vX.Y.Z tag matching the Cargo.toml version, which triggers the release
workflow. While the crate is at 0.x, minor releases may contain breaking
changes.
License
Licensed under the GNU General Public License v3.0.