diff --git a/website/docs/examples/ev.md b/website/docs/examples/ev.md index 58f93a7..abe77f3 100644 --- a/website/docs/examples/ev.md +++ b/website/docs/examples/ev.md @@ -66,7 +66,6 @@ The following sequence diagram is an example of what a message exchange between ![cem_rm_interactions](https://www.plantuml.com/plantuml/png/VP7DJiCm3CVlUOey0F007D1W0x539TI2E9lKWcYf7MndQ3mzeI0HMCNLF_y_BA_KGAnCoH4RUjwZ-FLrT-Bxxjm_ujF0OOVc0nDXC1oTgzIVNipy5cZK5zYXw-TPHUrmQRD7pKoARYblIz4YfFXUSrhBAk8Y0JiWU4RPe45CsleFc33Ocic4q_qXB_itt4Emk0VxatJJNwtFXeCQJXlK835RP78kCMSVoHFx368nb0JYMKQKLdx7RoWTWXR12ScElI-35J2MmS2A7aTNL4_yfks5CzwIcfGmTsgapVXB-P17C7H8e_zi_gl6WAfriSVNWchk_x-FKNzUlwf-PKeV)
- Image generated using the following PlantUML code: ``` @@ -111,7 +110,7 @@ The CEM informs the RM that it is a CEM and which versions of s2-ws-json it supp ```json { "message_type": "Handshake", - "message_id": "xxx", + "message_id": "eab48b05-99be-4c34-899d-30edaf5626db", "role": "CEM", "supported_protocol_versions": [ "0.0.2-beta" @@ -124,7 +123,7 @@ The RM informs the CEM that it is a RM and which versions of s2-ws-json it suppo ```json { "message_type": "Handshake", - "message_id": "xxx", + "message_id": "ea2e0f4f-5294-4578-a050-73fdd6110eec", "role": "RM", "supported_protocol_versions": [ "0.0.2-beta" @@ -137,7 +136,7 @@ The CEM informs the RM which version of s2-ws-json it has selected for this sess ```json { "message_type": "HandshakeResponse", - "message_id": "xxx", + "message_id": "04f2d3a7-f018-46d5-b769-c62393e02804", "selected_protocol_version": "0.0.2-beta" } ``` @@ -155,7 +154,7 @@ The RM informs the CEM about several static properties of the EV: ```json { "message_type": "ResourceManagerDetails", - "message_id": "xxx", + "message_id": "0c41efc2-771d-468f-afdc-fb69255dad33", "resource_id": "acme_ev_xxxxxx", "name": "My Electric Vehicle RM", "roles": [ @@ -184,7 +183,7 @@ The CEM informs the RM that it wants to use FRBC ControlType (the RM defined in ```json { "message_type": "SelectControlType", - "message_id": "xxx", + "message_id": "fe9f4f07-c731-4f91-8801-3b53a9fecaaf", "control_type": "FILL_RATE_BASED_CONTROL" } ``` @@ -304,7 +303,7 @@ And finally, putting everything together in one message: ```json { "message_type": "FRBC.SystemDescription", - "message_id": "xxx", + "message_id": "0c84b415-4e5e-429c-b5b6-116a5de6bfbf", "valid_from": "2019-08-24T14:15:22Z", "actuators": [ { @@ -407,7 +406,7 @@ Below is given an example of a power measurement message: ```json { "message_type": "PowerMeasurement", - "message_id": "xxx", + "message_id": "72355bab-e58e-47c7-bada-acf0dc893218", "measurement_timestamp": "2019-08-24T14:15:22Z", "values": [ { @@ -423,7 +422,7 @@ In S2, the RM is in charge of the control of a device. It receives instructions ```json { "message_type": "FRBC.ActuatorStatus", - "message_id": "xxx", + "message_id": "f0e229b3-ebbf-4ba2-829c-4e2f854a1d1d", "actuator_id": "actuator1", "active_operation_mode_id": "string", "operation_mode_factor": 0, @@ -448,7 +447,7 @@ After the CEM has determined how to use the energy flexibility provided by the R ```json { "message_type": "FRBC.Instruction", - "message_id": "xxx", + "message_id": "5bc49243-edee-4884-99b3-65a62766949c", "id": "instruction1", "actuator_id": "actuator1", "operation_mode": "om1", @@ -463,7 +462,7 @@ After the RM has received an instruction, it handles it internally. To inform th ```json { "message_type": "InstructionStatusUpdate", - "message_id": "xxx", + "message_id": "84522a12-7960-48b1-abf3-b7694dac80e6", "instruction_id": "instruction1", "status_type": "NEW", "timestamp": "2019-08-24T14:15:22Z" @@ -475,7 +474,7 @@ When the RM or CEM wants close the current connection and possibly initiate a ne ```json { "message_type": "SessionRequest", - "message_id": "xxx", + "message_id": "4f93f58f-0d6c-44b5-b35a-bf6dcb845c5f", "request": "RECONNECT", "diagnostic_label": "string" } diff --git a/website/docs/examples/heat-pump.md b/website/docs/examples/heat-pump.md index 74ddb87..b763d93 100644 --- a/website/docs/examples/heat-pump.md +++ b/website/docs/examples/heat-pump.md @@ -107,7 +107,7 @@ The CEM informs the RM that it is a CEM and which versions of s2-ws-json it supp ```json { "message_type": "Handshake", - "message_id": "xxx", + "message_id": "4834583e-5d8a-4fb2-a955-c99fc4583b7a", "role": "CEM", "supported_protocol_versions": [ "0.0.2-beta" @@ -120,7 +120,7 @@ The RM informs the CEM that it is a RM and which versions of s2-ws-json it suppo ```json { "message_type": "Handshake", - "message_id": "xxx", + "message_id": "164deb3f-952f-42d4-bebb-4666e8baa62e", "role": "RM", "supported_protocol_versions": [ "0.0.2-beta" @@ -133,7 +133,7 @@ The CEM informs the RM which version of s2-ws-json it has selected for this sess ```json { "message_type": "HandshakeResponse", - "message_id": "xxx", + "message_id": "7fd890a4-766e-4c66-9859-470daec3cdf9", "selected_protocol_version": "0.0.2-beta" } ``` @@ -151,7 +151,7 @@ The RM informs the CEM about several static properties of the RM/heat pump: ```json { "message_type": "ResourceManagerDetails", - "message_id": "xxx", + "message_id": "a348da35-eb0c-456c-9099-cdcc22e030a0", "resource_id": "acme_heat_pump", "name": "my_heat_pump", "roles": [ @@ -180,7 +180,7 @@ The CEM informs the RM that it wants to use FRBC ControlType (the RM defined in ```json { "message_type": "SelectControlType", - "message_id": "xxx", + "message_id": "b44a8e22-ede6-4b1d-908f-72dd45c69106", "control_type": "FILL_RATE_BASED_CONTROL" } ``` @@ -208,14 +208,133 @@ For debugging purposes (so for humans, not for algorithms) a label is provided f Secondly we'll define the heat pump itself. In FRBC this is referred to as an actuator. An actuator is something that the CEM can control, affects the fill level of the storage and exchanges power with the power grid (in our case, consuming electricity). -TODO +An actuator consists of operation modes, transitions (between operation modes) and timers (associated with transitions). An operation mode is defined for a fill_level_range. This allows for modeling non-linear behavior of the actuator. Furthermore, the operation mode contains a fill_rate which expresses how much the fill level changes in that operation mode, at a certain power consumption, which is defined in the power_range. This is used to model the relation between the actuator's consumed power and the effect on the fill level. + +The actuator also defines the possible transitions between operation modes. Finally, it contains timers that can be used to model temporal prohibition of operation mode transitions. + +Our heat pump has two operation modes. One for a heat pump that is idle and one for a running heat pump. + +The operation mode 'running' is the most interesting. We have heat pump with a minimum operation power of 500 W and a maximum of 2000 W, and a fixed COP of 3.5 With a delta T of 10 degrees Celsius and a buffer that contain 200 L of water, the total energy to store is: 8380000 J. This means that the fill_rate at minimum power is: 10\*500\*3.5/8380000=0.00209 and at maximum power: 10\*2000\*3.5/8380000=0.00835. This means that the CEM has control over de modulation of the heat pump between its minimum and maximum power. + +It is possible in S2 to associate cost to an operation mode or transition (for example to account for tear and wear associated with running or starting an appliance) but that does not apply to our simple heat pump model. + +So, the actuator of our example heat pump looks as follows: +```json +{ + "id": "actuator1", + "diagnostic_label": "heat pump", + "supported_commodities": [ + "ELECTRICITY" + ], + "operation_modes": [ + { + "id": "om0", + "diagnostic_label": "running", + "elements": [ + { + "fill_level_range": { + "start_of_range": 45, + "end_of_range": 55 + }, + "fill_rate": { + "start_of_range": 0.00209, + "end_of_range": 0.00835 + }, + "power_ranges": [ + { + "start_of_range": 500, + "end_of_range": 2000, + "commodity_quantity": "ELECTRIC.POWER.L1" + } + ], + "running_costs": { + "start_of_range": 0, + "end_of_range": 0 + } + } + ], + "abnormal_condition_only": false + }, + { + "id": "om1", + "diagnostic_label": "Off", + "elements": [ + { + "fill_level_range": { + "start_of_range": 45, + "end_of_range": 55 + }, + "fill_rate": { + "start_of_range": 0, + "end_of_range": 0 + }, + "power_ranges": [ + { + "start_of_range": 0, + "end_of_range": 0, + "commodity_quantity": "ELECTRIC.POWER.L1" + } + ], + "running_costs": { + "start_of_range": 0, + "end_of_range": 0 + } + } + ], + "abnormal_condition_only": false + } + ], + "transitions": [ + { + "id": "trans0", + "from": "om0", + "to": "om1", + "start_timers": [ + "timer0" + ], + "blocking_timers": [ + "timer1" + ], + "transition_costs": 0, + "transition_duration": 0, + "abnormal_condition_only": false + }, + { + "id": "trans1", + "from": "om1", + "to": "om0", + "start_timers": [ + "timer1" + ], + "blocking_timers": [ + "timer0" + ], + "transition_costs": 0, + "transition_duration": 0, + "abnormal_condition_only": false + } + ], + "timers": [ + { + "id": "timer0", + "diagnostic_label": "Minimum run time", + "duration": 7200 + }, + { + "id": "timer1", + "diagnostic_label": "Minimum off time", + "duration": 3600 + } + ] +} +``` And finally, putting everything together in one message: ```json { "message_type": "FRBC.SystemDescription", - "message_id": "xxx", + "message_id": "0f9063c5-ceb9-4ab9-8a4b-96b6d38dff8a", "valid_from": "2019-08-24T14:15:22Z", "actuators": [ { @@ -226,13 +345,41 @@ And finally, putting everything together in one message: ], "operation_modes": [ { - "id": "om1", - "diagnostic_label": "Off", + "id": "om0", + "diagnostic_label": "running", "elements": [ { "fill_level_range": { + "start_of_range": 45, + "end_of_range": 55 + }, + "fill_rate": { + "start_of_range": 0.00209, + "end_of_range": 0.00835 + }, + "power_ranges": [ + { + "start_of_range": 500, + "end_of_range": 2000, + "commodity_quantity": "ELECTRIC.POWER.L1" + } + ], + "running_costs": { "start_of_range": 0, "end_of_range": 0 + } + } + ], + "abnormal_condition_only": false + }, + { + "id": "om1", + "diagnostic_label": "Off", + "elements": [ + { + "fill_level_range": { + "start_of_range": 45, + "end_of_range": 55 }, "fill_rate": { "start_of_range": 0, @@ -251,30 +398,49 @@ And finally, putting everything together in one message: } } ], - "abnormal_condition_only": true + "abnormal_condition_only": false } ], "transitions": [ { - "id": "string", - "from": "string", - "to": "string", + "id": "trans0", + "from": "om0", + "to": "om1", "start_timers": [ - "string" + "timer0" ], "blocking_timers": [ - "string" + "timer1" ], "transition_costs": 0, "transition_duration": 0, - "abnormal_condition_only": true + "abnormal_condition_only": false + }, + { + "id": "trans1", + "from": "om1", + "to": "om0", + "start_timers": [ + "timer1" + ], + "blocking_timers": [ + "timer0" + ], + "transition_costs": 0, + "transition_duration": 0, + "abnormal_condition_only": false } ], "timers": [ { - "id": "string", - "diagnostic_label": "string", - "duration": 0 + "id": "timer0", + "diagnostic_label": "Minimum run time", + "duration": 7200 + }, + { + "id": "timer1", + "diagnostic_label": "Minimum off time", + "duration": 3600 } ] } @@ -294,30 +460,32 @@ And finally, putting everything together in one message: ``` ### RM -> CEM: FRBC.LeakageBehaviour -TODO +The leakage behavior informs the CEM about the standing losses of the buffer, i.e. all the changes in the fill level that are not associated with the user demand or an actuator. It can be expressed as being dependent on the fill level, such that non-linear leakage can be modelled. A constant leakage rate (in fill_level per second) is defined per fill_level_range. Our buffer has standing losses of 50 W over the range of our fill level. + ```json { "message_type": "FRBC.LeakageBehaviour", - "message_id": "string", + "message_id": "82861374-7653-4094-9153-8c59b4fffed4", "valid_from": "2019-08-24T14:15:22Z", "elements": [ { "fill_level_range": { - "start_of_range": 0, - "end_of_range": 0 + "start_of_range": 45, + "end_of_range": 55 }, - "leakage_rate": 0 + "leakage_rate": 0.00005 } ] } ``` ### RM -> CEM: PowerMeasurement -TODO +The RM can provide the CEM with real time power values that the appliance consumes. In this case these measurements refer to the electricity consumption of the heat pump. + ```json { "message_type": "PowerMeasurement", - "message_id": "string", + "message_id": "8db515c2-1ee0-40bb-8820-15c5ddc4bbd3", "measurement_timestamp": "2019-08-24T14:15:22Z", "values": [ { @@ -329,47 +497,55 @@ TODO ``` ### RM -> CEM: FRBC.ActuatorStatus -TODO +The ActuatorStatus message is meant to communicate the state of the actuator to the CEM. For every actuator, the RM inform the CEM about the operation mode the actuator is in and the factor is uses. + +The previous operation mode is also contained in the ActuatorStatus to determine if the actuator is still in the transition phase from the previous operation mode (as specified by the transition_duration in the actuator's transition definition). + ```json { "message_type": "FRBC.ActuatorStatus", - "message_id": "string", - "actuator_id": "string", - "active_operation_mode_id": "string", + "message_id": "2d553846-8023-45c4-8e6c-b0e161e60c34", + "actuator_id": "actuator0", + "active_operation_mode_id": "om0", "operation_mode_factor": 0, - "previous_operation_mode_id": "string", + "previous_operation_mode_id": "om1", "transition_timestamp": "2019-08-24T14:15:22Z" } ``` ### RM -> CEM: FRBC.StorageStatus -TODO +With the StorageStatus message the RM updates the CEM about the current fill level. + ```json { "message_type": "FRBC.StorageStatus", "message_id": "string", - "present_fill_level": 0 + "present_fill_level": 52 } ``` ### RM -> CEM: FRBC.TimerStatus -TODO +The moment that a timer elapses after a transition that has been made is communicated via the TimerStatus message. For every timer of all actuators this message is sent from the RM to the CEM. + ```json { "message_type": "FRBC.TimerStatus", - "message_id": "string", - "timer_id": "string", - "actuator_id": "string", + "message_id": "2ebec2c8-5cd4-46bc-9784-ea125543b544", + "timer_id": "timer0", + "actuator_id": "actuator", "finished_at": "2019-08-24T14:15:22Z" } ``` ### RM -> CEM: FRBC.UsageForecast -TODO +With the UsageForecast, the predicted demand from buffer by the user can be communicated to the CEM. One could think of activities like taking a shower and using hot water for doing the dishes that create the user demand. + +The usage forecast is expressed as sequence of expected demand and some statistical values that express the uncertainty of demand on a time slot basis (defined by the duration). + ```json { "message_type": "FRBC.UsageForecast", - "message_id": "string", + "message_id": "9616e431-5035-404a-bd93-d673a08ebb44", "start_time": "2019-08-24T14:15:22Z", "elements": [ { @@ -387,45 +563,42 @@ TODO ``` ### CEM -> RM: FRBC.Instruction -TODO +Message that instructs the resource manager to change the actuator state, i.e. change the operation mode and/or operation mode factor. In this example, we change the operation mode of actuator0 (the heat pump) to om0, which is the running operation mode, with factor 1 which means run at maximum power. + ```json { "message_type": "FRBC.Instruction", - "message_id": "string", - "id": "string", - "actuator_id": "string", - "operation_mode": "string", - "operation_mode_factor": 0, + "message_id": "795f10a7-2f5e-4052-90f6-832eecd33dad", + "id": "instr0", + "actuator_id": "actuator0", + "operation_mode": "om0", + "operation_mode_factor": 1, "execution_time": "2019-08-24T14:15:22Z", - "abnormal_condition": true + "abnormal_condition": false } ``` ### RM -> CEM: InstructionStatusUpdate -TODO +The InstructionStatusUpdate is used by the RM to let the CEM know about the handling of the instruction. + ```json { "message_type": "InstructionStatusUpdate", - "message_id": "string", + "message_id": "214b4dea-c93c-4567-9b42-6f82ff413ffc", "instruction_id": "string", "status_type": "NEW", "timestamp": "2019-08-24T14:15:22Z" } ``` -### RM -> CEM: SessionRequest -TODO +### RM -> CEM, CEM -> RM: SessionRequest +Both the RM and the CEM can send a connection life cycle management message, i.e. a SessionRequest message in order to let the other side know to gracefully shut down and if there is a request for a reconnect. + ```json { "message_type": "SessionRequest", - "message_id": "string", + "message_id": "9b360341-933e-4b83-9128-4ee1c3acfe47", "request": "TERMINATE", "diagnostic_label": "string" } -``` - - - - -## Example: Hybrid heat pump without buffering using DDBC -TODO +``` \ No newline at end of file