ESP-Framework – Übersicht¶

Die ESP32 Firmware bildet die Basis für alle mit der ActionConnect Library verbundenen IoT-Geräte. Die Firmware verwaltet Hardware-Kommunikation, BLE-Verbindungen und MQTT-Telemetrie.

Überblick¶

Der ESP32 fungiert als Brücke zwischen der physischen Hardware und der digitalen Cloud:

graph TB
    HW["🔌 Hardware<br/>(Sensoren, Aktoren)"]
    ESP["ESP32<br/>Mikrocontroller"]

    subgraph Firmware["Firmware-Komponenten"]
        HAL["Hardware Layer"]
        BLE_MGR["BLE Manager"]
        MQTT_MGR["MQTT Manager"]
        STATE["State Management"]
    end

    subgraph Comms["Kommunikation"]
        BLE["Bluetooth Low Energy"]
        MQTT["MQTT (TCP/IP)"]
        WLAN["WLAN/WiFi"]
    end

    subgraph Cloud["Cloud-Integration"]
        App["📱 Mobile App"]
        Hub["☁️ ConnectHub"]
    end

    HW -->|Sensoren| HAL
    HAL -->|Messwerte| STATE
    HAL -->|Befehle| HW

    ESP --> Firmware
    Firmware --> Comms

    BLE -->|direkt| App
    MQTT -->|über WLAN| Hub
    Hub -->|über WLAN| App

Architektur der Firmware¶

Schichtenmodell¶

graph TB
    App["Benutzer-Code<br/>(main.cpp)"]

    subgraph Layer1["Applikationsschicht"]
        DeviceLogic["Geräte-Logik<br/>(Setup, Loop)"]
        Hardware["Hardware-Driver<br/>(LED, Sensor)"]
        State["Zustandsverwaltung"]
    end

    subgraph Layer2["Kommunikationsschicht"]
        ActionConnect["ActionConnect Library"]
        BLE["BLE Manager"]
        MQTT["MQTT Manager"]
        WLAN["WLAN Manager"]
    end

    subgraph Layer3["Systemschicht"]
        NVS["NVS Storage"]
        FreeRTOS["FreeRTOS Kernel"]
        HAL["Hardware Abstraction"]
    end

    App -->|nutzt| Layer1
    Layer1 -->|nutzt| Layer2
    Layer2 -->|nutzt| Layer3

    ActionConnect -->|vereinfacht| BLE
    ActionConnect -->|vereinfacht| MQTT
    BLE -->|nutzt| HAL
    MQTT -->|nutzt| WLAN
    State -->|persistiert| NVS

Komponenten¶

Komponente	Beschreibung	Verantwortung
ActionConnect Library	Zentrale Kommunikations-Bibliothek	BLE, MQTT, UUIDs, Device-ID
BLE Manager	Bluetooth Low Energy	Direkte App-Kommunikation
MQTT Manager	Message Queuing	Cloud-Telemetrie
State Management	Geräte-Zustand	Sensorwerte, Aktuator-Status
Hardware Layer	Sensor/Aktuator-Treiber	GPIO, I2C, SPI, ADC

Repository-Struktur¶

esp32-firmware/
├── src/
│   ├── main.cpp                    # Einstiegspunkt
│   ├── device_logic.cpp            # Geräte-spezifische Logik
│   ├── hardware/
│   │   ├── led_driver.cpp          # LED-Steuerung via PWM
│   │   └── sensors.cpp             # Sensor-Lesefunktionen
│   └── state/
│       └── device_state.cpp        # Zustandsverwaltung
│
├── lib/
│   └── ActionConnect/              # Die Hauptbibliothek
│       ├── include/
│       │   ├── ActionConnect.h
│       │   ├── BLEManager.h
│       │   └── MQTTManager.h
│       └── src/
│           ├── BLEManager.cpp
│           ├── MQTTManager.cpp
│           └── StorageManager.cpp
│
├── platformio.ini                  # PlatformIO-Konfiguration
└── README.md

Kommunikationswege¶

BLE (Bluetooth Low Energy)¶

Direkt zwischen App und Gerät, keine Cloud nötig.

graph LR
    App["📱 App<br/>(BLE-Client)"]
    ESP["ESP32<br/>(BLE-Server)"]

    App -->|Befehle| ESP
    ESP -->|Telemetrie| App

    style App fill:#e1f5ff
    style ESP fill:#fff9c4

Reichweite: ~10-100m
Latenz: <100ms
Bandwidth: ~125 kbit/s
Einsatz: Schnelle Reaktion, lokale Steuerung

