Expand description
The S2 energy flexibility standard in Rust.
S2 — formally EN 50491-12-2, internationally IEC 63402-2-2 — is the European standard for communicating energy flexibility between a Customer Energy Manager (CEM) and a Resource Manager (RM). The RM describes how a device can behave; the CEM decides why it should. The standard’s own image is a menu: the RM writes it, the CEM orders from it, and the RM may always refuse.
This crate implements the two open specifications that make the standard usable over IP:
- S2 JSON v1.0.0 — the 36 messages and 41 component types, their encoding, and the protocol around them: control-type selection, reception statuses, revocation, validity windows, timers and instruction lifecycles.
- S2 Connect 1.0.0 — DNS-SD discovery, HMAC challenge–response pairing, access-token session initiation, the WebSocket transport and the reconnection rules.
§Where to start
| You are building | Start at |
|---|---|
| A device that offers flexibility | session::RmSession |
| An energy manager that uses it | session::CemSession |
| A proxy, analyzer or log reader | session::Analyzer |
| Two devices that must find and trust each other | connect |
| Something over a transport that is not WebSocket | session, and drive it yourself |
Longer guides, the full rule catalogue and the conformance statement are at https://hupe1980.github.io/s2-kit.
use s2_kit::prelude::*;
let details = ResourceManagerDetails::builder()
.resource_id(Id::parse("battery-1")?)
.roles(vec![Role { role: RoleType::EnergyStorage, commodity: Commodity::Electricity }])
.instruction_processing_delay(Duration::from_millis(500))
.available_control_types(vec![ControlType::FillRateBasedControl])
.provides_forecast(false)
.provides_power_measurement_types(vec![CommodityQuantity::ElectricPower3PhaseSymmetric])
.build();
let mut rm = RmSession::new(RmConfig::default(), details);
rm.open(Timestamp::now());
// Everything the session wants to say is waiting here; a driver writes it to a socket.
let first = rm.poll_transmit().expect("the RM speaks first");
assert!(first.text.contains(r#""message_type":"Handshake""#));§Design in one paragraph
The protocol core is sans-I/O: no sockets, no clock, no tasks. Every engine takes
now as a parameter and is driven by handle_* / poll_*, so a two-hour timer, a
lost acknowledgement and a revoked constraint are all ordinary unit tests. Drivers —
WebSocket, HTTPS, mDNS — are Cargo features that hang off the side. The data model is
hand-written and proven against the standard’s own JSON schemas in CI rather than
generated from a modified copy of them, and the layer above it is a
rule-numbered semantic validator for everything JSON Schema cannot express.
§Features
| Feature | Enables |
|---|---|
std (default) | The standard library. Without it the crate is no_std + alloc. |
uuid (default) | Id::generate and friends. |
tokio | io::Driver, which pumps a session over any text transport. |
connect-client | Pairing and session initiation, with leaf-fingerprint capture and CA pinning. |
connect-server | An axum router for both APIs and the authorised WebSocket, TLS serving, a self-signed CA helper. |
discovery | DNS-SD advertise and browse of _s2connect._tcp. |
tls-ring (default) | ring as the bundled TLS cryptography; no cmake to cross-compile. |
tls-aws-lc-rs | aws-lc-rs instead: FIPS-certifiable, post-quantum. Exactly one is linked. |
jiff / time / chrono | Timestamp conversions, with the crate re-exported. |
testing | Fixtures, the two-engine harness, the in-memory pipe, and .s2log transcripts read as well as written. |
schemars | JsonSchema for this crate’s own types, for the equivalence check. |
tracing | A span per session and an event per message from the drivers, keyed by message_id; never a payload. |
cli | The s2-kit command-line tool. |
Re-exports§
pub use codec::DecodeError;pub use codec::DecodeOptions;pub use codec::Strictness;pub use codec::decode;pub use codec::decode_with;pub use codec::encode;pub use message::Message;pub use message::MessageKind;pub use types::Duration;pub use types::Id;pub use types::ProtocolVersion;pub use types::Timestamp;pub use types::WireProfile;pub use chrono;chronopub use jiff;jiffpub use time;timepub use uuid;uuidpub use tokio;tokiopub use tokio_tungstenite;tokiopub use rustls;tokiopub use axum;connect-serverpub use mdns_sd;discovery
Modules§
- codec
- Turning bytes into
Messages, and back. - connect
- S2 Connect: discovery, pairing, session initiation and the transport.
- io
tokio - Driving a session over a real transport.
- message
Message— every S2 message, in one enum.- model
- The virtual device: what an instruction actually means.
- prelude
- Everything a typical Resource Manager or Customer Energy Manager needs.
- schema
- The shape of S2 JSON, as data.
- session
- Sans-I/O session engines for both roles.
- testing
testing - A harness for driving both engines against each other, on a virtual clock.
- types
- The S2 JSON data model: 36 messages and 41 component types.
- validate
- The semantic validator: everything JSON Schema cannot say.