@alteriom/painlessmesh 1.8.15 → 1.9.0

package/docs/PHASE2_GUIDE.md

@@ -1,543 +0,0 @@
-# Phase 2 Features Guide
-
-## Quick Summary
-
-Phase 2 adds production-ready features for scalable OTA distribution and professional monitoring:
-
-- ✅ **Broadcast OTA** - True mesh-wide firmware distribution scaling to 50+ nodes
-- ✅ **MQTT Status Bridge** - Professional monitoring integration with Grafana, InfluxDB, Prometheus
-
-## Features Overview
-
-### 1. Broadcast OTA (Option 1A)
-
-**What it does:** Distributes firmware to all nodes simultaneously via broadcast, dramatically reducing network traffic.
-
-**Key Benefits:**
-- **~98% network traffic reduction** vs unicast (1 broadcast vs N unicasts)
-- **Faster distribution** - All nodes receive chunks in parallel
-- **Scales to 50-100+ nodes** efficiently
-- **Backward compatible** - Works with Phase 1 compression
-- **Memory efficient** - Only +2-5KB per node
-
-**Architecture:**
-```
-Root Node                    All Nodes
-    ├─> Broadcast: Announce  ─┐
-    ├─> Broadcast: Chunk 0   ─┼─> Listen & Cache
-    ├─> Broadcast: Chunk 1   ─┼─> Assemble Firmware
-    └─> Broadcast: Chunk N   ─┘   Reboot When Complete
-```
-
-### 2. MQTT Status Bridge (Option 2E)
-
-**What it does:** Publishes comprehensive mesh status to MQTT topics for professional monitoring tools.
-
-**Key Benefits:**
-- **Cloud integration** via MQTT
-- **Professional monitoring** - Grafana, InfluxDB, Prometheus, Home Assistant
-- **Real-time visibility** into mesh health
-- **Automated alerting** for critical conditions
-- **Configurable publishing** intervals and topics
-
-**MQTT Topics:**
-- `mesh/status/nodes` - List of all nodes in mesh
-- `mesh/status/topology` - Complete mesh structure JSON
-- `mesh/status/metrics` - Performance statistics
-- `mesh/status/alerts` - Active alert conditions
-- `mesh/status/node/{id}` - Per-node detailed status (optional)
-
----
-
-## Getting Started
-
-### Prerequisites
-
-- Phase 1 features installed (Compressed OTA + Enhanced Status)
-- ESP32 or ESP8266 hardware
-- For MQTT Bridge: MQTT broker (Mosquitto, HiveMQ, etc.)
-- For MQTT Bridge: External WiFi connection
-
-### Quick Start: Broadcast OTA
-
-```cpp
-#include "painlessMesh.h"
-
-painlessMesh mesh;
-
-void setup() {
-  mesh.init(MESH_PREFIX, MESH_PASSWORD, &scheduler, MESH_PORT);
-  
-  #ifdef PAINLESSMESH_ENABLE_OTA
-  // Phase 2: Enable broadcast mode
-  mesh.offerOTA(
-    "sensor",          // Role
-    "ESP32",           // Hardware
-    firmwareMD5,       // MD5 hash
-    numParts,          // Number of chunks
-    false,             // Not forced
-    true,              // *** BROADCAST MODE ***
-    true               // Compressed (Phase 1)
-  );
-  #endif
-}
-```
-
-### Quick Start: MQTT Status Bridge
-
-```cpp
-#include <PubSubClient.h>
-#include "examples/bridge/mqtt_status_bridge.hpp"
-
-painlessMesh mesh;
-PubSubClient mqttClient(mqttBroker, 1883, mqttCallback, wifiClient);
-MqttStatusBridge* statusBridge;
-
-void setup() {
-  // Initialize mesh as bridge node
-  mesh.init(MESH_PREFIX, MESH_PASSWORD, MESH_PORT, WIFI_AP_STA, 6);
-  mesh.setRoot(true);
-  mesh.setContainsRoot(true);
-  
-  // Connect to external WiFi for MQTT
-  mesh.stationManual(STATION_SSID, STATION_PASSWORD);
-  
-  // Initialize status bridge
-  statusBridge = new MqttStatusBridge(mesh, mqttClient);
-  statusBridge->setPublishInterval(30000);  // 30 seconds
-  statusBridge->begin();
-}
-```
-
----
-
-## API Reference
-
-### Broadcast OTA
-
-#### mesh.offerOTA()
-
-```cpp
-std::shared_ptr<Task> offerOTA(
-  TSTRING role,
-  TSTRING hardware,
-  TSTRING md5,
-  size_t noPart,
-  bool forced = false,
-  bool broadcasted = false,  // Phase 2: Broadcast mode
-  bool compressed = false    // Phase 1: Compression
-)
-```
-
-**Parameters:**
-- `role` - Node role this firmware is for (e.g., "sensor", "gateway")
-- `hardware` - Hardware type: "ESP32" or "ESP8266"
-- `md5` - MD5 hash of firmware (for version checking)
-- `noPart` - Number of firmware chunks
-- `forced` - Force update even if MD5 matches (default: false)
-- **`broadcasted`** - **[Phase 2]** Enable broadcast mode (default: false)
-- `compressed` - [Phase 1] Enable compression (default: false)
-
-**Returns:** Shared pointer to Task that manages OTA announcements
-
-**Example:**
-```cpp
-auto otaTask = mesh.offerOTA(
-  "sensor", "ESP32", md5, 100,
-  false,  // not forced
-  true,   // BROADCAST MODE
-  true    // compressed
-);
-```
-
-### MQTT Status Bridge
-
-#### Constructor
-
-```cpp
-MqttStatusBridge(painlessMesh& mesh, PubSubClient& mqttClient)
-```
-
-#### Configuration Methods
-
-```cpp
-void setPublishInterval(uint32_t interval)
-```
-Set publishing interval in milliseconds (default: 30000)
-
-```cpp
-void setTopicPrefix(const String& prefix)
-```
-Set MQTT topic prefix (default: "mesh/status/")
-
-```cpp
-void enableTopology(bool enable)
-```
-Enable/disable topology publishing (default: true)
-
-```cpp
-void enableMetrics(bool enable)
-```
-Enable/disable metrics publishing (default: true)
-
-```cpp
-void enableAlerts(bool enable)
-```
-Enable/disable alerts publishing (default: true)
-
-```cpp
-void enablePerNode(bool enable)
-```
-Enable/disable per-node status publishing (default: false)  
-⚠️ **Warning:** Can be expensive for large meshes (50+ nodes)
-
-#### Control Methods
-
-```cpp
-void begin()
-```
-Start publishing status to MQTT
-
-```cpp
-void stop()
-```
-Stop publishing
-
-```cpp
-void publishNow()
-```
-Trigger immediate status publish (useful for testing)
-
----
-
-## Usage Examples
-
-### Example 1: Basic Broadcast OTA
-
-```cpp
-#include "painlessMesh.h"
-
-#define MESH_PREFIX "myMesh"
-#define MESH_PASSWORD "password"
-#define MESH_PORT 5555
-#define OTA_PART_SIZE 1024
-
-painlessMesh mesh;
-
-void setup() {
-  mesh.init(MESH_PREFIX, MESH_PASSWORD, MESH_PORT);
-  
-  #ifdef PAINLESSMESH_ENABLE_OTA
-  // Setup OTA sender
-  mesh.initOTASend(firmwareCallback, OTA_PART_SIZE);
-  
-  // Announce firmware with broadcast + compression
-  mesh.offerOTA(
-    "sensor",      // role
-    "ESP32",       // hardware
-    "abc123...",   // MD5
-    150,           // number of chunks
-    false,         // not forced
-    true,          // BROADCAST
-    true           // compressed
-  );
-  #endif
-}
-
-size_t firmwareCallback(ota::DataRequest pkg, char* buffer) {
-  // Read firmware chunk from storage
-  // Return bytes read into buffer
-}
-```
-
-### Example 2: MQTT Status Bridge with Custom Configuration
-
-```cpp
-#include <PubSubClient.h>
-#include "examples/bridge/mqtt_status_bridge.hpp"
-
-MqttStatusBridge* bridge;
-
-void setup() {
-  // ... initialize mesh and MQTT ...
-  
-  bridge = new MqttStatusBridge(mesh, mqttClient);
-  
-  // Custom configuration
-  bridge->setPublishInterval(60000);      // Publish every minute
-  bridge->setTopicPrefix("alteriom/");    // Custom topic prefix
-  bridge->enableTopology(true);           // Publish topology
-  bridge->enableMetrics(true);            // Publish metrics
-  bridge->enableAlerts(true);             // Publish alerts
-  bridge->enablePerNode(false);           // Disable per-node (too many nodes)
-  
-  bridge->begin();
-}
-
-void loop() {
-  mesh.update();
-  mqttClient.loop();
-  
-  // Trigger manual publish on demand
-  if (buttonPressed()) {
-    bridge->publishNow();
-  }
-}
-```
-
-### Example 3: Combined Phase 1 + Phase 2 Features
-
-```cpp
-#include "painlessMesh.h"
-#include "examples/alteriom/alteriom_sensor_package.hpp"
-#include "examples/bridge/mqtt_status_bridge.hpp"
-
-void setup() {
-  mesh.init(...);
-  
-  // Phase 1: Enhanced Status
-  alteriom::EnhancedStatusPackage status;
-  status.uptime = millis() / 1000;
-  status.nodeCount = mesh.getNodeList().size();
-  mesh.sendBroadcast(status.toJsonString());
-  
-  // Phase 2: Broadcast OTA
-  mesh.offerOTA("sensor", "ESP32", md5, parts, false, true, true);
-  
-  // Phase 2: MQTT Bridge
-  statusBridge->begin();
-}
-```
-
----
-
-## Performance & Scaling
-
-### Broadcast OTA Performance
-
-| Mesh Size | Unicast Traffic | Broadcast Traffic | Reduction |
-|-----------|----------------|-------------------|-----------|
-| 10 nodes  | 10x chunks     | 1x chunks         | 90%       |
-| 50 nodes  | 50x chunks     | 1x chunks         | 98%       |
-| 100 nodes | 100x chunks    | 1x chunks         | 99%       |
-
-**Example:** 150 chunk firmware update
-- **Unicast mode:** 50 nodes × 150 chunks = 7,500 transmissions
-- **Broadcast mode:** 1 × 150 chunks = 150 transmissions
-- **Reduction:** 7,350 fewer transmissions (98%)
-
-### Memory Usage
-
-| Feature | Memory Impact | Notes |
-|---------|--------------|-------|
-| Broadcast OTA | +2-5KB per node | Chunk bitmap + buffer |
-| MQTT Bridge | +5-8KB root node | Status collection |
-
-### MQTT Traffic
-
-| Feature | Messages/Interval | Size | Total/Interval |
-|---------|------------------|------|----------------|
-| Node List | 1 | ~200 bytes | 200 bytes |
-| Topology | 1 | ~1-5KB | 1-5KB |
-| Metrics | 1 | ~300 bytes | 300 bytes |
-| Alerts | 1 | ~400 bytes | 400 bytes |
-| Per-node (50 nodes) | 50 | ~150 bytes | ~7.5KB |
-
-**Recommended:** Disable per-node publishing for meshes >20 nodes
-
----
-
-## Integration with Monitoring Tools
-
-### Grafana Dashboard
-
-```json
-{
-  "datasource": "MQTT",
-  "targets": [
-    {
-      "topic": "mesh/status/metrics",
-      "field": "nodeCount"
-    }
-  ]
-}
-```
-
-### InfluxDB Telegraf
-
-```toml
-[[inputs.mqtt_consumer]]
-  servers = ["tcp://localhost:1883"]
-  topics = [
-    "mesh/status/metrics",
-    "mesh/status/alerts"
-  ]
-  data_format = "json"
-```
-
-### Prometheus MQTT Exporter
-
-```yaml
-mqtt:
-  server: tcp://localhost:1883
-  topics:
-    - mesh/status/metrics
-    - mesh/status/alerts
-```
-
-### Home Assistant
-
-```yaml
-sensor:
-  - platform: mqtt
-    name: "Mesh Node Count"
-    state_topic: "mesh/status/metrics"
-    value_template: "{{ value_json.nodeCount }}"
-    
-  - platform: mqtt
-    name: "Mesh Free Heap"
-    state_topic: "mesh/status/metrics"
-    value_template: "{{ value_json.freeHeap }}"
-    unit_of_measurement: "bytes"
-```
-
----
-
-## Troubleshooting
-
-### Broadcast OTA Issues
-
-**Problem:** Nodes not receiving broadcast chunks
-
-**Solutions:**
-1. Ensure `broadcasted=true` in offerOTA()
-2. Check mesh connectivity (all nodes must be connected)
-3. Verify nodes are running receiver code with `initOTAReceive()`
-4. Check for mesh congestion (add delays between chunks)
-
-**Problem:** Out-of-sequence chunks
-
-**Solution:** This is normal! Broadcast mode handles out-of-order delivery automatically.
-
-### MQTT Bridge Issues
-
-**Problem:** No status published to MQTT
-
-**Solutions:**
-1. Check MQTT broker connectivity
-2. Verify mqttClient.connected() returns true
-3. Check publish interval (default 30s)
-4. Enable Serial debug output
-
-**Problem:** High MQTT traffic
-
-**Solutions:**
-1. Increase publish interval (30s → 60s → 120s)
-2. Disable per-node publishing
-3. Disable topology publishing if mesh structure is static
-
----
-
-## Migration Guide
-
-### From Phase 1 to Phase 2
-
-**Step 1:** Update offerOTA() calls
-```cpp
-// Phase 1
-mesh.offerOTA(role, hardware, md5, parts, false, false, true);
-
-// Phase 2 - just add broadcast flag
-mesh.offerOTA(role, hardware, md5, parts, false, true, true);
-//                                                    ^^^^
-```
-
-**Step 2:** Add MQTT bridge (optional)
-```cpp
-#include "examples/bridge/mqtt_status_bridge.hpp"
-
-MqttStatusBridge* bridge = new MqttStatusBridge(mesh, mqttClient);
-bridge->begin();
-```
-
-### Backward Compatibility
-
-✅ **Fully backward compatible**
-- Broadcast defaults to `false` (unicast mode)
-- Non-broadcast nodes work alongside broadcast nodes
-- MQTT bridge is optional add-on
-- All Phase 1 features continue to work
-
----
-
-## Best Practices
-
-### When to Use Broadcast OTA
-
-✅ **Use broadcast mode when:**
-- Mesh has 10+ nodes
-- All nodes need same firmware
-- Network bandwidth is limited
-- Fast distribution is critical
-
-❌ **Don't use broadcast mode when:**
-- Mesh has <5 nodes (unicast is sufficient)
-- Different nodes need different firmware
-- Targeting specific nodes only
-
-### When to Use MQTT Status Bridge
-
-✅ **Use MQTT bridge when:**
-- Production deployment
-- Remote monitoring required
-- Integration with existing tools (Grafana, etc.)
-- Automated alerting needed
-- Cloud connectivity available
-
-❌ **Don't use MQTT bridge when:**
-- Development/testing environment
-- No external WiFi available
-- No MQTT broker available
-- Mesh is purely offline
-
-### Configuration Recommendations
-
-**Small meshes (1-10 nodes):**
-- Publish interval: 30 seconds
-- Enable all features
-- Enable per-node status
-
-**Medium meshes (10-50 nodes):**
-- Publish interval: 60 seconds
-- Enable topology, metrics, alerts
-- Disable per-node status
-
-**Large meshes (50+ nodes):**
-- Publish interval: 120 seconds
-- Enable metrics and alerts only
-- Disable topology and per-node
-
----
-
-## Next Steps
-
-### Phase 3 Features (Future)
-- Progressive rollout OTA (Option 1B)
-- Real-time telemetry streams (Option 2C)
-- Proactive alerting system
-- Large-scale mesh support (100+ nodes)
-
-### Further Reading
-- [PHASE2_IMPLEMENTATION.md](improvements/PHASE2_IMPLEMENTATION.md) - Technical details
-- [examples/alteriom/phase2_features.ino](../examples/alteriom/phase2_features.ino) - Complete example
-- [examples/bridge/mqtt_status_bridge_example.ino](../examples/bridge/mqtt_status_bridge_example.ino) - MQTT example
-- [FEATURE_PROPOSALS.md](improvements/FEATURE_PROPOSALS.md) - All features overview
-
----
-
-**Questions?** Open an issue on GitHub with logs and configuration details.
-
-**Status:** ✅ Phase 2 Complete - Production Ready  
-**Recommended For:** Medium to large mesh deployments (10-100+ nodes)  
-**Risk:** Low (backward compatible, well-tested)  
-**Value:** High (scalability + professional monitoring)

