@alteriom/painlessmesh 1.6.1 → 1.7.2

package/examples/mqttTopologyTest/README.md

@@ -0,0 +1,467 @@
+# MQTT Topology Test
+
+Hardware test sketch for painlessMesh topology reporting with @alteriom/mqtt-schema v0.5.0 compliance.
+
+## 📋 Requirements
+
+### Hardware
+- **3x ESP32 boards** (or ESP8266, but ESP32 recommended for better performance)
+- **3x USB cables** (for programming and Serial monitoring)
+- **MQTT broker** (e.g., Mosquitto, HiveMQ, or cloud service)
+- **WiFi network** accessible by all devices
+
+### Software
+- Arduino IDE 2.x or PlatformIO
+- painlessMesh library (this repository)
+- PubSubClient library (for MQTT)
+- ArduinoJson library (v7.x)
+
+## 🔧 Configuration
+
+### 1. Configure WiFi (Gateway Only)
+
+Edit these lines in `mqttTopologyTest.ino`:
+
+```cpp
+#define WIFI_SSID       "YourWiFiSSID"
+#define WIFI_PASSWORD   "YourWiFiPassword"
+```
+
+### 2. Configure MQTT Broker (Gateway Only)
+
+```cpp
+#define MQTT_BROKER     "192.168.1.100"  // Your MQTT broker IP
+#define MQTT_PORT       1883
+#define MQTT_USER       ""  // Leave empty if no auth
+#define MQTT_PASS       ""  // Leave empty if no auth
+```
+
+### 3. Configure Each Node
+
+**Node 1 (Gateway):**
+```cpp
+#define IS_GATEWAY      true
+#define NODE_ROLE       "gateway"
+```
+
+**Node 2 (Sensor):**
+```cpp
+#define IS_GATEWAY      false
+#define NODE_ROLE       "sensor"
+```
+
+**Node 3 (Repeater):**
+```cpp
+#define IS_GATEWAY      false
+#define NODE_ROLE       "repeater"
+```
+
+## 🚀 Installation & Testing
+
+### Step 1: Setup MQTT Broker
+
+**Option A: Local Mosquitto (Recommended for testing)**
+```bash
+# Install Mosquitto
+sudo apt-get install mosquitto mosquitto-clients
+
+# Start broker
+sudo systemctl start mosquitto
+
+# Test broker
+mosquitto_sub -h localhost -t "alteriom/mesh/#" -v
+```
+
+**Option B: Docker Mosquitto**
+```bash
+docker run -d -p 1883:1883 -p 9001:9001 eclipse-mosquitto
+```
+
+**Option C: Cloud MQTT** (HiveMQ, CloudMQTT, etc.)
+
+### Step 2: Flash Nodes
+
+1. **Flash Node 1 (Gateway)**
+   - Set `IS_GATEWAY = true`, `NODE_ROLE = "gateway"`
+   - Upload sketch
+   - Open Serial Monitor (115200 baud)
+
+2. **Flash Node 2 (Sensor)**
+   - Set `IS_GATEWAY = false`, `NODE_ROLE = "sensor"`
+   - Upload sketch
+   - Open Serial Monitor
+
+3. **Flash Node 3 (Repeater)**
+   - Set `IS_GATEWAY = false`, `NODE_ROLE = "repeater"`
+   - Upload sketch
+   - Open Serial Monitor
+
+### Step 3: Monitor MQTT Messages
+
+**Terminal 1: Monitor all mesh topics**
+```bash
+mosquitto_sub -h localhost -t "alteriom/mesh/#" -v
+```
+
+**Terminal 2: Monitor topology only**
+```bash
+mosquitto_sub -h localhost -t "alteriom/mesh/+/topology" -v
+```
+
+**Terminal 3: Monitor events only**
+```bash
+mosquitto_sub -h localhost -t "alteriom/mesh/+/events" -v
+```
+
+### Step 4: Test GET_TOPOLOGY Command
+
+**Send command:**
+```bash
+mosquitto_pub -h localhost -t "alteriom/mesh/MESH-001/command" -m '{
+  "event": "command",
+  "command": "get_topology",
+  "correlation_id": "test-001",
+  "parameters": {
+    "format": "full",
+    "include_metrics": true
+  }
+}'
+```
+
+**Expected response on** `alteriom/mesh/MESH-001/topology/response`:
+```json
+{
+  "schema_version": 1,
+  "device_id": "ALT-...",
+  "event": "command_response",
+  "command": "get_topology",
+  "correlation_id": "test-001",
+  "success": true,
+  "result": {
+    "event": "mesh_topology",
+    "nodes": [...],
+    "connections": [...],
+    "metrics": {...}
+  },
+  "latency_ms": 850
+}
+```
+
+## 📊 Expected Behavior
+
+### Mesh Formation (0-30 seconds)
+```
+✅ Node 2 joins mesh
+✅ Node 3 joins mesh
+🔄 Connections established
+⏰ Time synchronized
+```
+
+### Full Topology Publishing (every 60 seconds)
+```json
+{
+  "event": "mesh_topology",
+  "mesh_id": "MESH-001",
+  "gateway_node_id": "ALT-6825DD341CA4",
+  "update_type": "full",
+  "nodes": [
+    {
+      "node_id": "ALT-6825DD341CA4",
+      "role": "gateway",
+      "status": "online",
+      "connection_count": 2
+    },
+    {
+      "node_id": "ALT-441D64F804A0",
+      "role": "sensor",
+      "status": "online"
+    },
+    {
+      "node_id": "ALT-7F8E9D0A1B2C",
+      "role": "repeater",
+      "status": "online"
+    }
+  ],
+  "connections": [
+    {
+      "from_node": "ALT-6825DD341CA4",
+      "to_node": "ALT-441D64F804A0",
+      "quality": 95,
+      "latency_ms": 12,
+      "rssi": -42,
+      "hop_count": 1
+    },
+    {
+      "from_node": "ALT-6825DD341CA4",
+      "to_node": "ALT-7F8E9D0A1B2C",
+      "quality": 88,
+      "latency_ms": 18,
+      "rssi": -55,
+      "hop_count": 1
+    }
+  ],
+  "metrics": {
+    "total_nodes": 3,
+    "online_nodes": 3,
+    "network_diameter": 1,
+    "avg_connection_quality": 91
+  }
+}
+```
+
+### Incremental Updates (within 5 seconds of change)
+
+**When Node 4 joins:**
+```json
+{
+  "event": "mesh_topology",
+  "update_type": "incremental",
+  "nodes": [
+    {
+      "node_id": "ALT-NEW12345678",
+      "role": "sensor",
+      "status": "online"
+    }
+  ],
+  "connections": [
+    {
+      "from_node": "ALT-6825DD341CA4",
+      "to_node": "ALT-NEW12345678",
+      "quality": 78
+    }
+  ]
+}
+```
+
+**Followed by event:**
+```json
+{
+  "event": "mesh_event",
+  "event_type": "node_join",
+  "affected_nodes": ["ALT-NEW12345678"]
+}
+```
+
+### Node Leave Event
+
+**When node disconnects:**
+```json
+{
+  "event": "mesh_event",
+  "event_type": "node_leave",
+  "affected_nodes": ["ALT-441D64F804A0"],
+  "details": {
+    "reason": "timeout",
+    "last_seen": "2025-10-14T15:08:45Z",
+    "connections_lost": 1
+  }
+}
+```
+
+## 🧪 Test Scenarios
+
+### Test 1: Mesh Formation
+1. Power on all 3 nodes
+2. Watch Serial monitors for mesh formation
+3. Verify full topology published within 60 seconds
+4. ✅ **Pass:** All nodes appear in topology with correct roles
+
+### Test 2: Incremental Updates
+1. With mesh running, power off Node 3
+2. Watch for `node_leave` event within 5 seconds
+3. Verify incremental topology update shows Node 3 as offline
+4. Power on Node 3 again
+5. Watch for `node_join` event
+6. ✅ **Pass:** Events published within 5 seconds of change
+
+### Test 3: GET_TOPOLOGY Command
+1. Send `get_topology` command via MQTT
+2. Verify response on `/topology/response` topic
+3. Check response includes `correlation_id`
+4. Verify `latency_ms` is reasonable (< 2000ms)
+5. ✅ **Pass:** Response received with correct structure
+
+### Test 4: Schema Compliance
+1. Copy any published message
+2. Validate against @alteriom/mqtt-schema v0.5.0
+3. Check all required envelope fields present
+4. Verify Device ID format: `ALT-XXXXXXXXXXXX` (uppercase hex)
+5. Verify quality values: 0-100 range
+6. Verify RSSI values: negative dBm
+7. ✅ **Pass:** All messages validate successfully
+
+### Test 5: Quality Metrics
+1. Move nodes physically closer/farther apart
+2. Watch quality values change in topology updates
+3. Verify RSSI becomes more negative with distance
+4. Verify latency increases with poor connections
+5. ✅ **Pass:** Metrics reflect connection quality
+
+### Test 6: Network Diameter
+1. Start with 2 nodes (gateway + 1 sensor)
+2. Add 3rd node in range of sensor but not gateway
+3. Verify `network_diameter` increases to 2
+4. Verify `hop_count` shows multi-hop connections
+5. ✅ **Pass:** Topology correctly represents mesh structure
+
+## 🐛 Troubleshooting
+
+### Issue: Nodes won't join mesh
+
+**Symptoms:**
+- Serial shows "Connecting to mesh..."
+- No "New connection" messages
+
+**Solutions:**
+1. Verify all nodes have same `MESH_PREFIX` and `MESH_PASSWORD`
+2. Check nodes are within WiFi range (< 30m indoors)
+3. Try changing `MESH_PORT` to avoid conflicts
+4. Disable WiFi on gateway temporarily to test sensor-to-sensor mesh
+
+### Issue: Gateway won't connect to MQTT
+
+**Symptoms:**
+- "Connecting to MQTT broker... failed, rc=-2"
+
+**Solutions:**
+1. Verify `MQTT_BROKER` IP is correct
+2. Check broker is running: `mosquitto -v`
+3. Test broker connectivity: `mosquitto_pub -h <IP> -t test -m hello`
+4. Check firewall allows port 1883
+5. If using authentication, verify `MQTT_USER` and `MQTT_PASS`
+
+### Issue: Topology messages not publishing
+
+**Symptoms:**
+- Mesh formed but no MQTT messages
+- Serial shows "Failed to publish"
+
+**Solutions:**
+1. Check MQTT buffer size (should be 2048+)
+2. Verify topic permissions on broker
+3. Check JSON message size (< 2KB recommended)
+4. Monitor broker logs for errors
+5. Reduce `FULL_TOPOLOGY_INTERVAL` to 10s for testing
+
+### Issue: Device ID format incorrect
+
+**Symptoms:**
+- Device IDs like "ALT-0" or "ALT-12345"
+
+**Solutions:**
+1. Verify using ESP32 (ESP8266 has different chip ID)
+2. Check `getDeviceId()` function uses `%012llX` format
+3. Confirm uppercase hex output
+4. Test: Should be 16 characters total (ALT- + 12 hex digits)
+
+### Issue: Quality metrics always 0 or 100
+
+**Symptoms:**
+- Quality stuck at boundary values
+- RSSI always -90 or 0
+
+**Solutions:**
+1. Implement real RSSI measurement (this test uses simulation)
+2. Add WiFi signal strength reading: `WiFi.RSSI()`
+3. Calculate quality from packet loss, not simulation
+4. Add latency measurement with ping/pong messages
+
+### Issue: Incremental updates too slow
+
+**Symptoms:**
+- Node joins but update takes > 10 seconds
+
+**Solutions:**
+1. Reduce `INCREMENTAL_INTERVAL` to 1000ms for testing
+2. Check `lastTopologyUpdate` is being reset on connection changes
+3. Verify callbacks are triggering: add Serial.println in `newConnectionCallback`
+4. Confirm MQTT client is connected when change occurs
+
+## 📈 Performance Optimization
+
+### For Large Meshes (10+ nodes)
+
+1. **Increase MQTT buffer:**
+   ```cpp
+   mqttClient.setBufferSize(4096);
+   ```
+
+2. **Reduce full topology frequency:**
+   ```cpp
+   #define FULL_TOPOLOGY_INTERVAL  300000  // 5 minutes
+   ```
+
+3. **Implement topology compression:**
+   - Only send changed fields in incremental updates
+   - Use shorter field names
+   - Remove optional fields when empty
+
+4. **Add QoS levels:**
+   ```cpp
+   mqttClient.publish(topic.c_str(), jsonString.c_str(), true);  // Retained
+   ```
+
+5. **Batch incremental updates:**
+   - Wait 10s for multiple changes
+   - Send single update with all changes
+
+### For ESP8266 (Limited Memory)
+
+1. **Reduce JSON buffer size:**
+   ```cpp
+   JsonDocument doc;  // Uses 1KB by default
+   ```
+
+2. **Stream JSON directly to MQTT:**
+   ```cpp
+   // Instead of String, use streaming
+   mqttClient.beginPublish(topic.c_str(), measureJson(doc), false);
+   serializeJson(doc, mqttClient);
+   mqttClient.endPublish();
+   ```
+
+3. **Disable debug messages:**
+   ```cpp
+   mesh.setDebugMsgTypes(ERROR);
+   ```
+
+## 📚 Schema Reference
+
+This test implements these schemas from @alteriom/mqtt-schema v0.5.0:
+
+- ✅ **Envelope** (schema_version, device_id, device_type, timestamp, firmware_version)
+- ✅ **mesh_topology** (full and incremental updates)
+- ✅ **mesh_event** (node_join, node_leave events)
+- ✅ **command** (GET_TOPOLOGY command ID 300)
+- ✅ **command_response** (topology response with correlation_id)
+
+## 🎯 Success Criteria
+
+Test is successful when:
+
+- [x] All 3 nodes join mesh within 30 seconds
+- [x] Full topology published every 60 seconds
+- [x] Incremental updates published within 5 seconds of changes
+- [x] Node join/leave events published immediately
+- [x] GET_TOPOLOGY command returns valid response
+- [x] All messages validate against @alteriom/mqtt-schema
+- [x] Device IDs follow ALT-XXXXXXXXXXXX format
+- [x] Quality metrics in 0-100 range
+- [x] RSSI values are negative
+- [x] Connection count matches actual mesh connections
+
+## 📝 Notes
+
+- This test uses **simulated quality metrics** (RSSI, latency) based on node IDs
+- For production, implement **real measurements** using `WiFi.RSSI()` and ping/pong
+- The test uses **simplified topology** (all nodes connect to gateway)
+- For multi-hop meshes, implement **hop count tracking** from routing table
+- Message timing is **approximate** due to mesh synchronization delays
+- **Schema compliance** is validated by test/catch/catch_topology_schema.cpp
+
+## 🔗 Related Documentation
+
+- [MQTT Schema Review](../../docs/MQTT_SCHEMA_REVIEW.md)
+- [MQTT Bridge Commands](../../docs/MQTT_BRIDGE_COMMANDS.md)
+- [Schema Validation Tests](../../test/catch/catch_topology_schema.cpp)
+- [@alteriom/mqtt-schema Package](https://www.npmjs.com/package/@alteriom/mqtt-schema)