Common_messages

Common message reference

Version: 0.0.2-beta

Overview

Messages sent by RM	Messages sent by CEM	Data structures used in messages
Handshake PowerMeasurement ReceptionStatus InstructionStatusUpdate PowerForecast ResourceManagerDetails RevokeObject SessionRequest	Handshake HandshakeResponse SelectControlType ReceptionStatus RevokeObject SessionRequest	ID Duration Currency SessionRequestType RevokableObjects EnergyManagementRole ReceptionStatusValues PowerValue PowerForecastValue Role PowerForecastElement RoleType Commodity CommodityQuantity InstructionStatus ControlType

Common messages

SelectControlType

Type	Object
Sent by	CEM
Description	Instruction from the CEM to activate the indicated ControlType.
Preconditions	Session status is "Initialized"
Trigger	CEM decides which ControlType it wants to use to control the resource. Usually it is sent immediately after receiving the ResourceManagerDetails.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/SelectControlType.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "SelectControlType"
message_id	ID	yes	Identifier for this message
control_type	ControlType	yes	The ControlType to activate. Must be one of the available ControlTypes as defined in the ResourceManagerDetails

SessionRequest

Type	Object
Sent by	RM and CEM
Description	Request to the other endpoint to restart or to terminate the WebSockes session
Preconditions	Session status is "Initialized" or a ControlType is activated
Trigger	One of the endpoints shuts down or an error has occured (also see ReceptionStatusValues).
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/SessionRequest.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "SessionRequest"
message_id	ID	yes	Identifier for this message
request	SessionRequestType	yes	The type of request
diagnostic_label	string	no	Optional field for a human readible descirption for debugging purposes

RevokeObject

Type	Object
Sent by	RM and CEM
Description	Message to indicate that a previously sent message is no longer valid and should be forgotten
Preconditions	A ControlType is activated Message from "object_type" with "object_id" was sent earlier
Trigger	The message that is being revoked is no longer valid. For example, when a resource is no longer flexible a SystemDescription message can be revoked.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/RevokeObject.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "RevokeObject"
message_id	ID	yes	Identifier for this message
object_type	RevokableObjects	yes	The type of object that needs to be revoked
object_id	ID	yes	The ID of object that needs to be revoked

Handshake

Type	Object
Sent by	RM and CEM
Description	Initial message sent by both parties used to agree on the roles (CEM and RM) and the version of the protocol used
Preconditions	Session status is "WebSocket connected"
Trigger	The WebSocket has been connected
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/Handshake.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "Handshake"
message_id	ID	yes	Identifier for this message
role	EnergyManagementRole	yes	The role of the sender of this message
supported_protocol_versions	array of string	no	Protocol versions supported by the sender of this message. This field is mandatory for the RM, but optional for the CEM.

HandshakeResponse

Type	Object
Sent by	CEM
Description	Response from the CEM to the Handshake message to confirm the version of the protocol used
Preconditions	Session status is "WebSocket connected" RM has sent a Handshake
Trigger	Immedately sent after a Handshake has been received
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/HandshakeResponse.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "HandshakeResponse"
message_id	ID	yes	Identifier for this message
selected_protocol_version	string	yes	The protocol version the CEM selected for this session

ResourceManagerDetails

Type	Object
Sent by	RM
Description	Message in which the CEM is informed about static properties of the resource
Preconditions	Session status is "Initialized"
Trigger	Sent immediately by the RM after the session has been initialized.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/ResourceManagerDetails.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "ResourceManagerDetails"
message_id	ID	yes	Identifier for this message
resource_id	ID	yes	Identifier of the Resource Manager. Must be unique within the scope of the CEM.
name	string	no	Human readable name given by user
roles	array of Role	yes	Each Resource Manager provides one or more energy Roles
manufacturer	string	no	Name of Manufacturer
model	string	no	Name of the model of the device (provided by the manufacturer)
serial_number	string	no	Serial number of the device (provided by the manufacturer)
firmware_version	string	no	Version identifier of the firmware used in the device (provided by the manufacturer)
instruction_processing_delay	Duration	yes	The average time the combination of Resource Manager and HBES/BACS/SASS or (Smart) device needs to process and execute an instruction
available_control_types	array of ControlType	yes	The control types supported by this Resource Manager.
currency	Currency	no	Currency to be used for all information regarding costs. Mandatory if cost information is published.
provides_forecast	boolean	yes	Indicates whether the ResourceManager is able to provide PowerForecasts
provides_power_measurement_types	array of CommodityQuantity	yes	Array of all CommodityQuantities that this Resource Manager can provide measurements for.

