Getting Started¶

Überblick¶

Dieser Quick-Start-Guide führt von einem unbeschriebenen Mikrocontroller zu einem Gerät, das sich im Action Connect Hub anzeigen und bedienen lässt.

Voraussetzungen¶

Für die Entwicklung empfiehlt sich die Nutzung von Visual Studio Code mit der PlatformIO-Erweiterung sowie einem eingerichteten Copilot. Alternativ kann auch die Arduino IDE genutzt werden.

In wenigen Minuten zum ersten Gerät¶

1. Repository & Toolchain einrichten¶

Die Firmware wird als PlatformIO-Projekt entwickelt. Nach dem Öffnen des Framework-Repositorys in Visual Studio Code liest PlatformIO die Datei platformio.ini und richtet die Umgebung für das konfigurierte Board ein. Die benötigten Bibliotheken werden dabei automatisch importiert. Die vollständige Beschreibung von Projektstruktur und Einbindung der Bibliothek steht unter ESP → Setup & Build.

2. Thing Model erstellen¶

Das Gerät beschreibt seine Fähigkeiten in einem Thing Model. Es legt fest, welche Capabilities das Gerät besitzt, welchen Typ sie haben und wie sie in der Benutzeroberfläche dargestellt werden. Das Modell kann manuell geschrieben oder mit dem Thing-Model-Builder zusammengestellt werden.

Thing-Model-Builder¶

Beispiel Thing Model¶

Ein minimales Thing Model beschreibt ein Gerät mit einer einzigen steuerbaren Ein/Aus-Fähigkeit:

{
  "metadata": {
    "label": "Mein Gerät",
    "category": "Light"
  },
  "capabilities": [
    {
      "id": "power",
      "type": "ON_OFF",
      "label": "Power",
      "direction": "both"
    }
  ],
  "state": {
    "power": "OFF"
  }
}

Aus diesem Modell erzeugt die App einen einfachen Schalter. Weitere Capabilities werden als zusätzliche Einträge in der capabilities-Liste ergänzt.

3. Firmware entwickeln und flashen¶

Die Verbindung zur Plattform übernimmt die ActionConnect Library. Die eigene Gerätelogik wird um wenige Aufrufe ergänzt:

#include <Actionconnectlibrary.h>

void setup() {
  Serial.begin(115200);
  // eigene Hardware initialisieren …
  connectHubInit();            // WLAN, MQTT und BLE einrichten
}

void loop() {
  connectHubProcessTransport();  // eingehende MQTT-/BLE-Nachrichten verarbeiten

  // Messwert an die Plattform senden:
  connectHubSend("light_lux", String(lux));

  // vom Server zuletzt empfangenen Wert lesen:
  String brightness = connectHubGetCapability("brightness");
}

Das zuvor erstellte Thing Model wird in die Datei ThingModel.h integriert. Die id jeder Capability muss dabei exakt der Bezeichnung entsprechen, die die Firmware in connectHubSend() und connectHubGetCapability() verwendet – andernfalls lassen sich die Werte später nicht zuordnen. Der genaue Ablauf ist unter ESP → Setup & Build und ActionConnect Library beschrieben.

Das fertige Programm wird über die Upload-Funktion von PlatformIO auf den ESP übertragen.

4. Gerät im Dashboard prüfen¶

Beim ersten Start besitzt das Gerät noch keine WLAN-Zugangsdaten. Diese werden per BLE oder über die Weboberfläche des geräteeigenen Access Points (IP-Adresse: 192.168.4.1) übergeben (siehe Provisioning). Sobald die WLAN-Verbindung steht, meldet sich das Gerät über MQTT beim Backend an und überträgt dabei sein Thing Model.

Danach kann das Gerät im Action Connect Hub eingebunden werden, indem unter "Geräte hinzufügen" → "Per Geräte-ID hinzufügen" die Device-ID des Gerätes und der Pairing-Code eingegeben werden.

Video-Tutorial¶