feat: circuit energy in session log for ERE reporting (Plan 14, Increment 5) (#110)

Add circuit_energy_wh to session_record_t. When CircuitMeter is active,
session JSON includes circuit_kwh field for ERE compliance verification.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: basmeerman

SmartEVSE-3/src/main.cpp

@@ -2432,6 +2432,9 @@ static void timer10ms_ev_metering(uint8_t oldState, uint8_t pilot_val) {
         EVMeter.ResetKwh = 1;                                               // reset EV kWh meter on next B->C change
         // End charge session on vehicle disconnect (A + 12V)
         if (session_is_active()) {
+            if (CircuitMeter.Type) {
+                session_set_circuit_energy(0, CircuitMeter.Import_active_energy);
+            }
             session_end((uint32_t)time(NULL), EVMeter.Import_active_energy,
                         (uint16_t)(Balanced[0]), Nr_Of_Phases_Charging);
 #if MQTT
@@ -2447,6 +2450,9 @@ static void timer10ms_ev_metering(uint8_t oldState, uint8_t pilot_val) {
         EVMeter.ResetKwh = 0;
         // Start charge session on B->C transition
         session_start((uint32_t)time(NULL), EVMeter.Import_active_energy, Mode);
+        if (CircuitMeter.Type) {
+            session_set_circuit_energy(CircuitMeter.Import_active_energy, 0);
+        }
     }
 }
 

SmartEVSE-3/src/session_log.c

@@ -73,6 +73,19 @@ void session_set_ocpp_id(uint32_t ocpp_transaction_id) {
     s_active.ocpp_active = 1;
 }
 
+void session_set_circuit_energy(int32_t start_wh, int32_t end_wh) {
+    if (!s_session_active) {
+        return;
+    }
+    if (start_wh != 0) {
+        s_active.circuit_start_energy_wh = start_wh;
+    }
+    if (end_wh != 0) {
+        s_active.circuit_end_energy_wh = end_wh;
+        s_active.circuit_energy_wh = end_wh - s_active.circuit_start_energy_wh;
+    }
+}
+
 uint8_t session_is_active(void) {
     return s_session_active;
 }
@@ -167,7 +180,7 @@ int session_to_json(const session_record_t *rec, char *buf, size_t bufsz) {
         "\"max_current_a\":%u.%u,"
         "\"phases\":%u,"
         "\"mode\":\"%s\","
-        "\"ocpp_tx_id\":%s}",
+        "\"ocpp_tx_id\":%s",
         (unsigned)rec->session_id,
         start_iso,
         end_iso,
@@ -180,9 +193,31 @@ int session_to_json(const session_record_t *rec, char *buf, size_t bufsz) {
         ocpp_field);
 
     if (n < 0 || (size_t)n >= bufsz) {
-        /* Buffer too small — output was truncated */
         return -1;
     }
 
+    /* Append circuit_kwh when CircuitMeter was active */
+    if (rec->circuit_energy_wh != 0) {
+        int32_t ckwh_int = rec->circuit_energy_wh / 1000;
+        int32_t ckwh_frac = rec->circuit_energy_wh % 1000;
+        if (ckwh_frac < 0) ckwh_frac = -ckwh_frac;
+
+        int extra = snprintf(buf + n, bufsz - (size_t)n,
+            ",\"circuit_kwh\":%d.%03d}",
+            (int)ckwh_int, (int)ckwh_frac);
+        if (extra < 0 || (size_t)(n + extra) >= bufsz) {
+            return -1;
+        }
+        n += extra;
+    } else {
+        /* Close the JSON object */
+        if ((size_t)n + 1 >= bufsz) {
+            return -1;
+        }
+        buf[n] = '}';
+        n++;
+        buf[n] = '\0';
+    }
+
     return n;
 }

SmartEVSE-3/src/session_log.h

@@ -36,6 +36,9 @@ typedef struct {
     uint8_t  mode;                 /* MODE_NORMAL / MODE_SMART / MODE_SOLAR */
     uint8_t  ocpp_active;          /* Was OCPP controlling this session? */
     uint8_t  _reserved[3];         /* Alignment padding */
+    int32_t  circuit_start_energy_wh;  /* CircuitMeter energy at session start */
+    int32_t  circuit_end_energy_wh;    /* CircuitMeter energy at session end */
+    int32_t  circuit_energy_wh;        /* circuit end - start */
 } session_record_t;
 
 /* Initialize session logger state. Call once at startup. */
@@ -51,6 +54,11 @@ void session_end(uint32_t timestamp, int32_t end_energy_wh,
 /* Set OCPP transaction ID on the active session. No-op if no session active. */
 void session_set_ocpp_id(uint32_t ocpp_transaction_id);
 
+/* Set circuit energy on the active session. Call with start_wh at session start
+ * and end_wh at session end. Calculates circuit_energy_wh = end - start when
+ * end_wh > 0. No-op if no session active. */
+void session_set_circuit_energy(int32_t start_wh, int32_t end_wh);
+
 /* Returns 1 if a session is currently active, 0 otherwise. */
 uint8_t session_is_active(void);
 

SmartEVSE-3/test/native/tests/test_session_log.c

@@ -338,6 +338,93 @@ void test_session_zero_energy(void) {
     TEST_ASSERT_EQUAL_INT(0, last->energy_charged_wh);
 }
 
+/* ---- Circuit energy tests ---- */
+
+/*
+ * @feature Charge Session Logging
+ * @req REQ-CIR-020
+ * @scenario Session with circuit energy includes circuit_kwh in JSON
+ * @given A completed session with CircuitMeter energy set
+ * @when session_to_json is called
+ * @then JSON includes circuit_kwh field with correct value
+ */
+void test_session_circuit_energy_json(void) {
+    session_init();
+    session_start(1773930600, 142300, 0);
+    session_set_circuit_energy(200000, 0); /* start energy */
+    session_set_circuit_energy(0, 212345); /* end energy */
+    session_end(1773945900, 154645, 160, 3);
+
+    const session_record_t *last = session_get_last();
+    TEST_ASSERT_TRUE(last != NULL);
+    TEST_ASSERT_EQUAL_INT(200000, last->circuit_start_energy_wh);
+    TEST_ASSERT_EQUAL_INT(212345, last->circuit_end_energy_wh);
+    TEST_ASSERT_EQUAL_INT(12345, last->circuit_energy_wh);
+
+    int n = session_to_json(last, json_buf, sizeof(json_buf));
+    TEST_ASSERT_GREATER_THAN(0, n);
+    TEST_ASSERT_TRUE(strstr(json_buf, "\"circuit_kwh\":12.345") != NULL);
+}
+
+/*
+ * @feature Charge Session Logging
+ * @req REQ-CIR-021
+ * @scenario Session without circuit energy omits circuit_kwh from JSON
+ * @given A completed session without CircuitMeter energy
+ * @when session_to_json is called
+ * @then JSON does not include circuit_kwh field
+ */
+void test_session_no_circuit_energy_json(void) {
+    session_init();
+    session_start(1773930600, 142300, 0);
+    session_end(1773945900, 154645, 160, 3);
+
+    const session_record_t *last = session_get_last();
+    TEST_ASSERT_TRUE(last != NULL);
+    TEST_ASSERT_EQUAL_INT(0, last->circuit_energy_wh);
+
+    int n = session_to_json(last, json_buf, sizeof(json_buf));
+    TEST_ASSERT_GREATER_THAN(0, n);
+    TEST_ASSERT_TRUE(strstr(json_buf, "circuit_kwh") == NULL);
+}
+
+/*
+ * @feature Charge Session Logging
+ * @req REQ-CIR-022
+ * @scenario Circuit energy calculation: end minus start
+ * @given A session with circuit start=100000 and circuit end=107500
+ * @when The session ends
+ * @then circuit_energy_wh equals 7500
+ */
+void test_session_circuit_energy_calculation(void) {
+    session_init();
+    session_start(1710000000, 50000, 2);
+    session_set_circuit_energy(100000, 0);
+    session_set_circuit_energy(0, 107500);
+    session_end(1710001000, 55000, 80, 1);
+
+    const session_record_t *last = session_get_last();
+    TEST_ASSERT_TRUE(last != NULL);
+    TEST_ASSERT_EQUAL_INT(100000, last->circuit_start_energy_wh);
+    TEST_ASSERT_EQUAL_INT(107500, last->circuit_end_energy_wh);
+    TEST_ASSERT_EQUAL_INT(7500, last->circuit_energy_wh);
+}
+
+/*
+ * @feature Charge Session Logging
+ * @req REQ-CIR-023
+ * @scenario session_set_circuit_energy with no active session is ignored
+ * @given No active session
+ * @when session_set_circuit_energy is called
+ * @then No crash and no state change
+ */
+void test_session_set_circuit_energy_no_active(void) {
+    session_init();
+    session_set_circuit_energy(100000, 0);
+    TEST_ASSERT_FALSE(session_is_active());
+    TEST_ASSERT_TRUE(session_get_last() == NULL);
+}
+
 /* ---- NTP time validity guard tests ---- */
 
 /*
@@ -443,6 +530,12 @@ int main(void) {
     RUN_TEST(test_session_json_smart_mode);
     RUN_TEST(test_session_zero_energy);
 
+    /* Circuit energy tests */
+    RUN_TEST(test_session_circuit_energy_json);
+    RUN_TEST(test_session_no_circuit_energy_json);
+    RUN_TEST(test_session_circuit_energy_calculation);
+    RUN_TEST(test_session_set_circuit_energy_no_active);
+
     /* Minimum duration filter tests */
     RUN_TEST(test_session_short_duration_discarded);
     RUN_TEST(test_session_exact_min_duration_kept);

docs/configuration.md

@@ -195,6 +195,57 @@ If [CONFIG](#config) is set to **Fixed**, configure MAX to be lower than or equa
 
 Set the max current of the EVSE circuit: 10-160A per phase. When power sharing, this is the total current that will be split between connected and charging EVs.
 
+## CircuitMeter
+
+CircuitMeter is a third energy meter that monitors a subpanel circuit feeding the
+EVSE. It provides subpanel breaker protection and circuit-level energy data for ERE
+compliance. See [Features — CircuitMeter](features.md#circuitmeter--subpanel-metering)
+for background.
+
+CircuitMeter is configured via the web UI, REST API, or MQTT — it does not appear
+in the LCD menu.
+
+### CircuitMeter type
+
+Set the meter type for the circuit meter. Uses the same meter type list as
+MAINS MET and EV METER (Eastron, ABB, Finder, Orno, Custom, API, etc.).
+
+- **0** (default): Disabled — no circuit meter, zero runtime cost.
+- **1-19**: A supported Modbus energy meter type (same IDs as MAINS MET).
+- **9 (API)**: Circuit meter data is fed externally via MQTT (`Set/CircuitMeter`)
+  or REST API (`/currents` with `circuit_L1`, `circuit_L2`, `circuit_L3` params).
+
+**REST API:** `circuit_meter_type` field in GET/POST `/settings`
+**MQTT:** Not directly settable via MQTT (use REST API or web UI)
+**NVS key:** `CircuitMeter` (uint8_t)
+
+### CircuitMeter address
+
+Modbus address for the circuit meter: 10-247. Only relevant when CircuitMeter type
+is a Modbus meter (not Disabled or API).
+
+- **Default:** 14
+
+**REST API:** `circuit_meter_address` field in GET/POST `/settings`
+**NVS key:** `CirMeterAddr` (uint8_t)
+
+### MaxCircuitMains
+
+Maximum current allowed on the subpanel circuit (sum of all phases is per-phase,
+same convention as MAINS): 0-600A.
+
+- **0** (default): Disabled — no circuit current limiting.
+- **10-600**: Maximum current in Amperes per phase. SmartEVSE will reduce charging
+  current so that `CircuitMeter` measured current stays below this value.
+
+When both `MaxCircuitMains` and `MaxMains` are configured, the most restrictive
+limit applies.
+
+**REST API:** `max_circuit_mains` field in GET/POST `/settings`
+**MQTT:** `Set/MaxCircuitMains` (integer, 0-600)
+**NVS key:** `MaxCirMains` (uint16_t)
+**HA entity:** `Max Circuit Mains` (number, settable)
+
 ## START
 > Visible when: MODE = Solar, AND PWR SHARE = Disabled or Master
 

docs/ere-session-logging.md

@@ -136,6 +136,52 @@ mqtt:
 
 Replace `SmartEVSE-XXXX` with your device's MQTT prefix.
 
+## Circuit energy for ERE Path B
+
+When a [CircuitMeter](features.md#circuitmeter--subpanel-metering) is configured
+and active during a charge session, the session JSON includes a `circuit_kwh` field
+representing the total energy measured on the subpanel circuit during the session.
+
+### Payload with circuit energy
+
+```json
+{
+  "session_id": 1,
+  "start": "2026-03-19T14:30:00Z",
+  "end": "2026-03-19T18:45:00Z",
+  "kwh": 12.345,
+  "start_energy_wh": 142300,
+  "end_energy_wh": 154645,
+  "circuit_kwh": 12.380,
+  "max_current_a": 16.0,
+  "phases": 3,
+  "mode": "solar",
+  "ocpp_tx_id": null
+}
+```
+
+The `circuit_kwh` field is only present when CircuitMeter is enabled and has
+non-zero energy data. When CircuitMeter is disabled, the field is omitted.
+
+### ERE Path B compliance
+
+ERE Path B requires an "exclusief bemeterd allocatiepunt" — a separately metered
+circuit that exclusively feeds the charger. The CircuitMeter enables verification:
+
+- If `circuit_kwh` approximately equals `kwh` (within meter tolerance, typically
+  1-2% for MID Class B meters), the circuit exclusively feeds the charger. No
+  other loads consumed energy during the session.
+- If `circuit_kwh` is significantly higher than `kwh`, other loads are present on
+  the circuit. The circuit is not exclusive, and Path B may not apply.
+
+This comparison can be automated in Home Assistant or your ERE reporting workflow.
+The tolerance should account for meter accuracy class and any standby consumption
+of the EVSE itself.
+
+**Note:** Increment 5 (session log integration) implements the `circuit_kwh` field.
+If you are on a firmware version before that increment, the field will not be
+present in session JSON output.
+
 ## OCPP alignment
 
 When OCPP is active, charge sessions are aligned with OCPP transactions:

docs/features.md

@@ -283,6 +283,47 @@ Configuration: [MQTT & Home Assistant](mqtt-home-assistant.md) (capacity topics)
 
 ---
 
+## CircuitMeter — Subpanel Metering
+
+*New in this fork.*
+
+A third energy meter instance for monitoring subpanel circuits. CircuitMeter
+addresses two needs:
+
+- **Subpanel breaker protection** — limits EV charging current so the total
+  subpanel load stays below the breaker rating (`MaxCircuitMains`). Without this,
+  other loads on the same subpanel (heat pump, dryer) can cause the breaker to trip
+  during charging.
+- **ERE 2027 compliance support** — provides circuit-level energy measurement for
+  Dutch ERE Path B verification. If `circuit_kwh` matches `session_kwh` in the
+  session log, the circuit exclusively feeds the charger.
+
+**Key design points:**
+
+- Reuses the existing `Meter` class — supports all 19 meter types (Eastron, ABB,
+  Finder, Orno, Custom, etc.) with zero new meter code
+- Zero runtime cost when disabled (`CircuitMeter` type = 0, the default)
+- Integrates with load balancing: `MaxCircuitMains` acts as an additional current
+  constraint alongside `MaxMains` and `MaxCircuit`
+- Full MQTT + Home Assistant auto-discovery for circuit current, power, and energy
+- API/MQTT external feed supported (`Set/CircuitMeter` with `L1:L2:L3` format)
+
+**Typical wiring:**
+
+```
+Grid meter ─── Main panel ─── [CircuitMeter] ─── Subpanel
+                   │                                 ├── EVSE (EVMeter)
+                   │                                 └── Other loads (heat pump, etc.)
+                   ├── Kitchen
+                   └── Lighting
+```
+
+Configuration: [Configuration](configuration.md#circuitmeter),
+[MQTT topics](mqtt-home-assistant.md#circuitmeter-topics),
+[Power Input Methods](power-input-methods.md)
+
+---
+
 ## ERE Session Logging
 
 *New in this fork.*