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