How to Add a Device Command Sequence
Add a named, model-specific command sequence for any supported device category: a list of register operations the EMS can run against a device on demand, from an alarm, or from Python.
Purpose
A command sequence is configuration, not code. Adding one means adding an entry to a JSON file for a model, which is why a new manufacturer or model can be supported without touching the execution engine — provided a protocol adapter for it already exists.
Sequences are the thing alarms act with, and the thing the command-sequence editor edits.
Prerequisites
- Write access to the EMS backend's
emsConfig/tree. - The device category must already be a known device type. The engine carries a
DEVICESregistry; a category absent from it cannot be served however good its JSON is. - For execution: reachability of the device (or the simulator) over Modbus TCP, and
pyModbusTCPinstalled in the backend's environment. - Knowledge of the model's register map — addresses, data types and scaling are model facts, not guesses.
Relevant Files
| Path | Role |
|---|---|
device_command_sequences.py |
The universal device sequence engine |
pcs_power_sequence.py |
The underlying executor (execute_sequence, PowerSequenceError) |
command_sequence_admin.py |
Administration helpers |
command_sequence_test.py |
The test harness |
emsConfig/<category>/sequences/<prefix>_command_sequences.json |
The catalogue layer |
emsConfig/pcs/power_sequences/<MODEL>.json |
The PCS catalogue — PCS uses this path instead, one file per model |
emsConfig/<category>/<main>/… |
The main layer |
emsConfig/<category>/<device_dir>/… |
The device layer |
The three layers, most specific first
def sequence_layers(device_type, device_key=None):
layers = []
if device_key:
layers.append(("device", device_sequences_dir(device_type, device_key)))
layers.append(("main", main_sequences_dir(device_type)))
layers.append(("catalogue", sequence_path(device_type)))
return layers
The docstring states the precedence: "A device's own copy wins over the family main files,
which win over the catalogue that ships with the product." device_duplicate.py --sync seeds
a device folder from the main files, so a copy starts identical and diverges only where
someone edits it.
sequence_source(device_type, model, device_key) walks the layers and returns the first that
can serve the model, so "a stale copy left behind by a later model change falls through to
the next layer instead of driving a device with another model's registers."
Practical consequence: editing the catalogue changes every device that has no override. Editing a device's own copy changes only that device. Decide which you mean before you edit.
The File Shape
A real catalogue file, emsConfig/air_condition_unit/sequences/ac_command_sequences.json:
{
"schema_version": 1,
"device_type": "air_condition_unit",
"models": {
"GTW-ems100CX": {
"aliases": ["…"],
"notes": "…",
"actions": {
"start": [
{ "operation": "write_single", "address": 1114, "value": 1,
"encoding": "u16", "verify": true },
{ "operation": "write_single", "address": 1115, "value": 1,
"encoding": "u16", "verify": true }
],
"start_heating": [
{ "operation": "write_single", "address": 1114, "value": 2,
"encoding": "u16", "verify": true }
]
}
},
"AC_STD": { "aliases": [], "notes": "…", "actions": { "…": [] } },
"AC_PRO": { "…": {} },
"AC_MAX": { "…": {} }
}
}
models— keyed by model name. This is the lookupsequence_sourceperforms.actions— the sequences. The key is the sequence name.available_actions(device_type, model)returns exactly these keys, and it is what the alarm-action editor's picker lists.aliases— alternative model spellings that resolve to this entry.notes— free text carried with the model.
Step keys
| Key | Meaning |
|---|---|
operation |
What to do. Across the live PCS files: write_single, write_multiple, read_holding, read_input, delay |
address |
The register address, from the model's register map. A decimal integer or a hex string such as "0x0D57" |
value |
The value to write — a literal, or a ${parameter} placeholder |
values |
The values for write_multiple |
value_from |
Take the value from an earlier step's stored result instead of a literal |
encoding |
How to encode it. Live files use u16 and signed_i16 |
count |
How many registers to read, on a read step |
scale, offset, decimals |
How to convert a raw register value for display |
store_as |
Save a read result under this name for a later step |
verify |
Read the register back and confirm the write took |
seconds, milliseconds |
The wait, on a delay step |
reason |
A human note explaining why the step exists |
read_holding and read_input steps make a sequence purely observational, which is what you
want for a test. A delay step carries no address — it is a gap in the sequence, and for PCS
those gaps are part of the hardware specification rather than cosmetic waits.
The PCS Layout and Its Real Sequences
PCS is the one category that does not follow the layout above. The engine maps it to
emsConfig/pcs/power_sequences/, and each file there is named for its model and carries
model, aliases, notes and actions at the top level — there is no models wrapper and
no sequences directory. EPCS105.json in full:
{
"model": "EPCS105",
"aliases": ["EPCS105-EN", "EnjoyPCS EPCS105"],
"notes": ["...addresses and scaling from the EPCS105-EN spec..."],
"actions": {
"start": [
{ "operation": "write_single", "address": "0x0291", "value": 1, "encoding": "u16",
"verify": true },
{ "operation": "delay", "seconds": 10 }
],
"stop": [
{ "operation": "write_single", "address": "0x0D57", "value": 0,
"encoding": "signed_i16", "scale": 10, "verify": true },
{ "operation": "delay", "seconds": 1 },
{ "operation": "write_single", "address": "0x0291", "value": 0, "encoding": "u16",
"verify": true }
],
"change_power": [
{ "operation": "write_single", "address": "0x0D57", "value": "${power_kw}",
"encoding": "signed_i16", "scale": 10, "verify": true }
],
"mode_pq": [
{ "operation": "write_single", "address": "0x5066", "value": 0, "encoding": "u16",
"verify": true }
],
"mode_vf": [
{ "operation": "write_single", "address": "0x5066", "value": 1, "encoding": "u16",
"verify": true }
],
"read_soc": [
{ "operation": "read_holding", "address": 3005, "count": 1, "encoding": "u16",
"scale": 1, "offset": 0, "decimals": 0, "store_as": "soc_raw" }
],
"read_soh": [
{ "operation": "read_holding", "address": 3006, "count": 1, "encoding": "u16",
"scale": 1, "offset": 0, "decimals": 0, "store_as": "soh_raw" }
]
}
}
MODEL_TEMPLATE.json in the same directory exercises every operation the engine accepts —
write_single, write_multiple, read_holding, read_input and delay — with the
milliseconds, values and replace_before_use keys alongside them, and is the right file to
copy when adding a model. It is a template, not a deployable target; do not point a device at
it.
The directory also holds a legacy pcs_power_sequences.json, keyed schema_version +
models.EPCS105. The engine does not load it — it resolves PCS models from the per-model
files only:
python3 device_command_sequences.py --device pcs --list-models
# EPCS105 emsConfig/pcs/power_sequences/EPCS105.json
# MODEL_TEMPLATE emsConfig/pcs/power_sequences/MODEL_TEMPLATE.json
# SINEXCEL_PWS1_250K emsConfig/pcs/power_sequences/SINEXCEL_PWS1_250K.json
# SUNGROW_SC250UD emsConfig/pcs/power_sequences/SUNGROW_SC250UD.json
Edit the per-model file, never the monolith.
The seven real PCS sequences
These names are identical across all three PCS models; only the addresses and encodings differ.
| Sequence | Purpose |
|---|---|
start |
Power the unit on |
stop |
Power the unit off |
change_power |
Set active power, via the ${power_kw} parameter |
mode_pq |
Switch to PQ mode |
mode_vf |
Switch to VF mode |
read_soc |
Read state of charge, stored as soc_raw |
read_soh |
Read state of health, stored as soh_raw |
SINEXCEL_PWS1_250K and SUNGROW_SC250UD use different addresses for the same picks;
always read them from the model's own file rather than copying EPCS105's.
This is why the brief's PCS examples map onto real sequences one-for-one — START BESS to
start, SET ACTIVE POWER to change_power, SWITCH TO PQ MODE to mode_pq, SWITCH TO
VF MODE to mode_vf — with only the names differing. Note that change_power really does
use the ${power_kw} placeholder, so the parameter mechanism described below is in live use
on the PCS path.
Dynamic Input Parameters
A parameter is a ${name} placeholder in a step's value:
{ "operation": "write_single", "address": 4000, "value": "${power_kw}",
"encoding": "u16", "verify": true }
The caller supplies the value: run_action(client, device_type="…", action="…",
parameters={"power_kw": 50}).
There is no declaration block. The live files contain no inputs or parameters section
declaring a sequence's parameters; a parameter exists because a step references it and the
caller passes it. That has two consequences worth knowing:
- A misspelled placeholder (
${power_KW}) is not caught by schema validation. It fails at execution, when the value cannot be resolved. - A parameter the caller omits has nothing to resolve to at that step. Supply every parameter a sequence references, or the sequence will not complete.
The parameter names actually in use
These are the real ${…} names across the live sequence files:
| Parameter | Which |
|---|---|
power_kw |
Active power (kW) |
percent |
A percentage setpoint |
current_a |
Current (A) |
soc_pct |
State of charge (%) |
charge_limit, discharge_limit |
Charge/discharge limits |
cell_ov, cell_uv |
Cell over/under-voltage limits |
temp_over, temp_under |
Temperature limits |
energy_kwh |
Energy (kWh) |
minutes, seconds |
Durations |
mode |
Operating mode |
phases |
Phase configuration |
Reuse these names where they fit; a new name is fine as long as every caller passes it.
Step-by-Step Procedure
- Identify the device category. A top-level folder under
emsConfig/and a key in the engine'sDEVICESregistry. The engine key and the config directory are not always the same string — seven categories have a config directory whose name differs. Always pass the engine key in the left column to--device:
Engine key (--device) |
Config directory it resolves to |
|---|---|
pcs |
emsConfig/pcs/power_sequences/ |
ac |
emsConfig/air_condition_unit/sequences/ |
cooling |
emsConfig/liquid_cooling_unit/sequences/ |
fss |
emsConfig/fire_safety_system/sequences/ |
grid_meter |
emsConfig/grid_energy_meter/sequences/ |
solar_meter |
emsConfig/solar_energy_meter/sequences/ |
smoke_detector |
emsConfig/smoke_sensor/sequences/ |
ffr_meter |
emsConfig/ffr_energy_meter/sequences/ |
The other ten — bess_energy_meter, bmu, door_sensor, ev_charger, flood_sensor,
frequency_meter, heat_sensor, sensor_block, temperature_sensor, ups — use the same
name for both. Eighteen categories in total.
2. Identify the manufacturer and model. The model is the key under models.
3. Locate the sequence file. emsConfig/<category>/sequences/<prefix>_command_sequences.json
for the catalogue. Confirm which layer you should be editing — see the layering section.
4. List the models the file already serves, so you extend rather than duplicate:
python3 device_command_sequences.py --device <engine-key> --list-models
- Create or extend the model entry under
models. - Name the sequence. The
actionskey. Use the existing lowercase convention (start,start_heating,read_status), and make it unique within the model. - Describe it in
noteson the model; the schema carries no per-sequence description field, so this is where that context lives. - Add the steps in execution order.
- Set each
operation,address,encodingandvaluefrom the model's register map. - Use
${parameter}placeholders for anything that should vary at runtime. - Order is the array order. There is no explicit per-step order key; the list is the order.
- Set
verify: trueon writes where you want read-back confirmation. - Keep read-only sequences read-only. A test you cannot run safely is not a test.
-
Validate the JSON parses, then confirm the engine sees the sequence:
python3 device_command_sequences.py --device <engine-key> --model <MODEL> --list-actions -
Save the file. No backend restart is needed — the engine reads the file when it runs.
- Confirm it is offered by
available_actions(device_type, model), which is the same call the alarm-action editor uses to populate its picker.
Protocol adapters
protocol_for(device_type, device_key=None) and adapter_client(device_type, client, *,
device_key=None, protocol=None, control_path=None) sit between the sequence and the wire. A
sequence describes operations; the adapter turns them into Modbus or OCPP traffic. Adding a
new manufacturer or model therefore needs no engine change — you add a models entry and
the existing adapter serves it. Adding a genuinely new protocol does need an adapter.
Examples
These are templates for new sequences you are adding, not a description of what already exists. Several of the brief's names have a configured counterpart already, and you should extend those files rather than create a second sequence that does the same job:
| Brief name | Real configured sequence | Where it lives |
|---|---|---|
| START BESS / STOP BESS | start / stop |
emsConfig/pcs/power_sequences/<MODEL>.json |
| SET ACTIVE POWER | change_power |
same |
| SWITCH TO PQ MODE / SWITCH TO VF MODE | mode_pq / mode_vf |
same |
| START CHARGING / START DISCHARGING | start_charging / stop_charging |
emsConfig/ev_charger/sequences/ev_charger_command_sequences.json |
| EV CHARGER POWER LIMIT | set_power_limit |
same |
SET REACTIVE POWER has no configured counterpart anywhere in the tree, so it is a genuine addition — but only for models whose register map actually exposes a reactive-power register.
Always confirm before writing:
python3 device_command_sequences.py --device <engine-key> --list-actions
START BESS / STOP BESS
{
"START BESS": [
{ "operation": "write_single", "address": 4000, "value": 1, "encoding": "u16", "verify": true },
{ "operation": "write_single", "address": 4001, "value": 1, "encoding": "u16", "verify": true }
],
"STOP BESS": [
{ "operation": "write_single", "address": 4000, "value": 0, "encoding": "u16", "verify": true }
]
}
SET ACTIVE POWER / SET REACTIVE POWER
{
"SET ACTIVE POWER": [
{ "operation": "write_single", "address": 4010, "value": "${power_kw}",
"encoding": "u16", "verify": true }
],
"SET REACTIVE POWER": [
{ "operation": "write_single", "address": 4011, "value": "${power_kw}",
"encoding": "u16", "verify": true }
]
}
START CHARGING / START DISCHARGING
{
"START CHARGING": [
{ "operation": "write_single", "address": 4020, "value": "${current_a}",
"encoding": "u16", "verify": true },
{ "operation": "write_single", "address": 4021, "value": "${charge_limit}",
"encoding": "u16", "verify": true }
],
"START DISCHARGING": [
{ "operation": "write_single", "address": 4020, "value": "${current_a}",
"encoding": "u16", "verify": true },
{ "operation": "write_single", "address": 4021, "value": "${discharge_limit}",
"encoding": "u16", "verify": true }
]
}
SWITCH TO PQ MODE / SWITCH TO VF MODE
{
"SWITCH TO PQ MODE": [
{ "operation": "write_single", "address": 4030, "value": 0, "encoding": "u16", "verify": true }
],
"SWITCH TO VF MODE": [
{ "operation": "write_single", "address": 4030, "value": 1, "encoding": "u16", "verify": true }
]
}
EV CHARGER POWER LIMIT
{
"EV CHARGER POWER LIMIT": [
{ "operation": "write_single", "address": 5000, "value": "${current_a}",
"encoding": "u16", "verify": true }
]
}
The real EV charger catalogue already holds sixteen sequences for its EVC1 model under
models.EVC1.actions — set_power_limit, set_current_limit, set_phases,
set_min_current, set_fallback_current, set_energy_target, set_soc_target,
start_charging, stop_charging, reset_charger, clear_alarms, read_status,
read_measurements, apply_load_balancing_limit, enable_dynamic_load_balancing and
disable_dynamic_load_balancing. If what you want is a power limit, extend set_power_limit
in emsConfig/ev_charger/sequences/ev_charger_command_sequences.json rather than adding a
parallel sequence.
Every address above is a placeholder. Substituting real addresses requires the model's register map, and a wrong address is a write to the wrong register — the one failure mode in this guide that moves hardware.
Testing
List what the engine sees, then run it against a simulator:
python3 device_command_sequences.py --device <engine-key> --list-devices
python3 device_command_sequences.py --device <engine-key> --model <MODEL> --list-actions
python3 device_command_sequences.py --device <engine-key> --device-key <key> \
--task <sequence> --param power_kw=50 --json
Full procedure in How to Test Device Command Sequences.
Troubleshooting
| Symptom | Cause |
|---|---|
--list-actions prints nothing |
The model key does not match, or the model has no actions |
No power sequence file matches … model |
The model is absent from every layer for that device type |
sequence path not found: … |
The layer file is missing or misnamed |
| A sequence runs but a value is wrong | A ${param} was not supplied, or a wrong address |
| A stale edit has no effect | A higher layer (device copy) wins. sequence_source returns the layer it used |
| The sequence never appears in the alarm-action picker | available_actions does not return it — usually a model mismatch |
Implementation Gaps
- The brief's sequence names are not the configured names.
START BESS,STOP BESS,START CHARGING,START DISCHARGING,SET ACTIVE POWER,SET REACTIVE POWER,SWITCH TO PQ MODEandSWITCH TO VF MODEappear nowhere in the tree. The real PCS names cover the same ground —start,stop,change_power,mode_pq,mode_vf,read_soc,read_soh— and are listed in the PCS section below. - No per-sequence description field, and no declaration of a sequence's parameters.
Both live in
notesand in the${…}placeholders respectively, which is why a misspelled placeholder is caught at runtime rather than at save time. - The register map is not in this file. Addresses come from
<prefix>_register_full.json; nothing cross-checks a sequence address against it, so a wrong address is accepted and then written. - One category is not like the others. PCS keeps its catalogue in
emsConfig/pcs/power_sequences/, one file per model, rather than in asequences/directory. Any file-based inventory that globsemsConfig/*/sequences/*silently omits PCS — which is exactly how an earlier revision of this guide came to claim, wrongly, that PCS had no sequences at all.