Skip to content

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 DEVICES registry; 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 pyModbusTCP installed 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 lookup sequence_source performs.
  • 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

  1. Identify the device category. A top-level folder under emsConfig/ and a key in the engine's DEVICES registry. 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
  1. Create or extend the model entry under models.
  2. Name the sequence. The actions key. Use the existing lowercase convention (start, start_heating, read_status), and make it unique within the model.
  3. Describe it in notes on the model; the schema carries no per-sequence description field, so this is where that context lives.
  4. Add the steps in execution order.
  5. Set each operation, address, encoding and value from the model's register map.
  6. Use ${parameter} placeholders for anything that should vary at runtime.
  7. Order is the array order. There is no explicit per-step order key; the list is the order.
  8. Set verify: true on writes where you want read-back confirmation.
  9. Keep read-only sequences read-only. A test you cannot run safely is not a test.
  10. Validate the JSON parses, then confirm the engine sees the sequence:

    python3 device_command_sequences.py --device <engine-key> --model <MODEL> --list-actions
    
  11. Save the file. No backend restart is needed — the engine reads the file when it runs.

  12. 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

  1. 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 MODE and SWITCH TO VF MODE appear 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.
  2. No per-sequence description field, and no declaration of a sequence's parameters. Both live in notes and in the ${…} placeholders respectively, which is why a misspelled placeholder is caught at runtime rather than at save time.
  3. 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.
  4. One category is not like the others. PCS keeps its catalogue in emsConfig/pcs/power_sequences/, one file per model, rather than in a sequences/ directory. Any file-based inventory that globs emsConfig/*/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.