Skip to main content

spodes_rs/
lib.rs

1//! `spodes-rs` — a pure-Rust implementation of the DLMS/COSEM stack for
2//! electricity metering.
3//!
4//! It follows IEC 62056 (the DLMS Green Book / Blue Book) and the Russian
5//! companion profiles **СПОДЭС** (СТО 34.01-5.1-006-2023, the meter model),
6//! **Р 1323565.1** (the GOST cryptography profile) and **СПОДУС**
7//! (СТО 34.01-5.1-013-2023, the ИВКЭ data-concentrator model). Every wire format
8//! and cryptographic primitive is validated byte-for-byte against the reference
9//! test vectors of those standards.
10//!
11//! The crate has no required feature flags and no unsafe code in its own
12//! sources; it can be used a layer at a time or as a whole.
13//!
14//! [![GitHub Pages](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://gvtret.github.io/spodes-rs/)
15//! [![crates.io](https://img.shields.io/crates/v/spodes-rs.svg)](https://crates.io/crates/spodes-rs)
16#![cfg_attr(docsrs, feature(doc_cfg))]
17#![doc(html_root_url = "https://gvtret.github.io/spodes-rs/")]
18//!
19//! # The stack
20//!
21//! ```text
22//! ┌────────────────────────────────────────────────────────────┐
23//! │  session (client)     server (dispatcher)     spodus       │  drivers / profile
24//! ├────────────────────────────────────────────────────────────┤
25//! │  service    GET/SET/ACTION, ACSE, notifications, ciphering │  application layer
26//! │  security   suites, policy, HLS mechanisms, ECDH/GOST      │
27//! ├────────────────────────────────────────────────────────────┤
28//! │  transport  HDLC (62056-46) and wrapper (62056-47)         │  transport layer
29//! ├────────────────────────────────────────────────────────────┤
30//! │  classes / interface  -  COSEM interface objects           │  object model
31//! │  types (A-XDR/BER)  -  obis                                │
32//! └────────────────────────────────────────────────────────────┘
33//! ```
34//!
35//! # Modules
36//!
37//! * [`types`] — the COSEM data types ([`CosemDataType`](types::CosemDataType))
38//!   and their A-XDR (BER) serialization.
39//! * [`obis`] — OBIS object identification codes ([`ObisCode`](obis::ObisCode)).
40//! * [`interface`] / [`classes`] — the COSEM interface classes (Data, Register,
41//!   Clock, Profile generic, Association LN, Security setup, …), all behind the
42//!   [`InterfaceClass`](interface::InterfaceClass) trait.
43//! * [`transport`] — the physical-medium abstraction
44//!   ([`PhysicalTransport`](transport::PhysicalTransport)) and the HDLC and
45//!   wrapper data-link sub-layers (IEC 62056-46 / IEC 62056-47).
46//! * [`service`] — the application-layer xDLMS services (GET/SET/ACTION,
47//!   notifications, association and ciphering APDUs), using LN referencing.
48//! * [`security`] — the security model: suites (0/1/2 and the GOST suite),
49//!   protection policy, the authentication mechanisms (0..10) and the ECDH/GOST
50//!   key-agreement primitives.
51//! * [`session`] — a blocking client-side driver
52//!   ([`ClientSession`](session::ClientSession)); [`server`] — a request
53//!   dispatcher ([`RequestDispatcher`](server::RequestDispatcher)).
54//! * [`spodus`] — the СПОДУС ИВКЭ data-concentrator object model and the
55//!   [`Concentrator`](spodus::node::Concentrator) node.
56//!
57//! # Examples
58//!
59//! Build a COSEM object and read its attributes:
60//!
61//! ```
62//! use spodes_rs::classes::data::Data;
63//! use spodes_rs::interface::InterfaceClass;
64//! use spodes_rs::obis::ObisCode;
65//! use spodes_rs::types::CosemDataType;
66//!
67//! let object = Data::new(ObisCode::new(0, 0, 0x80, 0, 0, 0xFF), CosemDataType::LongUnsigned(0x1234));
68//! assert_eq!(object.class_id(), 1);
69//! assert_eq!(object.attributes()[1].1, CosemDataType::LongUnsigned(0x1234));
70//! ```
71//!
72//! Encode an xDLMS GET-request APDU:
73//!
74//! ```
75//! use spodes_rs::obis::ObisCode;
76//! use spodes_rs::service::get::GetRequest;
77//! use spodes_rs::service::{invoke_id_and_priority, AttributeDescriptor};
78//!
79//! let request = GetRequest::Normal {
80//!     invoke_id_and_priority: invoke_id_and_priority(1, true, true),
81//!     attribute: AttributeDescriptor::new(1, ObisCode::new(0, 0, 0x80, 0, 0, 0xFF), 2),
82//!     access_selection: None,
83//! };
84//! // C0 01 C1 0001 0000800000FF 02 00
85//! assert_eq!(request.encode().unwrap()[0], 0xC0);
86//! ```
87//!
88//! Answer a request server-side with a [`RequestDispatcher`](server::RequestDispatcher):
89//!
90//! ```
91//! use spodes_rs::classes::data::Data;
92//! use spodes_rs::obis::ObisCode;
93//! use spodes_rs::server::RequestDispatcher;
94//! use spodes_rs::service::get::{GetRequest, GetResponse};
95//! use spodes_rs::service::{invoke_id_and_priority, AttributeDescriptor};
96//! use spodes_rs::types::CosemDataType;
97//!
98//! let obis = ObisCode::new(1, 0, 1, 8, 0, 0xFF);
99//! let mut server = RequestDispatcher::new();
100//! server.add(Box::new(Data::new(obis.clone(), CosemDataType::DoubleLongUnsigned(123_456))));
101//!
102//! let request = GetRequest::Normal {
103//!     invoke_id_and_priority: invoke_id_and_priority(1, true, true),
104//!     attribute: AttributeDescriptor::new(1, obis, 2),
105//!     access_selection: None,
106//! };
107//! let response = GetResponse::decode(&server.dispatch(&request.encode().unwrap()).unwrap()).unwrap();
108//! assert!(matches!(response, GetResponse::Normal { .. }));
109//! ```
110//!
111//! # Standards
112//!
113//! IEC 62056-5-3 (application layer), IEC 62056-6-2 (interface classes),
114//! IEC 62056-46 / -47 (HDLC / wrapper transport), СТО 34.01-5.1-006-2023
115//! (СПОДЭС), СТО 34.01-5.1-013-2023 (СПОДУС) and Р 1323565.1 (GOST cryptography).
116#![warn(missing_docs)]
117
118/// COSEM data types and their BER (A-XDR) serialization.
119pub mod types;
120
121/// OBIS object identification codes.
122pub mod obis;
123
124/// The [`InterfaceClass`](interface::InterfaceClass) trait shared by all COSEM
125/// interface classes.
126pub mod interface;
127
128/// Implementations of the COSEM interface classes (Data, Register, Clock, …).
129pub mod classes;
130
131/// BER serialization and deserialization helpers.
132pub mod serialization;
133
134/// Transport layer: physical-medium abstraction and the HDLC and wrapper
135/// data-link sub-layers that carry xDLMS APDUs (IEC 62056-46 / IEC 62056-47).
136pub mod transport;
137
138/// Application-layer xDLMS services (GET/SET/ACTION) and association
139/// establishment (AARQ/AARE), per IEC 62056-5-3, using LN referencing.
140pub mod service;
141
142/// Security model: security suites (0/1/2), security policy (protection level)
143/// and the HLS/LLS authentication mechanisms (0..10), including the GOST profile
144/// of Р 1323565.1.
145pub mod security;
146
147/// Client-side session driver that ties the transport, service and ciphering
148/// layers into blocking GET/SET/ACTION/associate/release round trips.
149pub mod session;
150
151/// Server-side request dispatcher: routes incoming GET/SET/ACTION APDUs to the
152/// addressed COSEM object and returns the response APDU.
153pub mod server;
154
155/// СПОДУС — the ИВКЭ concentrator/gateway information model
156/// (СТО 34.01-5.1-013-2023): meter aggregation upstream and pass-through access.
157pub mod spodus;