PowerMeasurement

Type	Object
Sent by	RM
Description	Message to inform the CEM about new values of the power exchanged between the resource and the grid
Preconditions	Session status is "Initialized" or a ControlType is activated ResourceManagerDetails was sent to CEM The array "provides_power_measurement_types" in the ResourceManagerDetails message was not empty
Trigger	Sent when the power value has changed significantely (what a significant change is is determined by the RM). Can also be sent immedately after the session has been initialized, or when the RM receives its first measurement from the device or sensor.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/PowerMeasurement.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "PowerMeasurement"
message_id	ID	yes	Identifier for this message
measurement_timestamp	date-time (string)	yes	Timestamp when PowerValues were measured.
values	array of PowerValue	yes	Array of measured PowerValues. Must contain at least one item and at most one item per ‘commodity_quantity’ (defined inside the PowerValue).

ReceptionStatus

Type	Object
Sent by	RM and CEM
Description	Message to inform the other endpoint if a messages was received and processed successfully
Preconditions	A message with message_id "subject_message_id" was sent by the other endpoint
Trigger	Sent immediatly when a message has been received and processed
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/ReceptionStatus.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "ReceptionStatus"
message_id	ID	yes	Identifier for this message
subject_message_id	ID	yes	The message this ReceptionStatus refers to
status	ReceptionStatusValues	yes	Enumeration of status values
diagnostic_label	string	no	Diagnostic label that can be used to provide additional information for debugging. However, not for HMI purposes.

InstructionStatusUpdate

Type	Object
Sent by	RM
Description	Message to inform the CEM about the status of an instruction that is being processed by the RM
Preconditions	A ControlType is activated An instruction message with id "instruction" id was sent by the CEM
Trigger	Sent immediatly by the RM when the status of an instruction has changed (see InstructionStatus).
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/InstructionStatusUpdate.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "InstructionStatusUpdate"
message_id	ID	yes	Identifier for this message
instruction_id	ID	yes	ID of this instruction (as provided by the CEM)
status_type	InstructionStatus	yes	Present status of this instruction.
timestamp	date-time (string)	yes	Timestamp when status_type has changed the last time.

PowerForecast

Type	Object
Sent by	RM
Description	Message to inform the CEM about the forecast power exchange between the device and the grid
Preconditions	Session status is "Initialized" or a ControlType is activated ResourceManagerDetails was sent to CEM The value of "provides_forecast" in the ResourceManagerDetails was "true"
Trigger	Sent when a new forecast has been created. Can also be sent immediately after the session has been initialized or when the first forecast has been created
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/PowerForecast.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "PowerForecast"
message_id	ID	yes	Identifier for this message
start_time	date-time (string)	yes	Start time of time period that is covered by the profile.
elements	array of PowerForecastElement	yes	Elements of which this forecast consists. Contains at least one element. Elements must be placed in chronological order.

Data structures used in Common messages

ID

Type	string with pattern "[a-zA-Z0-9\\-_:]{2,64}"
Description	Unique identifier (UUID) for certain objects and messages
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/schemas/ID.schema.json

Duration

Type	integer (>= 0)
Description	Duration described in milliseconds
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/schemas/Duration.schema.json

Currency

Type	string
Description	Financial currency described as a three letter code (in capitals) according to ISO 4217
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/schemas/Currency.schema.json

SessionRequestType

