FRBC_messages

FRBC 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 FRBC.SystemDescription FRBC.ActuatorStatus FRBC.StorageStatus FRBC.LeakageBehaviour FRBC.UsageForecast FRBC.FillLevelTargetProfile FRBC.TimerStatus RevokeObject SessionRequest	Handshake HandshakeResponse SelectControlType ReceptionStatus FRBC.Instruction RevokeObject SessionRequest	ID Duration Currency SessionRequestType RevokableObjects EnergyManagementRole ReceptionStatusValues PowerValue PowerForecastValue PowerRange NumberRange Role Transition Timer PowerForecastElement FRBC.ActuatorDescription FRBC.OperationMode FRBC.OperationModeElement FRBC.StorageDescription FRBC.LeakageBehaviourElement FRBC.UsageForecastElement FRBC.FillLevelTargetProfileElement RoleType Commodity CommodityQuantity InstructionStatus ControlType

FRBC messages

FRBC.TimerStatus

Type	Object
Sent by	RM
Description	Message for informing the CEM about a changed status of a Timer.
Preconditions	The ControlType FRBC is activated A FRBC.SystemDescription was sent (and not revoked or expired) in which the Timer was defined.
Trigger	Sent when the status of a Timer has changed. It is assumed that the initial state of the Timer is that it is not active (finished_at is in the past). If this is not the case when the ControlType is activated, a OMBC.TimerStatus message must be sent immedately after the initial OMBC.SystemDescrption message is sent after the activation fo the ControlType.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/FRBC.TimerStatus.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "FRBC.TimerStatus"
message_id	ID	yes	Identifier for this message
timer_id	ID	yes	The ID of the timer this message refers to
actuator_id	ID	yes	The ID of the actuator the timer belongs to
finished_at	date-time (string)	yes	Indicates when the Timer will be finished. If the DateTimeStamp is in the future, the timer is not yet finished. If the DateTimeStamp is in the past, the timer is finished. If the timer was never started, the value can be an arbitrary DateTimeStamp in the past.

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.

FRBC.SystemDescription

Type	Object
Sent by	RM
Description	Message informing the CEM about the structure, behaviour and contstrainst of the resource. These properties can be updated by the RM, but for many devices they are static.
Preconditions	The ControlType FRBC is activated
Trigger	Sent immediately after the ControlType is activated, or when the SystemDescription changes (can be done in advance using "valid_from"). When the device is (temporarly) not flexible, no FRBC.SystemDescription has to be sent (or the current one can be revoked).
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/FRBC.SystemDescription.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "FRBC.SystemDescription"
message_id	ID	yes	Identifier for this message
valid_from	date-time (string)	yes	Moment this FRBC.SystemDescription starts to be valid. If the system description is immediately valid, the DateTimeStamp should be now or in the past.
actuators	array of FRBC.ActuatorDescription	yes	Details of all Actuators.
storage	FRBC.StorageDescription	yes	Details of the storage.

FRBC.ActuatorStatus

Type	Object
Sent by	RM
Description	Message to inform the CEM about a change in the status of an actuator.
Preconditions	The ControlType FRBC is activated A FRBC.SystemDescription was sent (and not revoked or expired) in which the actuator was defined.
Trigger	The status of an Actuator changes. Also has te be sent immedately after a new FRBC.SystemDestription becomes active.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/FRBC.ActuatorStatus.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "FRBC.ActuatorStatus"
message_id	ID	yes	Identifier for this message
actuator_id	ID	yes	ID of the actuator this messages refers to
active_operation_mode_id	ID	yes	ID of the FRBC.OperationMode that is presently active.
operation_mode_factor	number	yes	The number indicates the factor with which the FRBC.OperationMode is configured. The factor should be greater than or equal than 0 and less or equal to 1.
previous_operation_mode_id	ID	no	ID of the FRBC.OperationMode that was active before the present one. This value shall always be provided, unless the active FRBC.OperationMode is the first FRBC.OperationMode the Resource Manager is aware of.
transition_timestamp	date-time (string)	no	Time at which the transition from the previous FRBC.OperationMode to the active FRBC.OperationMode was initiated. This value shall always be provided, unless the active FRBC.OperationMode is the first FRBC.OperationMode the Resource Manager is aware of.

FRBC.StorageStatus

