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, on its way to becoming IEC 63402-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.
tracingStructured events from the drivers: what crossed the wire, and what was refused.
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

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.