Type	Enumeration
Description	Types of requests an endpoint can make regarding termiantion of the session.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/schemas/SessionRequestType.schema.json

Value	Description
RECONNECT	Please reconnect the WebSocket session. Once reconnected, it starts from scratch with a handshake.
TERMINATE	Disconnect the session (client can try to reconnecting with exponential backoff)

RevokableObjects

Type	Enumeration
Description	Enumeration containing all the types of objects/messages that can be revoked.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/schemas/RevokableObjects.schema.json

Value	Description
PEBC.PowerConstraints	Object type PEBC.PowerConstraints
PEBC.EnergyConstraint	Object type PEBC.EnergyConstraint
PEBC.Instruction	Object type PEBC.Instruction
PPBC.PowerProfileDefinition	Object type PPBC.PowerProfileDefinition
PPBC.ScheduleInstruction	Object type PPBC.ScheduleInstruction
PPBC.StartInterruptionInstruction	Object type PPBC.StartInterruptionInstruction
PPBC.EndInterruptionInstruction	Object type PPBC.EndInterruptionInstruction
OMBC.SystemDescription	Object type OMBC.SystemDescription
OMBC.Instruction	Object type OMBC.Instruction
FRBC.SystemDescription	Object type FRBC.SystemDescription
FRBC.Instruction	Object type FRBC.Instruction
DDBC.SystemDescription	Object type DDBC.SystemDescription
DDBC.Instruction	Object type DDBC.Instruction

EnergyManagementRole

Type	Enumeration
Description	Enumeration for the types of endpoints for an S2 session.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/schemas/EnergyManagementRole.schema.json

Value	Description
CEM	Customer Energy Manager
RM	Resource Manager

ReceptionStatusValues

Type	Enumeration
Description	Enumeration containing all the possible ways a message could have been received by an S2 endpoint.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/schemas/ReceptionStatusValues.schema.json

Value	Description
INVALID_DATA	Message not understood (e.g. not valid JSON, no message_id found). Consequence: Message is ignored, proceed if possible
INVALID_MESSAGE	Message was not according to schema. Consequence: Message is ignored, proceed if possible
INVALID_CONTENT	Message contents is invalid (e.g. contains a non-existing ID). Somewhat equivalent to BAD_REQUEST in HTTP.. Consequence: Message is ignored, proceed if possible.
TEMPORARY_ERROR	Receiver encountered an error. Consequence: Try to send to message again
PERMANENT_ERROR	Receiver encountered an error which it cannot recover from. Consequence: Disconnect.
OK	Message processed normally. Consequence: Proceed normally.

PowerValue

Type	Object
Description	Describes the amount of power exchanged between the resource and the grid, according to the defined CommodityQuantity. A positive value indicates energy being delivered from the grid to the resource. A negative value indicates energy being delivered from the resourcce to the grid.

Name	Type	Mandatory	Description
commodity_quantity	CommodityQuantity	yes	The power quantity the value refers to
value	number	yes	Power value expressed in the unit associated with the CommodityQuantity

PowerForecastValue

Type	Object
Description	Described a forecasted amount of energy being exchanged between resource and the grid, according to the defined CommodityQuantity. When a value_lower_limit is provided, a value_upper limit must also be provided and vice versa. When one of the numbered PPR fields is provided, all of them need to be provided.

Name	Type	Mandatory	Description
value_upper_limit	number	no	The upper boundary of the range with 100 % certainty the power value is in it
value_upper_95PPR	number	no	The upper boundary of the range with 95 % certainty the power value is in it
value_upper_68PPR	number	no	The upper boundary of the range with 68 % certainty the power value is in it
value_expected	number	yes	The expected power value.
value_lower_68PPR	number	no	The lower boundary of the range with 68 % certainty the power value is in it
value_lower_95PPR	number	no	The lower boundary of the range with 95 % certainty the power value is in it
value_lower_limit	number	no	The lower boundary of the range with 100 % certainty the power value is in it
commodity_quantity	CommodityQuantity	yes	The power quantity the value refers to

