feat: MQTT, REST, HA discovery for CircuitMeter (Plan 14, Increment 4) (#109)

basmeerman · claude · basmeerman · commit c9b38ffa6ee9 · 2026-03-25T23:38:25.000+01:00
Publish circuit current/power/energy via MQTT with HA auto-discovery.
Add Set/MaxCircuitMains and Set/CircuitMeter topics. REST /settings
integration for circuit meter configuration.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/SmartEVSE-3/src/esp32.cpp b/SmartEVSE-3/src/esp32.cpp
@@ -837,6 +837,28 @@ void mqtt_receive_callback(const String topic, const String payload) {
             break;
         // END PLAN-09
 
+        // BEGIN PLAN-14: CircuitMeter MQTT commands
+        case MQTT_CMD_MAX_CIRCUIT_MAINS:
+            if (LoadBl < 2)
+                MaxCircuitMains = cmd.max_circuit_mains;
+            break;
+
+        case MQTT_CMD_CIRCUIT_METER:
+            if (CircuitMeter.Type != EM_API || LoadBl >= 2)
+                return;
+#if SMARTEVSE_VERSION < 40
+            CircuitMeter.setTimeout(COMM_TIMEOUT);
+            CircuitMeter.Irms[0] = cmd.circuit_meter.L1;
+            CircuitMeter.Irms[1] = cmd.circuit_meter.L2;
+            CircuitMeter.Irms[2] = cmd.circuit_meter.L3;
+            CircuitMeter.CalcImeasured();
+#else
+            Serial1.printf("@Irms:%03u,%d,%d,%d\n", CircuitMeter.Address,
+                           (int)cmd.circuit_meter.L1, (int)cmd.circuit_meter.L2, (int)cmd.circuit_meter.L3);
+#endif
+            break;
+        // END PLAN-14
+
         // BEGIN PLAN-09: HomeWizard manual IP fallback
         case MQTT_CMD_HOMEWIZARD_IP:
             homeWizardManualIP = cmd.homewizard_ip;
@@ -1029,6 +1051,29 @@ void SetupMQTTClient() {
         MQTTclient.announce("EV Total Energy Charged", "sensor", optional_payload);
     }
 
+    // BEGIN PLAN-14: CircuitMeter HA discovery
+    if (CircuitMeter.Type) {
+        // Circuit current sensors
+        optional_payload = MQTTclient.jsna("device_class","current") + MQTTclient.jsna("state_class","measurement") + MQTTclient.jsna("unit_of_measurement","A") + MQTTclient.jsna("value_template", R"({{ value | int / 10 }})");
+        MQTTclient.announce("Circuit Current L1", "sensor", optional_payload);
+        MQTTclient.announce("Circuit Current L2", "sensor", optional_payload);
+        MQTTclient.announce("Circuit Current L3", "sensor", optional_payload);
+
+        // Circuit power sensor
+        optional_payload = MQTTclient.jsna("device_class","power") + MQTTclient.jsna("state_class","measurement") + MQTTclient.jsna("unit_of_measurement","W");
+        MQTTclient.announce("Circuit Power", "sensor", optional_payload);
+
+        // Circuit energy sensors
+        optional_payload = MQTTclient.jsna("device_class","energy") + MQTTclient.jsna("unit_of_measurement","Wh") + MQTTclient.jsna("state_class","total_increasing");
+        MQTTclient.announce("Circuit Import Energy", "sensor", optional_payload);
+        MQTTclient.announce("Circuit Export Energy", "sensor", optional_payload);
+    }
+
+    // MaxCircuitMains number entity (always announced, even when CircuitMeter disabled)
+    optional_payload = MQTTclient.jsna("device_class","current") + MQTTclient.jsna("unit_of_measurement","A") + MQTTclient.jsna("command_topic", String(MQTTprefix + "/Set/MaxCircuitMains")) + MQTTclient.jsna("min", "0") + MQTTclient.jsna("max", "600") + MQTTclient.jsna("mode","box");
+    MQTTclient.announce("Max Circuit Mains", "number", optional_payload);
+    // END PLAN-14
+
     //set the parameters for and MQTTclient.announce sensor entities without device_class or unit_of_measurement:
     optional_payload = "";
     MQTTclient.announce("EV Plug State", "sensor", optional_payload);
@@ -1241,6 +1286,19 @@ void mqttPublishData() {
             if (EVMeter.EnergyPhase[2] > 0)
                 mqtt_pub_int(MQTT_SLOT_EV_ENERGY_L3, "/EVEnergyL3", EVMeter.EnergyPhase[2], false, now_s);
         }
+        // BEGIN PLAN-14: CircuitMeter publishing
+        if (CircuitMeter.Type) {
+            mqtt_pub_int(MQTT_SLOT_CIRCUIT_L1, "/CircuitCurrentL1", CircuitMeter.Irms[0], false, now_s);
+            mqtt_pub_int(MQTT_SLOT_CIRCUIT_L2, "/CircuitCurrentL2", CircuitMeter.Irms[1], false, now_s);
+            mqtt_pub_int(MQTT_SLOT_CIRCUIT_L3, "/CircuitCurrentL3", CircuitMeter.Irms[2], false, now_s);
+            mqtt_pub_int(MQTT_SLOT_CIRCUIT_POWER, "/CircuitPower", CircuitMeter.PowerMeasured, false, now_s);
+            if (CircuitMeter.Import_active_energy > 0)
+                mqtt_pub_int(MQTT_SLOT_CIRCUIT_IMPORT_ENERGY, "/CircuitImportEnergy", CircuitMeter.Import_active_energy, false, now_s);
+            if (CircuitMeter.Export_active_energy > 0)
+                mqtt_pub_int(MQTT_SLOT_CIRCUIT_EXPORT_ENERGY, "/CircuitExportEnergy", CircuitMeter.Export_active_energy, false, now_s);
+        }
+        mqtt_pub_int(MQTT_SLOT_MAX_CIRCUIT_MAINS, "/MaxCircuitMains", MaxCircuitMains, true, now_s);
+        // END PLAN-14
         mqtt_pub_int(MQTT_SLOT_ESP_TEMP, "/ESPTemp", TempEVSE, false, now_s);
         mqtt_pub_str(MQTT_SLOT_MODE, "/Mode", AccessStatus == OFF ? "Off" : AccessStatus == PAUSE ? "Pause" : Mode > 3 ? "N/A" : StrMode[Mode], true, now_s);
         mqtt_pub_int(MQTT_SLOT_MAX_CURRENT, "/MaxCurrent", MaxCurrent * 10, true, now_s);
diff --git a/SmartEVSE-3/src/http_handlers.cpp b/SmartEVSE-3/src/http_handlers.cpp
@@ -63,6 +63,7 @@ extern capacity_state_t CapacityState;
 extern uint16_t MaxCurrent;
 extern uint16_t MinCurrent;
 extern uint16_t MaxCircuit;
+extern uint16_t MaxCircuitMains;
 extern uint16_t StartCurrent;
 extern uint16_t StopTime;
 extern uint16_t ImportCurrent;
@@ -166,7 +167,7 @@ bool handle_URI(struct mg_connection *c, struct mg_http_message *hm,  webServerR
 
         boolean evConnected = pilot != PILOT_12V;                    //when access bit = 1, p.ex. in OFF mode, the STATEs are no longer updated
 
-        DynamicJsonDocument doc(3700); // https://arduinojson.org/v6/assistant/ (3200 + nodes array)
+        DynamicJsonDocument doc(4096); // https://arduinojson.org/v6/assistant/ (3200 + nodes + circuit_meter)
         doc["version"] = String(VERSION);
         doc["serialnr"] = serialnr;
         doc["mode"] = mode;
@@ -223,6 +224,9 @@ bool handle_URI(struct mg_connection *c, struct mg_http_message *hm,  webServerR
         doc["settings"]["current_main"] = MaxMains;
         doc["settings"]["current_max_circuit"] = MaxCircuit;
         doc["settings"]["current_max_sum_mains"] = MaxSumMains;
+        doc["settings"]["circuit_meter_type"] = CircuitMeter.Type;
+        doc["settings"]["circuit_meter_address"] = CircuitMeter.Address;
+        doc["settings"]["max_circuit_mains"] = MaxCircuitMains;
         doc["settings"]["max_sum_mains_time"] = MaxSumMainsTime;
         doc["settings"]["solar_max_import"] = ImportCurrent;
         doc["settings"]["solar_start_current"] = StartCurrent;
@@ -344,6 +348,20 @@ bool handle_URI(struct mg_connection *c, struct mg_http_message *hm,  webServerR
             doc["mains_meter"]["host"] = !homeWizardHost.isEmpty() ? homeWizardHost : "HomeWizard P1 Not Found";
         }
 
+        // BEGIN PLAN-14: CircuitMeter data in /settings GET
+        if (CircuitMeter.Type) {
+            doc["circuit_meter"]["description"] = EMConfig[CircuitMeter.Type].Desc;
+            doc["circuit_meter"]["address"] = CircuitMeter.Address;
+            doc["circuit_meter"]["import_active_energy"] = CircuitMeter.Import_active_energy;
+            doc["circuit_meter"]["export_active_energy"] = CircuitMeter.Export_active_energy;
+            doc["circuit_meter"]["power"] = CircuitMeter.PowerMeasured;
+            doc["circuit_meter"]["currents"]["TOTAL"] = CircuitMeter.Irms[0] + CircuitMeter.Irms[1] + CircuitMeter.Irms[2];
+            doc["circuit_meter"]["currents"]["L1"] = CircuitMeter.Irms[0];
+            doc["circuit_meter"]["currents"]["L2"] = CircuitMeter.Irms[1];
+            doc["circuit_meter"]["currents"]["L3"] = CircuitMeter.Irms[2];
+        }
+        // END PLAN-14
+
         doc["phase_currents"]["TOTAL"] = MainsMeter.Irms[0] + MainsMeter.Irms[1] + MainsMeter.Irms[2];
         doc["phase_currents"]["L1"] = MainsMeter.Irms[0];
         doc["phase_currents"]["L2"] = MainsMeter.Irms[1];
@@ -431,6 +449,18 @@ bool handle_URI(struct mg_connection *c, struct mg_http_message *hm,  webServerR
             }
         }
 
+        // BEGIN PLAN-14: MaxCircuitMains via REST
+        if(request->hasParam("max_circuit_mains")) {
+            int current = request->getParam("max_circuit_mains")->value().toInt();
+            if (LoadBl < 2 && (current == 0 || (current >= 10 && current <= 600))) {
+                MaxCircuitMains = current;
+                doc["max_circuit_mains"] = MaxCircuitMains;
+            } else {
+                doc["max_circuit_mains"] = "Value not allowed!";
+            }
+        }
+        // END PLAN-14
+
         if(request->hasParam("max_sum_mains_timer")) {
             int time = request->getParam("max_sum_mains_timer")->value().toInt();
             if(time >= 0 && time <= 60 && LoadBl < 2) {
@@ -896,6 +926,28 @@ bool handle_URI(struct mg_connection *c, struct mg_http_message *hm,  webServerR
             }
         }
 
+        // BEGIN PLAN-14: CircuitMeter API feed via /currents POST
+        if(CircuitMeter.Type == EM_API) {
+            if(request->hasParam("circuit_L1") && request->hasParam("circuit_L2") && request->hasParam("circuit_L3")) {
+                if (LoadBl < 2) {
+#if SMARTEVSE_VERSION < 40 //v3
+                    CircuitMeter.Irms[0] = request->getParam("circuit_L1")->value().toInt();
+                    CircuitMeter.Irms[1] = request->getParam("circuit_L2")->value().toInt();
+                    CircuitMeter.Irms[2] = request->getParam("circuit_L3")->value().toInt();
+                    CircuitMeter.CalcImeasured();
+                    CircuitMeter.setTimeout(COMM_TIMEOUT);
+#else //v4
+                    Serial1.printf("@Irms:%03u,%d,%d,%d\n", CircuitMeter.Address, (int16_t) request->getParam("circuit_L1")->value().toInt(), (int16_t) request->getParam("circuit_L2")->value().toInt(), (int16_t) request->getParam("circuit_L3")->value().toInt());
+#endif
+                    for (int x = 0; x < 3; x++)
+                        doc["circuit"]["L" + x] = CircuitMeter.Irms[x];
+                    doc["circuit"]["TOTAL"] = CircuitMeter.Irms[0] + CircuitMeter.Irms[1] + CircuitMeter.Irms[2];
+                } else
+                    doc["circuit"]["TOTAL"] = "not allowed on slave";
+            }
+        }
+        // END PLAN-14
+
         String json;
         serializeJson(doc, json);
         mg_http_reply(c, 200, "Content-Type: application/json\r\n", "%s\r\n", json.c_str());    // Yes. Respond JSON
diff --git a/SmartEVSE-3/src/mqtt_parser.c b/SmartEVSE-3/src/mqtt_parser.c
@@ -360,6 +360,24 @@ bool mqtt_parse_command(const char *prefix, const char *topic,
         return true;
     }
 
+    /* CircuitMeter: max circuit mains current (0 = disabled, 10-600 A) */
+    if (match_topic(prefix, topic, "/Set/MaxCircuitMains")) {
+        out->cmd = MQTT_CMD_MAX_CIRCUIT_MAINS;
+        int val = atoi(payload);
+        if (val == 0 || (val >= 10 && val <= 600)) {
+            out->max_circuit_mains = (uint16_t)val;
+            return true;
+        }
+        return false;
+    }
+
+    /* CircuitMeter API feed: L1:L2:L3 format (same as MainsMeter) */
+    if (match_topic(prefix, topic, "/Set/CircuitMeter")) {
+        out->cmd = MQTT_CMD_CIRCUIT_METER;
+        return mqtt_parse_mains_meter(payload, &out->circuit_meter.L1,
+                                      &out->circuit_meter.L2, &out->circuit_meter.L3);
+    }
+
     if (match_topic(prefix, topic, "/Set/DiagProfile")) {
         out->cmd = MQTT_CMD_DIAG_PROFILE;
         if (strcmp(payload, "off") == 0 || strcmp(payload, "0") == 0) {
diff --git a/SmartEVSE-3/src/mqtt_parser.h b/SmartEVSE-3/src/mqtt_parser.h
@@ -38,6 +38,8 @@ typedef enum {
     MQTT_CMD_ENERGY_REQUEST,
     MQTT_CMD_EVCCID_SET,
     MQTT_CMD_CAPACITY_LIMIT,
+    MQTT_CMD_MAX_CIRCUIT_MAINS,
+    MQTT_CMD_CIRCUIT_METER,
 } mqtt_cmd_type_t;
 
 // Mode values matching firmware MODE_NORMAL/MODE_SOLAR/MODE_SMART
@@ -83,6 +85,8 @@ typedef struct {
         int32_t energy_capacity;                // MQTT_CMD_ENERGY_CAPACITY (-1 or 0-200000 Wh)
         int32_t energy_request;                 // MQTT_CMD_ENERGY_REQUEST (-1 or 0-200000 Wh)
         uint16_t capacity_limit;                // MQTT_CMD_CAPACITY_LIMIT (0=disabled, max 25000W)
+        uint16_t max_circuit_mains;             // MQTT_CMD_MAX_CIRCUIT_MAINS (0-600)
+        struct { int32_t L1, L2, L3; } circuit_meter; // MQTT_CMD_CIRCUIT_METER
     };
 } mqtt_command_t;
 
diff --git a/SmartEVSE-3/src/mqtt_publish.h b/SmartEVSE-3/src/mqtt_publish.h
@@ -9,7 +9,7 @@
 extern "C" {
 #endif
 
-#define MQTT_CACHE_MAX_SLOTS 88  /* 85 current topics + headroom */
+#define MQTT_CACHE_MAX_SLOTS 96  /* 92 current topics + headroom */
 
 /* One slot per published MQTT topic, in mqttPublishData() call order */
 typedef enum {
@@ -98,6 +98,13 @@ typedef enum {
     MQTT_SLOT_CAPACITY_WINDOW_AVG,
     MQTT_SLOT_CAPACITY_MONTHLY_PEAK,
     MQTT_SLOT_CAPACITY_HEADROOM,
+    MQTT_SLOT_CIRCUIT_L1,
+    MQTT_SLOT_CIRCUIT_L2,
+    MQTT_SLOT_CIRCUIT_L3,
+    MQTT_SLOT_CIRCUIT_POWER,
+    MQTT_SLOT_CIRCUIT_IMPORT_ENERGY,
+    MQTT_SLOT_CIRCUIT_EXPORT_ENERGY,
+    MQTT_SLOT_MAX_CIRCUIT_MAINS,
     MQTT_SLOT_COUNT  /* must be <= MQTT_CACHE_MAX_SLOTS */
 } mqtt_slot_t;
 
diff --git a/SmartEVSE-3/test/native/tests/test_mqtt_parser.c b/SmartEVSE-3/test/native/tests/test_mqtt_parser.c
@@ -1188,6 +1188,132 @@ void test_capacity_limit_non_numeric(void) {
     TEST_ASSERT_FALSE(mqtt_parse_command(PREFIX, PREFIX "/Set/CapacityLimit", "abc", &cmd));
 }
 
+// ---- MaxCircuitMains ----
+
+/*
+ * @feature MQTT Command Parsing
+ * @req REQ-CIR-010
+ * @scenario Set MaxCircuitMains to valid value via MQTT
+ * @given A valid MQTT prefix
+ * @when Topic is prefix/Set/MaxCircuitMains with payload "25"
+ * @then Command type is MQTT_CMD_MAX_CIRCUIT_MAINS with value 25
+ */
+void test_max_circuit_mains_valid(void) {
+    TEST_ASSERT_TRUE(mqtt_parse_command(PREFIX, PREFIX "/Set/MaxCircuitMains", "25", &cmd));
+    TEST_ASSERT_EQUAL_INT(MQTT_CMD_MAX_CIRCUIT_MAINS, cmd.cmd);
+    TEST_ASSERT_EQUAL_INT(25, cmd.max_circuit_mains);
+}
+
+/*
+ * @feature MQTT Command Parsing
+ * @req REQ-CIR-010
+ * @scenario Set MaxCircuitMains to zero (disable) via MQTT
+ * @given A valid MQTT prefix
+ * @when Topic is prefix/Set/MaxCircuitMains with payload "0"
+ * @then Command type is MQTT_CMD_MAX_CIRCUIT_MAINS with value 0
+ */
+void test_max_circuit_mains_zero(void) {
+    TEST_ASSERT_TRUE(mqtt_parse_command(PREFIX, PREFIX "/Set/MaxCircuitMains", "0", &cmd));
+    TEST_ASSERT_EQUAL_INT(MQTT_CMD_MAX_CIRCUIT_MAINS, cmd.cmd);
+    TEST_ASSERT_EQUAL_INT(0, cmd.max_circuit_mains);
+}
+
+/*
+ * @feature MQTT Command Parsing
+ * @req REQ-CIR-010
+ * @scenario Set MaxCircuitMains to boundary max (600) via MQTT
+ * @given A valid MQTT prefix
+ * @when Topic is prefix/Set/MaxCircuitMains with payload "600"
+ * @then Command type is MQTT_CMD_MAX_CIRCUIT_MAINS with value 600
+ */
+void test_max_circuit_mains_max(void) {
+    TEST_ASSERT_TRUE(mqtt_parse_command(PREFIX, PREFIX "/Set/MaxCircuitMains", "600", &cmd));
+    TEST_ASSERT_EQUAL_INT(MQTT_CMD_MAX_CIRCUIT_MAINS, cmd.cmd);
+    TEST_ASSERT_EQUAL_INT(600, cmd.max_circuit_mains);
+}
+
+/*
+ * @feature MQTT Input Validation
+ * @req REQ-CIR-010
+ * @scenario Reject MaxCircuitMains below minimum (1-9 range)
+ * @given A valid MQTT prefix
+ * @when Topic is prefix/Set/MaxCircuitMains with payload "5"
+ * @then Parsing returns false (gap between 0 and 10)
+ */
+void test_max_circuit_mains_below_min(void) {
+    TEST_ASSERT_FALSE(mqtt_parse_command(PREFIX, PREFIX "/Set/MaxCircuitMains", "5", &cmd));
+}
+
+/*
+ * @feature MQTT Input Validation
+ * @req REQ-CIR-010
+ * @scenario Reject MaxCircuitMains above maximum
+ * @given A valid MQTT prefix
+ * @when Topic is prefix/Set/MaxCircuitMains with payload "601"
+ * @then Parsing returns false
+ */
+void test_max_circuit_mains_above_max(void) {
+    TEST_ASSERT_FALSE(mqtt_parse_command(PREFIX, PREFIX "/Set/MaxCircuitMains", "601", &cmd));
+}
+
+// ---- CircuitMeter ----
+
+/*
+ * @feature MQTT Command Parsing
+ * @req REQ-CIR-011
+ * @scenario Set CircuitMeter API feed via MQTT with L1:L2:L3 format
+ * @given A valid MQTT prefix
+ * @when Topic is prefix/Set/CircuitMeter with payload "100:200:150"
+ * @then Command type is MQTT_CMD_CIRCUIT_METER with parsed phase currents
+ */
+void test_circuit_meter_valid(void) {
+    TEST_ASSERT_TRUE(mqtt_parse_command(PREFIX, PREFIX "/Set/CircuitMeter", "100:200:150", &cmd));
+    TEST_ASSERT_EQUAL_INT(MQTT_CMD_CIRCUIT_METER, cmd.cmd);
+    TEST_ASSERT_EQUAL_INT(100, cmd.circuit_meter.L1);
+    TEST_ASSERT_EQUAL_INT(200, cmd.circuit_meter.L2);
+    TEST_ASSERT_EQUAL_INT(150, cmd.circuit_meter.L3);
+}
+
+/*
+ * @feature MQTT Command Parsing
+ * @req REQ-CIR-011
+ * @scenario CircuitMeter API feed with negative values (export)
+ * @given A valid MQTT prefix
+ * @when Topic is prefix/Set/CircuitMeter with payload "-50:100:-25"
+ * @then Command type is MQTT_CMD_CIRCUIT_METER with correct phase currents
+ */
+void test_circuit_meter_negative(void) {
+    TEST_ASSERT_TRUE(mqtt_parse_command(PREFIX, PREFIX "/Set/CircuitMeter", "-50:100:-25", &cmd));
+    TEST_ASSERT_EQUAL_INT(MQTT_CMD_CIRCUIT_METER, cmd.cmd);
+    TEST_ASSERT_EQUAL_INT(-50, cmd.circuit_meter.L1);
+    TEST_ASSERT_EQUAL_INT(100, cmd.circuit_meter.L2);
+    TEST_ASSERT_EQUAL_INT(-25, cmd.circuit_meter.L3);
+}
+
+/*
+ * @feature MQTT Input Validation
+ * @req REQ-CIR-011
+ * @scenario Reject CircuitMeter with out of range values
+ * @given A valid MQTT prefix
+ * @when Topic is prefix/Set/CircuitMeter with payload "2001:0:0"
+ * @then Parsing returns false (exceeds +/-2000 dA range)
+ */
+void test_circuit_meter_out_of_range(void) {
+    TEST_ASSERT_FALSE(mqtt_parse_command(PREFIX, PREFIX "/Set/CircuitMeter", "2001:0:0", &cmd));
+}
+
+/*
+ * @feature MQTT Input Validation
+ * @req REQ-CIR-011
+ * @scenario Reject CircuitMeter with missing fields
+ * @given A valid MQTT prefix
+ * @when Topic is prefix/Set/CircuitMeter with payload "100:200"
+ * @then Parsing returns false (needs 3 fields)
+ */
+void test_circuit_meter_missing_fields(void) {
+    TEST_ASSERT_FALSE(mqtt_parse_command(PREFIX, PREFIX "/Set/CircuitMeter", "100:200", &cmd));
+}
+
 // ---- Unrecognized topic ----
 
 /*
@@ -1351,6 +1477,19 @@ int main(void) {
     RUN_TEST(test_capacity_limit_empty);
     RUN_TEST(test_capacity_limit_non_numeric);
 
+    // MaxCircuitMains (Plan 14)
+    RUN_TEST(test_max_circuit_mains_valid);
+    RUN_TEST(test_max_circuit_mains_zero);
+    RUN_TEST(test_max_circuit_mains_max);
+    RUN_TEST(test_max_circuit_mains_below_min);
+    RUN_TEST(test_max_circuit_mains_above_max);
+
+    // CircuitMeter (Plan 14)
+    RUN_TEST(test_circuit_meter_valid);
+    RUN_TEST(test_circuit_meter_negative);
+    RUN_TEST(test_circuit_meter_out_of_range);
+    RUN_TEST(test_circuit_meter_missing_fields);
+
     // Unrecognized
     RUN_TEST(test_unrecognized_topic);
     RUN_TEST(test_wrong_prefix);