Type	Object
Sent by	RM
Description	Message to inform the CEM about a change in the status of the energy storage.
Preconditions	The ControlType FRBC is activated A FRBC.SystemDescription was sent (and not revoked or expired).
Trigger	The status of the storage changes (i.e. a new fill level was measured or determined). Also has te be sent immedately after a new FRBC.SystemDestription becomes active.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/FRBC.StorageStatus.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "FRBC.StorageStatus"
message_id	ID	yes	Identifier for this message
present_fill_level	number	yes	Present fill level of the Storage

FRBC.LeakageBehaviour

Type	Object
Sent by	RM
Description	Message to inform the CEM about (a change in) the expected energy leakage behaviour of the storage.
Preconditions	The ControlType FRBC is activated A FRBC.SystemDescription was sent (and not revoked or expired) where the value of "provides_leakage_behaviour" inside the FRBC.StorageDescription was "true".
Trigger	The leakage behaviour has changed. Also has te be sent immedately after a new FRBC.SystemDestription becomes active.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/FRBC.LeakageBehaviour.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "FRBC.LeakageBehaviour"
message_id	ID	yes	Identifier for this message
valid_from	date-time (string)	yes	Moment this FRBC.LeakageBehaviour starts to be valid. If the FRBC.LeakageBehaviour is immediately valid, the DateTimeStamp should be now or in the past.
elements	array of FRBC.LeakageBehaviourElement	yes	List of elements that model the leakage behaviour of the buffer. The fill_level_ranges of the elements must be contiguous.

FRBC.Instruction

Type	Object
Sent by	CEM
Description	Instruction from the CEM to change to a certain operation mode and factor at a certain point in time.
Preconditions	The ControlType FRBC is activated A FRBC.SystemDescription was sent (and not revoked or expired) in which the actuator and operation mode was defined.
Trigger	Sent when the CEM decided to change the opertion mode (or its factor) based on its internal logic.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/FRBC.Instruction.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "FRBC.Instruction"
message_id	ID	yes	Identifier for this message
id	ID	yes	ID of the instruction. Must be unique in the scope of the Resource Manager, for at least the duration of the session between Resource Manager and CEM.
actuator_id	ID	yes	ID of the actuator this instruction belongs to.
operation_mode	ID	yes	ID of the FRBC.OperationMode that should be activated.
operation_mode_factor	number	yes	The number indicates the factor with which the FRBC.OperationMode should be configured. The factor should be greater than or equal to 0 and less or equal to 1.
execution_time	date-time (string)	yes	Indicates the moment the execution of the instruction shall start. When the specified execution time is in the past, execution must start as soon as possible.
abnormal_condition	boolean	yes	Indicates if this is an instruction during an abnormal condition.

FRBC.UsageForecast

Type	Object
Sent by	RM
Description	Message to inform the CEM about (a change in) the forecasted energy consumption from the energy storage.
Preconditions	The ControlType FRBC is activated A FRBC.SystemDescription was sent (and not revoked or expired) where the value of "provides_usage_forecast" inside the FRBC.StorageDescription was "true".
Trigger	A new usage forecast has been made by the RM.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/FRBC.UsageForecast.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "FRBC.UsageForecast"
message_id	ID	yes	Identifier for this message
start_time	date-time (string)	yes	Time at which the FRBC.UsageForecast starts.
elements	array of FRBC.UsageForecastElement	yes	Further elements that model the profile. There shall be at least one element. Elements must be placed in chronological order.

FRBC.FillLevelTargetProfile

Type	Object
Sent by	RM
Description	Message to inform the CEM that the fill level of the storage should be within a certain range at a certain point in time. The instructions of the CEM should lead to that fill level.
Preconditions	The ControlType FRBC is activated A FRBC.SystemDescription was sent (and not revoked or expired) where the value of "provides_fill_level_target_profile" inside the FRBC.StorageDescription was "true".
Trigger	A new fill level target has been determined by the RM.
JSON Schema	https://github.com/flexiblepower/s2-ws-json/blob/main/s2-json-schema/messages/FRBC.FillLevelTargetProfile.schema.json

Name	Type	Mandatory	Description
message_type	string	yes	Fixed value "FRBC.FillLevelTargetProfile"
message_id	ID	yes	Identifier for this message
start_time	date-time (string)	yes	Time at which the FRBC.FillLevelTargetProfile starts.
elements	array of FRBC.FillLevelTargetProfileElement	yes	List of different fill levels that have to be targeted within a given duration. There shall be at least one element. Elements must be placed in chronological order.