package/docs/QUICK_REFERENCE_VERSIONING.md

@@ -1,127 +0,0 @@
-# Quick Reference: Version Management
-
-## 🎯 Where to Find Version Information
-
-| File | Purpose | When to Update |
-|------|---------|----------------|
-| `library.properties` | **Official Arduino version** | Every release |
-| `library.json` | **Official PlatformIO version** | Every release |
-| `package.json` | **Official NPM version** | Every release |
-| `src/painlessMesh.h` | Header documentation | Every release (recommended) |
-| `src/AlteriomPainlessMesh.h` | Version defines | Every release (recommended) |
-| `CHANGELOG.md` | Release history | Every release |
-
-## 🚀 Quick Release Checklist
-
-```bash
-# 1. Bump version
-./scripts/bump-version.sh patch  # or minor, major
-
-# 2. Update CHANGELOG.md
-# Move [Unreleased] items to new [X.Y.Z] section
-
-# 3. Update header files
-# Edit src/painlessMesh.h - update @version comment
-# Edit src/AlteriomPainlessMesh.h - update version defines
-
-# 4. Validate
-./scripts/release-agent.sh
-
-# 5. Commit and push
-git add library.properties library.json package.json CHANGELOG.md src/*.h
-git commit -m "release: vX.Y.Z - Brief description"
-git push origin main
-```
-
-## 📝 Version Comment Format
-
-### In `src/painlessMesh.h`:
-```cpp
-/**
- * @file painlessMesh.h
- * @brief Main header file for Alteriom painlessMesh library
- * 
- * @version 1.8.7      // ← Library version
- * @date 2025-11-12    // ← Current date
- * 
- * painlessMesh is a user-friendly library...
- */
-```
-
-### In `src/AlteriomPainlessMesh.h`:
-```cpp
-/**
- * @brief AlteriomPainlessMesh library version information
- */
-#define ALTERIOM_PAINLESS_MESH_VERSION "1.8.7"
-#define ALTERIOM_PAINLESS_MESH_VERSION_MAJOR 1
-#define ALTERIOM_PAINLESS_MESH_VERSION_MINOR 8
-#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 7
-```
-
-## 🔍 Quick Commands
-
-### Check current version:
-```bash
-grep "version=" library.properties
-```
-
-### Verify all versions match:
-```bash
-grep -E "version|VERSION" library.properties library.json package.json src/*.h
-```
-
-### See file modification history:
-```bash
-git log --oneline -- src/painlessMesh.h
-```
-
-### See last modification date:
-```bash
-git log -1 --format="%ai" -- src/painlessMesh.h
-```
-
-## ❓ Common Questions
-
-**Q: What version is the library?**  
-→ Check `library.properties`, line 2
-
-**Q: When was a file last modified?**  
-→ Use `git log -1 -- path/to/file`
-
-**Q: Why is header version different from library.properties?**  
-→ Header comments may not have been updated. Trust `library.properties`.
-
-**Q: Do I need to update header versions?**  
-→ Recommended but not critical. Update during releases.
-
-## 📚 Full Documentation
-
-For complete information:
-- **[VERSION_MANAGEMENT.md](VERSION_MANAGEMENT.md)** - Complete guide
-- **[FAQ_VERSION_NUMBERS.md](FAQ_VERSION_NUMBERS.md)** - Common questions
-- **[RELEASE_GUIDE.md](../RELEASE_GUIDE.md)** - Release process
-
-## 🎓 Key Principles
-
-1. **Single Source of Truth**: `library.properties` / `library.json` / `package.json`
-2. **Header Comments**: Documentation only, not source of truth
-3. **Git History**: Actual record of file modifications
-4. **Synchronize on Release**: Keep all versions aligned during releases
-5. **When in Doubt**: Check `library.properties`
-
----
-
-**Quick Access:**
-```bash
-# View this file
-cat docs/QUICK_REFERENCE_VERSIONING.md
-
-# View full guide
-cat docs/VERSION_MANAGEMENT.md
-
-# View FAQ
-cat docs/FAQ_VERSION_NUMBERS.md
-```
-
-**Last Updated:** November 12, 2025