@alteriom/painlessmesh 1.10.0 → 2.0.0

package/examples/alteriom/README.md

@@ -44,7 +44,7 @@ Extended status package with comprehensive health metrics (18 fields).
 - `avgLatency`, `packetLossRate`, `throughput` - Performance metrics
 - `alertFlags`, `lastError` - Alert system
 
-### MetricsPackage (Type 204) - NEW in v1.7.7
+### MetricsPackage (Type 204)
 Comprehensive performance metrics for detailed monitoring and dashboards.
 
 **Key Fields:**
@@ -61,7 +61,7 @@ Comprehensive performance metrics for detailed monitoring and dashboards.
 - Network throughput analysis
 - Latency monitoring
 
-### HealthCheckPackage (Type 605) - NEW in v1.7.7
+### HealthCheckPackage (Type 605)
 Proactive health monitoring with problem detection and recommendations.
 
 **Key Fields:**
@@ -93,7 +93,7 @@ Proactive health monitoring with problem detection and recommendations.
 - Automated alerting
 - Memory leak detection
 
-### MeshNodeListPackage (Type 600) - NEW in v1.7.7
+### MeshNodeListPackage (Type 600)
 List of all nodes in the mesh network with their status.
 
 **Fields:**
@@ -110,7 +110,7 @@ List of all nodes in the mesh network with their status.
 - Network health visualization
 - Device inventory management
 
-### MeshTopologyPackage (Type 601) - NEW in v1.7.7
+### MeshTopologyPackage (Type 601)
 Mesh network topology with all connections between nodes.
 
 **Fields:**
@@ -128,7 +128,7 @@ Mesh network topology with all connections between nodes.
 - Network optimization
 - Path analysis
 
-### MeshAlertPackage (Type 602) - NEW in v1.7.7
+### MeshAlertPackage (Type 602)
 Mesh network alerts for critical events and warnings.
 
 **Fields:**
@@ -147,7 +147,7 @@ Mesh network alerts for critical events and warnings.
 - Problem notification
 - Event logging
 
-### MeshBridgePackage (Type 603) - NEW in v1.7.7
+### MeshBridgePackage (Type 603)
 Bridge package for encapsulating native mesh protocol messages.
 
 **Fields:**
@@ -184,7 +184,7 @@ OTA enhancement example demonstrating:
 - Alert system implementation
 - Usage patterns for advanced features
 
-### `metrics_health_node.ino` (NEW in v1.7.7)
+### `metrics_health_node.ino`
 Comprehensive monitoring node example demonstrating:
 - MetricsPackage (Type 204) collection and broadcasting
 - HealthCheckPackage (Type 605) proactive monitoring (MESH_METRICS)
@@ -278,9 +278,7 @@ This validates:
 
 For developers adding new configuration fields to Alteriom packages:
 
