Crate s2energy 

This crate provides type definitions and utilities for working with the S2 energy flexibility standard. S2 is a communication standard for energy flexibility and energy management in homes and buildings, designed to simplify the use of energy flexibility of smart devices. To learn more about the S2 standard:

• Read the documentation for a detailed explanation of S2
• Visit the website for a high-level explanation of S2
• Read the whitepaper to learn why it’s important to expose and utilise energy flexibility

Crate contents

This crate provides Rust types for all types specified by S2. It also includes provides utilities in the connection and transport modules that help you set up S2 connections.

JSON over WebSockets is a common and recommended way to implement S2, but you’re free to choose a different format and communication protocol. In that case, the types in this crate should still be useful but you may wish to disable the websockets-json feature.

Using this crate

When implementing S2, you need to have a clear picture of which control types you want to implement. If you’re not sure which control type you’re implementing, see the documentation website for an overview of the available control types.

S2 types common to all control types (such as PowerValue and Commodity) are in the common module. The types specific to control types (such as FRBC.ActuatorStatus or PEBC.PowerConstraints) are divided into modules based on the control type they belong to.

Creating S2 types

S2 types have all their fields exposed, so you can construct them using regular Rust constructor syntax:

use s2energy::{common::NumberRange, frbc::ActuatorStatus};

let range = NumberRange {
    start_of_range: 1.0,
    end_of_range: 30.5,
};

let actuator_status = ActuatorStatus::builder()
    .active_operation_mode_id(operation_mode_id)
    .actuator_id(actuator_id)
    .operation_mode_factor(0.7)
    .build();

Most S2 types have an automatically generated builder (such as ActuatorStatus::builder in the above example), so you can use those to create an actuator status as a more convenient alternative to the regular object initialization syntax. S2 types with only one field have a new function to easily create them.

Working with Message

When sending or receiving S2 messages, you’ll be working with common::Message. This type represents all possible S2 messages in a big enum. When receiving messages, you’ll want to match on Message to determine how to handle it:

match incoming_message {
    Message::FrbcSystemDescription(system_description) => { /* Handle it */ },
    Message::FrbcStorageStatus(storage_status) => { /* Handle it */ },
    _ => { /* Ignore other messages */ }
}

All types that serve as the content of a message (such as frbc::SystemDescription and frbc::StorageStatus in the above example) implement Into<Message> for convenience. This means you can do:

let storage_status = StorageStatus::new(2.1);
let message: Message = storage_status.into();

Connection::send_message accepts an impl Into<Message>, so you can just give it any compatible type and it will work.

Sending/receiving S2 messages

S2 does not specify a particular transport protocol for S2 messages. As a result, many transport protocols can be used: WebSockets, MQTT, even D-Bus. To facilitate the use of different transport protocols, this crates provides a central abstraction in connection::S2Connection and transport::S2Transport. An S2Connection can use any transport protocol implementing the S2Transport trait.

This crate provides some transport implementations for end-users. Currently, only a WebSockets implementation is provided (in transport::websockets_json). D-Bus support is also planned for the near future.

Crate features

The crate currently has these features:

• websockets-json (enabled by default): enables WebSocket support with the transport::websockets_json module.

Reading this documentation

Part of this documentation is automatically generated by extracting descriptions from the S2 specification. Specifically, the S2 type definitions in common and the control type specific modules are all generated, and their documentation can be spotty. The language-agnostic documentation for the S2 standard is often more helpful and complete.

Module documentation (for all modules) and documentation for other types (like those in connection or transport) is hand-written and generally of a higher standard. It assumes that you are familiar with the S2 standard; if this is not the case, it may be useful to refer to the S2 documentation website.

Modules

common

Types common to all S2 control types.

connection

Types and utilities for S2 connections.

ddbc

Types specific to the Demand Driven Based Control type.

error

Error types.

frbc

Types specific to the Fill Rate Based Control type.

ombc

Types specific to the Operation Mode Based Control type.

pebc

Types specific to the Power Envelope Based Control type.

ppbc

Types specific to the Power Profile Based Control type.

transport

Abstractions over transport protocols, and their implementations.

Functions

s2_schema_version

Returns the version of S2 this library was built with.