@alteriom/painlessmesh 1.9.18 → 1.9.20

package/CHANGELOG.md

@@ -13,6 +13,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+## [1.9.20] - 2026-03-27
+
+### Added
+
+- **Bridge Coordination Monitoring Callbacks** - User-facing API for observing bridge coordination events
+  - `mesh.onBridgeCoordination(cb)` — fires on every coordination message (~30s per bridge)
+  - `mesh.onBridgeCoordinationChanged(cb)` — fires on state changes: "new", "updated", "lost"
+  - Works on both bridge and non-bridge nodes (monitoring is not bridge-only)
+  - Lost bridge detection with 60-second timeout
+  - 5 new test scenarios with 18 assertions for change detection logic
+
+### Fixed
+
+- **Full Repo Cleanup** - Comprehensive audit and cleanup of the entire codebase (#357)
+  - Fix double-free of mScheduler in ~Mesh() destructor
+  - Fix int8_t RSSI aggregation overflow (widened to int32_t)
+  - Fix Task object memory leak in scheduleAsyncClientDeletion
+  - Replace blocking delay(1000) with yield-based approach in bridge init
+  - Add max-iteration guard to getPathToNode (prevents infinite loop)
+  - Move static vars from connection.hpp to connection.cpp (ODR violation fix)
+  - Initialize shouldContainRoot to false (undefined behavior fix)
+  - Fix getAccurateTime() to always return seconds
+  - Fix cancelInternetRequest reentrancy via scheduled callback
+  - Widen BFS hop counter from uint8_t to uint16_t
+  - Remove dead revert path in promoteToBridge
+  - Cap knownBridgePeers at 32 entries
+  - Increase WiFi event semaphore timeout from 100 to 1000 ticks
+  - Inline getGatewayCount() to avoid temporary vector allocation
+  - Remove MessageQueue::reserve(1000) (wasted heap on ESP8266)
+  - Fix Timer::elapsed_us() to return microseconds on ESP32
+  - Cache hasActualInternetAccess() with 60s TTL
+  - Remove ~3,600 lines of dead code (unused classes, stubs, AI-generated shelf code)
+  - Remove 40 AI-generated markdown files from root directory
+  - Delete abandoned documentation systems (docs-website/, website/)
+  - Fix all CI/CD workflow action versions
+  - Remove 15 fake test files (only REQUIRE(true) assertions)
+  - Fix millis()/micros() test mocks to prevent uint32_t overflow
+- **Documentation Consistency** - Feature audit and doc fixes (#358)
+  - Fix README version (1.9.17 -> 1.9.20)
+  - Fix 6 broken documentation links
+  - Fix Message Queue API examples to use real enableMessageQueue/queueMessage API
+  - Remove non-existent onBridgeCoordination callback from examples
+  - Fix EnhancedStatusPackage type ID comment (203 -> 604)
+  - Rewrite Quick Start example to use TaskScheduler instead of delay()
+  - Remove dead conditional includes from painlessMesh.h
+  - Add missing examples to library.json
+
+## [1.9.19] - 2025-12-21
+
+### Fixed
+
+- **Gateway Connectivity Error Non-Retryable Fix** - Infrastructure errors no longer waste time with futile retries
+  - Gateway connectivity errors ("Router has no internet", "Gateway WiFi not connected") are now non-retryable
+  - Distinguishes between infrastructure issues (need user fix) and transient errors (can retry)
+  - Provides immediate failure feedback instead of retrying for ~14+ seconds
+  - Saves battery and network resources by avoiding retries that can't succeed
+  - Clear error messages help users identify and fix infrastructure problems quickly
+  - Transient errors (HTTP 203, 5xx, 429, timeouts) still retry with exponential backoff
+  - New comprehensive test suite with 25 assertions covering retry logic
+  - Documentation: ISSUE_GATEWAY_CONNECTIVITY_NON_RETRYABLE_FIX.md
+  - Fully backward compatible: No API changes required
+
 ## [1.9.18] - 2025-12-21
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@
 
 <div align="center">
 
-**Version 1.9.18** - Internet connectivity check enhancement with DNS resolution verification
+**Version 1.9.20** - Full repo cleanup, bug fixes, and documentation consistency
 
 [![CI/CD Pipeline](https://github.com/Alteriom/painlessMesh/actions/workflows/ci.yml/badge.svg)](https://github.com/Alteriom/painlessMesh/actions/workflows/ci.yml)
 [![Documentation](https://github.com/Alteriom/painlessMesh/actions/workflows/docs.yml/badge.svg)](https://github.com/Alteriom/painlessMesh/actions/workflows/docs.yml)
@@ -209,11 +209,25 @@ mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
                   ROUTER_SSID, ROUTER_PASSWORD,
                   &userScheduler, MESH_PORT, 10);
 
-// Configure load balancing strategy
-mesh.setBridgeSelectionStrategy(ROUND_ROBIN);
+// Enable bridge failover for high availability
+mesh.enableBridgeFailover(true);
+
+// Monitor bridge coordination (fires every ~30s per bridge)
+mesh.onBridgeCoordination(
+  [](const plugin::BridgeCoordinationPackage& pkg, uint32_t fromNode) {
+    Serial.printf("Bridge %u: priority=%d, load=%d%%\n",
+                  fromNode, pkg.priority, pkg.load);
+  }
+);
 
-// Monitor bridge coordination
-mesh.onBridgeCoordination(&bridgeCoordinationCallback);
+// Get notified when bridge state changes
+mesh.onBridgeCoordinationChanged(
+  [](const plugin::BridgeCoordinationPackage& pkg, uint32_t fromNode,
+     TSTRING changeType) {
+    Serial.printf("Bridge %s: %u (role=%s)\n",
+                  changeType.c_str(), fromNode, pkg.role.c_str());
+  }
+);
 ```
 
 See [BRIDGE_TO_INTERNET.md](BRIDGE_TO_INTERNET.md) for multi-bridge documentation.
@@ -239,16 +253,11 @@ See [BRIDGE_TO_INTERNET.md](BRIDGE_TO_INTERNET.md) for multi-bridge documentatio
 **Example:**
 ```cpp
 // Enable message queue with max 100 messages
-mesh.enableMessageQueue(true);
-mesh.setMaxQueueSize(100);
+mesh.enableMessageQueue(true, 100);
 
 // Queue critical alarm message
 String criticalAlarm = "{\"sensor\":\"O2\",\"value\":2.5,\"alarm\":true}";
-mesh.queueMessage(criticalAlarm, CRITICAL);
-
-// Set callbacks
-mesh.onQueueFull(&queueFullCallback);
-mesh.onQueueFlushed(&queueFlushedCallback);
+mesh.queueMessage(bridgeNodeId, criticalAlarm);
 ```
 
 See [BRIDGE_TO_INTERNET.md](BRIDGE_TO_INTERNET.md) for message queue documentation.
@@ -393,46 +402,34 @@ If platformio is used to install the library, then the dependencies will be inst
 
 ```cpp
 #include "painlessMesh.h"
-#include "examples/alteriom/alteriom_sensor_package.hpp"
 
-using namespace alteriom;
-
-#define MESH_PREFIX     "AlteriomMesh"
-#define MESH_PASSWORD   "your_password"
-#define MESH_PORT       5555
+#define MESH_PREFIX "whateverYouLike"
+#define MESH_PASSWORD "somethingSneaky"
+#define MESH_PORT 5555
 
 Scheduler userScheduler;
 painlessMesh mesh;
 
-void setup() {
-    Serial.begin(115200);
-    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
-    mesh.onReceive(&receivedCallback);
+Task taskSendMessage(TASK_SECOND * 30, TASK_FOREVER, []() {
+  String msg = "Hello from node ";
+  msg += mesh.getNodeId();
+  mesh.sendBroadcast(msg);
+});
+
+void receivedCallback(uint32_t from, String &msg) {
+  Serial.printf("Received from %u: %s\n", from, msg.c_str());
 }
 
-void loop() {
-    mesh.update();
-    
-    // Create and send sensor data
-    SensorPackage sensor;
-    sensor.temperature = 25.5;
-    sensor.humidity = 60.0;
-    sensor.sensorId = mesh.getNodeId();
-    sensor.timestamp = mesh.getNodeTime();
-    
-    mesh.sendBroadcast(sensor.toJsonString());
-    delay(30000); // Send every 30 seconds
+void setup() {
+  Serial.begin(115200);
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+  mesh.onReceive(&receivedCallback);
+  userScheduler.addTask(taskSendMessage);
+  taskSendMessage.enable();
 }
 
-void receivedCallback(uint32_t from, String& msg) {
-    JsonDocument doc;  // ArduinoJson v7
-    deserializeJson(doc, msg);
-    
-    if (doc["type"] == 200) { // SensorPackage
-        SensorPackage sensor(doc.as<JsonObject>());
-        Serial.printf("Sensor %u: %.1f°C, %.1f%% RH\n", 
-                     sensor.sensorId, sensor.temperature, sensor.humidity);
-    }
+void loop() {
+  mesh.update();
 }
 ```
 
@@ -563,14 +560,16 @@ These are the message types used by applications built on painlessMesh:
 - **Event Coordination** - Synchronized displays, distributed processing
 - **Bridge Networks** - Connect mesh to WiFi/Internet/MQTT - [📖 Bridge Guide](BRIDGE_TO_INTERNET.md)
 
-## Latest Release: v1.9.17 (December 21, 2025)
+## Latest Release: v1.9.20 (March 27, 2026)
 
-**Documentation Enhancement & Package Organization**
+**Full Repo Cleanup, Bug Fixes & Bridge Coordination Callbacks**
 
-- 📚 **Production-Level Documentation** - Removed phase terminology for clearer product positioning
-- 📦 **Complete Package Catalog** - All 19 application-level package types documented in numerical order
-- 🎯 **Enhanced Feature Clarity** - Improved Advanced Features section with comprehensive capability list
-- ✨ **Professional Quality** - Documentation suitable for enterprise adoption and production deployments
+- New `onBridgeCoordination()` and `onBridgeCoordinationChanged()` monitoring callbacks
+- Fixed 13 critical/high/medium bugs (double-free, RSSI overflow, memory leaks, blocking delays)
+- Removed ~3,600 lines of dead code and 40 AI-generated docs
+- Fixed all CI/CD workflows (corrected action versions)
+- Removed 15 fake test files, fixed test infrastructure
+- Documentation consistency audit — fixed broken links, API examples, version references
 
 **Recent Key Features (v1.9.0 - v1.9.16):**
 
@@ -578,16 +577,16 @@ These are the message types used by applications built on painlessMesh:
 - 🌉 **Improved Bridge Detection** - `getPrimaryBridge()` returns last known bridge when disconnected
 - ⚡ **Enhanced TCP Reliability** - Exponential backoff and increased retries for mesh connections
 - 🛡️ **Race Condition Fixes** - Improved bridge status and connection validation
-- 📦 **Consolidated Examples** - Streamlined to 14 essential examples
+- 📦 **Consolidated Examples** - Streamlined to 15 essential examples
 - ⚙️ **Configurable Election Timing** - Prevent split-brain with `setElectionStartupDelay()` and `setElectionRandomDelay()`
 
 **[📋 Full CHANGELOG](CHANGELOG.md)**
 
 ## Getting Help
 
-- **[FAQ](docs/troubleshooting/faq.md)** - Common questions and solutions
-- **[Common Issues](docs/troubleshooting/common-issues.md)** - Troubleshooting guide
-- **[GitHub Issues](https://github.com/Alteriom/painlessMesh/issues)** - Bug reports and feature requests  
+- **[FAQ](USER_GUIDE.md)** - Common questions and solutions
+- **[Common Issues](USER_GUIDE.md)** - Troubleshooting guide
+- **[GitHub Issues](https://github.com/Alteriom/painlessMesh/issues)** - Bug reports and feature requests
 - **[Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)** - Community support
 - **[API Documentation](https://alteriom.github.io/painlessMesh/#/api/doxygen)** - Generated API docs
 
@@ -610,6 +609,28 @@ run-parts --regex catch_ bin/  # Run tests
 - **Dependencies**: ArduinoJson 7.x, TaskScheduler 4.x  
 - **Development**: CMake, Ninja, Boost (for desktop testing)
 
+### Testing Bridge/Internet Functionality
+
+painlessMesh includes a **Mock HTTP Server** for testing `sendToInternet()` functionality without requiring actual Internet connectivity. This enables:
+
+- 🚀 **Fast testing cycles** - Instant responses instead of waiting for external APIs
+- 🔧 **Offline development** - No Internet connection required
+- ✅ **Reproducible scenarios** - Control all test conditions precisely
+- 🤖 **CI/CD automation** - Automated testing in pipelines
+
+```bash
+# Start mock server
+cd test/mock-http-server
+python3 server.py
+
+# Test various HTTP scenarios
+curl http://localhost:8080/status/200     # Success
+curl http://localhost:8080/status/404     # Not Found
+curl http://localhost:8080/whatsapp?...   # WhatsApp API simulation
+```
+
+See [Mock HTTP Server Documentation](test/mock-http-server/README.md) for complete usage guide.
+
 ### CI/CD Pipeline
 
 painlessMesh features a state-of-the-art automated CI/CD pipeline:
@@ -651,8 +672,6 @@ We try to follow the [git flow](https://www.atlassian.com/git/tutorials/comparin
 
 If you like the library please consider supporting its development. Your contributions help me spend more time improving painlessMesh.
 
-[![PayPal Donation](paypal/qrcode.png)](https://www.paypal.com/paypalme/domlavoie)
-
 **[Donate via PayPal](https://www.paypal.com/paypalme/domlavoie)** • [dominic.lavoie@gmail.com](mailto:dominic.lavoie@gmail.com)
 
 ## 📚 Documentation
@@ -669,18 +688,18 @@ If you like the library please consider supporting its development. Your contrib
 ### 🚀 Quick Links
 
 **New to AlteriomPainlessMesh?**
-- [Quick Start](docs/getting-started/quickstart.md) - Get your first mesh running in 5 minutes
-- [Installation](docs/getting-started/installation.md) - Arduino IDE and PlatformIO setup
-- [First Mesh](docs/getting-started/first-mesh.md) - Build a multi-node network
+- [Quick Start](USER_GUIDE.md) - Get your first mesh running in 5 minutes
+- [Installation](USER_GUIDE.md) - Arduino IDE and PlatformIO setup
+- [First Mesh](USER_GUIDE.md) - Build a multi-node network
 
 **Reference Documentation:**
-- [Core API](docs/api/core-api.md) - painlessMesh class methods
-- [Alteriom Extensions](docs/alteriom/overview.md) - SensorPackage, CommandPackage, StatusPackage
-- [Examples](examples/) - 16 working examples for common scenarios
+- [Core API](USER_GUIDE.md) - painlessMesh class methods
+- [Alteriom Extensions](examples/alteriom/README.md) - SensorPackage, CommandPackage, StatusPackage
+- [Examples](examples/) - 15 working examples for common scenarios
 
 **Need Help?**
-- [FAQ](docs/troubleshooting/faq.md) - Frequently asked questions
-- [Common Issues](docs/troubleshooting/common-issues.md) - Troubleshooting guide
+- [FAQ](USER_GUIDE.md) - Frequently asked questions
+- [Common Issues](USER_GUIDE.md) - Troubleshooting guide
 - [GitHub Issues](https://github.com/Alteriom/painlessMesh/issues) - Bug reports and support
 
 ## 🔧 Quick API Reference

package/examples/alteriom/README.md

@@ -34,7 +34,7 @@ Broadcast package for sharing device health and status information.
 - `wifiStrength` - WiFi signal strength (0-100)
 - `firmwareVersion` - Current firmware version string
 
-### EnhancedStatusPackage (Type 203) - Phase 1
+### EnhancedStatusPackage (Type 604)
 Extended status package with comprehensive health metrics (18 fields).
 
 **Additional Fields:**
@@ -177,12 +177,12 @@ Complete Arduino sketch demonstrating:
 - Message type discrimination
 - Integration with painlessMesh
 
-### `phase1_features.ino` (NEW)
-Phase 1 OTA enhancement example demonstrating:
+### `phase1_features.ino`
+OTA enhancement example demonstrating:
 - Compressed OTA transfer infrastructure
 - Enhanced status reporting with comprehensive metrics
 - Alert system implementation
-- Usage patterns for Phase 1 features
+- Usage patterns for advanced features
 
 ### `metrics_health_node.ino` (NEW in v1.7.7)
 Comprehensive monitoring node example demonstrating:

package/examples/alteriom/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 203+ 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)
+ *   203 : MpptPackage        (MPPT solar charge controller data)  <-- this file
+ *   204 : MetricsPackage     (network performance metrics)
+ *   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: 205-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 = 205;
+ *
+ *   MyCustomPackage() : BroadcastPackage(205) {}
+ *
+ *   MyCustomPackage(JsonObject jsonObj) : BroadcastPackage(jsonObj) {
+ *     myId        = jsonObj["id"];
+ *     myValue     = jsonObj["val"];
+ *     myText      = jsonObj["txt"].as<TSTRING>();
+ *     messageType = jsonObj["message_type"] | 205;
+ *   }
+ *
+ *   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 203) 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: 203
+ */
+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 = 203;  // MPPT_DATA
+
+  // -------------------------------------------------------------------------
+  // Constructors
+  // -------------------------------------------------------------------------
+
+  MpptPackage() : BroadcastPackage(203) {}
+
+  /**
+   * @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"] | 203;
+  }
+
+  // -------------------------------------------------------------------------
+  // 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

package/examples/alteriom/alteriom_sensor_package.hpp

@@ -520,7 +520,7 @@ class StatusPackage : public painlessmesh::plugin::BroadcastPackage {
  *
  * This is an extended version of StatusPackage that includes additional
  * mesh statistics, performance metrics, and alerting capabilities.
- * Type ID 203 is used to distinguish from the basic StatusPackage (202).
+ * Type ID 604 is used to distinguish from the basic StatusPackage (202).
  */
 class EnhancedStatusPackage : public painlessmesh::plugin::BroadcastPackage {
  public: