Diagnostic Test 02 — State of Charge (SOC) Validation
| Mode number | 2 |
| Registered handler | state_of_charge → _run_test_02_soc_validation in ems_diagnostic_handlers.py |
| Model action | read_soc (in emsConfig/pcs/power_sequences/<MODEL>.json) |
| Result metric | SOC (%) |
Theory
State of Charge (SOC) is the remaining energy in the battery expressed as a percentage of its current usable capacity. SOC is the primary input for almost every EMS control decision: charge/discharge setpoints, reserve margins for FFR/FCR, and safety limits all depend on knowing how full the battery is.
SOC cannot be measured directly — it is estimated by the BMS from voltage, current integration (coulomb counting) and model-based correction. Because the estimate can drift or disagree between units, "validation" here means:
- confirming that the EMS can read a live SOC value from every PCS/BESS interface,
- confirming the values are plausible and mutually consistent across PCS units.
This test establishes the baseline SOC telemetry that other diagnostics (Test 03 cell balancing, Test 04 internal resistance) rely on before they will run.
Settings needed
There are no JSON parameters for Test 02 — it only needs the model action to exist and be reachable.
-
Model action
read_socmust be defined inemsConfig/pcs/power_sequences/<MODEL>.jsonfor each PCS model under test. The action must contain a Modbus read step (address,count,encoding,scale,offset) that decodes to a SOC percentage. -
PCS device configuration in
ems_control_setting.json— each PCS entry must have an activestatus, adevice.model, an IP/host,portand Modbusunit_id(see Test 01 for the exact keys and defaults).
Prerequisites
Before the test runs, the following must all be true:
- At least one active PCS is configured in
ems_control_setting.json. - Every configured active PCS is reachable over Modbus TCP.
- The PCS model resolves to a sequence file containing the
read_socaction. - Every register required by
read_socexists in the PCS device register map (emsConfig/pcs/<pcs>/pcs_register_full.json, falling back toemsConfig/pcs/pcs_register.json). pymodbusis installed in theems-backendenvironment.
If no PCS is available, or if a required register is missing from the device
register map, the test returns prerequisite_failed without touching the PCS
hardware. The report's register_checks list names the missing registers.
Testing procedure
- Phase 1 — Prerequisite check. Locate active PCS devices and confirm each
one answers a Modbus TCP connection. Then verify every register required by
read_socis defined in the device register map. A missing device or missing register aborts the test and is reported asprerequisite_failed. - Phase 2 — Initialization. Stop every available PCS, wait 10 seconds, then start every available PCS.
- Phase 3 — Test operation. Execute the model-specific
read_socaction against every available PCS and decode the returned registers into a SOC percentage. - Pass / fail. The test passes only when every attempted PCS read
succeeded (
successful == attempted).
Report output
The report (measurements) contains:
test_number(2) andtest_name.prerequisite_checks— per-PCS availability result.initialization_events— stop / wait / start event log.successful_pcsandattempted_pcs.pcs_readings— per-PCS record withvalue_percent(SOC %), register address, encoding, scale and raw registers.
A bar graph (soc-by-pcs) plots SOC (%) per PCS.
Pass / fail summary
| Result | Condition |
|---|---|
pass |
Every available PCS returned a valid SOC reading |
partial |
At least one PCS read succeeded but not all |
error |
No PCS read succeeded |
prerequisite_failed |
No active PCS, no Modbus-reachable PCS, or a required register missing from the register map |
initialization_failed |
Stop / wait / start sequence failed |