Diagnostic Test 01 — State of Health (SOH) Estimation
| Mode number | 1 |
| Registered handler | state_of_health → _run_test_01_soh_estimation in ems_diagnostic_handlers.py |
| Model action | read_soh (in emsConfig/pcs/power_sequences/<MODEL>.json) |
| Result metric | SOH (%) |
Theory
State of Health (SOH) expresses how much of the battery's original capacity and performance remains. A new cell has SOH = 100 %; as the battery ages it loses usable capacity, so a pack that can only deliver 80 % of its rated capacity has SOH ≈ 80 %.
SOH is commonly estimated from one or more of:
- Capacity ratio — measured full-charge capacity divided by the rated (reference) capacity of the battery.
- Impedance / internal-resistance growth — resistance rises as cells age; this is measured separately by Diagnostic Test 04.
- Coulomb counting vs reference — integrating current over a full charge/discharge cycle and comparing the extracted energy against the reference capacity.
In this EMS the SOH value is read directly from the PCS / BESS management
interface rather than computed locally. Each active PCS exposes a read_soh
model action that returns the BMS-reported SOH, so the test verifies that the
EMS can obtain a valid SOH figure for every connected PCS.
Settings needed
There are no JSON parameters for Test 01 — it only needs the model action to exist and be reachable.
-
Model action
read_sohmust be defined inemsConfig/pcs/power_sequences/<MODEL>.jsonfor each PCS model that will be tested. The action must contain at least one Modbus read step (holding or input register) with the correctaddress,count,encoding,scaleandoffsetso the raw register decodes to a SOH percentage. -
PCS device configuration in
ems_control_setting.json— each PCS entry must have: statusset to anything other thaninactive/disabled/off/false/0;- a
device.model(ormodel) value; - an IP/host (
ip,ip_address,hostorhostname); port(default502) and Modbusunit_id(default1).
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
(
pymodbusModbusTcpClient.connect()succeeds). - The PCS model resolves to a sequence file containing the
read_sohaction. - Every register required by
read_sohexists 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_sohis 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. This guarantees a known starting state before any measurement.
- Phase 3 — Test operation. Execute the model-specific
read_sohaction against every available PCS and decode the returned registers into a SOH percentage. - Pass / fail. The test passes only when every attempted PCS read
succeeded (
successful == attempted).
Report output
The report (measurements) contains:
test_number(1) 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(SOH %), register address, encoding, scale and raw registers.
A bar graph (soh-by-pcs) plots SOH (%) per PCS.
Pass / fail summary
| Result | Condition |
|---|---|
pass |
Every available PCS returned a valid SOH 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 |