# OTA Commands and API Reference

## Overview

This document provides a complete reference for OTA (Over-The-Air) firmware update commands in painlessMesh, including Phase 2 broadcast mode enhancements and Alteriom MQTT schema compliance for firmware status reporting.

## Table of Contents

1. [OTA Command API](#ota-command-api)
2. [Broadcast OTA (Phase 2)](#broadcast-ota-phase-2)
3. [Firmware Status Reporting](#firmware-status-reporting)
4. [MQTT Schema Compliance](#mqtt-schema-compliance)
5. [Complete Examples](#complete-examples)
6. [Troubleshooting](#troubleshooting)

---

## OTA Command API

### mesh.offerOTA()

Announce and distribute firmware updates to mesh nodes.

```cpp
std::shared_ptr<Task> offerOTA(
  TSTRING role,
  TSTRING hardware,
  TSTRING md5,
  size_t noPart,
  bool forced = false,
  bool broadcasted = false,  // Phase 2 feature
  bool compressed = false    // Phase 1 feature
)
```

#### Parameters

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `role` | TSTRING | Target node role (e.g., "sensor", "gateway") | Required |
| `hardware` | TSTRING | Hardware type: "ESP32" or "ESP8266" | Required |
| `md5` | TSTRING | MD5 hash of firmware binary for version checking | Required |
| `noPart` | size_t | Total number of firmware chunks | Required |
| `forced` | bool | Force update even if MD5 matches current version | false |
| `broadcasted` | bool | **[Phase 2]** Enable broadcast distribution mode | false |
| `compressed` | bool | [Phase 1] Enable compression (40-60% bandwidth savings) | false |

#### Returns

`std::shared_ptr<Task>` - Shared pointer to task managing OTA announcements

#### Behavior

**Unicast Mode (broadcasted=false):**
- Each node requests chunks individually
- Root node responds to each request
- Network traffic: O(N × F) where N=nodes, F=firmware size
- Best for: 1-10 nodes

**Broadcast Mode (broadcasted=true):**
- Root node broadcasts chunks once
- All nodes receive simultaneously
- Network traffic: O(F) - independent of node count
- Best for: 10-100+ nodes
- ~98% traffic reduction for 50-node mesh

#### Example

```cpp
// Phase 2 Broadcast OTA with compression
auto otaTask = mesh.offerOTA(
  "sensor",        // Role
  "ESP32",         // Hardware
  firmwareMD5,     // MD5 hash
  numChunks,       // Number of chunks
  false,           // Not forced
  true,            // BROADCAST MODE (Phase 2)
  true             // Compressed (Phase 1)
);

// Monitor OTA progress
otaTask->setCallback([]() {
  Serial.println("OTA announcement sent");
});
```

### mesh.initOTAReceive()

Initialize OTA receiver on a node to accept firmware updates.

```cpp
void initOTAReceive(
  TSTRING role,
  std::function<void(size_t current, size_t total)> progressCallback = nullptr,
  bool acceptCompressed = true,
  bool acceptBroadcast = true
)
```

#### Parameters

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `role` | TSTRING | This node's role for matching firmware | Required |
| `progressCallback` | function | Callback for progress updates (current, total) | nullptr |
| `acceptCompressed` | bool | Accept compressed firmware (Phase 1) | true |
| `acceptBroadcast` | bool | Accept broadcast OTA (Phase 2) | true |

#### Example

```cpp
mesh.initOTAReceive(
  "sensor",
  [](size_t current, size_t total) {
    Serial.printf("OTA Progress: %d/%d (%d%%)\n", 
                  current, total, (current * 100) / total);
  },
  true,  // Accept compressed
  true   // Accept broadcast
);
```

---

## Broadcast OTA (Phase 2)

### Architecture

Broadcast OTA distributes firmware to all nodes simultaneously instead of individually, dramatically reducing network traffic and update time.

**Message Flow:**

```
1. Root Node Announces Update:
   Root → ALL: Broadcast Announce {role, hardware, md5, noPart, broadcasted=true}

2. Root Node Broadcasts Chunks:
   Root → ALL: Broadcast Data(chunk 0)
   Root → ALL: Broadcast Data(chunk 1)
   Root → ALL: Broadcast Data(chunk 2)
   ...
   Root → ALL: Broadcast Data(chunk N)

3. All Nodes Process:
   Each node:
   - Receives broadcasts
   - Assembles chunks
   - Verifies MD5
   - Flashes firmware
   - Reboots into new version
```

### Performance Comparison

| Mesh Size | Unicast Transmissions | Broadcast Transmissions | Reduction | Time Improvement |
|-----------|----------------------|------------------------|-----------|------------------|
| 10 nodes  | 1,500                | 150                    | 90%       | ~10x faster      |
| 50 nodes  | 7,500                | 150                    | 98%       | ~50x faster      |
| 100 nodes | 15,000               | 150                    | 99%       | ~100x faster     |

*Assuming 150 firmware chunks*

### Memory Requirements

**Per Node:**
- Chunk buffer: ~1-2KB
- Tracking bitmap: ~1KB (for 150 chunks)
- Total overhead: +2-5KB

**Scalability:**
- Tested: Up to 100 nodes
- Theoretical: 200+ nodes with proper rate limiting
- Recommended: 10-100 nodes for optimal performance

### Implementation Details

The broadcast mode is implemented through a minimal change to `src/painlessmesh/ota.hpp`:

```cpp
static Data replyTo(const DataRequest& req, TSTRING data, size_t partNo) {
  Data d;
  // ... initialize fields ...
  
  // Phase 2: Set BROADCAST routing when broadcasted flag is true
  if (req.broadcasted) {
    d.routing = router::BROADCAST;
  }
  return d;
}
```

### Best Practices

1. **Rate Limiting:** Don't broadcast chunks faster than nodes can process
2. **Chunk Size:** Use 1024-2048 byte chunks for optimal balance
3. **Network Stability:** Ensure mesh is stable before starting OTA
4. **Monitoring:** Use progress callbacks to track update status
5. **Fallback:** Keep unicast mode available for small deployments

---

## Firmware Status Reporting

### Alteriom MQTT Schema v1 Compliance

The firmware update process can report status using the Alteriom MQTT schema `firmware_status.schema.json` v1.

#### Schema Structure

```json
{
  "schema_version": 1,
  "device_id": "node-123456",
  "device_type": "sensor",
  "timestamp": "2024-10-11T16:30:00Z",
  "firmware_version": "1.0.0",
  "status": "downloading",
  "from_version": "1.0.0",
  "to_version": "2.0.0",
  "progress_pct": 45.5,
  "error": null
}
```

#### Status Values

| Status | Description | Required Fields |
|--------|-------------|----------------|
| `pending` | Update queued, not started | None |
| `downloading` | Downloading firmware chunks | `progress_pct` recommended |
| `flashing` | Writing firmware to flash | `progress_pct` recommended |
| `verifying` | Verifying firmware integrity | None |
| `rebooting` | Rebooting into new firmware | None |
| `completed` | Update successful | `to_version` |
| `failed` | Update failed | `error` required |

#### Example Implementation

```cpp
// Report OTA progress via MQTT
void reportOTAStatus(String status, float progress = -1, String error = "") {
  DynamicJsonDocument doc(512);
  
  // Envelope fields (required)
  doc["schema_version"] = 1;
  doc["device_id"] = String(mesh.getNodeId());
  doc["device_type"] = "sensor";
  doc["timestamp"] = getCurrentISO8601Timestamp();
  doc["firmware_version"] = FIRMWARE_VERSION;
  
  // Firmware status fields
  doc["status"] = status;
  doc["from_version"] = OLD_VERSION;
  doc["to_version"] = NEW_VERSION;
  
  if (progress >= 0) {
    doc["progress_pct"] = progress;
  }
  
  if (error.length() > 0) {
    doc["error"] = error;
  } else {
    doc["error"] = nullptr;
  }
  
  String payload;
  serializeJson(doc, payload);
  mqttClient.publish("device/firmware/status", payload.c_str());
}

// Usage in OTA progress callback
mesh.initOTAReceive("sensor", [](size_t current, size_t total) {
  float progress = (current * 100.0) / total;
  
  if (current == 0) {
    reportOTAStatus("downloading", 0);
  } else if (current < total) {
    reportOTAStatus("downloading", progress);
  } else {
    reportOTAStatus("flashing", 100);
  }
});
```

---

## MQTT Schema Compliance

### Gateway Metrics

The MQTT Status Bridge publishes gateway metrics in full compliance with Alteriom MQTT schema v1.

**Schema:** `gateway_metrics.schema.json` v1

**Required Fields:**
- Envelope: `schema_version`, `device_id`, `device_type`, `timestamp`, `firmware_version`
- Metrics: `uptime_s` (minimum required)

**Published Message:**
```json
{
  "schema_version": 1,
  "device_id": "gateway-001",
  "device_type": "gateway",
  "timestamp": "2024-10-11T16:30:00Z",
  "firmware_version": "2.1.0",
  "metrics": {
    "uptime_s": 3600,
    "mesh_nodes": 12,
    "memory_usage_pct": 45.2,
    "connected_devices": 12
  }
}
```

### Validation

To validate messages against the schema:

```javascript
// Node.js validation example
const { validators } = require('@alteriom/mqtt-schema');

const message = JSON.parse(mqttPayload);
const result = validators.gatewayMetrics(message);

if (!result.valid) {
  console.error('Validation errors:', result.errors);
}
```

---

## Complete Examples

### Example 1: Basic OTA Sender

```cpp
#include <painlessMesh.h>

#define MESH_PREFIX     "mesh"
#define MESH_PASSWORD   "password"
#define MESH_PORT       5555

painlessMesh mesh;

void setup() {
  Serial.begin(115200);
  mesh.init(MESH_PREFIX, MESH_PASSWORD, MESH_PORT);
  
  // Calculate firmware chunks
  File firmware = SD.open("/firmware.bin");
  size_t fileSize = firmware.size();
  size_t numChunks = (fileSize + 1023) / 1024;  // 1KB chunks
  String md5 = calculateMD5(firmware);
  
  // Offer OTA with Phase 2 broadcast
  auto otaTask = mesh.offerOTA(
    "sensor",
    "ESP32",
    md5,
    numChunks,
    false,  // not forced
    true,   // BROADCAST
    true    // compressed
  );
  
  Serial.println("Broadcasting OTA update...");
}

void loop() {
  mesh.update();
}
```

### Example 2: OTA Receiver with Status Reporting

```cpp
#include <painlessMesh.h>
#include <PubSubClient.h>

painlessMesh mesh;
PubSubClient mqttClient;

void reportOTAStatus(String status, float progress = -1) {
  // Implementation as shown above
}

void setup() {
  Serial.begin(115200);
  mesh.init(MESH_PREFIX, MESH_PASSWORD, MESH_PORT);
  
  // Initialize OTA receiver with progress reporting
  mesh.initOTAReceive(
    "sensor",
    [](size_t current, size_t total) {
      float pct = (current * 100.0) / total;
      Serial.printf("OTA: %d/%d (%.1f%%)\n", current, total, pct);
      
      // Report via MQTT
      if (current == 0) {
        reportOTAStatus("downloading", 0);
      } else if (current < total) {
        reportOTAStatus("downloading", pct);
      } else {
        reportOTAStatus("flashing", 100);
      }
    },
    true,  // accept compressed
    true   // accept broadcast
  );
}

void loop() {
  mesh.update();
  mqttClient.loop();
}
```

### Example 3: Full MQTT Bridge with Schema Compliance

```cpp
#include <painlessMesh.h>
#include <PubSubClient.h>
#include "examples/bridge/mqtt_status_bridge.hpp"

painlessMesh mesh;
WiFiClient wifiClient;
PubSubClient mqttClient(wifiClient);
MqttStatusBridge* statusBridge;

void setup() {
  Serial.begin(115200);
  
  // Initialize mesh as bridge node
  mesh.init(MESH_PREFIX, MESH_PASSWORD, MESH_PORT, WIFI_AP_STA);
  mesh.setRoot(true);
  mesh.setContainsRoot(true);
  mesh.stationManual(WIFI_SSID, WIFI_PASSWORD);
  
  // Connect to MQTT broker
  mqttClient.setServer(MQTT_BROKER, 1883);
  mqttClient.connect("painlessMesh-bridge");
  
  // Initialize schema-compliant MQTT status bridge
  statusBridge = new MqttStatusBridge(mesh, mqttClient);
  statusBridge->setDeviceId("gateway-001");
  statusBridge->setFirmwareVersion("2.1.0");
  statusBridge->setPublishInterval(30000);  // 30 seconds
  statusBridge->enableMetrics(true);        // Schema v1 compliant
  statusBridge->enableTopology(true);
  statusBridge->enableAlerts(true);
  statusBridge->begin();
  
  Serial.println("MQTT Status Bridge started");
  Serial.println("Publishing schema-compliant gateway metrics");
}

void loop() {
  mesh.update();
  mqttClient.loop();
}
```

---

## Troubleshooting

### Common Issues

#### 1. OTA Not Starting

**Symptom:** Nodes don't respond to OTA announcements

**Solutions:**
- Verify role matches between sender and receiver
- Check hardware type (ESP32 vs ESP8266)
- Ensure nodes have OTA initialized with `initOTAReceive()`
- Check MD5 is different from current firmware

#### 2. Broadcast OTA Slow/Failing

**Symptom:** Broadcast mode slower than expected or nodes miss chunks

**Solutions:**
- Reduce broadcast rate (add delays between chunks)
- Check mesh stability (`mesh.getNodeList()` should be stable)
- Verify sufficient memory on nodes (check `ESP.getFreeHeap()`)
- Consider smaller chunk size for congested meshes
- Reduce number of nodes or use unicast for <10 nodes

#### 3. Schema Validation Failures

**Symptom:** MQTT consumers reject messages

**Solutions:**
- Verify `schema_version` is exactly 1 (integer)
- Check `device_id` matches pattern `^[A-Za-z0-9_-]+$` (no spaces)
- Ensure `device_type` is exactly "gateway" or "sensor"
- Validate timestamp is ISO 8601: `YYYY-MM-DDTHH:MM:SSZ`
- Check `firmware_version` is not empty and ≤40 characters
- Ensure `metrics` object exists for gateway_metrics
- Verify `uptime_s` is present and non-negative integer

#### 4. Timestamp Issues

**Symptom:** Timestamps rejected or incorrect

**Solutions:**
- Use NTP time sync for accurate timestamps
- Implement RTC module for offline accuracy
- Fallback implementation uses Unix epoch + millis()
- Ensure format: `1970-01-15T12:34:56Z` (must include date and Z suffix)
- Validate with regex: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$`

### Debug Commands

```cpp
// Enable OTA debug logging
mesh.setDebugMsgTypes(ERROR | STARTUP | OTA);

// Check OTA status
Serial.printf("Accepting OTA: %s\n", mesh.isAcceptingOTA() ? "YES" : "NO");

// Monitor memory during OTA
Serial.printf("Free heap: %d bytes\n", ESP.getFreeHeap());

// Validate MQTT message locally
#include <ArduinoJson.h>
DynamicJsonDocument doc(1024);
deserializeJson(doc, mqttPayload);
// Check required fields manually
bool valid = doc.containsKey("schema_version") &&
             doc["schema_version"] == 1 &&
             doc.containsKey("metrics");
```

---

## References

- **painlessMesh OTA Plugin:** [src/painlessmesh/ota.hpp](../src/painlessmesh/ota.hpp)
- **MQTT Status Bridge:** [examples/bridge/mqtt_status_bridge.hpp](../examples/bridge/mqtt_status_bridge.hpp)
- **Alteriom MQTT Schema:** https://www.npmjs.com/package/@alteriom/mqtt-schema
- **Phase 2 Guide:** [PHASE2_GUIDE.md](PHASE2_GUIDE.md)
- **Schema Compliance:** [MQTT_SCHEMA_COMPLIANCE.md](MQTT_SCHEMA_COMPLIANCE.md)
- **Phase 2 Implementation:** [improvements/PHASE2_IMPLEMENTATION.md](improvements/PHASE2_IMPLEMENTATION.md)

---

**Last Updated:** October 2024  
**Schema Version:** v1  
**painlessMesh Version:** 1.6.1+  
**Phase:** 2 (Broadcast OTA + MQTT Status Bridge)