npm - @alteriom/painlessmesh - Versions diffs - 1.7.4 → 1.7.5 - Mend

@alteriom/painlessmesh 1.7.4 → 1.7.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1736) hide show

package/docs/MQTT_BRIDGE_COMMANDS.md CHANGED Viewed

@@ -1,894 +1,894 @@
-# MQTT Bridge Commands Reference
-## Overview
-This document provides a complete reference for MQTT-to-mesh bridge commands in painlessMesh Alteriom fork. The MQTT bridge enables bidirectional communication between MQTT brokers and mesh networks, allowing web applications to control and monitor mesh nodes.
-## Table of Contents
-1. [Architecture Overview](#architecture-overview)
-2. [Command Types](#command-types)
-3. [MQTT Topic Structure](#mqtt-topic-structure)
-4. [Command Definitions](#command-definitions)
-5. [Implementation Guide](#implementation-guide)
-6. [Complete Examples](#complete-examples)
-7. [Troubleshooting](#troubleshooting)
----
-## Architecture Overview
-### Communication Flow
-```
-Web Application → MQTT Broker → Gateway Bridge → Mesh Network → Target Node
-Target Node → Mesh Network → Gateway Bridge → MQTT Broker → Web Application
-```
-### Components
-1. **MQTT Broker** - Central message router (Mosquitto, HiveMQ, AWS IoT)
-2. **Gateway Bridge** - ESP32/ESP8266 with WiFi + mesh capability
-3. **Mesh Nodes** - ESP devices in mesh network
-4. **Web Application** - Control interface publishing MQTT commands
-### Message Types
-| Direction | Package Type | Purpose |
-|-----------|--------------|---------|
-| MQTT → Mesh | CommandPackage (201) | Control device, request data |
-| Mesh → MQTT | StatusPackage (202) | Report device status |
-| Mesh → MQTT | SensorPackage (200) | Sensor data reports |
-| Mesh → MQTT | EnhancedStatusPackage (203) | Detailed health metrics |
----
-## Command Types
-### Device Control Commands (1-99)
-| Command ID | Name | Description | Parameters |
-|------------|------|-------------|------------|
-| 1 | RESET | Restart device | None |
-| 2 | SLEEP | Enter deep sleep | `duration_ms` (uint32_t) |
-| 3 | WAKE | Wake from sleep | None |
-| 10 | LED_CONTROL | Control onboard LED | `state` (bool), `brightness` (uint8_t) |
-| 11 | RELAY_SWITCH | Control relay output | `channel` (uint8_t), `state` (bool) |
-| 12 | PWM_SET | Set PWM output | `pin` (uint8_t), `duty` (uint16_t) |
-| 20 | SENSOR_ENABLE | Enable/disable sensor | `sensor_id` (uint8_t), `enabled` (bool) |
-| 21 | SENSOR_CALIBRATE | Calibrate sensor | `sensor_id` (uint8_t) |
-### Configuration Commands (100-199)
-| Command ID | Name | Description | Parameters |
-|------------|------|-------------|------------|
-| 100 | GET_CONFIG | Request current configuration | None |
-| 101 | SET_CONFIG | Update configuration | JSON config object |
-| 102 | RESET_CONFIG | Reset to factory defaults | None |
-| 103 | SAVE_CONFIG | Persist config to flash | None |
-| 110 | SET_SAMPLE_RATE | Change sensor sample rate | `rate_ms` (uint32_t) |
-| 111 | SET_DEVICE_NAME | Update device name | `name` (string) |
-### Status Commands (200-255)
-| Command ID | Name | Description | Parameters |
-|------------|------|-------------|------------|
-| 200 | GET_STATUS | Request basic status | None |
-| 201 | GET_METRICS | Request performance metrics | None |
-| 202 | GET_DIAGNOSTICS | Request detailed diagnostics | None |
-| 210 | START_MONITORING | Begin continuous monitoring | `interval_ms` (uint32_t) |
-| 211 | STOP_MONITORING | Stop continuous monitoring | None |
-### Topology Commands (300-399) ✨ NEW in v0.5.0
-| Command ID | Name | Description | Parameters |
-|------------|------|-------------|------------|
-| 300 | GET_TOPOLOGY | Request mesh network topology | `format` (optional): "full" or "summary" |
-**Response:** Full mesh topology published to `alteriom/mesh/{mesh_id}/topology/response` with `correlation_id` field matching the command ID.
-**Example Response:**
-```json
-{
-  "schema_version": 1,
-  "event": "mesh_topology",
-  "correlation_id": "12345",
-  "mesh_id": "MESH-001",
-  "nodes": [...],
-  "connections": [...],
-  "metrics": {...}
-}
-```
----
-## MQTT Topic Structure
-### Command Topics (Published by Web App)
-```
-mesh/command/{nodeId}           # Send command to specific node
-mesh/command/broadcast          # Broadcast command to all nodes
-mesh/config/{nodeId}/get        # Request configuration
-mesh/config/{nodeId}/set        # Update configuration
-mesh/ota/{nodeId}/start         # Initiate OTA update
-```
-### Response Topics (Published by Gateway Bridge)
-```
-mesh/response/{nodeId}                    # Command acknowledgments
-mesh/status/{nodeId}                      # Status updates (Type 202)
-mesh/sensor/{nodeId}                      # Sensor data (Type 200)
-mesh/health/{nodeId}                      # Enhanced status (Type 203)
-mesh/config/{nodeId}                      # Configuration data
-mesh/error/{nodeId}                       # Error reports
-```
-### System Topics (Legacy - v0.4.0)
-```
-mesh/gateway/status                       # Gateway bridge health
-mesh/topology                             # Mesh network topology (old format)
-mesh/nodes                                # List of connected nodes
-```
-### Topology & Event Topics ✨ NEW (v0.5.0 - @alteriom/mqtt-schema compliant)
-```
-alteriom/mesh/{mesh_id}/topology          # Full/incremental mesh topology
-alteriom/mesh/{mesh_id}/topology/response # Topology responses to GET_TOPOLOGY command
-alteriom/mesh/{mesh_id}/events            # Real-time mesh state change events
-```
-**Schema Compliance:** All topology and event messages conform to **@alteriom/mqtt-schema v0.5.0** specification.
-**Key Features:**
-- **Device ID Format:** `ALT-XXXXXXXXXXXX` (12 hex digits)
-- **Envelope Fields:** `schema_version`, `device_id`, `device_type`, `timestamp`, `firmware_version`
-- **Connection Metrics:** RSSI, latency, quality (0-100), packet counts
-- **Network Metrics:** Total nodes, network diameter, average quality
-- **Update Types:** Full (every 60s), Incremental (every 5s if changed)
-- **Event Types:** node_join, node_leave, connection_lost, connection_restored, network_split, network_merged
----
-## Command Definitions
-### CommandPackage Structure (Type 201)
-Defined in `examples/alteriom/alteriom_sensor_package.hpp`:
-```cpp
-class CommandPackage : public painlessmesh::plugin::SinglePackage {
-public:
-  uint8_t command = 0;          // Command ID (1-255)
-  uint32_t targetDevice = 0;    // Destination node ID
-  uint32_t commandId = 0;       // Unique command tracking ID
-  TSTRING parameters = "";      // JSON-encoded parameters
-  CommandPackage() : SinglePackage(201) {}
-};
-```
-### Command Parameter Encoding
-Parameters are JSON-encoded strings:
-```json
-{
-  "state": "ON",
-  "brightness": 75,
-  "duration_ms": 5000
-}
-```
-### Command Response Structure
-Responses use StatusPackage (Type 202) with enhanced fields:
-```cpp
-class StatusPackage : public painlessmesh::plugin::BroadcastPackage {
-public:
-  uint8_t deviceStatus = 0;     // 0=OK, 1=Warning, 2=Error
-  uint32_t uptime = 0;          // Seconds since boot
-  uint16_t freeMemory = 0;      // Free heap in KB
-  TSTRING firmwareVersion = ""; // Current firmware version
-  // Response fields
-  uint32_t responseToCommand = 0;  // Original commandId
-  TSTRING responseMessage = "";    // Success/error message
-  StatusPackage() : BroadcastPackage(202) {}
-};
-```
----
-## Implementation Guide
-### Gateway Bridge Implementation
-The gateway bridge is implemented in `examples/bridge/mqtt_command_bridge.hpp` and provides:
-1. **MQTT → Mesh Command Forwarding**
-   - Subscribes to command topics
-   - Parses JSON payloads
-   - Routes commands to target nodes
-2. **Mesh → MQTT Response Forwarding**
-   - Receives mesh messages
-   - Publishes to appropriate MQTT topics
-   - Maintains message routing
-3. **Configuration Management**
-   - Handles config requests
-   - Applies config updates
-   - Sends acknowledgments
-4. **Local Command Execution**
-   - Executes commands targeted at gateway
-   - Sends responses via MQTT
-### Mesh Node Implementation
-Mesh nodes implement command handlers in `examples/alteriom/mesh_command_node.ino`:
-1. **Command Reception**
-   - Listen for CommandPackage (Type 201)
-   - Parse command and parameters
-   - Execute appropriate action
-2. **Response Generation**
-   - Create StatusPackage response
-   - Include commandId for tracking
-   - Broadcast back to mesh
-3. **Status Reporting**
-   - Send periodic status updates
-   - Report errors and warnings
-   - Include relevant metrics
----
-## Mesh Topology Reporting ✨ NEW in v0.5.0
-### Overview
-The mesh topology system provides real-time visibility into the structure and health of your mesh network. It publishes detailed information about nodes, connections, and network metrics in a standardized format that complies with **@alteriom/mqtt-schema v0.5.0**.
-**Implementation:** `examples/bridge/mesh_topology_reporter.hpp`
-### Topology Message Structure
-#### Envelope Fields (Required by @alteriom/mqtt-schema)
-```json
-{
-  "schema_version": 1,
-  "device_id": "ALT-6825DD341CA4",
-  "device_type": "gateway",
-  "timestamp": "2025-01-12T15:00:00Z",
-  "firmware_version": "GW 2.3.4"
-}
-```
-#### Topology Payload
-```json
-{
-  "event": "mesh_topology",
-  "mesh_id": "MESH-001",
-  "gateway_node_id": "ALT-6825DD341CA4",
-  "nodes": [
-    {
-      "node_id": "ALT-6825DD341CA4",
-      "role": "gateway",
-      "status": "online",
-      "last_seen": "2025-01-12T15:00:00Z",
-      "firmware_version": "GW 2.3.4",
-      "uptime_seconds": 86400,
-      "free_memory_kb": 128,
-      "connection_count": 3
-    }
-  ],
-  "connections": [
-    {
-      "from_node": "ALT-6825DD341CA4",
-      "to_node": "ALT-441D64F804A0",
-      "quality": 95,
-      "latency_ms": 12,
-      "rssi": -42,
-      "hop_count": 1
-    }
-  ],
-  "metrics": {
-    "total_nodes": 4,
-    "online_nodes": 4,
-    "network_diameter": 2,
-    "avg_connection_quality": 85,
-    "messages_per_second": 12.4
-  },
-  "update_type": "full"
-}
-```
-### Publishing Schedule
-| Update Type | Frequency | Trigger | Topic |
-|-------------|-----------|---------|-------|
-| Full Topology | Every 60 seconds | Timer | `alteriom/mesh/MESH-001/topology` |
-| Incremental | Every 5 seconds | Change detection | `alteriom/mesh/MESH-001/topology` |
-| On-Demand | Immediate | GET_TOPOLOGY command | `alteriom/mesh/MESH-001/topology/response` |
-### Node Roles
-| Role | Description | Typical Use |
-|------|-------------|-------------|
-| gateway | MQTT bridge with WiFi | Root node, MQTT publisher |
-| sensor | Sensor measurement node | Data collection |
-| repeater | Range extender | Network coverage |
-### Connection Quality Metrics
-**Quality Score (0-100):** Calculated from latency, packet loss, and RSSI
-- **90-100:** Excellent - Low latency (<50ms), strong signal (>-50 dBm)
-- **70-89:** Good - Moderate latency (<100ms), good signal (>-70 dBm)
-- **50-69:** Fair - Higher latency (<200ms), weaker signal (>-80 dBm)
-- **0-49:** Poor - High latency (>200ms), weak signal (<-80 dBm)
-**RSSI (Received Signal Strength Indicator):**
-- Values in dBm (negative numbers)
-- Stronger signal = higher (less negative) value
-- Example: -42 dBm is better than -75 dBm
-**Latency:**
-- Round-trip time in milliseconds
-- Calculated from message exchange timing
-- Lower is better
-### GET_TOPOLOGY Command (300)
-**Request:** Publish to `mesh/command/{gateway_id}` or `mesh/command/broadcast`
-```json
-{
-  "type": 201,
-  "command": 300,
-  "targetDevice": 0,
-  "commandId": 12345,
-  "parameters": "{}"
-}
-```
-**Response:** Published to `alteriom/mesh/MESH-001/topology/response`
-```json
-{
-  "schema_version": 1,
-  "device_id": "ALT-6825DD341CA4",
-  "event": "mesh_topology",
-  "correlation_id": "12345",
-  "mesh_id": "MESH-001",
-  ... full topology ...
-}
-```
-**Key Feature:** The `correlation_id` field matches the command's `commandId` for request tracking.
----
-## Mesh Events ✨ NEW in v0.5.0
-### Overview
-Real-time notifications of mesh network state changes. Published immediately when events occur.
-**Implementation:** `examples/bridge/mesh_event_publisher.hpp`
-**Topic:** `alteriom/mesh/MESH-001/events`
-### Event Types
-| Event Type | Description | When Triggered |
-|------------|-------------|----------------|
-| node_join | New node connected | onNewConnection() callback |
-| node_leave | Node disconnected | onDroppedConnection() callback |
-| connection_lost | Direct connection failed | Connection timeout |
-| connection_restored | Connection recovered | After connection_lost |
-| network_split | Mesh partitioned | Network segmentation detected |
-| network_merged | Partitions rejoined | Segments reconnected |
-### Event Message Structure
-#### Node Join Event
-```json
-{
-  "schema_version": 1,
-  "device_id": "ALT-6825DD341CA4",
-  "device_type": "gateway",
-  "timestamp": "2025-01-12T15:05:00Z",
-  "firmware_version": "GW 2.3.4",
-  "event": "mesh_event",
-  "event_type": "node_join",
-  "mesh_id": "MESH-001",
-  "affected_nodes": ["ALT-441D64F804A0"],
-  "details": {
-    "total_nodes": 4,
-    "timestamp": "2025-01-12T15:05:00Z"
-  }
-}
-```
-#### Node Leave Event
-```json
-{
-  "schema_version": 1,
-  "device_id": "ALT-6825DD341CA4",
-  "device_type": "gateway",
-  "timestamp": "2025-01-12T15:10:00Z",
-  "firmware_version": "GW 2.3.4",
-  "event": "mesh_event",
-  "event_type": "node_leave",
-  "mesh_id": "MESH-001",
-  "affected_nodes": ["ALT-441D64F804A0"],
-  "details": {
-    "reason": "connection_lost",
-    "last_seen": "2025-01-12T15:08:45Z",
-    "total_nodes": 3
-  }
-}
-```
-#### Connection Lost Event
-```json
-{
-  "event": "mesh_event",
-  "event_type": "connection_lost",
-  "affected_nodes": ["ALT-441D64F804A0"],
-  "details": {
-    "reason": "timeout",
-    "timestamp": "2025-01-12T15:10:00Z"
-  }
-}
-```
-### Integration with Web Dashboards
-**Subscribe to events:**
-```javascript
-const mqtt = require('mqtt');
-const client = mqtt.connect('mqtt://broker.local:1883');
-client.subscribe('alteriom/mesh/+/events');
-client.subscribe('alteriom/mesh/+/topology');
-client.on('message', (topic, message) => {
-  const data = JSON.parse(message.toString());
-  if (data.event === 'mesh_event') {
-    switch (data.event_type) {
-      case 'node_join':
-        console.log(`✅ Node joined: ${data.affected_nodes[0]}`);
-        break;
-      case 'node_leave':
-        console.log(`⚠️  Node left: ${data.affected_nodes[0]}`);
-        break;
-    }
-  }
-  if (data.event === 'mesh_topology') {
-    console.log(`📊 Topology update: ${data.nodes.length} nodes`);
-    // Render network graph with D3.js or similar
-  }
-});
-```
-**Python example:**
-```python
-import paho.mqtt.client as mqtt
-import json
-def on_message(client, userdata, msg):
-    data = json.loads(msg.payload.decode())
-    if data['event'] == 'mesh_event':
-        event_type = data['event_type']
-        nodes = data['affected_nodes']
-        print(f"Event: {event_type} - Nodes: {nodes}")
-    elif data['event'] == 'mesh_topology':
-        total_nodes = data['metrics']['total_nodes']
-        quality = data['metrics']['avg_connection_quality']
-        print(f"Topology: {total_nodes} nodes, quality: {quality}%")
-client = mqtt.Client()
-client.on_message = on_message
-client.connect("broker.local", 1883)
-client.subscribe("alteriom/mesh/+/events")
-client.subscribe("alteriom/mesh/+/topology")
-client.loop_forever()
-```
----
-## Complete Examples
-### Example 1: Send LED Control Command via MQTT
-**Publish to:** `mesh/command/123456`
-```json
-{
-  "type": 201,
-  "command": 10,
-  "targetDevice": 123456,
-  "commandId": 1001,
-  "parameters": "{\"state\":true,\"brightness\":75}"
-}
-```
-**Expected Response on:** `mesh/response/123456`
-```json
-{
-  "type": 202,
-  "from": 123456,
-  "deviceStatus": 0,
-  "uptime": 3600,
-  "freeMemory": 45,
-  "firmwareVersion": "1.0.0",
-  "responseToCommand": 1001,
-  "responseMessage": "LED ON"
-}
-```
-### Example 2: Broadcast Configuration Request
-**Publish to:** `mesh/command/broadcast`
-```json
-{
-  "type": 201,
-  "command": 100,
-  "targetDevice": 0,
-  "commandId": 2001,
-  "parameters": "{}"
-}
-```
-All nodes respond with their configuration on respective `mesh/config/<nodeId>` topics.
-### Example 3: Update Node Configuration
-**Publish to:** `mesh/config/123456/set`
-```json
-{
-  "config": {
-    "deviceName": "Sensor-Living-Room",
-    "sampleRate": 30000,
-    "ledEnabled": false
-  }
-}
-```
-**Expected Response on:** `mesh/response/123456`
-```json
-{
-  "status": "success",
-  "device_id": "123456",
-  "message": "Configuration updated"
-}
-```
-### Example 4: Request Device Status
-**Publish to:** `mesh/command/123456`
-```json
-{
-  "type": 201,
-  "command": 200,
-  "targetDevice": 123456,
-  "commandId": 3001,
-  "parameters": "{}"
-}
-```
-**Expected Response on:** `mesh/status/123456`
-```json
-{
-  "type": 202,
-  "from": 123456,
-  "deviceStatus": 0,
-  "uptime": 7200,
-  "freeMemory": 42,
-  "firmwareVersion": "1.0.0",
-  "responseToCommand": 3001,
-  "responseMessage": "OK"
-}
-```
----
-## Using with Web Applications
-### JavaScript/Node.js Example
-```javascript
-const mqtt = require('mqtt');
-const client = mqtt.connect('mqtt://192.168.1.100:1883');
-client.on('connect', () => {
-  console.log('Connected to MQTT broker');
-  // Subscribe to response topics
-  client.subscribe('mesh/response/#');
-  client.subscribe('mesh/status/#');
-  // Send LED control command
-  const command = {
-    type: 201,
-    command: 10,
-    targetDevice: 123456,
-    commandId: Date.now(),
-    parameters: JSON.stringify({
-      state: true,
-      brightness: 75
-    })
-  };
-  client.publish('mesh/command/123456', JSON.stringify(command));
-});
-client.on('message', (topic, message) => {
-  console.log(`Received on ${topic}:`, message.toString());
-  const response = JSON.parse(message.toString());
-  if (response.responseToCommand) {
-    console.log(`Command ${response.responseToCommand} result: ${response.responseMessage}`);
-  }
-});
-```
-### Python Example
-```python
-import paho.mqtt.client as mqtt
-import json
-import time
-def on_connect(client, userdata, flags, rc):
-    print(f"Connected with result code {rc}")
-    client.subscribe("mesh/response/#")
-    client.subscribe("mesh/status/#")
-    # Send LED control command
-    command = {
-        "type": 201,
-        "command": 10,
-        "targetDevice": 123456,
-        "commandId": int(time.time() * 1000),
-        "parameters": json.dumps({
-            "state": True,
-            "brightness": 75
-        })
-    }
-    client.publish("mesh/command/123456", json.dumps(command))
-def on_message(client, userdata, msg):
-    print(f"Received on {msg.topic}: {msg.payload.decode()}")
-    response = json.loads(msg.payload.decode())
-    if "responseToCommand" in response:
-        print(f"Command {response['responseToCommand']} result: {response['responseMessage']}")
-client = mqtt.Client()
-client.on_connect = on_connect
-client.on_message = on_message
-client.connect("192.168.1.100", 1883, 60)
-client.loop_forever()
-```
----
-## Troubleshooting
-### Commands Not Reaching Nodes
-**Symptoms:**
-- Commands published to MQTT but nodes don't respond
-- No error messages in gateway logs
-**Solutions:**
-1. **Check MQTT Connection**: Verify bridge is connected to broker
-   ```cpp
-   if (mqttClient.connected()) {
-     Serial.println("MQTT connected");
-   }
-   ```
-2. **Verify Topic Format**: Ensure exact topic structure with nodeId
-   ```
-   Correct: mesh/command/123456
-   Wrong:   mesh/commands/123456
-   Wrong:   mesh/command/0x1E240
-   ```
-3. **Check JSON Format**: Validate command payload structure
-   ```bash
-   # Use mosquitto_pub to test
-   mosquitto_pub -h 192.168.1.100 -t "mesh/command/123456" -m '{"type":201,"command":10,"targetDevice":123456,"commandId":1001,"parameters":"{}"}'
-   ```
-4. **Inspect Mesh Connectivity**: Use `mesh.getNodeList()` to verify nodes
-   ```cpp
-   auto nodes = mesh.getNodeList();
-   Serial.printf("Connected nodes: %d\n", nodes.size());
-   ```
-5. **Enable Debug Logging**:
-   ```cpp
-   mesh.setDebugMsgTypes(ERROR | CONNECTION | COMMUNICATION);
-   ```
-### No Response from Nodes
-**Symptoms:**
-- Commands reach nodes but no response received
-- Node serial shows command execution but no MQTT response
-**Solutions:**
-1. **Verify Command Handler**: Ensure nodes have command handler implemented
-2. **Check Command ID**: Confirm command ID is supported by node
-3. **Monitor Serial Output**: Check node serial for command reception
-4. **Validate Parameters**: Ensure parameter JSON is valid
-5. **Check Response Routing**: Verify responses are reaching gateway
-### MQTT Broker Issues
-**Symptoms:**
-- Gateway can't connect to broker
-- Messages not being delivered
-**Solutions:**
-1. **Connection Refused**: Check broker IP, port, credentials
-   ```cpp
-   mqttClient.setServer(MQTT_BROKER_IP, MQTT_BROKER_PORT);
-   if (!mqttClient.connect("painlessMesh-gateway")) {
-     Serial.printf("MQTT error: %d\n", mqttClient.state());
-   }
-   ```
-2. **Topic Not Found**: Verify subscription before publishing
-   ```cpp
-   // Subscribe first
-   mqtt.subscribe("mesh/command/#");
-   delay(100);
-   // Then publish
-   mqtt.publish("mesh/response/123", "test");
-   ```
-3. **QoS Issues**: Use QoS 1 for reliable delivery
-   ```cpp
-   mqtt.publish(topic, payload, true); // retained = true
-   ```
-4. **Retained Messages**: Clear retained messages if needed
-   ```bash
-   mosquitto_pub -h 192.168.1.100 -t "mesh/command/123456" -n -r
-   ```
-### Memory Issues
-**Symptoms:**
-- Gateway crashes or reboots unexpectedly
-- Commands work initially but fail after time
-**Solutions:**
-1. **Monitor Heap**: Check free memory regularly
-   ```cpp
-   Serial.printf("Free heap: %d\n", ESP.getFreeHeap());
-   ```
-2. **Optimize JSON Buffer Size**: Use appropriate buffer sizes
-   ```cpp
-   // Too large wastes memory
-   DynamicJsonDocument doc(1024); // Adjust based on needs
-   ```
-3. **Clean Up Objects**: Delete unused objects
-   ```cpp
-   delete commandBridge; // If recreating
-   ```
-4. **Reduce Debug Output**: Disable verbose logging in production
-### Network Stability
-**Symptoms:**
-- Intermittent command delivery
-- Nodes dropping from mesh
-**Solutions:**
-1. **Check WiFi Signal**: Ensure strong WiFi for gateway
-2. **Reduce Mesh Traffic**: Space out command sends
-3. **Use Exponential Backoff**: Retry failed commands with delay
-4. **Monitor Mesh Health**: Track connection changes
----
-## Best Practices
-### Command Design
-1. **Use Unique Command IDs**: Generate unique IDs for tracking
-   ```cpp
-   cmd.commandId = millis() | (nodeId << 16);
-   ```
-2. **Keep Parameters Small**: Minimize JSON parameter size
-   ```json
-   Good:  {"s":1,"b":75}
-   Avoid: {"state":"enabled","brightness_level":75,"extra_field":"unused"}
-   ```
-3. **Implement Timeouts**: Don't wait indefinitely for responses
-   ```javascript
-   const timeout = setTimeout(() => {
-     console.log('Command timeout');
-   }, 5000);
-   ```
-4. **Handle Failures Gracefully**: Retry important commands
-   ```javascript
-   let retries = 3;
-   function sendCommand() {
-     client.publish(topic, command);
-     setTimeout(() => {
-       if (!responseReceived && retries-- > 0) {
-         sendCommand();
-       }
-     }, 2000);
-   }
-   ```
-### Security Considerations
-1. **Use Authentication**: Enable MQTT broker authentication
-2. **Validate Commands**: Check command bounds and parameters
-3. **Rate Limiting**: Limit command frequency per client
-4. **Access Control**: Restrict sensitive commands
-5. **Encryption**: Use TLS for production MQTT connections
-### Performance Optimization
-1. **Batch Commands**: Group related commands when possible
-2. **Cache Configuration**: Avoid repeated config requests
-3. **Use Broadcast Sparingly**: Unicast when targeting specific nodes
-4. **Monitor Latency**: Track command response times
----
-## Related Documentation
-- [OTA Commands Reference](OTA_COMMANDS_REFERENCE.md) - Firmware update commands
-- [API Reference](api/core-api.md) - Core painlessMesh API
-- [Plugin System](architecture/plugin-system.md) - Custom package development
-- [Alteriom Overview](alteriom/overview.md) - Alteriom package types
----
-**Last Updated:** October 2025
-**painlessMesh Version:** 1.7.0+ Alteriom Fork
-**Author:** Alteriom Development Team
+# MQTT Bridge Commands Reference
+## Overview
+This document provides a complete reference for MQTT-to-mesh bridge commands in painlessMesh Alteriom fork. The MQTT bridge enables bidirectional communication between MQTT brokers and mesh networks, allowing web applications to control and monitor mesh nodes.
+## Table of Contents
+1. [Architecture Overview](#architecture-overview)
+2. [Command Types](#command-types)
+3. [MQTT Topic Structure](#mqtt-topic-structure)
+4. [Command Definitions](#command-definitions)
+5. [Implementation Guide](#implementation-guide)
+6. [Complete Examples](#complete-examples)
+7. [Troubleshooting](#troubleshooting)
+---
+## Architecture Overview
+### Communication Flow
+```
+Web Application → MQTT Broker → Gateway Bridge → Mesh Network → Target Node
+Target Node → Mesh Network → Gateway Bridge → MQTT Broker → Web Application
+```
+### Components
+1. **MQTT Broker** - Central message router (Mosquitto, HiveMQ, AWS IoT)
+2. **Gateway Bridge** - ESP32/ESP8266 with WiFi + mesh capability
+3. **Mesh Nodes** - ESP devices in mesh network
+4. **Web Application** - Control interface publishing MQTT commands
+### Message Types
+| Direction | Package Type | Purpose |
+|-----------|--------------|---------|
+| MQTT → Mesh | CommandPackage (201) | Control device, request data |
+| Mesh → MQTT | StatusPackage (202) | Report device status |
+| Mesh → MQTT | SensorPackage (200) | Sensor data reports |
+| Mesh → MQTT | EnhancedStatusPackage (203) | Detailed health metrics |
+---
+## Command Types
+### Device Control Commands (1-99)
+| Command ID | Name | Description | Parameters |
+|------------|------|-------------|------------|
+| 1 | RESET | Restart device | None |
+| 2 | SLEEP | Enter deep sleep | `duration_ms` (uint32_t) |
+| 3 | WAKE | Wake from sleep | None |
+| 10 | LED_CONTROL | Control onboard LED | `state` (bool), `brightness` (uint8_t) |
+| 11 | RELAY_SWITCH | Control relay output | `channel` (uint8_t), `state` (bool) |
+| 12 | PWM_SET | Set PWM output | `pin` (uint8_t), `duty` (uint16_t) |
+| 20 | SENSOR_ENABLE | Enable/disable sensor | `sensor_id` (uint8_t), `enabled` (bool) |
+| 21 | SENSOR_CALIBRATE | Calibrate sensor | `sensor_id` (uint8_t) |
+### Configuration Commands (100-199)
+| Command ID | Name | Description | Parameters |
+|------------|------|-------------|------------|
+| 100 | GET_CONFIG | Request current configuration | None |
+| 101 | SET_CONFIG | Update configuration | JSON config object |
+| 102 | RESET_CONFIG | Reset to factory defaults | None |
+| 103 | SAVE_CONFIG | Persist config to flash | None |
+| 110 | SET_SAMPLE_RATE | Change sensor sample rate | `rate_ms` (uint32_t) |
+| 111 | SET_DEVICE_NAME | Update device name | `name` (string) |
+### Status Commands (200-255)
+| Command ID | Name | Description | Parameters |
+|------------|------|-------------|------------|
+| 200 | GET_STATUS | Request basic status | None |
+| 201 | GET_METRICS | Request performance metrics | None |
+| 202 | GET_DIAGNOSTICS | Request detailed diagnostics | None |
+| 210 | START_MONITORING | Begin continuous monitoring | `interval_ms` (uint32_t) |
+| 211 | STOP_MONITORING | Stop continuous monitoring | None |
+### Topology Commands (300-399) ✨ NEW in v0.5.0
+| Command ID | Name | Description | Parameters |
+|------------|------|-------------|------------|
+| 300 | GET_TOPOLOGY | Request mesh network topology | `format` (optional): "full" or "summary" |
+**Response:** Full mesh topology published to `alteriom/mesh/{mesh_id}/topology/response` with `correlation_id` field matching the command ID.
+**Example Response:**
+```json
+{
+  "schema_version": 1,
+  "event": "mesh_topology",
+  "correlation_id": "12345",
+  "mesh_id": "MESH-001",
+  "nodes": [...],
+  "connections": [...],
+  "metrics": {...}
+}
+```
+---
+## MQTT Topic Structure
+### Command Topics (Published by Web App)
+```
+mesh/command/{nodeId}           # Send command to specific node
+mesh/command/broadcast          # Broadcast command to all nodes
+mesh/config/{nodeId}/get        # Request configuration
+mesh/config/{nodeId}/set        # Update configuration
+mesh/ota/{nodeId}/start         # Initiate OTA update
+```
+### Response Topics (Published by Gateway Bridge)
+```
+mesh/response/{nodeId}                    # Command acknowledgments
+mesh/status/{nodeId}                      # Status updates (Type 202)
+mesh/sensor/{nodeId}                      # Sensor data (Type 200)
+mesh/health/{nodeId}                      # Enhanced status (Type 203)
+mesh/config/{nodeId}                      # Configuration data
+mesh/error/{nodeId}                       # Error reports
+```
+### System Topics (Legacy - v0.4.0)
+```
+mesh/gateway/status                       # Gateway bridge health
+mesh/topology                             # Mesh network topology (old format)
+mesh/nodes                                # List of connected nodes
+```
+### Topology & Event Topics ✨ NEW (v0.5.0 - @alteriom/mqtt-schema compliant)
+```
+alteriom/mesh/{mesh_id}/topology          # Full/incremental mesh topology
+alteriom/mesh/{mesh_id}/topology/response # Topology responses to GET_TOPOLOGY command
+alteriom/mesh/{mesh_id}/events            # Real-time mesh state change events
+```
+**Schema Compliance:** All topology and event messages conform to **@alteriom/mqtt-schema v0.5.0** specification.
+**Key Features:**
+- **Device ID Format:** `ALT-XXXXXXXXXXXX` (12 hex digits)
+- **Envelope Fields:** `schema_version`, `device_id`, `device_type`, `timestamp`, `firmware_version`
+- **Connection Metrics:** RSSI, latency, quality (0-100), packet counts
+- **Network Metrics:** Total nodes, network diameter, average quality
+- **Update Types:** Full (every 60s), Incremental (every 5s if changed)
+- **Event Types:** node_join, node_leave, connection_lost, connection_restored, network_split, network_merged
+---
+## Command Definitions
+### CommandPackage Structure (Type 201)
+Defined in `examples/alteriom/alteriom_sensor_package.hpp`:
+```cpp
+class CommandPackage : public painlessmesh::plugin::SinglePackage {
+public:
+  uint8_t command = 0;          // Command ID (1-255)
+  uint32_t targetDevice = 0;    // Destination node ID
+  uint32_t commandId = 0;       // Unique command tracking ID
+  TSTRING parameters = "";      // JSON-encoded parameters
+  CommandPackage() : SinglePackage(201) {}
+};
+```
+### Command Parameter Encoding
+Parameters are JSON-encoded strings:
+```json
+{
+  "state": "ON",
+  "brightness": 75,
+  "duration_ms": 5000
+}
+```
+### Command Response Structure
+Responses use StatusPackage (Type 202) with enhanced fields:
+```cpp
+class StatusPackage : public painlessmesh::plugin::BroadcastPackage {
+public:
+  uint8_t deviceStatus = 0;     // 0=OK, 1=Warning, 2=Error
+  uint32_t uptime = 0;          // Seconds since boot
+  uint16_t freeMemory = 0;      // Free heap in KB
+  TSTRING firmwareVersion = ""; // Current firmware version
+  // Response fields
+  uint32_t responseToCommand = 0;  // Original commandId
+  TSTRING responseMessage = "";    // Success/error message
+  StatusPackage() : BroadcastPackage(202) {}
+};
+```
+---
+## Implementation Guide
+### Gateway Bridge Implementation
+The gateway bridge is implemented in `examples/bridge/mqtt_command_bridge.hpp` and provides:
+1. **MQTT → Mesh Command Forwarding**
+   - Subscribes to command topics
+   - Parses JSON payloads
+   - Routes commands to target nodes
+2. **Mesh → MQTT Response Forwarding**
+   - Receives mesh messages
+   - Publishes to appropriate MQTT topics
+   - Maintains message routing
+3. **Configuration Management**
+   - Handles config requests
+   - Applies config updates
+   - Sends acknowledgments
+4. **Local Command Execution**
+   - Executes commands targeted at gateway
+   - Sends responses via MQTT
+### Mesh Node Implementation
+Mesh nodes implement command handlers in `examples/alteriom/mesh_command_node.ino`:
+1. **Command Reception**
+   - Listen for CommandPackage (Type 201)
+   - Parse command and parameters
+   - Execute appropriate action
+2. **Response Generation**
+   - Create StatusPackage response
+   - Include commandId for tracking
+   - Broadcast back to mesh
+3. **Status Reporting**
+   - Send periodic status updates
+   - Report errors and warnings
+   - Include relevant metrics
+---
+## Mesh Topology Reporting ✨ NEW in v0.5.0
+### Overview
+The mesh topology system provides real-time visibility into the structure and health of your mesh network. It publishes detailed information about nodes, connections, and network metrics in a standardized format that complies with **@alteriom/mqtt-schema v0.5.0**.
+**Implementation:** `examples/bridge/mesh_topology_reporter.hpp`
+### Topology Message Structure
+#### Envelope Fields (Required by @alteriom/mqtt-schema)
+```json
+{
+  "schema_version": 1,
+  "device_id": "ALT-6825DD341CA4",
+  "device_type": "gateway",
+  "timestamp": "2025-01-12T15:00:00Z",
+  "firmware_version": "GW 2.3.4"
+}
+```
+#### Topology Payload
+```json
+{
+  "event": "mesh_topology",
+  "mesh_id": "MESH-001",
+  "gateway_node_id": "ALT-6825DD341CA4",
+  "nodes": [
+    {
+      "node_id": "ALT-6825DD341CA4",
+      "role": "gateway",
+      "status": "online",
+      "last_seen": "2025-01-12T15:00:00Z",
+      "firmware_version": "GW 2.3.4",
+      "uptime_seconds": 86400,
+      "free_memory_kb": 128,
+      "connection_count": 3
+    }
+  ],
+  "connections": [
+    {
+      "from_node": "ALT-6825DD341CA4",
+      "to_node": "ALT-441D64F804A0",
+      "quality": 95,
+      "latency_ms": 12,
+      "rssi": -42,
+      "hop_count": 1
+    }
+  ],
+  "metrics": {
+    "total_nodes": 4,
+    "online_nodes": 4,
+    "network_diameter": 2,
+    "avg_connection_quality": 85,
+    "messages_per_second": 12.4
+  },
+  "update_type": "full"
+}
+```
+### Publishing Schedule
+| Update Type | Frequency | Trigger | Topic |
+|-------------|-----------|---------|-------|
+| Full Topology | Every 60 seconds | Timer | `alteriom/mesh/MESH-001/topology` |
+| Incremental | Every 5 seconds | Change detection | `alteriom/mesh/MESH-001/topology` |
+| On-Demand | Immediate | GET_TOPOLOGY command | `alteriom/mesh/MESH-001/topology/response` |
+### Node Roles
+| Role | Description | Typical Use |
+|------|-------------|-------------|
+| gateway | MQTT bridge with WiFi | Root node, MQTT publisher |
+| sensor | Sensor measurement node | Data collection |
+| repeater | Range extender | Network coverage |
+### Connection Quality Metrics
+**Quality Score (0-100):** Calculated from latency, packet loss, and RSSI
+- **90-100:** Excellent - Low latency (<50ms), strong signal (>-50 dBm)
+- **70-89:** Good - Moderate latency (<100ms), good signal (>-70 dBm)
+- **50-69:** Fair - Higher latency (<200ms), weaker signal (>-80 dBm)
+- **0-49:** Poor - High latency (>200ms), weak signal (<-80 dBm)
+**RSSI (Received Signal Strength Indicator):**
+- Values in dBm (negative numbers)
+- Stronger signal = higher (less negative) value
+- Example: -42 dBm is better than -75 dBm
+**Latency:**
+- Round-trip time in milliseconds
+- Calculated from message exchange timing
+- Lower is better
+### GET_TOPOLOGY Command (300)
+**Request:** Publish to `mesh/command/{gateway_id}` or `mesh/command/broadcast`
+```json
+{
+  "type": 201,
+  "command": 300,
+  "targetDevice": 0,
+  "commandId": 12345,
+  "parameters": "{}"
+}
+```
+**Response:** Published to `alteriom/mesh/MESH-001/topology/response`
+```json
+{
+  "schema_version": 1,
+  "device_id": "ALT-6825DD341CA4",
+  "event": "mesh_topology",
+  "correlation_id": "12345",
+  "mesh_id": "MESH-001",
+  ... full topology ...
+}
+```
+**Key Feature:** The `correlation_id` field matches the command's `commandId` for request tracking.
+---
+## Mesh Events ✨ NEW in v0.5.0
+### Overview
+Real-time notifications of mesh network state changes. Published immediately when events occur.
+**Implementation:** `examples/bridge/mesh_event_publisher.hpp`
+**Topic:** `alteriom/mesh/MESH-001/events`
+### Event Types
+| Event Type | Description | When Triggered |
+|------------|-------------|----------------|
+| node_join | New node connected | onNewConnection() callback |
+| node_leave | Node disconnected | onDroppedConnection() callback |
+| connection_lost | Direct connection failed | Connection timeout |
+| connection_restored | Connection recovered | After connection_lost |
+| network_split | Mesh partitioned | Network segmentation detected |
+| network_merged | Partitions rejoined | Segments reconnected |
+### Event Message Structure
+#### Node Join Event
+```json
+{
+  "schema_version": 1,
+  "device_id": "ALT-6825DD341CA4",
+  "device_type": "gateway",
+  "timestamp": "2025-01-12T15:05:00Z",
+  "firmware_version": "GW 2.3.4",
+  "event": "mesh_event",
+  "event_type": "node_join",
+  "mesh_id": "MESH-001",
+  "affected_nodes": ["ALT-441D64F804A0"],
+  "details": {
+    "total_nodes": 4,
+    "timestamp": "2025-01-12T15:05:00Z"
+  }
+}
+```
+#### Node Leave Event
+```json
+{
+  "schema_version": 1,
+  "device_id": "ALT-6825DD341CA4",
+  "device_type": "gateway",
+  "timestamp": "2025-01-12T15:10:00Z",
+  "firmware_version": "GW 2.3.4",
+  "event": "mesh_event",
+  "event_type": "node_leave",
+  "mesh_id": "MESH-001",
+  "affected_nodes": ["ALT-441D64F804A0"],
+  "details": {
+    "reason": "connection_lost",
+    "last_seen": "2025-01-12T15:08:45Z",
+    "total_nodes": 3
+  }
+}
+```
+#### Connection Lost Event
+```json
+{
+  "event": "mesh_event",
+  "event_type": "connection_lost",
+  "affected_nodes": ["ALT-441D64F804A0"],
+  "details": {
+    "reason": "timeout",
+    "timestamp": "2025-01-12T15:10:00Z"
+  }
+}
+```
+### Integration with Web Dashboards
+**Subscribe to events:**
+```javascript
+const mqtt = require('mqtt');
+const client = mqtt.connect('mqtt://broker.local:1883');
+client.subscribe('alteriom/mesh/+/events');
+client.subscribe('alteriom/mesh/+/topology');
+client.on('message', (topic, message) => {
+  const data = JSON.parse(message.toString());
+  if (data.event === 'mesh_event') {
+    switch (data.event_type) {
+      case 'node_join':
+        console.log(`✅ Node joined: ${data.affected_nodes[0]}`);
+        break;
+      case 'node_leave':
+        console.log(`⚠️  Node left: ${data.affected_nodes[0]}`);
+        break;
+    }
+  }
+  if (data.event === 'mesh_topology') {
+    console.log(`📊 Topology update: ${data.nodes.length} nodes`);
+    // Render network graph with D3.js or similar
+  }
+});
+```
+**Python example:**
+```python
+import paho.mqtt.client as mqtt
+import json
+def on_message(client, userdata, msg):
+    data = json.loads(msg.payload.decode())
+    if data['event'] == 'mesh_event':
+        event_type = data['event_type']
+        nodes = data['affected_nodes']
+        print(f"Event: {event_type} - Nodes: {nodes}")
+    elif data['event'] == 'mesh_topology':
+        total_nodes = data['metrics']['total_nodes']
+        quality = data['metrics']['avg_connection_quality']
+        print(f"Topology: {total_nodes} nodes, quality: {quality}%")
+client = mqtt.Client()
+client.on_message = on_message
+client.connect("broker.local", 1883)
+client.subscribe("alteriom/mesh/+/events")
+client.subscribe("alteriom/mesh/+/topology")
+client.loop_forever()
+```
+---
+## Complete Examples
+### Example 1: Send LED Control Command via MQTT
+**Publish to:** `mesh/command/123456`
+```json
+{
+  "type": 201,
+  "command": 10,
+  "targetDevice": 123456,
+  "commandId": 1001,
+  "parameters": "{\"state\":true,\"brightness\":75}"
+}
+```
+**Expected Response on:** `mesh/response/123456`
+```json
+{
+  "type": 202,
+  "from": 123456,
+  "deviceStatus": 0,
+  "uptime": 3600,
+  "freeMemory": 45,
+  "firmwareVersion": "1.0.0",
+  "responseToCommand": 1001,
+  "responseMessage": "LED ON"
+}
+```
+### Example 2: Broadcast Configuration Request
+**Publish to:** `mesh/command/broadcast`
+```json
+{
+  "type": 201,
+  "command": 100,
+  "targetDevice": 0,
+  "commandId": 2001,
+  "parameters": "{}"
+}
+```
+All nodes respond with their configuration on respective `mesh/config/<nodeId>` topics.
+### Example 3: Update Node Configuration
+**Publish to:** `mesh/config/123456/set`
+```json
+{
+  "config": {
+    "deviceName": "Sensor-Living-Room",
+    "sampleRate": 30000,
+    "ledEnabled": false
+  }
+}
+```
+**Expected Response on:** `mesh/response/123456`
+```json
+{
+  "status": "success",
+  "device_id": "123456",
+  "message": "Configuration updated"
+}
+```
+### Example 4: Request Device Status
+**Publish to:** `mesh/command/123456`
+```json
+{
+  "type": 201,
+  "command": 200,
+  "targetDevice": 123456,
+  "commandId": 3001,
+  "parameters": "{}"
+}
+```
+**Expected Response on:** `mesh/status/123456`
+```json
+{
+  "type": 202,
+  "from": 123456,
+  "deviceStatus": 0,
+  "uptime": 7200,
+  "freeMemory": 42,
+  "firmwareVersion": "1.0.0",
+  "responseToCommand": 3001,
+  "responseMessage": "OK"
+}
+```
+---
+## Using with Web Applications
+### JavaScript/Node.js Example
+```javascript
+const mqtt = require('mqtt');
+const client = mqtt.connect('mqtt://192.168.1.100:1883');
+client.on('connect', () => {
+  console.log('Connected to MQTT broker');
+  // Subscribe to response topics
+  client.subscribe('mesh/response/#');
+  client.subscribe('mesh/status/#');
+  // Send LED control command
+  const command = {
+    type: 201,
+    command: 10,
+    targetDevice: 123456,
+    commandId: Date.now(),
+    parameters: JSON.stringify({
+      state: true,
+      brightness: 75
+    })
+  };
+  client.publish('mesh/command/123456', JSON.stringify(command));
+});
+client.on('message', (topic, message) => {
+  console.log(`Received on ${topic}:`, message.toString());
+  const response = JSON.parse(message.toString());
+  if (response.responseToCommand) {
+    console.log(`Command ${response.responseToCommand} result: ${response.responseMessage}`);
+  }
+});
+```
+### Python Example
+```python
+import paho.mqtt.client as mqtt
+import json
+import time
+def on_connect(client, userdata, flags, rc):
+    print(f"Connected with result code {rc}")
+    client.subscribe("mesh/response/#")
+    client.subscribe("mesh/status/#")
+    # Send LED control command
+    command = {
+        "type": 201,
+        "command": 10,
+        "targetDevice": 123456,
+        "commandId": int(time.time() * 1000),
+        "parameters": json.dumps({
+            "state": True,
+            "brightness": 75
+        })
+    }
+    client.publish("mesh/command/123456", json.dumps(command))
+def on_message(client, userdata, msg):
+    print(f"Received on {msg.topic}: {msg.payload.decode()}")
+    response = json.loads(msg.payload.decode())
+    if "responseToCommand" in response:
+        print(f"Command {response['responseToCommand']} result: {response['responseMessage']}")
+client = mqtt.Client()
+client.on_connect = on_connect
+client.on_message = on_message
+client.connect("192.168.1.100", 1883, 60)
+client.loop_forever()
+```
+---
+## Troubleshooting
+### Commands Not Reaching Nodes
+**Symptoms:**
+- Commands published to MQTT but nodes don't respond
+- No error messages in gateway logs
+**Solutions:**
+1. **Check MQTT Connection**: Verify bridge is connected to broker
+   ```cpp
+   if (mqttClient.connected()) {
+     Serial.println("MQTT connected");
+   }
+   ```
+2. **Verify Topic Format**: Ensure exact topic structure with nodeId
+   ```
+   Correct: mesh/command/123456
+   Wrong:   mesh/commands/123456
+   Wrong:   mesh/command/0x1E240
+   ```
+3. **Check JSON Format**: Validate command payload structure
+   ```bash
+   # Use mosquitto_pub to test
+   mosquitto_pub -h 192.168.1.100 -t "mesh/command/123456" -m '{"type":201,"command":10,"targetDevice":123456,"commandId":1001,"parameters":"{}"}'
+   ```
+4. **Inspect Mesh Connectivity**: Use `mesh.getNodeList()` to verify nodes
+   ```cpp
+   auto nodes = mesh.getNodeList();
+   Serial.printf("Connected nodes: %d\n", nodes.size());
+   ```
+5. **Enable Debug Logging**:
+   ```cpp
+   mesh.setDebugMsgTypes(ERROR | CONNECTION | COMMUNICATION);
+   ```
+### No Response from Nodes
+**Symptoms:**
+- Commands reach nodes but no response received
+- Node serial shows command execution but no MQTT response
+**Solutions:**
+1. **Verify Command Handler**: Ensure nodes have command handler implemented
+2. **Check Command ID**: Confirm command ID is supported by node
+3. **Monitor Serial Output**: Check node serial for command reception
+4. **Validate Parameters**: Ensure parameter JSON is valid
+5. **Check Response Routing**: Verify responses are reaching gateway
+### MQTT Broker Issues
+**Symptoms:**
+- Gateway can't connect to broker
+- Messages not being delivered
+**Solutions:**
+1. **Connection Refused**: Check broker IP, port, credentials
+   ```cpp
+   mqttClient.setServer(MQTT_BROKER_IP, MQTT_BROKER_PORT);
+   if (!mqttClient.connect("painlessMesh-gateway")) {
+     Serial.printf("MQTT error: %d\n", mqttClient.state());
+   }
+   ```
+2. **Topic Not Found**: Verify subscription before publishing
+   ```cpp
+   // Subscribe first
+   mqtt.subscribe("mesh/command/#");
+   delay(100);
+   // Then publish
+   mqtt.publish("mesh/response/123", "test");
+   ```
+3. **QoS Issues**: Use QoS 1 for reliable delivery
+   ```cpp
+   mqtt.publish(topic, payload, true); // retained = true
+   ```
+4. **Retained Messages**: Clear retained messages if needed
+   ```bash
+   mosquitto_pub -h 192.168.1.100 -t "mesh/command/123456" -n -r
+   ```
+### Memory Issues
+**Symptoms:**
+- Gateway crashes or reboots unexpectedly
+- Commands work initially but fail after time
+**Solutions:**
+1. **Monitor Heap**: Check free memory regularly
+   ```cpp
+   Serial.printf("Free heap: %d\n", ESP.getFreeHeap());
+   ```
+2. **Optimize JSON Buffer Size**: Use appropriate buffer sizes
+   ```cpp
+   // Too large wastes memory
+   DynamicJsonDocument doc(1024); // Adjust based on needs
+   ```
+3. **Clean Up Objects**: Delete unused objects
+   ```cpp
+   delete commandBridge; // If recreating
+   ```
+4. **Reduce Debug Output**: Disable verbose logging in production
+### Network Stability
+**Symptoms:**
+- Intermittent command delivery
+- Nodes dropping from mesh
+**Solutions:**
+1. **Check WiFi Signal**: Ensure strong WiFi for gateway
+2. **Reduce Mesh Traffic**: Space out command sends
+3. **Use Exponential Backoff**: Retry failed commands with delay
+4. **Monitor Mesh Health**: Track connection changes
+---
+## Best Practices
+### Command Design
+1. **Use Unique Command IDs**: Generate unique IDs for tracking
+   ```cpp
+   cmd.commandId = millis() | (nodeId << 16);
+   ```
+2. **Keep Parameters Small**: Minimize JSON parameter size
+   ```json
+   Good:  {"s":1,"b":75}
+   Avoid: {"state":"enabled","brightness_level":75,"extra_field":"unused"}
+   ```
+3. **Implement Timeouts**: Don't wait indefinitely for responses
+   ```javascript
+   const timeout = setTimeout(() => {
+     console.log('Command timeout');
+   }, 5000);
+   ```
+4. **Handle Failures Gracefully**: Retry important commands
+   ```javascript
+   let retries = 3;
+   function sendCommand() {
+     client.publish(topic, command);
+     setTimeout(() => {
+       if (!responseReceived && retries-- > 0) {
+         sendCommand();
+       }
+     }, 2000);
+   }
+   ```
+### Security Considerations
+1. **Use Authentication**: Enable MQTT broker authentication
+2. **Validate Commands**: Check command bounds and parameters
+3. **Rate Limiting**: Limit command frequency per client
+4. **Access Control**: Restrict sensitive commands
+5. **Encryption**: Use TLS for production MQTT connections
+### Performance Optimization
+1. **Batch Commands**: Group related commands when possible
+2. **Cache Configuration**: Avoid repeated config requests
+3. **Use Broadcast Sparingly**: Unicast when targeting specific nodes
+4. **Monitor Latency**: Track command response times
+---
+## Related Documentation
+- [OTA Commands Reference](OTA_COMMANDS_REFERENCE.md) - Firmware update commands
+- [API Reference](api/core-api.md) - Core painlessMesh API
+- [Plugin System](architecture/plugin-system.md) - Custom package development
+- [Alteriom Overview](alteriom/overview.md) - Alteriom package types
+---
+**Last Updated:** October 2025
+**painlessMesh Version:** 1.7.0+ Alteriom Fork
+**Author:** Alteriom Development Team