hems_flex/lib.rs
1//! The household's flexibility, in the language Europe agreed on.
2//!
3//! [S2](https://s2standard.org) — **EN 50491-12-2** — is the interface between a
4//! Customer Energy Manager and the Resource Managers in a building. Its central
5//! idea is worth stating plainly, because it is what makes it different from
6//! every protocol that came before:
7//!
8//! > A device describes **what it can do**, not what it is for.
9//!
10//! A battery, a hot water tank and a parked car are all *storage with a fill
11//! level*. Once they say so in the same words, an energy manager can plan all
12//! three without knowing what any of them is — and a device that arrives next
13//! year works without a driver being written for it. EEBUS, by contrast,
14//! organises around named use cases, which is why it needs a new one for each
15//! new thing a device might want to do.
16//!
17//! hems plans in S2's terms internally and speaks EEBUS where the German grid
18//! requires it. This crate is the first half: which control type each asset
19//! belongs to, the description a Customer Energy Manager would be sent, and the
20//! translation of an instruction back into something [`hems_device`] can issue.
21//!
22//! The wire types are [`s2energy`], generated from the official schema by the
23//! standard's own authors. Writing our own would be a second opinion about a
24//! wire format, which is the one thing a standard exists to prevent.
25//!
26//! # The five control types
27//!
28//! | Control type | For | Example |
29//! |---|---|---|
30//! | **FRBC** Fill Rate Based Control | anything with a fill level and a rate | battery, hot water tank, the building's own thermal mass |
31//! | **PEBC** Power Envelope Based Control | anything that just needs a bound | charge point, inverter curtailment |
32//! | **OMBC** Operation Mode Based Control | discrete states | SG Ready heat pump, a two-speed pump |
33//! | **PPBC** Power Profile Based Control | a fixed sequence started in a window | washing machine, dishwasher |
34//! | **DDBC** Demand Driven Based Control | actuators serving a reported demand | a heat pump following a heat demand |
35
36#![forbid(unsafe_code)]
37#![warn(missing_docs, clippy::pedantic)]
38#![allow(
39 clippy::module_name_repetitions,
40 clippy::must_use_candidate,
41 clippy::doc_markdown
42)]
43
44pub mod describe;
45pub mod instruct;
46pub mod map;
47
48pub use describe::{
49 BatteryDescription, HeatPumpDescription, describe_battery, describe_evse, describe_heat_pump,
50 describe_pv, resource_manager_details,
51};
52pub use instruct::{InstructError, battery_power, envelope_command, envelope_now, heat_pump_state};
53pub use map::{ControlType, control_type_for, roles_for};