Data structures used in FRBC 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

PowerRange

Type	Object
Description	Generic datatype indicating a range of power values.

Name	Type	Mandatory	Description
start_of_range	number	yes	Power value that defines the start of the range.
end_of_range	number	yes	Power value that defines the end of the range.
commodity_quantity	CommodityQuantity	yes	The power quantity the values refer to

NumberRange

Type	Object
Description	Generic datatype indicating a range of numbers.

Name	Type	Mandatory	Description
start_of_range	number	yes	Number that defines the start of the range
end_of_range	number	yes	Number that defines the end of the range

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.

Transition

Type	Object
Description	Object describing the possibility of a resource to transition from one operation mode to another.

Name	Type	Mandatory	Description
id	ID	yes	ID of the Transition. Must be unique in the scope of the OMBC.SystemDescription, FRBC.ActuatorDescription or DDBC.ActuatorDescription in which it is used.
from	ID	yes	ID of the OperationMode (exact type differs per ControlType) that should be switched from.
to	ID	yes	ID of the OperationMode (exact type differs per ControlType) that will be switched to.
start_timers	array of ID	yes	List of IDs of Timers that will be (re)started when this transition is initiated
blocking_timers	array of ID	yes	List of IDs of Timers that block this Transition from initiating while at least one of these Timers is not yet finished
transition_costs	number	no	Absolute costs for going through this Transition in the currency as described in the ResourceManagerDetails.
transition_duration	Duration	no	Indicates the time between the initiation of this Transition, and the time at which the device behaves according to the Operation Mode which is defined in the ‘to’ data element. When no value is provided it is assumed the transition duration is negligible.
abnormal_condition_only	boolean	yes	Indicates if this Transition may only be used during an abnormal condition (see Clause )

Timer

Type	Object
Description	Object describing the static properties of a Timer. A Timer can be thought of as a countdown timer. When it is started it is active until the Duration has passed. Timers are started by Transitions, and can block Transitions while they are active. Also see TimerStatus messages.

Name	Type	Mandatory	Description
id	ID	yes	ID of the Timer. Must be unique in the scope of the OMBC.SystemDescription, FRBC.ActuatorDescription or DDBC.ActuatorDescription in which it is used.
diagnostic_label	string	no	Human readable name/description of the Timer. This element is only intended for diagnostic purposes and not for HMI applications.
duration	Duration	yes	The time it takes for the Timer to finish after it has been started

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.

FRBC.ActuatorDescription

Type	Object
Description	Part of the FRBC.SystemDescription. Describes the properties of an Actuator that can affect the energy storage.

Name	Type	Mandatory	Description
id	ID	yes	ID of the Actuator. Must be unique in the scope of the Resource Manager, for at least the duration of the session between Resource Manager and CEM.
diagnostic_label	string	no	Human readable name/description for the actuator. This element is only intended for diagnostic purposes and not for HMI applications.
supported_commodities	array of Commodity	yes	List of all supported Commodities.
operation_modes	array of FRBC.OperationMode	yes	Provided FRBC.OperationModes associated with this actuator
transitions	array of Transition	yes	Possible transitions between FRBC.OperationModes associated with this actuator.
timers	array of Timer	yes	List of Timers associated with this actuator

FRBC.OperationMode

Type	Object
Description	Part of the FRBC.ActuatorDescription. Describes a mode the actuator can be in, together with its energy consuming/producing behaviour and its effects on the energy storage.

Name	Type	Mandatory	Description
id	ID	yes	ID of the FRBC.OperationMode. Must be unique in the scope of the FRBC.ActuatorDescription in which it is used.
diagnostic_label	string	no	Human readable name/description of the FRBC.OperationMode. This element is only intended for diagnostic purposes and not for HMI applications.
elements	array of FRBC.OperationModeElement	yes	List of FRBC.OperationModeElements, which describe the properties of this FRBC.OperationMode depending on the fill_level. The fill_level_ranges of the items in the Array must be contiguous.
abnormal_condition_only	boolean	yes	Indicates if this FRBC.OperationMode may only be used during an abnormal condition

FRBC.OperationModeElement

Type	Object
Description	Part of the FRBC.OperationMode. Describes the behaviour of an operation mode for a certain range of the fill level.