Dokumentation: BLE-Kommunikation

MQTT (über WiFi)¶

Indirekt über ConnectHub, für globale Erreichbarkeit.

graph LR
    App["📱 App"]
    Hub["☁️ ConnectHub<br/>(MQTT Broker)"]
    ESP["ESP32"]

    App -->|HTTP/WebSocket| Hub
    Hub -->|MQTT| ESP
    ESP -->|MQTT| Hub

    style Hub fill:#c8e6c9

Reichweite: Global (mit WiFi)
Latenz: 100-1000ms (je nach Netzwerk)
Bandwidth: Kein Limit (WiFi)
Einsatz: Telemetrie, historische Daten

Dokumentation: MQTT

Initialisierungs-Ablauf¶

sequenceDiagram
    participant Boot as Boot
    participant HAL as Hardware
    participant Lib as ActionConnect
    participant BLE as BLE
    participant MQTT as MQTT

    Boot->>HAL: setup()
    HAL->>HAL: GPIO, PWM, I2C init

    Boot->>Lib: setupBLE()
    Lib->>BLE: Init + Advertising

    Boot->>Lib: setupMQTT()
    Lib->>MQTT: Connect + Subscribe

    Boot->>Boot: Callbacks registrieren

    Boot->>Boot: Bereit

    Boot->>Boot: loop() - kontinuierlich
    loop Befehlsverarbeitung
        BLE-->>Boot: Befehl
        MQTT-->>Boot: Befehl
        Boot->>HAL: Aktion ausführen
        Boot->>Lib: Telemetrie senden
    end

Dokumentation nach Thema¶

Schnelleinstieg¶

Getting Started - Erste Schritte
Thing Model - Geräte-Definition

Kommunikation¶

BLE-Kommunikation - Bluetooth Low Energy Details
WLAN-Kommunikation - WLAN-Verbindung und MQTT auf dem Gerät
MQTT - Topics und Payloads
Provisioning - WiFi-Setup für neue Geräte

Entwicklung¶

ActionConnect Library - API-Referenz
Beispiele - Demo-Objekt mit LED + Sensor
Setup - Projekt-Struktur

State Management¶

Jedes Gerät verwaltet seinen Zustand zentral:

// Beispiel Zustand-Struktur
struct DeviceState {
  // Aktoren
  bool power;
  uint8_t brightness;

  // Sensoren
  float temperature;
  uint32_t light_lux;

  // Metadaten
  String device_note;
  unsigned long last_update;
};

// Zustandsverwaltung
DeviceState state = { /* initial values */ };

// Änderungen auslösen Telemetrie
void publishStateChange() {
  // JSON erstellen
  // BLE notify()
  // MQTT publish()
}

Persistencer Speicher (NVS)¶

Die ActionConnect Library speichert automatisch:

Bereich	Inhalt	Zweck
`ble_storage`	Service UUID, TX UUID, RX UUID	Gerät nach Restart identifizierbar
`device`	Device-ID (6 Zeichen)	Eindeutige Gerätekennzeichnung
`wifi`	SSID, Passwort	WiFi-Verbindungsdaten
`mqtt`	Broker-Adresse, Credentials	MQTT-Verbindungsdaten

// Beispiel: Eigene Daten persistieren
nvs_handle_t handle;
nvs_open("my_app", NVS_READWRITE, &handle);

// Speichern
int calibration = 42;
nvs_set_i32(handle, "calibration", calibration);
nvs_commit(handle);

// Laden
nvs_get_i32(handle, "calibration", &calibration);

nvs_close(handle);

Typischer Geräte-Setup¶

Struktur einer Firmware¶

// 1. Hardware-Initialisierung
void setupHardware() {
  pinMode(LED_PIN, OUTPUT);
  // Sensoren, I2C, SPI, etc.
}

// 2. Kommunikation-Setup
void setup() {
  setupHardware();
  setupBLE("Device-Name");
  setupMQTT();
  setBLELineCallback(handleCommand);
}

// 3. Befehlsverarbeitung
void handleCommand(const String& cmd) {
  // Parse JSON
  // Update State
  // Change Hardware
  // Publish Telemetry
}

// 4. Hauptschleife
void loop() {
  readSensors();
  checkCommands();
  publishTelemetryIfNeeded();
}

Siehe auch: Demo-Objekt Beispiel

Nächste Schritte¶

Erste Hardware aufbauen? → Getting Started
Eigenes Gerät entwickeln? → Beispiele → BLE
Telemetrie senden? → MQTT
In App integrieren? → Thing Model