Skip to content

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.

  1. Model action read_soc must be defined in emsConfig/pcs/power_sequences/<MODEL>.json for each PCS model under test. The action must contain a Modbus read step (address, count, encoding, scale, offset) that decodes to a SOC percentage.

  2. PCS device configuration in ems_control_setting.json — each PCS entry must have an active status, a device.model, an IP/host, port and Modbus unit_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_soc action.
  • Every register required by read_soc exists in the PCS device register map (emsConfig/pcs/<pcs>/pcs_register_full.json, falling back to emsConfig/pcs/pcs_register.json).
  • pymodbus is installed in the ems-backend environment.

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

  1. Phase 1 — Prerequisite check. Locate active PCS devices and confirm each one answers a Modbus TCP connection. Then verify every register required by read_soc is defined in the device register map. A missing device or missing register aborts the test and is reported as prerequisite_failed.
  2. Phase 2 — Initialization. Stop every available PCS, wait 10 seconds, then start every available PCS.
  3. Phase 3 — Test operation. Execute the model-specific read_soc action against every available PCS and decode the returned registers into a SOC percentage.
  4. Pass / fail. The test passes only when every attempted PCS read succeeded (successful == attempted).

Report output

The report (measurements) contains:

  • test_number (2) and test_name.
  • prerequisite_checks — per-PCS availability result.
  • initialization_events — stop / wait / start event log.
  • successful_pcs and attempted_pcs.
  • pcs_readings — per-PCS record with value_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