Skip to content

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.

  1. Model action read_soh must be defined in emsConfig/pcs/power_sequences/<MODEL>.json for each PCS model that will be tested. The action must contain at least one Modbus read step (holding or input register) with the correct address, count, encoding, scale and offset so the raw register decodes to a SOH percentage.

  2. PCS device configuration in ems_control_setting.json — each PCS entry must have:

  3. status set to anything other than inactive / disabled / off / false / 0;
  4. a device.model (or model) value;
  5. an IP/host (ip, ip_address, host or hostname);
  6. port (default 502) and Modbus unit_id (default 1).

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 (pymodbus ModbusTcpClient.connect() succeeds).
  • The PCS model resolves to a sequence file containing the read_soh action.
  • Every register required by read_soh 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_soh 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. This guarantees a known starting state before any measurement.
  3. Phase 3 — Test operation. Execute the model-specific read_soh action against every available PCS and decode the returned registers into a SOH percentage.
  4. Pass / fail. The test passes only when every attempted PCS read succeeded (successful == attempted).

Report output

The report (measurements) contains:

  • test_number (1) 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 (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