S2 example for PV

S2 example for PV installations

This page serves as a guide for implementing an S2 RM for a PV installation. It provides example S2 messages that help developers to understand how to interact with PV installations and what kind of flexibility they can offer.

[ add architecture picture ]

Flexibility of a PV installation

A PV installation produces electricity by converting solar energy into electricity. This electricity can be used for several purposes, such as self-consumption or earning money by delivering electricity to the grid.

Usually a PV installation is not flexible at all, as it only produces electricity when there is sun and depending on weather circumstances (e.g. such as cloud coverage) it will produce more or less, i.e. its production is intermittent. But many PV inverters also allow to control the maximum output power of the PV installation, also known as curtailment. This curtailment is for example needed when too much installations are connected to the same local grid and produce at high power, pushing the voltage of the network above its acceptable limits, or when prices for delivering electricity back to the grid become to low (or even negative) to be profitable.

Choosing the S2 control type

S2 supports five different control types for flexibility (and one for no control possibility), each supporting a different way of modelling flexibility of a device. For PV installations the choice is somehow simple, as the capabilities of these installations are limited:

Control capability of PV installation	Control type	Remark
No control possible	NOT_CONTROLABLE	As there is no way to control this PV installation, the NOT_CONTROLABLE ControlType should be selected. Although nothing can be controlled, devices can still send PowerMeasurements and PowerForecasts
Set maximum output power	POWER_ENVELOPE_BASED_CONTROL (PEBC)	Based on the constraints of the PV installation (e.g. the minimum and maximum power output of the inverter), the CEM can provide the Resource Manager of the PV installation a PowerEnvelope that describes the minimum (usually 0) and maximum (e.g. -2kW, negative for production) that the inverter of the PV installation should produce

The table shows two ways to interact with a PV installation: just using the power measurements such that the CEM can optimize based on the production of the PV installation and using Power Envelope Based Control, which allows the CEM to instruct the PV installation to curtail.

We could also model the PV installation as a state machine using Operation Mode Based Control (OMBC). Different states (operation modes in S2 language) could be modeled that describe at which maximum power output the PV installation should adhere to, but this approach is more work to configure than PEBC, and does not increase the amount of flexiblity that a CEM can utilize.

The Power Envelope Based Control control type is used for devices that can be influenced to use or produce a minimum and/or maximum amount of power over time. This means that the CEM cannot control the amount of power produced or consumed by the device directly, but it can dictate power limits, which can change over time. The Resource Manager informs the CEM with which power limits it can work using the PEBC.PowerConstraints message. Optionally, the Resource Manager can also instruct the CEM how much energy it needs to consume or produce in a certain timespan (by sending a PEBC.EnergyConstraints message), which the CEM shall take into consideration while setting power limits.

Example of controlling an PV inverter using Power Envelope Based control (PEBC)

This example describes how a PV interter can expose its curtailment capabilities to the CEM and let the CEM control this inverter by sending it messages that will ask it to curtail itself.

The following sequence diagram is an example of what a message exchange between a CEM and RM could look like, but messages could also be sent in a different order (see also State of communication and the PEBC Message reference). ReceptionStatus messages are omitted for readability.

First an overview of the messages is presented graphically, next sections will describe the example messages in more detail.

Communication between the PV installation and the Resource Manager (RM)

For the RM to work correctly, some information is required to fill in the messages between the RM and the CEM.

The diagram below depicts this process and the data that is needed.

Image generated using the following PlantUML code:

@startuml
title Initialize communication between the RM and the PV installation
'participant CEM
participant RM
participant "PV Inverter" as PV

note over RM, PV: Initialize connection between RM and PV Inverter

RM <-> PV: connect using inverter protocol
PV -> RM: Send constraints, \ne.g. maximum production power
loop every x seconds
PV -> RM: Send PV measurements
PV -> RM: Send forecasts (if available)
end loop
@enduml

As shown, the RM needs to know what the maximum output power of the inverter is and how it can get measurements that can be send to the CEM.

Communication between de RM of the PV installation and a CEM

In the picture below the S2 message exchange is depicted as a sequence diagram. It can be split up in five parts:

1. Setup of the connection between the CEM and the RM
2. Exchange the Resource Manager configuration and selection of Control type
3. Configuration of the power and/or energy constraints of the PV installation
4. Normal operation: Exchange of measurements and curtailment instructions
5. Disconnect the communication between the CEM and the RM.

PlantUML code for this diagram:

@startuml
title Example communication between CEM and RM of a PV Installation
participant CEM
participant RM

note over CEM, RM: WebSocket connected

CEM -> RM: Handshake
RM -> CEM: Handshake
CEM -> RM: HandshakeResponse

note over CEM, RM #lightblue: Initialized

|||

group Send RM configuration for this inverter and \nthe control type that this RM supports
RM -> CEM: ResourceManagerDetails
CEM -> RM: SelectControlType
note right: The CEM will select the \nPEBC control type for this RM
end group


note over CEM, RM #lightgreen: ControlType PEBC activated 

|||

group #fff0b7 Send power or energy constraints of this PV Installation 
RM -> CEM: PEBC.EnergyConstraint
RM -> CEM: PEBC.PowerConstraint
note right: The RM informs the CEM of the\n maximum power output of the PV inverter
end

|||

loop in no particular order

RM -> CEM: PowerMeasurement
RM --> CEM: PowerForecast [Optional]

CEM -> RM: PEBC.Instruction
note right: Here the CEM will ask the RM to curtail its production
RM -> CEM: InstructionStatusUpdate
note right: The RM will confirm (or not) this curtailment
end loop

|||

RM -> CEM: SessionRequest