-- **[API Design Guidelines](../../docs/API_DESIGN_GUIDELINES.md)** - Comprehensive guide on when to use nested vs flat JSON structures
 - **[Time Field Naming Convention](alteriom_sensor_package.hpp#L10-L55)** - How to handle time-based fields (ms/s variants)
-- **[Boolean Naming Convention](../../docs/BOOLEAN_NAMING_CONVENTION.md)** - Consistent patterns for boolean fields (*Set, *Enabled, is*)
 - **[JSON Structure Guidelines](alteriom_sensor_package.hpp#L57-L121)** - Quick reference for nesting patterns
 
-These guidelines ensure consistency and maintainability across all Alteriom packages.
+These guidelines ensure consistency and maintainability across all Alteriom packages.

package/examples/alteriom/alteriom.ino

@@ -90,7 +90,7 @@ void handleStatusRequest() {
   status.uptime = millis() / 1000;
   status.freeMemory = ESP.getFreeHeap() / 1024;  // KB
   status.wifiStrength = 75;                      // Placeholder
-  status.firmwareVersion = "1.0.0-alteriom";
+  status.firmwareVersion = "2.0.0";
 
   // Serialize and send (using ArduinoJson v7 API)
   JsonDocument doc;
@@ -184,4 +184,4 @@ void changedConnectionCallback() { Serial.printf("Changed connections\n"); }
 
 void nodeTimeAdjustedCallback(int32_t offset) {
   Serial.printf("Adjusted time %u. Offset = %d\n", mesh.getNodeTime(), offset);
-}
+}

package/examples/alteriom/alteriom_sensor_package.hpp

@@ -1233,7 +1233,7 @@ class BridgeStatusPackage : public painlessmesh::plugin::BroadcastPackage {
  *
  * Election process:
  * 1. Bridge failure detected (no heartbeat for 60+ seconds)
- * 2. Nodes broadcast BridgeElectionPackage with their router RSSI
+ * 2. Nodes broadcast BridgeElectionPackage with router RSSI and channel
  * 3. 5-second collection window for all candidates
  * 4. Each node evaluates all candidates locally (deterministic)
  * 5. Winner promotes itself to bridge, others remain as regular nodes
@@ -1242,11 +1242,12 @@ class BridgeStatusPackage : public painlessmesh::plugin::BroadcastPackage {
  */
 class BridgeElectionPackage : public painlessmesh::plugin::BroadcastPackage {
  public:
-  int8_t routerRSSI = 0;    // Router WiFi signal strength in dBm (-127 to 0)
-  uint32_t uptime = 0;      // Node uptime in milliseconds
-  uint32_t freeMemory = 0;  // Free memory in bytes
-  uint32_t timestamp = 0;   // Election timestamp
-  TSTRING routerSSID = "";  // Router SSID (for verification)
+  int8_t routerRSSI = 0;      // Router WiFi signal strength in dBm (-127 to 0)
+  uint8_t routerChannel = 0;  // Channel the candidate would use as bridge
+  uint32_t uptime = 0;        // Node uptime in milliseconds
+  uint32_t freeMemory = 0;    // Free memory in bytes
+  uint32_t timestamp = 0;     // Election timestamp
+  TSTRING routerSSID = "";    // Router SSID (for verification)
 
   // MQTT Schema v0.7.3+ message_type
   uint16_t messageType = 611;  // BRIDGE_ELECTION
@@ -1255,6 +1256,7 @@ class BridgeElectionPackage : public painlessmesh::plugin::BroadcastPackage {
 
   BridgeElectionPackage(JsonObject jsonObj) : BroadcastPackage(jsonObj) {
     routerRSSI = jsonObj["routerRSSI"] | 0;
+    routerChannel = jsonObj["routerChannel"] | 0;
     uptime = jsonObj["uptime"] | 0;
     freeMemory = jsonObj["freeMemory"] | 0;
     timestamp = jsonObj["timestamp"] | 0;
@@ -1265,6 +1267,7 @@ class BridgeElectionPackage : public painlessmesh::plugin::BroadcastPackage {
   JsonObject addTo(JsonObject&& jsonObj) const {
     jsonObj = BroadcastPackage::addTo(std::move(jsonObj));
     jsonObj["routerRSSI"] = routerRSSI;
+    jsonObj["routerChannel"] = routerChannel;
     jsonObj["uptime"] = uptime;
     jsonObj["freeMemory"] = freeMemory;
     jsonObj["timestamp"] = timestamp;
@@ -1275,7 +1278,7 @@ class BridgeElectionPackage : public painlessmesh::plugin::BroadcastPackage {
 
 #if ARDUINOJSON_VERSION_MAJOR < 7
   size_t jsonObjectSize() const {
-    return JSON_OBJECT_SIZE(noJsonFields + 6) + routerSSID.length();
+    return JSON_OBJECT_SIZE(noJsonFields + 7) + routerSSID.length();
   }
 #endif
 };
@@ -1294,8 +1297,9 @@ class BridgeTakeoverPackage : public painlessmesh::plugin::BroadcastPackage {
   uint32_t previousBridge = 0;  // Previous bridge node ID (0 if none)
   TSTRING reason =
       "";  // Reason for takeover (e.g., "Election winner - best router signal")
-  int8_t routerRSSI = 0;   // New bridge's router signal strength
-  uint32_t timestamp = 0;  // Takeover timestamp
+  int8_t routerRSSI = 0;      // New bridge's router signal strength
+  uint8_t routerChannel = 0;  // Channel peers follow during takeover
+  uint32_t timestamp = 0;     // Takeover timestamp
 
   // MQTT Schema v0.7.3+ message_type
   uint16_t messageType = 612;  // BRIDGE_TAKEOVER
@@ -1306,6 +1310,7 @@ class BridgeTakeoverPackage : public painlessmesh::plugin::BroadcastPackage {
     previousBridge = jsonObj["previousBridge"] | 0;
     reason = jsonObj["reason"].as<TSTRING>();
     routerRSSI = jsonObj["routerRSSI"] | 0;
+    routerChannel = jsonObj["routerChannel"] | 0;
     timestamp = jsonObj["timestamp"] | 0;
     messageType = jsonObj["message_type"] | 612;
   }
@@ -1315,6 +1320,7 @@ class BridgeTakeoverPackage : public painlessmesh::plugin::BroadcastPackage {
     jsonObj["previousBridge"] = previousBridge;
     jsonObj["reason"] = reason;
     jsonObj["routerRSSI"] = routerRSSI;
+    jsonObj["routerChannel"] = routerChannel;
     jsonObj["timestamp"] = timestamp;
     jsonObj["message_type"] = messageType;
     return jsonObj;
@@ -1322,7 +1328,7 @@ class BridgeTakeoverPackage : public painlessmesh::plugin::BroadcastPackage {
 
 #if ARDUINOJSON_VERSION_MAJOR < 7
   size_t jsonObjectSize() const {
-    return JSON_OBJECT_SIZE(noJsonFields + 5) + reason.length();
+    return JSON_OBJECT_SIZE(noJsonFields + 6) + reason.length();
   }
 #endif
 };
@@ -1380,4 +1386,4 @@ class NTPTimeSyncPackage : public painlessmesh::plugin::BroadcastPackage {
 
 }  // namespace alteriom
 
-#endif  // ALTERIOM_SENSOR_PACKAGE_HPP
+#endif  // ALTERIOM_SENSOR_PACKAGE_HPP

package/examples/alteriom/mppt_example/alteriom_custom_package_template.hpp

@@ -0,0 +1,320 @@
+#ifndef ALTERIOM_CUSTOM_PACKAGE_TEMPLATE_HPP
+#define ALTERIOM_CUSTOM_PACKAGE_TEMPLATE_HPP
+
+#include "painlessmesh/plugin.hpp"
+
+/**
+ * @file alteriom_custom_package_template.hpp
+ * @brief Template and example for creating custom Alteriom packages
+ *
+ * HOW TO CREATE A CUSTOM PACKAGE
+ * ===============================
+ *
+ * This file serves two purposes:
+ *   1. A step-by-step guide to creating custom painlessMesh packages
+ *   2. A concrete example: MpptPackage for MPPT solar charge controllers
+ *
+ * QUICK START
+ * -----------
+ * To create your own custom package:
+ *   1. Pick an unused Type ID from the table below (use 206+ range)
+ *   2. Choose a base class: BroadcastPackage (all nodes) or SinglePackage (one
+ *      node)
+ *   3. Add your data fields with appropriate types
+ *   4. Implement the JSON constructor and addTo() method
+ *   5. Add a test in test/catch/catch_custom_package.cpp
+ *
+ * RESERVED TYPE IDS
+ * -----------------
+ * The following IDs are already used; do NOT reuse them:
+ *
+ *   200 : SensorPackage      (environmental sensors: temp, humidity, pressure)
+ *   202 : StatusPackage      (device health and configuration)
+ *   204 : MetricsPackage     (network performance metrics)
+ *   205 : MpptPackage        (MPPT solar charge controller data)  <-- this file
+ *   400 : CommandPackage     (device control commands)
+ *   600 : MeshNodeListPackage
+ *   601 : MeshTopologyPackage
+ *   602 : MeshAlertPackage
+ *   603 : MeshBridgePackage
+ *   604 : EnhancedStatusPackage
+ *   605 : HealthCheckPackage
+ *   610 : BridgeStatusPackage
+ *   611 : BridgeElectionPackage
+ *   612 : BridgeTakeoverPackage
+ *   614 : NTPTimeSyncPackage
+ *
+ * Available ranges: 206-399 (add your package here and update this table).
+ *
+ *
+ * CHOOSING BASE CLASS
+ * -------------------
+ *
+ * BroadcastPackage  – sent to every node in the mesh.
+ *   Use for: sensor readings, status updates, telemetry data.
+ *   Base fields: from, routing (BROADCAST), type  (noJsonFields = 3)
+ *
+ * SinglePackage     – sent to one specific destination node.
+ *   Use for: commands, acknowledgements, targeted responses.
+ *   Base fields: from, dest, routing (SINGLE), type  (noJsonFields = 4)
+ *
+ *
+ * FIELD TYPE GUIDELINES
+ * ---------------------
+ *
+ * Choose types appropriate for your platform:
+ *
+ *   uint8_t   – flags, states, small counts (0-255)
+ *   uint16_t  – larger counts, port numbers, voltages in mV (0-65535)
+ *   uint32_t  – device IDs, Unix timestamps, large counters
+ *   int8_t    – signed small values, e.g. temperature in °C (-128 to +127)
+ *   float     – measured values requiring decimals (4 bytes; fine on both
+ *               ESP8266 and ESP32)
+ *   double    – high-precision measurements (8 bytes; prefer float on ESP8266)
+ *   TSTRING   – text strings (always use TSTRING, NOT Arduino String)
+ *   bool      – boolean flags; see BOOLEAN NAMING CONVENTION below
+ *
+ * BOOLEAN NAMING CONVENTION
+ * -------------------------
+ *   *Set suffix     – configuration data has been provided
+ *                     e.g., serverAddressSet = true
+ *   *Enabled suffix – feature is currently active/on
+ *                     e.g., loggingEnabled = true
+ *   is* prefix      – current runtime state
+ *                     e.g., isCharging = true
+ *
+ *
+ * JSON FIELD NAMING
+ * -----------------
+ *
+ * Use SHORT keys to minimise over-the-air message sizes:
+ *
+ *   batteryVoltage  ->  "bv"
+ *   solarCurrent    ->  "sc"
+ *   chargeState     ->  "cs"
+ *   deviceId        ->  "did"
+ *   timestamp       ->  "ts"
+ *
+ * Always document the mapping in a comment near the field declaration.
+ *
+ *
+ * TIME FIELDS
+ * -----------
+ *
+ * For interval / duration fields, follow the Alteriom time convention:
+ *   - Store internally in milliseconds (uint32_t)
+ *   - Serialise both a _ms and a _s variant in JSON
+ *   - Deserialise from the _ms variant only
+ *
+ * Timestamp fields (Unix epoch seconds) are an exception: single field, no
+ * dual-unit serialisation needed.
+ *
+ *
+ * ARDUINOJSON COMPATIBILITY
+ * -------------------------
+ *
+ * Always wrap the jsonObjectSize() method in an
+ * #if ARDUINOJSON_VERSION_MAJOR < 7 guard.  ArduinoJson v7 computes document
+ * sizes automatically; v6 requires an explicit capacity hint.
+ *
+ * The formula is:
+ *   JSON_OBJECT_SIZE(noJsonFields + <number of your own fields>)
+ *   + <total length of all TSTRING fields>
+ *
+ *
+ * MINIMAL PACKAGE TEMPLATE
+ * ========================
+ *
+ * Copy this skeleton and replace the placeholder names / IDs:
+ *
+ * @code
+ * namespace alteriom {
+ *
+ * class MyCustomPackage : public painlessmesh::plugin::BroadcastPackage {
+ *  public:
+ *   // --- Your data fields ---
+ *   uint32_t myId    = 0;
+ *   float    myValue = 0.0f;
+ *   TSTRING  myText  = "";
+ *
+ *   // MQTT message_type (set to your chosen type ID)
+ *   uint16_t messageType = 206;
+ *
+ *   MyCustomPackage() : BroadcastPackage(206) {}
+ *
+ *   MyCustomPackage(JsonObject jsonObj) : BroadcastPackage(jsonObj) {
+ *     myId        = jsonObj["id"];
+ *     myValue     = jsonObj["val"];
+ *     myText      = jsonObj["txt"].as<TSTRING>();
+ *     messageType = jsonObj["message_type"] | 206;
+ *   }
+ *
+ *   JsonObject addTo(JsonObject&& jsonObj) const {
+ *     jsonObj = BroadcastPackage::addTo(std::move(jsonObj));
+ *     jsonObj["id"]           = myId;
+ *     jsonObj["val"]          = myValue;
+ *     jsonObj["txt"]          = myText;
+ *     jsonObj["message_type"] = messageType;
+ *     return jsonObj;
+ *   }
+ *
+ * #if ARDUINOJSON_VERSION_MAJOR < 7
+ *   size_t jsonObjectSize() const {
+ *     // noJsonFields covers base-class fields; 3 = number of YOUR fields
+ *     return JSON_OBJECT_SIZE(noJsonFields + 3) + myText.length();
+ *   }
+ * #endif
+ * };
+ *
+ * } // namespace alteriom
+ * @endcode
+ *
+ *
+ * CONCRETE EXAMPLE: MpptPackage
+ * ==============================
+ *
+ * The MpptPackage (Type 205) transmits real-time telemetry from an MPPT solar
+ * charge controller (e.g. Renegy, Epever, Victron).  It is a BroadcastPackage
+ * so every node in the mesh receives the data automatically.
+ *
+ * Fields at a glance:
+ *
+ *   solarVoltage    (float,   V)   – PV panel open-circuit / input voltage
+ *   solarCurrent    (float,   A)   – PV panel current
+ *   solarPower      (uint16_t, W)  – PV panel instantaneous power
+ *   batteryVoltage  (float,   V)   – Battery terminal voltage
+ *   batterySOC      (uint8_t, %)   – State of charge 0–100
+ *   loadVoltage     (float,   V)   – Load output voltage
+ *   loadCurrent     (float,   A)   – Load output current
+ *   chargeState     (uint8_t)      – Controller state (see ChargeState enum)
+ *   controllerTemp  (int8_t,  °C)  – Internal controller temperature
+ *   deviceId        (uint32_t)     – Unique hardware identifier
+ *   timestamp       (uint32_t)     – Unix timestamp of the reading
+ */
+
+namespace alteriom {
+
+/**
+ * @brief Charge state values for MpptPackage::chargeState
+ */
+enum ChargeState : uint8_t {
+  CHARGE_OFF = 0,       ///< Charging disabled
+  CHARGE_NORMAL = 1,    ///< Normal PWM charging
+  CHARGE_MPPT = 2,      ///< Maximum Power Point Tracking active
+  CHARGE_EQUALIZE = 3,  ///< Equalisation charge (battery maintenance)
+  CHARGE_BOOST = 4,     ///< Boost / bulk charge stage
+  CHARGE_FLOAT = 5,     ///< Float / maintenance stage
+  CHARGE_LIMITED = 6    ///< Current-limited charging
+};
+
+/**
+ * @brief Real-time telemetry from an MPPT solar charge controller
+ *
+ * Broadcasts voltage, current, power and status from an MPPT charge controller
+ * to all nodes in the mesh (e.g. for logging, display, or load management).
+ *
+ * Adapting for your controller
+ * ----------------------------
+ * Most MPPT controllers expose data over RS-232/RS-485 or I²C.  Read the raw
+ * values from your hardware, assign them to the struct fields, then call
+ * sendBroadcast() as shown in alteriom_mppt_example.ino.
+ *
+ * Type ID: 205
+ */
+class MpptPackage : public painlessmesh::plugin::BroadcastPackage {
+ public:
+  // JSON key : "sv"  – PV panel voltage in Volts
+  float solarVoltage = 0.0f;
+  // JSON key : "sc"  – PV panel current in Amperes
+  float solarCurrent = 0.0f;
+  // JSON key : "sp"  – PV panel power in Watts
+  uint16_t solarPower = 0;
+  // JSON key : "bv"  – Battery terminal voltage in Volts
+  float batteryVoltage = 0.0f;
+  // JSON key : "bsoc" – Battery state of charge, 0–100 %
+  uint8_t batterySOC = 0;
+  // JSON key : "lv"  – Load output voltage in Volts
+  float loadVoltage = 0.0f;
+  // JSON key : "lc"  – Load output current in Amperes
+  float loadCurrent = 0.0f;
+  // JSON key : "cs"  – Charge controller state (see ChargeState enum)
+  uint8_t chargeState = CHARGE_OFF;
+  // JSON key : "ct"  – Controller internal temperature in °C (signed)
+  int8_t controllerTemp = 0;
+  // JSON key : "did" – Unique hardware / node identifier
+  uint32_t deviceId = 0;
+  // JSON key : "ts"  – Unix timestamp of measurement (seconds since epoch)
+  uint32_t timestamp = 0;
+
+  // MQTT Schema message_type for fast classification at the bridge
+  uint16_t messageType = 205;  // MPPT_DATA
+
+  // -------------------------------------------------------------------------
+  // Constructors
+  // -------------------------------------------------------------------------
+
+  MpptPackage() : BroadcastPackage(205) {}
+
+  /**
+   * @brief Deserialise from a JSON object received over the mesh
+   *
+   * @param jsonObj  Parsed JSON object (ArduinoJson JsonObject)
+   */
+  MpptPackage(JsonObject jsonObj) : BroadcastPackage(jsonObj) {
+    solarVoltage = jsonObj["sv"];
+    solarCurrent = jsonObj["sc"];
+    solarPower = jsonObj["sp"];
+    batteryVoltage = jsonObj["bv"];
+    batterySOC = jsonObj["bsoc"];
+    loadVoltage = jsonObj["lv"];
+    loadCurrent = jsonObj["lc"];
+    chargeState = jsonObj["cs"];
+    controllerTemp = jsonObj["ct"];
+    deviceId = jsonObj["did"];
+    timestamp = jsonObj["ts"];
+    messageType = jsonObj["message_type"] | 205;
+  }
+
+  // -------------------------------------------------------------------------
+  // Serialisation
+  // -------------------------------------------------------------------------
+
+  /**
+   * @brief Serialise this package into the provided JSON object
+   *
+   * Call addTo() on a freshly created JsonObject, then serialise with
+   * ArduinoJson's serializeJson() before passing the result to
+   * mesh.sendBroadcast().
+   */
+  JsonObject addTo(JsonObject&& jsonObj) const {
+    jsonObj = BroadcastPackage::addTo(std::move(jsonObj));
+    jsonObj["sv"] = solarVoltage;
+    jsonObj["sc"] = solarCurrent;
+    jsonObj["sp"] = solarPower;
+    jsonObj["bv"] = batteryVoltage;
+    jsonObj["bsoc"] = batterySOC;
+    jsonObj["lv"] = loadVoltage;
+    jsonObj["lc"] = loadCurrent;
+    jsonObj["cs"] = chargeState;
+    jsonObj["ct"] = controllerTemp;
+    jsonObj["did"] = deviceId;
+    jsonObj["ts"] = timestamp;
+    jsonObj["message_type"] = messageType;
+    return jsonObj;
+  }
+
+#if ARDUINOJSON_VERSION_MAJOR < 7
+  /**
+   * @brief Required capacity hint for ArduinoJson v6
+   *
+   * noJsonFields covers the 3 base-class fields (from, routing, type).
+   * The +12 accounts for the 12 fields declared in this class.
+   * No TSTRING fields, so no extra string length term.
+   */
+  size_t jsonObjectSize() const { return JSON_OBJECT_SIZE(noJsonFields + 12); }
+#endif
+};
+
+}  // namespace alteriom
+
+#endif  // ALTERIOM_CUSTOM_PACKAGE_TEMPLATE_HPP