Skip to main content

Crate s2_kit

Crate s2_kit 

Source
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 buildingStart at
A device that offers flexibilitysession::RmSession
An energy manager that uses itsession::CemSession
A proxy, analyzer or log readersession::Analyzer
Two devices that must find and trust each otherconnect
Something over a transport that is not WebSocketsession, 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

FeatureEnables
std (default)The standard library. Without it the crate is no_std + alloc.
uuid (default)Id::generate and friends.
tokioio::Driver, which pumps a session over any text transport.
connect-clientPairing and session initiation, with leaf-fingerprint capture and CA pinning.
connect-serverAn axum router for both APIs and the authorised WebSocket, TLS serving, a self-signed CA helper.
discoveryDNS-SD advertise and browse of _s2connect._tcp.
tls-ring (default)ring as the bundled TLS cryptography; no cmake to cross-compile.
tls-aws-lc-rsaws-lc-rs instead: FIPS-certifiable, post-quantum. Exactly one is linked.
jiff / time / chronoTimestamp conversions, with the crate re-exported.
testingFixtures, the two-engine harness, the in-memory pipe, and .s2log transcripts read as well as written.
schemarsJsonSchema for this crate’s own types, for the equivalence check.
tracingA span per session and an event per message from the drivers, keyed by message_id; never a payload.
cliThe 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;chrono
pub use jiff;jiff
pub use time;time
pub use uuid;uuid
pub use tokio;tokio
pub use tokio_tungstenite;tokio
pub use rustls;tokio
pub use axum;connect-server
pub use mdns_sd;discovery

Modules§

codec
Turning bytes into Messages, and back.
connect
S2 Connect: discovery, pairing, session initiation and the transport.
iotokio
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.
testingtesting
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.