FIRMWARE_INTEGRATION_GUIDE.cpp

/*
   INTEGRATION GUIDE: Adding Fleet Management API to Evil Firmware
   
   This file shows how to integrate EvilFirmwareAPI into your existing
   device firmware (Cardputer, Atom S3, ESP32 C5, etc.)
   
   Steps:
   1. Include the API headers
   2. Create API instance
   3. Initialize the API with device info
   4. Add REST endpoints to your WebServer
   5. Optionally add BLE service
   6. Implement payload/command execution
*/

// ─────────────────────────────────────────────────────────────────
// STEP 1: Add these includes to your firmware (after existing includes)
// ─────────────────────────────────────────────────────────────────

#include <ArduinoJson.h>        // Required: npm/platformio install
#include "EvilFirmwareAPI.h"    // Include the API library
#include "EvilFleetAPI.h"       // Include REST handlers (see below)

// ─────────────────────────────────────────────────────────────────
// STEP 2: Create a custom API class for your device
// ─────────────────────────────────────────────────────────────────

class CardputerAPI : public EvilFirmwareAPI {
public:
  void executePayload(String payload_name, String parameters) override {
    Serial.println("[API] Executing payload: " + payload_name + " with: " + parameters);
    // Call your existing payload execution logic here
    // Example: triggerNetworkScan(parameters);
  }
  
  void executeCommand(Command cmd) override {
    Serial.println("[API] Executing command: " + cmd.command_type);
    // Route command to appropriate handler
    if (cmd.command_type == "wifi_scan") {
      // triggerWiFiScan();
    } else if (cmd.command_type == "ble_scan") {
      // triggerBLEScan();
    }
  }
};

// ─────────────────────────────────────────────────────────────────
// STEP 3: Create global instance in setup() or at top level
// ─────────────────────────────────────────────────────────────────

CardputerAPI fleetAPI;

void setupFleetAPI() {
  // Generate unique device ID (based on MAC address or custom ID)
  String device_id = WiFi.macAddress();
  device_id.replace(":", "");
  
  fleetAPI.begin(
    device_id,                    // Unique device ID
    "CARDPUTER-ADV",             // Device type
    "1.5.2"                      // Current firmware version
  );
  
  Serial.println("[API] Fleet API initialized: " + device_id);
}

// ─────────────────────────────────────────────────────────────────
// STEP 4: Register REST API endpoints with your WebServer
// ─────────────────────────────────────────────────────────────────

void setupAPIRoutes(WebServer* server) {
  // Status endpoint
  server->on(API_ENDPOINT_STATUS, HTTP_GET, [&]() {
    fleetAPI.updateStatus();
    String json = fleetAPI.statusToJSON();
    server->send(200, "application/json", json);
  });
  
  // Battery endpoint
  server->on(API_ENDPOINT_BATTERY, HTTP_GET, [&]() {
    String json = fleetAPI.batteryToJSON();
    server->send(200, "application/json", json);
  });
  
  // Sensors endpoint
  server->on(API_ENDPOINT_SENSORS, HTTP_GET, [&]() {
    String json = fleetAPI.sensorsToJSON();
    server->send(200, "application/json", json);
  });
  
  // Payload execution endpoint
  server->on(API_ENDPOINT_PAYLOAD, HTTP_POST, [&]() {
    if (!server->hasArg("plain")) {
      server->send(400, "application/json", "{\"error\":\"No body\"}");
      return;
    }
    
    DynamicJsonDocument doc(256);
    deserializeJson(doc, server->arg("plain"));
    
    String payload_name = doc["name"] | "";
    String parameters = doc["params"] | "";
    
    if (payload_name.length() == 0) {
      server->send(400, "application/json", "{\"error\":\"Missing payload name\"}");
      return;
    }
    
    fleetAPI.executePayload(payload_name, parameters);
    
    DynamicJsonDocument response(128);
    response["success"] = true;
    response["payload"] = payload_name;
    response["timestamp"] = millis();
    
    String json;
    serializeJson(response, json);
    server->send(200, "application/json", json);
  });
  
  // Command execution endpoint
  server->on(API_ENDPOINT_COMMAND, HTTP_POST, [&]() {
    if (!server->hasArg("plain")) {
      server->send(400, "application/json", "{\"error\":\"No body\"}");
      return;
    }
    
    DynamicJsonDocument doc(256);
    deserializeJson(doc, server->arg("plain"));
    
    Command cmd;
    cmd.command_id = doc["id"] | "";
    cmd.command_type = doc["type"] | "";
    cmd.target = doc["target"] | "";
    cmd.parameters = doc["params"] | "";
    cmd.timestamp = millis();
    
    fleetAPI.executeCommand(cmd);
    
    DynamicJsonDocument response(128);
    response["success"] = true;
    response["command_id"] = cmd.command_id;
    response["timestamp"] = millis();
    
    String json;
    serializeJson(response, json);
    server->send(200, "application/json", json);
  });
  
  // Logs endpoint (returns recent activity logs)
  server->on(API_ENDPOINT_LOGS, HTTP_GET, [&]() {
    DynamicJsonDocument doc(512);
    doc["logs"] = "[]";  // Replace with actual log retrieval
    doc["timestamp"] = millis();
    
    String json;
    serializeJson(doc, json);
    server->send(200, "application/json", json);
  });
  
  Serial.println("[API] REST endpoints registered");
}

