dbus_switch_s2 - victronenergy/venus GitHub Wiki
switch
Service created for the Energy Solutions (ES) smartswitch, but also for some Victron products like the GX IO extender and more to follow. In addition, devices which contain switchable outputs will also list them in their service with the same structure as given below. E.g., a com.victronenergy.solarcharger will also create the paths /SwitchableOutput/0/... to list the MPPT relay. The UI and other services (node-red) pick this up to list/control the output.
com.victronenergy.switch
Generic:
/State <-- Current state of the whole module. Visible in the UI in the Device List ->
SmartSwitch -> Settings. Not visible on the switch card, also not necessary
because in case of a module level problem, all channels will indicate disabled.
Values offset by 0x100 to allow common state component in QML
0x100 = Connected
0x101 = Over temperature
0x102 = Temperature warning
0x103 = Channel fault
0x104 = Channel Tripped
0x105 = Under Voltage
OPERATIONAL PATHS PER CHANNEL:
Note that <x> should be a clear label of the output channel, not necessarily an integer. <x> can be used in the UI to display the output when /SwitchableOutput/x/Settings/CustomName is not set or not valid.
/SwitchableOutput/x/State <-- RW / Requested on/off state of channel, separate from dimming.
/SwitchableOutput/x/Dimming <-- RW / 0 to 100%, read/write.
Optional: required only for dimmable outputs, otherwise invalid or
doesn't exist.
/SwitchableOutput/x/Status <-- R / Channel status
Normal states, visible in the component itself:
0x00 = Off
0x09 = On <- Ored state of Active and Input Active.
Exceptional states visible in the component itself
0x02 = Tripped
0x04 = Over temperature
Exceptional states, made visible by a extra label in the UI:
0x01 = Powered <- Voltage present on the Channels supply in the case where the
channels are individually supplied or if not and channel output
is being back fed. In latter case query if input/analog input
and if they go on dbus as com.victronenergy.digitalinput
0x08 = Output fault <- Indicates that the channel is "active" but sees no voltage.
Not available when function is set to be dimmable, since
then at low dimming levels its normal to do this.
0x10 = Short fault <- A certain hardware error that the switch self-diagnoses
0x20 = Disabled <- The hardware indicates this status in case for some
reason the switch is disabled. For example in case
the whole module is in over temperature.
/SwitchableOutput/x/Temperature <-- R / temperature of the switch,
Optional: not all output types will feature temp. measurement.
/SwitchableOutput/x/Voltage <-- R / voltage of its output
Optional: not all output types will feature voltage measurement.
/SwitchableOutput/x/Current <-- R / the current in amps. optional
Optional: not all output types will feature current measurement.
SETTINGS:
/SwitchableOutput/x/Settings/Group <-- RW / 32 character long string, free input, used by the
UI to group switches with the same group name onto
the same card. When left blank (dbus-invalid), the UI
falls back to grouping them by dbus service.
/SwitchableOutput/x/Settings/CustomName <-- RW / the label; Preferably stored on the device itself.
/SwitchableOutput/x/Settings/ShowUIControl <-- RW / boolean to indicate if the control is shown
in the UI (for usage in Node-RED, but not in the gui)
/SwitchableOutput/x/Settings/Type <-- RW / 0 = momentary, 1 = latching/relay, 2 = dimmable/pwm;
Preferably stored on the device itself
/SwitchableOutput/x/Settings/ValidTypes <-- R / binary field where each bit corresponds to the
enum of xx/type indicates which options the UI should
provide to the user.
/SwitchableOutput/x/Settings/Function <-- RW / 0 = Alarm, 1 = Generator start/stop, 2 = Manual,
3 = Tank pump, 4 = Temperature, 5 = Genset helper relay
ES SmartSwitch: only manual
GX: builtin relays all options, second relay at
least manual, alarm (new) and temperature
IO extender: only manual
BMV, smartsolar, other: only manual
(this is for the future, for now they remain under /Relay as they are)
/SwitchableOutput/x/Settings/ValidFunctions <-- R / binary field where each bit corresponds
to the enum of xx/function indicates which options the UI
should provide to the user.
/SwitchableOutput/x/Settings/FuseRating <-- RW (optional) Channel trip rating in amps;
Preferably stored on the device.
GetMin and GetMax are implemented to get the limits.
S2 support
This service also exposes a set of paths used to control switchable outputs with S2. For the customer energy manager (CEM), the main use-case for switchable (and dimmable) outputs is a so-called opportunity load which can be engaged when there is excess energy. The load then stores the excess energy - usually in the form of heat - in a buffer to be used later. The resource manager (RM) communicates with the CEM and controls the load(s) accordingly.
Flexibility pattern and control mode
The flexibility pattern that fits this device is the "Buffer energy" pattern. The control type to be used is "Fill rate based control" (FRBC)
In FRBC, the RM needs to inform the CEM about:
- The fill level of the buffer
- Lower and upper bound of the fill level
- (Optional) Target fill level and by when that target level should be reached
The actuator that is used to affect the fill level of the buffer (e.g. a heating rod) must be modeled with a statemachine in order for the CEM to be able to utilize it. The statemachine contains two states: 'On' and 'Off'. We use the power range property of the 'On'state to specify the power usage of the connected heating device.
For a switchable output without dimming capability, the power range min and max are both equal to the device rated power. For a switchable output with dimming capability, the power range corresponds to the power at the minimum and maximum dim level of the output. Typically the range will go from 0 to the rated power linearly with the dim level.
S2 messages
Example FRBC messages here
The handshake process is omitted for now since the RM will connect to the CEM locally
RM -> CEM: ResourceManagerDetails
{
"message_type": "ResourceManagerDetails",
"message_id": "xxx",
"resource_id": "switchable_output_x",
"name": "Switchable Output x",
"roles": [
{
"role": "ENERGY_CONSUMER",
"commodity": "ELECTRICITY"
}
],
"manufacturer": "Victron Energy",
"model": "GX IO Extender 150",
"serial_number": "HQxxxx",
"firmware_version": "vx.x",
"instruction_processing_delay": 1000,
"available_control_types": [
"FILL_RATE_BASED_CONTROL"
],
"provides_forecast": false,
"provides_power_measurement_types": [
"ELECTRIC.POWER.L1"
]
}
CEM -> RM: SelectControlType
{
"message_type": "SelectControlType",
"message_id": "xxx",
"control_type": "FILL_RATE_BASED_CONTROL"
}
RM -> CEM: FRBC.SystemDescription
A switchable output with heating rod specifies two operation modes: "On" and "Off". In the Off state, the heating device is turned off, so the fill rate and the power range are set to 0. In the "On" mode, heating device consumes its rated power continuously (assuming no dimming capability), so the power range min and max are both set to the rated power. The fill rate describes the rate the fill level increases in seconds at the start and end of the power range, so that is also set to a static value. So a value of 0.0001 means the fill level increases by 0.0001% each second the device is consuming the associated power.
In case of a dimmable output, the power and fill rate range of the "On" operation mode must be set to go from 0 to the rated power / corresponding fill rate instead.
{
"message_type": "FRBC.SystemDescription",
"message_id": "xxx",
"valid_from": "2019-08-24T14:15:22Z",
"actuators": [
{
"id": "actuator1",
"diagnostic_label": "Heating rod",
"supported_commodities": [
"ELECTRICITY"
],
"operation_modes": [
{
"id": "om1",
"diagnostic_label": "Off",
"elements": [
{
"fill_level_range": {
"start_of_range": 0,
"end_of_range": 100
},
"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"
}
]
}
],
"abnormal_condition_only": true
},
{
"id": "om2",
"diagnostic_label": "On",
"elements": [
{
"fill_level_range": {
"start_of_range": 0,
"end_of_range": 100
},
"fill_rate": {
"start_of_range": 0.0001,
"end_of_range": 0.0001
},
"power_ranges": [
{
"start_of_range": 1000,
"end_of_range": 1000,
"commodity_quantity": "ELECTRIC.POWER.L1"
}
]
}
],
"abnormal_condition_only": true
}
],
"transitions": [
{
"id": "transition1",
"from": "om1",
"to": "om2",
"start_timers": [],
"blocking_timers": [],
"transition_duration": 3000,
"abnormal_condition_only": true
},
{
"id": "transition2",
"from": "om2",
"to": "om1",
"start_timers": [],
"blocking_timers": [],
"transition_duration": 3000,
"abnormal_condition_only": true
}
],
"timers": []
}
],
"storage": {
"diagnostic_label": "Heat buffer",
"fill_level_label": "Heat buffer fill level",
"provides_leakage_behaviour": false,
"provides_fill_level_target_profile": true,
"provides_usage_forecast": false,
"fill_level_range": {
"start_of_range": 0,
"end_of_range": 100
}
}
}
Dbus paths for S2
Since every individual output can be a resource, the following paths are added to the /SwitchableOutput/x/ path whenever there is a resource manager available for it:
/SwitchableOutput/x/S2/ResourceManagerName
/SwitchableOutput/x/S2/ResourceManagerStatus
/SwitchableOutput/x/S2/InstructionToRM
/SwitchableOutput/x/S2/InstructionFromRm