@alteriom/painlessmesh 1.6.1 → 1.7.2

package/docs/IMPLEMENTATION_PLAN_MESH_TOPOLOGY.md

@@ -0,0 +1,1062 @@
+# painlessMesh Implementation Plan for MQTT Schema v0.5.0
+
+**Date:** October 12, 2025  
+**Target:** Support mesh_topology.schema.json and mesh_event.schema.json  
+**Status:** 📋 IMPLEMENTATION PLAN
+
+---
+
+## Executive Summary
+
+Assuming @alteriom/mqtt-schema v0.5.0 is released with the new mesh topology and event schemas, this document outlines **all required implementations** in the painlessMesh library to fully support these features.
+
+### What's Already Done ✅
+
+1. ✅ **Command Bridge** - MqttCommandBridge class (417 lines)
+2. ✅ **Gateway Example** - mqttCommandBridge.ino with basic topology
+3. ✅ **Node Handler** - mesh_command_node.ino with command responses
+4. ✅ **Status Packages** - Enhanced StatusPackage with response tracking
+5. ✅ **Basic Topology** - Simple node list publishing every 30s
+
+### What Needs Implementation ⚠️
+
+1. ⚠️ **Schema-Compliant Topology Reporter** - Full mesh structure with connections
+2. ⚠️ **Connection Quality Tracking** - RSSI, latency, hop count per link
+3. ⚠️ **Mesh Event Publisher** - Real-time node join/leave notifications
+4. ⚠️ **Topology Command Handler** - `get_topology` command support
+5. ⚠️ **Enhanced Gateway Bridge** - Schema v0.5.0 compliance
+6. ⚠️ **Connection Metadata API** - Expose connection details from painlessMesh core
+
+---
+
+## Part 1: Core Library Enhancements
+
+### 1.1 Add Connection Metadata API
+
+**File:** `src/painlessmesh/mesh.hpp`
+
+**Problem:** painlessMesh tracks connections internally but doesn't expose connection quality metrics (RSSI, latency, hop count).
+
+**Solution:** Add public API to retrieve connection metadata.
+
+#### New Public Methods
+
+```cpp
+/**
+ * @brief Get connection quality for a specific link
+ * @param fromNode Source node ID
+ * @param toNode Destination node ID
+ * @return Connection quality (0-100) or -1 if not connected
+ */
+int getConnectionQuality(uint32_t fromNode, uint32_t toNode);
+
+/**
+ * @brief Get RSSI for a direct connection
+ * @param nodeId Connected node ID
+ * @return RSSI in dBm (typically -30 to -90) or 0 if not available
+ */
+int getConnectionRSSI(uint32_t nodeId);
+
+/**
+ * @brief Get average latency to a node
+ * @param nodeId Target node ID
+ * @return Latency in milliseconds or -1 if not available
+ */
+int getConnectionLatency(uint32_t nodeId);
+
+/**
+ * @brief Get hop count to a node
+ * @param nodeId Target node ID
+ * @return Number of hops or -1 if unreachable
+ */
+int getHopCount(uint32_t nodeId);
+
+/**
+ * @brief Get all direct connections with metadata
+ * @return List of connection objects with quality metrics
+ */
+std::vector<ConnectionInfo> getConnectionDetails();
+
+/**
+ * @brief Get routing table for mesh visualization
+ * @return Map of destination -> next hop mappings
+ */
+std::map<uint32_t, uint32_t> getRoutingTable();
+```
+
+#### New Data Structure
+
+```cpp
+struct ConnectionInfo {
+  uint32_t nodeId;           // Connected node ID
+  uint32_t lastSeen;         // Timestamp of last message (ms)
+  int rssi;                  // Signal strength (dBm)
+  int avgLatency;            // Average round-trip time (ms)
+  int hopCount;              // Hops from current node
+  int quality;               // Connection quality (0-100)
+  uint32_t messagesRx;       // Messages received
+  uint32_t messagesTx;       // Messages sent
+  uint32_t messagesDropped;  // Failed transmissions
+};
+```
+
+#### Implementation Location
+
+**File to modify:** `src/painlessmesh/mesh.hpp`
+
+**Add after line 365 (after `subConnectionJson()`):**
+
+```cpp
+  /**
+   * Get detailed connection information for all direct neighbors
+   */
+  std::vector<ConnectionInfo> getConnectionDetails() {
+    std::vector<ConnectionInfo> connections;
+    
+    for (auto conn : this->connections) {
+      if (conn->isConnected()) {
+        ConnectionInfo info;
+        info.nodeId = conn->nodeId;
+        info.lastSeen = conn->timeLastReceived;
+        info.rssi = conn->getRSSI();  // Need to add this to Connection class
+        info.avgLatency = conn->getLatency();  // Need to add this
+        info.hopCount = 1;  // Direct connection
+        info.quality = conn->getQuality();  // Need to add this
+        info.messagesRx = conn->messagesRx;  // Need to add counter
+        info.messagesTx = conn->messagesTx;  // Need to add counter
+        info.messagesDropped = conn->messagesDropped;  // Need to add counter
+        
+        connections.push_back(info);
+      }
+    }
+    
+    return connections;
+  }
+  
+  /**
+   * Get hop count to specific node using routing table
+   */
+  int getHopCount(uint32_t nodeId) {
+    auto route = this->findRoute(nodeId);
+    if (route.empty()) return -1;
+    return route.size() - 1;  // Don't count source node
+  }
+  
+  /**
+   * Get routing table as map (destination -> next hop)
+   */
+  std::map<uint32_t, uint32_t> getRoutingTable() {
+    std::map<uint32_t, uint32_t> table;
+    auto nodeList = this->getNodeList(false);
+    
+    for (auto destNode : nodeList) {
+      auto route = this->findRoute(destNode);
+      if (!route.empty() && route.size() > 1) {
+        table[destNode] = route[1];  // Next hop after source
+      }
+    }
+    
+    return table;
+  }
+```
+
+**Estimated Effort:** 4-6 hours (requires adding metrics tracking to Connection class)
+
+---
+
+### 1.2 Enhance Connection Class with Metrics
+
+**File:** `src/painlessmesh/tcp.hpp` (or wherever Connection is defined)
+
+**Add to Connection class:**
+
+```cpp
+class Connection {
+public:
+  // Existing members...
+  
+  // New metrics tracking
+  uint32_t messagesRx = 0;
+  uint32_t messagesTx = 0;
+  uint32_t messagesDropped = 0;
+  uint32_t timeLastReceived = 0;
+  
+  // Latency tracking
+  std::vector<uint32_t> latencySamples;
+  const size_t MAX_LATENCY_SAMPLES = 10;
+  
+  /**
+   * Record message received timestamp
+   */
+  void onMessageReceived() {
+    messagesRx++;
+    timeLastReceived = millis();
+  }
+  
+  /**
+   * Record message sent
+   */
+  void onMessageSent(bool success) {
+    if (success) {
+      messagesTx++;
+    } else {
+      messagesDropped++;
+    }
+  }
+  
+  /**
+   * Record round-trip time sample
+   */
+  void recordLatency(uint32_t latencyMs) {
+    latencySamples.push_back(latencyMs);
+    if (latencySamples.size() > MAX_LATENCY_SAMPLES) {
+      latencySamples.erase(latencySamples.begin());
+    }
+  }
+  
+  /**
+   * Get average latency from recent samples
+   */
+  int getLatency() {
+    if (latencySamples.empty()) return -1;
+    
+    uint32_t sum = 0;
+    for (auto sample : latencySamples) {
+      sum += sample;
+    }
+    return sum / latencySamples.size();
+  }
+  
+  /**
+   * Calculate connection quality (0-100)
+   * Based on: latency, packet loss, RSSI
+   */
+  int getQuality() {
+    // Simple quality calculation
+    int quality = 100;
+    
+    // Penalize high latency (>100ms)
+    int latency = getLatency();
+    if (latency > 100) quality -= (latency - 100) / 5;
+    
+    // Penalize packet loss
+    if (messagesTx > 0) {
+      int lossRate = (messagesDropped * 100) / messagesTx;
+      quality -= lossRate;
+    }
+    
+    // Penalize weak RSSI (if available)
+    int rssi = getRSSI();
+    if (rssi < -80) quality -= (80 + rssi);
+    
+    return max(0, min(100, quality));
+  }
+  
+  /**
+   * Get WiFi RSSI if available
+   * Note: Requires ESP8266/ESP32 specific code
+   */
+  int getRSSI() {
+    #if defined(ESP32) || defined(ESP8266)
+      // This needs platform-specific implementation
+      // For now, return placeholder
+      return -60;  // TODO: Get actual RSSI from WiFi
+    #else
+      return 0;  // Not available on non-WiFi platforms
+    #endif
+  }
+};
+```
+
+**Estimated Effort:** 6-8 hours (requires testing on ESP32/ESP8266)
+
+---
+
+## Part 2: Topology Reporter Implementation
+
+### 2.1 Create MeshTopologyReporter Class
+
+**File:** `examples/bridge/mesh_topology_reporter.hpp` (NEW)
+
+**Purpose:** Generate schema-compliant topology messages
+
+```cpp
+#ifndef MESH_TOPOLOGY_REPORTER_HPP
+#define MESH_TOPOLOGY_REPORTER_HPP
+
+#include "painlessMesh.h"
+#include <ArduinoJson.h>
+
+class MeshTopologyReporter {
+private:
+  painlessMesh& mesh;
+  String meshId;
+  String lastTopologyHash;  // Detect changes
+  
+public:
+  MeshTopologyReporter(painlessMesh& mesh, const String& meshId) 
+    : mesh(mesh), meshId(meshId) {}
+  
+  /**
+   * Generate full topology message (schema v0.5.0 compliant)
+   */
+  String generateFullTopology() {
+    DynamicJsonDocument doc(8192);  // Large buffer for full topology
+    
+    // Envelope fields (from @alteriom/mqtt-schema)
+    doc["schema_version"] = 1;
+    doc["device_id"] = String(mesh.getNodeId());
+    doc["device_type"] = "gateway";
+    doc["timestamp"] = getISO8601Timestamp();
+    doc["firmware_version"] = "GW 2.3.4";  // Make configurable
+    
+    // Event discriminator
+    doc["event"] = "mesh_topology";
+    
+    // Mesh identification
+    doc["mesh_id"] = meshId;
+    doc["gateway_node_id"] = String(mesh.getNodeId());
+    
+    // Nodes array
+    JsonArray nodes = doc.createNestedArray("nodes");
+    addNodeInfo(nodes, mesh.getNodeId(), "gateway");  // Self
+    
+    auto nodeList = mesh.getNodeList(false);
+    for (auto nodeId : nodeList) {
+      addNodeInfo(nodes, nodeId, "sensor");  // Assume sensor role
+    }
+    
+    // Connections array
+    JsonArray connections = doc.createNestedArray("connections");
+    addConnectionInfo(connections);
+    
+    // Network metrics
+    JsonObject metrics = doc.createNestedObject("metrics");
+    metrics["total_nodes"] = nodeList.size() + 1;  // +1 for gateway
+    metrics["online_nodes"] = nodeList.size() + 1;
+    metrics["network_diameter"] = calculateNetworkDiameter();
+    metrics["avg_connection_quality"] = calculateAvgQuality();
+    metrics["messages_per_second"] = calculateThroughput();
+    
+    doc["update_type"] = "full";
+    
+    String output;
+    serializeJson(doc, output);
+    return output;
+  }
+  
+  /**
+   * Generate incremental topology update
+   */
+  String generateIncrementalUpdate(uint32_t nodeId, bool joined) {
+    DynamicJsonDocument doc(2048);
+    
+    // Envelope fields
+    doc["schema_version"] = 1;
+    doc["device_id"] = String(mesh.getNodeId());
+    doc["device_type"] = "gateway";
+    doc["timestamp"] = getISO8601Timestamp();
+    doc["firmware_version"] = "GW 2.3.4";
+    
+    doc["event"] = "mesh_topology";
+    doc["mesh_id"] = meshId;
+    doc["gateway_node_id"] = String(mesh.getNodeId());
+    
+    // Node that changed
+    JsonArray nodes = doc.createNestedArray("nodes");
+    if (joined) {
+      addNodeInfo(nodes, nodeId, "sensor");
+    } else {
+      // For node leaving, mark as offline
+      JsonObject node = nodes.createNestedObject();
+      node["node_id"] = String(nodeId);
+      node["status"] = "offline";
+    }
+    
+    // Update connections
+    JsonArray connections = doc.createNestedArray("connections");
+    // Add connections related to this node
+    
+    doc["update_type"] = "incremental";
+    
+    String output;
+    serializeJson(doc, output);
+    return output;
+  }
+  
+  /**
+   * Check if topology has changed
+   */
+  bool hasTopologyChanged() {
+    String currentHash = calculateTopologyHash();
+    if (currentHash != lastTopologyHash) {
+      lastTopologyHash = currentHash;
+      return true;
+    }
+    return false;
+  }
+  
+private:
+  /**
+   * Add node information to JSON array
+   */
+  void addNodeInfo(JsonArray& nodes, uint32_t nodeId, const char* role) {
+    JsonObject node = nodes.createNestedObject();
+    node["node_id"] = String(nodeId);
+    node["role"] = role;
+    node["status"] = "online";
+    node["last_seen"] = getISO8601Timestamp();
+    
+    // If we have connection to this node, add metrics
+    // This requires connection metadata API
+    node["uptime_seconds"] = 0;  // TODO: Track per-node uptime
+    node["free_memory_kb"] = 0;  // TODO: Get from node status messages
+    node["connection_count"] = 0;  // TODO: Calculate from mesh structure
+    
+    // Gateway node has additional info
+    if (nodeId == mesh.getNodeId()) {
+      node["uptime_seconds"] = millis() / 1000;
+      node["free_memory_kb"] = ESP.getFreeHeap() / 1024;
+      node["connection_count"] = mesh.getNodeList().size();
+    }
+  }
+  
+  /**
+   * Add connection information to JSON array
+   */
+  void addConnectionInfo(JsonArray& connections) {
+    // Get direct connections with quality metrics
+    // This requires new API: mesh.getConnectionDetails()
+    
+    auto nodeList = mesh.getNodeList(false);
+    uint32_t gatewayId = mesh.getNodeId();
+    
+    // For now, create basic connection data
+    // TODO: Use actual connection quality API
+    for (auto nodeId : nodeList) {
+      JsonObject conn = connections.createNestedObject();
+      conn["from_node"] = String(gatewayId);
+      conn["to_node"] = String(nodeId);
+      conn["quality"] = 85;  // TODO: Get actual quality
+      conn["latency_ms"] = 20;  // TODO: Get actual latency
+      conn["rssi"] = -55;  // TODO: Get actual RSSI
+      conn["hop_count"] = 1;  // TODO: Calculate hop count
+    }
+  }
+  
+  /**
+   * Calculate network diameter (max hop count)
+   */
+  int calculateNetworkDiameter() {
+    int maxHops = 0;
+    auto nodeList = mesh.getNodeList(false);
+    
+    for (auto nodeId : nodeList) {
+      // TODO: Use mesh.getHopCount(nodeId)
+      // For now assume max 2 hops
+      maxHops = max(maxHops, 2);
+    }
+    
+    return maxHops;
+  }
+  
+  /**
+   * Calculate average connection quality
+   */
+  float calculateAvgQuality() {
+    // TODO: Use connection quality API
+    // For now return placeholder
+    return 85.0;
+  }
+  
+  /**
+   * Calculate network throughput
+   */
+  float calculateThroughput() {
+    // TODO: Track message rates
+    // For now return placeholder
+    return 12.4;
+  }
+  
+  /**
+   * Calculate topology hash for change detection
+   */
+  String calculateTopologyHash() {
+    auto nodeList = mesh.getNodeList(true);
+    String hash = String(nodeList.size());
+    for (auto nodeId : nodeList) {
+      hash += String(nodeId);
+    }
+    return hash;
+  }
+  
+  /**
+   * Get current timestamp in ISO 8601 format
+   */
+  String getISO8601Timestamp() {
+    // TODO: Use proper NTP time if available
+    // For now return epoch-based timestamp
+    unsigned long ms = millis();
+    char timestamp[32];
+    snprintf(timestamp, sizeof(timestamp), "2025-10-12T%02lu:%02lu:%02luZ",
+             (ms / 3600000) % 24,
+             (ms / 60000) % 60,
+             (ms / 1000) % 60);
+    return String(timestamp);
+  }
+};
+
+#endif  // MESH_TOPOLOGY_REPORTER_HPP
+```
+
+**Estimated Effort:** 8-10 hours (initial implementation + testing)
+
+---
+
+### 2.2 Create MeshEventPublisher Class
+
+**File:** `examples/bridge/mesh_event_publisher.hpp` (NEW)
+
+**Purpose:** Publish real-time mesh events
+
+```cpp
+#ifndef MESH_EVENT_PUBLISHER_HPP
+#define MESH_EVENT_PUBLISHER_HPP
+
+#include "painlessMesh.h"
+#include <PubSubClient.h>
+#include <ArduinoJson.h>
+
+class MeshEventPublisher {
+private:
+  painlessMesh& mesh;
+  PubSubClient& mqttClient;
+  String meshId;
+  String eventTopic;
+  
+public:
+  MeshEventPublisher(painlessMesh& mesh, PubSubClient& mqttClient, 
+                     const String& meshId, const String& topic = "mesh/events")
+    : mesh(mesh), mqttClient(mqttClient), meshId(meshId), eventTopic(topic) {}
+  
+  /**
+   * Publish node join event
+   */
+  void publishNodeJoin(uint32_t nodeId) {
+    DynamicJsonDocument doc(1024);
+    
+    // Envelope
+    doc["schema_version"] = 1;
+    doc["device_id"] = String(mesh.getNodeId());
+    doc["device_type"] = "gateway";
+    doc["timestamp"] = getISO8601Timestamp();
+    doc["firmware_version"] = "GW 2.3.4";
+    
+    // Event
+    doc["event"] = "mesh_event";
+    doc["event_type"] = "node_join";
+    doc["mesh_id"] = meshId;
+    
+    JsonArray affected = doc.createNestedArray("affected_nodes");
+    affected.add(String(nodeId));
+    
+    JsonObject details = doc.createNestedObject("details");
+    details["total_nodes"] = mesh.getNodeList().size() + 1;
+    details["timestamp"] = getISO8601Timestamp();
+    
+    publishEvent(doc);
+  }
+  
+  /**
+   * Publish node leave event
+   */
+  void publishNodeLeave(uint32_t nodeId) {
+    DynamicJsonDocument doc(1024);
+    
+    // Envelope
+    doc["schema_version"] = 1;
+    doc["device_id"] = String(mesh.getNodeId());
+    doc["device_type"] = "gateway";
+    doc["timestamp"] = getISO8601Timestamp();
+    doc["firmware_version"] = "GW 2.3.4";
+    
+    // Event
+    doc["event"] = "mesh_event";
+    doc["event_type"] = "node_leave";
+    doc["mesh_id"] = meshId;
+    
+    JsonArray affected = doc.createNestedArray("affected_nodes");
+    affected.add(String(nodeId));
+    
+    JsonObject details = doc.createNestedObject("details");
+    details["reason"] = "connection_lost";
+    details["last_seen"] = getISO8601Timestamp();
+    details["total_nodes"] = mesh.getNodeList().size() + 1;
+    
+    publishEvent(doc);
+  }
+  
+  /**
+   * Publish connection lost event
+   */
+  void publishConnectionLost(uint32_t nodeId) {
+    DynamicJsonDocument doc(1024);
+    
+    doc["schema_version"] = 1;
+    doc["device_id"] = String(mesh.getNodeId());
+    doc["device_type"] = "gateway";
+    doc["timestamp"] = getISO8601Timestamp();
+    doc["firmware_version"] = "GW 2.3.4";
+    
+    doc["event"] = "mesh_event";
+    doc["event_type"] = "connection_lost";
+    doc["mesh_id"] = meshId;
+    
+    JsonArray affected = doc.createNestedArray("affected_nodes");
+    affected.add(String(nodeId));
+    
+    publishEvent(doc);
+  }
+  
+  /**
+   * Publish connection restored event
+   */
+  void publishConnectionRestored(uint32_t nodeId) {
+    DynamicJsonDocument doc(1024);
+    
+    doc["schema_version"] = 1;
+    doc["device_id"] = String(mesh.getNodeId());
+    doc["device_type"] = "gateway";
+    doc["timestamp"] = getISO8601Timestamp();
+    doc["firmware_version"] = "GW 2.3.4";
+    
+    doc["event"] = "mesh_event";
+    doc["event_type"] = "connection_restored";
+    doc["mesh_id"] = meshId;
+    
+    JsonArray affected = doc.createNestedArray("affected_nodes");
+    affected.add(String(nodeId));
+    
+    publishEvent(doc);
+  }
+  
+private:
+  void publishEvent(const DynamicJsonDocument& doc) {
+    if (!mqttClient.connected()) return;
+    
+    String payload;
+    serializeJson(doc, payload);
+    
+    mqttClient.publish(eventTopic.c_str(), payload.c_str());
+    
+    Serial.printf("[Event] Published: %s\n", 
+                  doc["event_type"].as<const char*>());
+  }
+  
+  String getISO8601Timestamp() {
+    unsigned long ms = millis();
+    char timestamp[32];
+    snprintf(timestamp, sizeof(timestamp), "2025-10-12T%02lu:%02lu:%02luZ",
+             (ms / 3600000) % 24,
+             (ms / 60000) % 60,
+             (ms / 1000) % 60);
+    return String(timestamp);
+  }
+};
+
+#endif  // MESH_EVENT_PUBLISHER_HPP
+```
+
+**Estimated Effort:** 4-6 hours
+
+---
+
+## Part 3: Enhanced Gateway Bridge
+
+### 3.1 Update mqttCommandBridge.ino
+
+**File:** `examples/mqttCommandBridge/mqttCommandBridge.ino`
+
+**Changes Required:**
+
+1. Include new reporters
+2. Replace simple topology with schema-compliant topology
+3. Add event publisher integration
+4. Add topology command handler
+
+```cpp
+// Add includes
+#include "examples/bridge/mesh_topology_reporter.hpp"
+#include "examples/bridge/mesh_event_publisher.hpp"
+
+// Add global instances
+MeshTopologyReporter* topologyReporter;
+MeshEventPublisher* eventPublisher;
+
+// Update taskTopology
+Task taskTopology(TASK_SECOND * 60, TASK_FOREVER, []() {
+  if (mqttClient.connected()) {
+    // Generate schema-compliant topology
+    String topology = topologyReporter->generateFullTopology();
+    mqttClient.publish("alteriom/mesh/MESH-001/topology", topology.c_str());
+    
+    Serial.println("[Topology] Published full mesh topology");
+  }
+});
+
+// Add incremental topology task
+Task taskTopologyIncremental(TASK_SECOND * 5, TASK_FOREVER, []() {
+  if (mqttClient.connected() && topologyReporter->hasTopologyChanged()) {
+    // Publish incremental update only if topology changed
+    // Note: This requires tracking what changed
+    Serial.println("[Topology] Topology changed, publishing update");
+    
+    // For now, publish full topology
+    // TODO: Generate incremental updates
+    String topology = topologyReporter->generateFullTopology();
+    mqttClient.publish("alteriom/mesh/MESH-001/topology", topology.c_str());
+  }
+});
+
+// Update setup()
+void setup() {
+  // ... existing setup code ...
+  
+  // Initialize topology reporter
+  topologyReporter = new MeshTopologyReporter(mesh, "MESH-001");
+  
+  // Initialize event publisher
+  eventPublisher = new MeshEventPublisher(mesh, mqttClient, "MESH-001");
+  
+  // Update mesh callbacks to use event publisher
+  mesh.onNewConnection([](uint32_t nodeId) {
+    Serial.printf("New node connected: %u\n", nodeId);
+    eventPublisher->publishNodeJoin(nodeId);
+    
+    // Trigger topology update
+    String topology = topologyReporter->generateIncrementalUpdate(nodeId, true);
+    mqttClient.publish("alteriom/mesh/MESH-001/topology", topology.c_str());
+  });
+  
+  mesh.onDroppedConnection([](uint32_t nodeId) {
+    Serial.printf("Node disconnected: %u\n", nodeId);
+    eventPublisher->publishNodeLeave(nodeId);
+    
+    // Trigger topology update
+    String topology = topologyReporter->generateIncrementalUpdate(nodeId, false);
+    mqttClient.publish("alteriom/mesh/MESH-001/topology", topology.c_str());
+  });
+  
+  // Add incremental topology task
+  userScheduler.addTask(taskTopologyIncremental);
+  taskTopologyIncremental.enable();
+  
+  // ... rest of setup ...
+}
+```
+
+**Estimated Effort:** 3-4 hours
+
+---
+
+### 3.2 Add Topology Command Handler
+
+**Update:** `examples/bridge/mqtt_command_bridge.hpp`
+
+**Add command 300 (GET_TOPOLOGY):**
+
+```cpp
+case 300:  // GET_TOPOLOGY
+  Serial.println("Command: GET_TOPOLOGY");
+  if (cmd.targetDevice == mesh.getNodeId() || cmd.targetDevice == 0) {
+    // Gateway should respond with full topology
+    // This requires access to MeshTopologyReporter
+    // For now, acknowledge and let scheduled task handle it
+    executeCommand(cmd);
+  } else {
+    // Forward to specific node (may not make sense)
+    forwardCommandToMesh(cmd);
+  }
+  break;
+```
+
+**Estimated Effort:** 2-3 hours
+
+---
+
+## Part 4: Testing & Validation
+
+### 4.1 Create Test Sketch
+
+**File:** `examples/mqttTopologyTest/mqttTopologyTest.ino` (NEW)
+
+**Purpose:** Test topology reporting with 3-node mesh
+
+```cpp
+// Minimal test setup with 3 ESP32s
+// - 1 Gateway (publishes topology)
+// - 2 Sensor nodes
+// Verify:
+// - Full topology published every 60s
+// - Incremental updates on node join/leave
+// - Events published correctly
+// - Schema validation passes
+```
+
+**Estimated Effort:** 4-6 hours (requires physical hardware)
+
+---
+
+### 4.2 Schema Validation Tests
+
+**File:** `test/catch/catch_topology_schema.cpp` (NEW)
+
+**Purpose:** Validate generated topology matches schema
+
+```cpp
+#define CATCH_CONFIG_MAIN
+#include "catch2/catch.hpp"
+#include "Arduino.h"
+#include "catch_utils.hpp"
+#include "../../examples/bridge/mesh_topology_reporter.hpp"
+
+SCENARIO("Topology message validates against schema") {
+  GIVEN("A MeshTopologyReporter") {
+    // Test that generated JSON matches schema requirements
+    REQUIRE(topology_has_envelope_fields());
+    REQUIRE(topology_has_nodes_array());
+    REQUIRE(topology_has_connections_array());
+    REQUIRE(topology_has_metrics_object());
+  }
+}
+```
+
+**Estimated Effort:** 6-8 hours
+
+---
+
+## Part 5: Documentation Updates
+
+### 5.1 Update MQTT_BRIDGE_COMMANDS.md
+
+Add sections:
+
+- Mesh Topology Reporting
+- Mesh Events
+- Topology command (300)
+
+**Estimated Effort:** 2-3 hours
+
+---
+
+### 5.2 Create MESH_TOPOLOGY_GUIDE.md
+
+**File:** `docs/MESH_TOPOLOGY_GUIDE.md` (NEW)
+
+**Content:**
+
+- How topology reporting works
+- How to visualize with D3.js
+- Troubleshooting topology issues
+- Performance considerations
+
+**Estimated Effort:** 4-6 hours
+
+---
+
+## Implementation Summary
+
+### Phase 1: Core Library (HIGH PRIORITY)
+
+| Task | File | Effort | Priority |
+|------|------|--------|----------|
+| Add ConnectionInfo struct | mesh.hpp | 2h | 🔴 HIGH |
+| Add getConnectionDetails() | mesh.hpp | 4h | 🔴 HIGH |
+| Add getHopCount() | mesh.hpp | 2h | 🔴 HIGH |
+| Add getRoutingTable() | mesh.hpp | 2h | 🔴 HIGH |
+| Add Connection metrics | tcp.hpp | 6h | 🔴 HIGH |
+| **Subtotal** | | **16h** | |
+
+### Phase 2: Topology Reporter (HIGH PRIORITY)
+
+| Task | File | Effort | Priority |
+|------|------|--------|----------|
+| Create MeshTopologyReporter | NEW | 8h | 🔴 HIGH |
+| Create MeshEventPublisher | NEW | 4h | 🔴 HIGH |
+| Update mqttCommandBridge.ino | MODIFY | 4h | 🔴 HIGH |
+| Add topology command handler | MODIFY | 2h | 🟡 MEDIUM |
+| **Subtotal** | | **18h** | |
+
+### Phase 3: Testing (MEDIUM PRIORITY)
+
+| Task | File | Effort | Priority |
+|------|------|--------|----------|
+| Physical hardware testing | NEW | 6h | 🟡 MEDIUM |
+| Schema validation tests | NEW | 8h | 🟡 MEDIUM |
+| Integration testing | VARIOUS | 4h | 🟡 MEDIUM |
+| **Subtotal** | | **18h** | |
+
+### Phase 4: Documentation (LOW PRIORITY)
+
+| Task | File | Effort | Priority |
+|------|------|--------|----------|
+| Update MQTT_BRIDGE_COMMANDS.md | MODIFY | 3h | 🟢 LOW |
+| Create MESH_TOPOLOGY_GUIDE.md | NEW | 6h | 🟢 LOW |
+| Update README examples | MODIFY | 2h | 🟢 LOW |
+| **Subtotal** | | **11h** | |
+
+---
+
+## Total Implementation Effort
+
+| Phase | Hours | Priority |
+|-------|-------|----------|
+| Phase 1: Core Library | 16h | 🔴 HIGH |
+| Phase 2: Topology Reporter | 18h | 🔴 HIGH |
+| Phase 3: Testing | 18h | 🟡 MEDIUM |
+| Phase 4: Documentation | 11h | 🟢 LOW |
+| **TOTAL** | **63h** | |
+
+**Estimated Calendar Time:** 2-3 weeks (assuming 1 developer, part-time)
+
+---
+
+## Dependencies
+
+### External Dependencies
+
+1. ✅ **@alteriom/mqtt-schema v0.5.0** - Schema definitions
+2. ✅ **ArduinoJson** - Already used
+3. ✅ **PubSubClient** - Already used
+4. ✅ **TaskScheduler** - Already used
+
+### Internal Dependencies
+
+1. ⚠️ **painlessMesh core API changes** - Breaking changes to Connection class
+2. ⚠️ **RSSI tracking** - Platform-specific (ESP32/ESP8266)
+3. ⚠️ **NTP time sync** - For accurate ISO 8601 timestamps
+
+---
+
+## Risk Assessment
+
+### High Risk ⚠️
+
+1. **Connection metrics API** - Requires changes to core library
+   - Mitigation: Extensive testing, backward compatibility checks
+
+2. **RSSI tracking** - Platform-specific implementation
+   - Mitigation: Abstract platform differences, provide defaults
+
+3. **Memory constraints** - Large JSON documents (8KB topology)
+   - Mitigation: Use streaming JSON, reduce buffer sizes on ESP8266
+
+### Medium Risk 🟡
+
+1. **Performance impact** - Additional metric tracking overhead
+   - Mitigation: Make metrics collection optional, optimize data structures
+
+2. **Breaking changes** - Connection class modifications
+   - Mitigation: Version bump to v1.7.0, update changelog
+
+### Low Risk ✅
+
+1. **Schema compliance** - Matching @alteriom/mqtt-schema exactly
+   - Mitigation: Automated schema validation tests
+
+---
+
+## Backward Compatibility
+
+### Breaking Changes ⚠️
+
+1. **Connection class** - New public members may break existing code that copies/serializes Connection objects
+   - **Solution:** Version bump to v1.7.0, deprecation warnings in v1.6.x
+
+2. **Memory usage** - Increased RAM usage due to metric tracking
+   - **Solution:** Make metrics optional via compile-time flag `PAINLESSMESH_ENABLE_METRICS`
+
+### Non-Breaking Changes ✅
+
+1. **New API methods** - additive, doesn't affect existing code
+2. **MQTT bridge enhancements** - in examples, not core library
+3. **Documentation** - purely additive
+
+---
+
+## Recommended Implementation Order
+
+### Week 1: Foundation
+
+1. ✅ Review and approve schema additions
+2. Add ConnectionInfo struct to mesh.hpp
+3. Add basic metric tracking to Connection class
+4. Implement getConnectionDetails() API
+
+### Week 2: Topology Reporting
+
+1. Create MeshTopologyReporter class
+2. Create MeshEventPublisher class
+3. Update mqttCommandBridge.ino
+4. Basic testing with 2-node mesh
+
+### Week 3: Polish & Testing
+
+1. Add topology command handler
+2. Physical hardware testing (3-4 node mesh)
+3. Schema validation tests
+4. Documentation updates
+
+---
+
+## Success Criteria
+
+✅ **Must Have (v1.7.0):**
+
+- Schema-compliant topology messages
+- Real-time mesh events (join/leave)
+- Connection quality metrics (RSSI, latency, quality)
+- Full and incremental topology updates
+- Backward compatible with v1.6.x (no breaking changes to public API)
+
+📋 **Should Have (v1.7.1):**
+
+- Topology command handler (GET_TOPOLOGY)
+- Hop count calculation
+- Routing table export
+- Performance optimization
+
+🎯 **Nice to Have (v1.8.0):**
+
+- Mesh diagnostics command
+- Per-message route tracking
+- Historical topology storage
+- Advanced quality metrics (jitter, throughput)
+
+---
+
+## Next Steps
+
+### Immediate Actions
+
+1. 📝 **Review this plan** - Get team approval
+2. 🔧 **Set up development branch** - `feature/mesh-topology-v0.5`
+3. 📦 **Create GitHub issues** - Break down tasks
+4. 🧪 **Set up test hardware** - 3x ESP32 boards
+5. 📚 **Wait for schema release** - Monitor @alteriom/mqtt-schema repo
+
+### Development Kickoff
+
+Once @alteriom/mqtt-schema v0.5.0 is released:
+
+1. Start with Phase 1 (Core Library APIs)
+2. Weekly progress check-ins
+3. Code reviews for each major component
+4. Continuous integration testing
+
+---
+
+**Prepared By:** Alteriom Development Team  
+**Date:** October 12, 2025  
+**Status:** 📋 READY FOR IMPLEMENTATION  
+**Estimated Completion:** 3 weeks from start