Role

Type	Object
Description	Describes the role of a resource with respect to a commodity

Name	Type	Mandatory	Description
role	RoleType	yes	Role type of the Resource Manager for the given commodity
commodity	Commodity	yes	Commodity the role refers to.

PowerForecastElement

Type	Object
Description	Part of a PowerForecast. Describes the PowerForecastValue for a certian Duration.

Name	Type	Mandatory	Description
duration	Duration	yes	Duration of the PowerForecastElement
power_values	array of PowerForecastValue	yes	The values of power that are expected for the given period of time. There shall be at least one PowerForecastValue, and at most one PowerForecastValue per CommodityQuantity.

RoleType

Type	Enumeration
Description	Describes the three roles a resource can have for a certain Commodity.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/schemas/RoleType.schema.json

Value	Description
ENERGY_PRODUCER	Identifier for RoleType Producer
ENERGY_CONSUMER	Identifier for RoleType Consumer
ENERGY_STORAGE	Identifier for RoleType Storage

Commodity

Type	Enumeration
Description	Describes the four types of energy a resource can potentially exchange with a grid (i.e. an energy infrastructure).
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/schemas/Commodity.schema.json

Value	Description
GAS	Identifier for Commodity GAS
HEAT	Identifier for Commodity HEAT
ELECTRICITY	Identifier for Commodity ELECTRICITY
OIL	Identifier for Commodity OIL

CommodityQuantity

Type	Enumeration
Description	Describes types of energy a resource can exchange with a grid. A CommodityQuantity is the combination of a type of energy and the associated unit used in S2.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/schemas/CommodityQuantity.schema.json

Value	Description
ELECTRIC.POWER.L1	Electric power described in Watt on phase 1. If a device utilizes only one phase it should always use L1.
ELECTRIC.POWER.L2	Electric power described in Watt on phase 2. Only applicable for 3 phase devices.
ELECTRIC.POWER.L3	Electric power described in Watt on phase 3. Only applicable for 3 phase devices.
ELECTRIC.POWER.3_PHASE_SYMMETRIC	Electric power described in Watt on when power is equally shared among the three phases. Only applicable for 3 phase devices.
NATURAL_GAS.FLOW_RATE	Gas flow rate described in liters per second
HYDROGEN.FLOW_RATE	Gas flow rate described in grams per second
HEAT.TEMPERATURE	Heat described in degrees Celsius
HEAT.FLOW_RATE	Flow rate of heat carrying gas or liquid in liters per second
HEAT.THERMAL_POWER	Thermal power in Watt
OIL.FLOW_RATE	Oil flow rate described in liters per hour

InstructionStatus

Type	Enumeration
Description	The status types an instruction can have at a certain point in time
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/schemas/InstructionStatus.schema.json

Value	Description
NEW	Instruction was newly created
ACCEPTED	Instruction has been accepted
REJECTED	Instruction was rejected
REVOKED	Instruction was revoked
STARTED	Instruction was executed
SUCCEEDED	Instruction finished successfully
ABORTED	Instruction was aborted.

ControlType

Type	Enumeration
Description	A enumeration for ControlTypes used in S2. Additionally, there is a value for indicating the resource doesn't support any ControlType at all, as well as a value to indicate that no ControlType is currently active.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/schemas/ControlType.schema.json

Value	Description
POWER_ENVELOPE_BASED_CONTROL	Identifier for the Power Envelope Based Control type
POWER_PROFILE_BASED_CONTROL	Identifier for the Power Profile Based Control type
OPERATION_MODE_BASED_CONTROL	Identifier for the Operation Mode Based Control type
FILL_RATE_BASED_CONTROL	Identifier for the Demand Driven Based Control type
DEMAND_DRIVEN_BASED_CONTROL	Identifier for the Fill Rate Based Control type
NOT_CONTROLABLE	Identifier that is to be used if no control is possible. Resources of this type can still provide measurements and forecast
NO_SELECTION	Identifier that is to be used if no control type is or has been selected.