// ─────────────────────────────────────────────────────────────────
// STEP 5: Call in your main setup()
// ─────────────────────────────────────────────────────────────────

void setup() {
  Serial.begin(115200);
  
  // ... your existing setup code ...
  
  setupFleetAPI();
  setupAPIRoutes(&server);  // Pass your WebServer instance
  
  // Start your server
  server.begin();
}

// ─────────────────────────────────────────────────────────────────
// STEP 6: Optional - Add BLE GATT Service (for direct device communication)
// ─────────────────────────────────────────────────────────────────

#ifdef INCLUDE_BLE_SERVICE

#include <BLEDevice.h>
#include <BLEServer.h>
#include <BLEUtils.h>
#include <BLE2902.h>

BLECharacteristic *pTxCharacteristic;
uint8_t txValue = 0;

class MyServerCallbacks: public BLEServerCallbacks {
  void onConnect(BLEServer* pServer) {
    Serial.println("[BLE] Client connected");
  }
  
  void onDisconnect(BLEServer* pServer) {
    Serial.println("[BLE] Client disconnected");
    pServer->getAdvertising()->start();
  }
};

class MyCharacteristicCallbacks: public BLECharacteristicCallbacks {
  EvilFirmwareAPI* api;
  
  MyCharacteristicCallbacks(EvilFirmwareAPI* _api) { api = _api; }
  
  void onWrite(BLECharacteristic *pCharacteristic) {
    String rxValue = pCharacteristic->getValue();
    
    if (rxValue.length() > 0) {
      Serial.print("[BLE] Received: ");
      Serial.println(rxValue);
      
      // Parse and execute BLE command
      DynamicJsonDocument doc(256);
      deserializeJson(doc, rxValue);
      
      // Execute command via API
      Command cmd;
      cmd.command_type = doc["type"];
      api->executeCommand(cmd);
    }
  }
};

void setupBLEService() {
  BLEDevice::init("Evil-Fleet-Device");
  BLEServer *pServer = BLEDevice::createServer();
  pServer->setCallbacks(new MyServerCallbacks());
  
  BLEService *pService = pServer->createService(EVIL_BLE_SERVICE_UUID);
  
  pTxCharacteristic = pService->createCharacteristic(
    EVIL_BLE_TX_CHAR_UUID,
    BLECharacteristic::PROPERTY_NOTIFY
  );
  pTxCharacteristic->addDescriptor(new BLE2902());
  
  BLECharacteristic *pRxCharacteristic = pService->createCharacteristic(
    EVIL_BLE_RX_CHAR_UUID,
    BLECharacteristic::PROPERTY_WRITE
  );
  pRxCharacteristic->setCallbacks(new MyCharacteristicCallbacks(&fleetAPI));
  
  pService->start();
  pServer->getAdvertising()->start();
  
  Serial.println("[BLE] GATT service started");
}

#endif // INCLUDE_BLE_SERVICE

// ─────────────────────────────────────────────────────────────────
// API ENDPOINTS REFERENCE
// ─────────────────────────────────────────────────────────────────
/*

GET /api/status
Response: {
  "device_id": "...",
  "device_type": "CARDPUTER-ADV",
  "firmware_version": "1.5.2",
  "api_version": "1.0.0",
  "wifi_connected": true,
  "wifi_ssid": "...",
  "wifi_rssi": -42,
  "uptime_ms": 123456,
  "battery_voltage": 4.2,
  "battery_percent": 85,
  "cpu_temp": 42.5,
  "free_heap": 51234,
  "total_heap": 81920
}

GET /api/battery
Response: {
  "voltage": 4.2,
  "percent": 85,
  "timestamp": 123456
}

GET /api/sensors
Response: {
  "temperature": 22.5,
  "humidity": 45.2,
  "pressure": 1013.25,
  "gps_valid": true,
  "latitude": 40.7128,
  "longitude": -74.0060,
  "gps_accuracy": 5.2
}

POST /api/payload
Body: {
  "name": "network_scan",
  "params": "{\"channel\": 1}"
}
Response: {
  "success": true,
  "payload": "network_scan",
  "timestamp": 123456
}

POST /api/command
Body: {
  "id": "cmd_123",
  "type": "wifi_scan",
  "target": "all",
  "params": ""
}
Response: {
  "success": true,
  "command_id": "cmd_123",
  "timestamp": 123456
}

GET /api/logs
Response: {
  "logs": [...],
  "timestamp": 123456
}

*/