note over CEM, RM: WebSocket disconnected

@enduml

The following messages are exchanged:

RM -> CEM: Handshake

The RM informs the CEM that it is a RM and which versions of s2-ws-json it supports.

{
  "message_type": "Handshake",
  "message_id": "xxx",
  "role": "RM",
  "supported_protocol_versions": [
    "0.0.2-beta"
  ]
}

CEM -> RM: HandshakeResponse

The CEM informs the RM which version of s2-ws-json it has selected for this session.

{
  "message_type": "HandshakeResponse",
  "message_id": "xxx",
  "selected_protocol_version": "0.0.2-beta"
}

RM -> CEM: ResourceManagerDetails

The RM informs the CEM about several static properties of the RM/PV installation:

• The resource_id is a unique string in the context of the CEM.
• The name is a default name or user defined name (when possible) for UI purposes.
• In this context the PV installation is an electricity producer and not a consumer or storage. S2 is concerned with what is exchanged with the grid, and in this case the PV installation participates in an electricity grid that needs to be managed by the CEM.
• The instruction processing delay indicates that the PV installation will on average respond in 5000 milliseconds to an instruction from the CEM.
• This PV installation does not define any costs related parameters, so no currency needs to be provided.
• This RM only implements the Power Envelope Based Control (PEBC) Control Type.
• This RM also provides power forecasts (e.g. by using an external forecast service connected to this RM).
• This PV installation is a single phase electric device (when there is only one phase the phase L1 must be used), so it will only provide measurements for the single phase. For three phase inverters, all phases should be listed here (and for each phase measurements should be provided)

{
  "message_type": "ResourceManagerDetails",
  "message_id": "xxx",
  "resource_id": "acme_pv_installation",
  "name": "Solar panels on roof",
  "roles": [
    {
      "role": "ENERGY_PRODUCER",
      "commodity": "ELECTRICITY"
    }
  ],
  "manufacturer": "ACME",
  "model": "InverterType2024",
  "serial_number": "123",
  "firmware_version": "v1.0",
  "instruction_processing_delay": 5000,
  "available_control_types": [
    "POWER_ENVELOPE_BASED_CONTROL"
  ],
  "provides_forecast": true,
  "provides_power_measurement_types": [
    "ELECTRIC.POWER.L1"
  ]
}

CEM -> RM: SelectControlType

The CEM informs the RM that it wants to use PEBC ControlType (the RM defined in the ResourceManagerDetails that this is the only supported ControlType).

{
  "message_type": "SelectControlType",
  "message_id": "xxx",
  "control_type": "POWER_ENVELOPE_BASED_CONTROL"
}

Configuration of the power and/or energy constraints of the PV installation

RM -> CEM: PEBC.PowerConstraints

Using the PEBC.PowerConstraints message, a RM can specify the constraints in which the CEM can operate. For curtailing a PV installation, it is important for the CEM to know in what range it can control the power output. The message contains a few relevant properties (see below for the example):

1. valid_from and valid_until specify for which period this constraint is valid. In the example it is defined as 24 hours.
2. consequence_type defines what happens if the constraint is applied. For PV installations it means that if the installation is curtailed, the amount of electricity that is curtailed is vanished (denoted by the the enum literal VANISHED), e.g. it will be lost and never reappear. For other devices (e.g. for an EV or other devices that can shift their consumption in time) the consequence could be DEFER to denote that the load is postponed (e.g. the lost energy is caught up later in time e.g. by longer charging or compensated by faster charging later on).
3. A list of allowed_limit_ranges of type PEBC.AllowedLimitRange. These are the actual envelopes that need to be defined. For each Allowed limit range one needs to specify: a. the commodity_quantity (for our example this is "ELECTRIC.POWER.L1" (Eletriticy phase 1)) b. limit_type defining if it is an U

In the example below, a 4 kWp PV installation is configured.

NOTE: In, S2 production is denoted with a negative number, as opposed to consumption which is positive. So for a 4 kWp PV installation, one should use -4000 W as constraint value.

{
  "message_type": "PEBC.PowerConstraints",
  "message_id": "xxx",
  "id": "constraint1",
  "valid_from": "2024-08-24T14:15:22Z",
  "valid_until": "2024-08-25T14:15:22Z",
  "consequence_type": "VANISH",
  "allowed_limit_ranges": [
    {
      "commodity_quantity": "ELECTRIC.POWER.L1",
      "limit_type": "UPPER_LIMIT",
      "range_boundary": {
        "start_of_range": 0,
        "end_of_range": -4000
      },
      "abnormal_condition_only": false
    },
    {
      "commodity_quantity": "ELECTRIC.POWER.L1",
      "limit_type": "LOWER_LIMIT",
      "range_boundary": {
        "start_of_range": 0,
        "end_of_range": 0
      },
      "abnormal_condition_only": false
    }
  ]
}

RM -> CEM: PEBC.EnergyConstraint

Normal operation: Exchange of measurements, forecasts and curtailment instructions

RM -> CEM: PowerMeasurement

TODO

{
  "message_type": "PowerMeasurement",
  "message_id": "string",
  "measurement_timestamp": "2019-08-24T14:15:22Z",
  "values": [
    {
      "commodity_quantity": "ELECTRIC.POWER.L1",
      "value": 0
    }
  ]
}

RM -> CEM: PowerForecast

CEM -> RM: PEBC.Instruction

RM -> CEM: InstructionStatusUpdate

RM -> CEM: SessionRequest

TODO

{
  "message_type": "SessionRequest",
  "message_id": "xxx",
  "request": "TERMINATE",
  "diagnostic_label": "PV Inverter resource manager shutdown"
}