Name	Type	Mandatory	Description
fill_level_range	NumberRange	yes	The range of the fill level for which this FRBC.OperationModeElement applies. The start of the NumberRange shall be smaller than the end of the NumberRange.
fill_rate	NumberRange	yes	Indicates the change in fill_level per second. The lower_boundary of the NumberRange is associated with an operation_mode_factor of 0, the upper_boundary is associated with an operation_mode_factor of 1.
power_ranges	array of PowerRange	yes	The power produced or consumed by this operation mode. The start of each PowerRange is associated with an operation_mode_factor of 0, the end is associated with an operation_mode_factor of 1. In the array there must be at least one PowerRange, and at most one PowerRange per CommodityQuantity.
running_costs	NumberRange	no	Additional costs per second (e.g. wear, services) associated with this operation mode in the currency defined by the ResourceManagerDetails, excluding the commodity cost. The range is expressing uncertainty and is not linked to the operation_mode_factor.

FRBC.StorageDescription

Type	Object
Description	Part of the FRBC.SystemDescription. Describes the energy storage.

Name	Type	Mandatory	Description
diagnostic_label	string	no	Human readable name/description of the storage (e.g. hot water buffer or battery). This element is only intended for diagnostic purposes and not for HMI applications.
fill_level_label	string	no	Human readable description of the (physical) units associated with the fill_level (e.g. degrees Celsius or percentage state of charge). This element is only intended for diagnostic purposes and not for HMI applications.
provides_leakage_behaviour	boolean	yes	Indicates whether the Storage could provide details of power leakage behaviour through the FRBC.LeakageBehaviour.
provides_fill_level_target_profile	boolean	yes	Indicates whether the Storage could provide a target profile for the fill level through the FRBC.FillLevelTargetProfile.
provides_usage_forecast	boolean	yes	Indicates whether the Storage could provide a UsageForecast through the FRBC.UsageForecast.
fill_level_range	NumberRange	yes	The range in which the fill_level should remain. It is expected of the CEM to keep the fill_level within this range. When the fill_level is not within this range, the Resource Manager can ignore instructions from the CEM (except during abnormal conditions).

FRBC.LeakageBehaviourElement

Type	Object
Description	Part of the FRBC.LeakageBehaviour. Describes the energy that leaks from the storage for a certain range of the fill level.

Name	Type	Mandatory	Description
fill_level_range	NumberRange	yes	The fill level range for which this FRBC.LeakageBehaviourElement applies. The start of the range must be less than the end of the range.
leakage_rate	number	yes	Indicates how fast the momentary fill level will decrease per second due to leakage within the given range of the fill level. A positive value indicates that the fill level decreases over time due to leakage.

FRBC.UsageForecastElement

Type	Object
Description	Part of the FRBC.UsageForecastElement. Describes the forecasted usage of the energy in the storage for a certain duration.

Name	Type	Mandatory	Description
duration	Duration	yes	Indicator for how long the given usage_rate is valid.
usage_rate_upper_limit	number	no	The upper limit of the range with a 100 % probability that the usage rate is within that range. A positive value indicates that the fill level will decrease due to usage.
usage_rate_upper_95PPR	number	no	The upper limit of the range with a 95 % probability that the usage rate is within that range. A positive value indicates that the fill level will decrease due to usage.
usage_rate_upper_68PPR	number	no	The upper limit of the range with a 68 % probability that the usage rate is within that range. A positive value indicates that the fill level will decrease due to usage.
usage_rate_expected	number	yes	The most likely value for the usage rate; the expected increase or decrease of the fill_level per second. A positive value indicates that the fill level will decrease due to usage.
usage_rate_lower_68PPR	number	no	The lower limit of the range with a 68 % probability that the usage rate is within that range. A positive value indicates that the fill level will decrease due to usage.
usage_rate_lower_95PPR	number	no	The lower limit of the range with a 95 % probability that the usage rate is within that range. A positive value indicates that the fill level will decrease due to usage.
usage_rate_lower_limit	number	no	The lower limit of the range with a 100 % probability that the usage rate is within that range. A positive value indicates that the fill level will decrease due to usage.

FRBC.FillLevelTargetProfileElement

Type	Object
Description	Part of the FRBC.FillLevelTargetProfile. Describes the desired range for the fill level for a certain duration.

Name	Type	Mandatory	Description
duration	Duration	yes	The duration of the element.
fill_level_range	NumberRange	yes	The target range in which the fill_level must be for the time period during which the element is active. The start of the range must be smaller or equal to the end of the range. The CEM must take best-effort actions to proactively achieve this target.

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.