Skip to content

Integration Guide

Dieses Kapitel dient als Leitfaden, wie ein eigenes Produkt an die Action Connect Plattform angebunden werden kann.

Der entscheidende Vorteil an der Nutzung von Action Connect ist, dass an der Plattform selbst keine Veränderungen vorgenommen werden müssen. Weder am Backend noch an den Oberflächen ist eine Anpassung nötig, um ein neues Produkt aufzunehmen. Die gesamte Integration findet in der Programmierung der Geräteseite statt. Dazu müssen das Thing Model und die Firmware implementiert werden.

Abgrenzung

Getting Started zeigt einen schnellen Weg zu einem ersten lauffähigen Gerät. Dieser Leitfaden geht die Anbindung eines Produkts systematisch durch und beschreibt am Ende mögliche Erweiterungsszenarien.

Die Rolle des Thing Models

Das Thing Model ist die Schnittstelle zwischen Produkt und Plattform. Es beschreibt nicht, wie ein Gerät intern funktioniert, sondern was es für Fähigkeiten besitzt: Welche Werte es liefert und welche Befehle es entgegennimmt.

Aus dieser Beschreibung leitet die Plattform alles Weitere ab. Das Backend speichert das Modell und weiß dadurch, welche Capabilities ein Gerät besitzt. Die Oberfläche liest es und generiert für jede Capability das passende Bedienelement. Auch die Automationen greifen darauf zu, da Trigger und Aktionen über Capabilities formuliert werden.

Statt die Plattform um ein Produkt zu erweitern, beschreibt das Produkt sich selbst so, dass die Plattform es direkt aufnehmen und steuern kann. Ein Gerät, das die Plattform zuvor noch nie gesehen hat, ist sofort nach der Registrierung bedienbar.

graph LR
    P["Eigenes Produkt<br/>(Firmware + Thing Model)"] -->|Registrierung| B["Backend<br/>(unverändert)"]
    B -->|Thing Model| U["Oberfläche<br/>(unverändert)"]
    U -->|Bedienelemente| N["Nutzer"]

Schritt 1 – Fähigkeiten bestimmen

Am Anfang muss festgelegt werden, welche Funktionen des Produkts über die Plattform sichtbar oder bedienbar sein sollen. Jede dieser Funktionen wird zu einer Capability.

Für jede Capability werden drei Dinge festgelegt: ein eindeutiger Bezeichner (id), ein Grundtyp und die Datenrichtung.

Die Abstraktion der spezifischen Fähigkeiten des Geräts auf Grundtypen ist der eigentliche Schritt der Integration. Eine Heizung, ein Ventilator und eine Lampe unterscheiden sich physikalisch stark, lassen sich aber alle über dieselben Typen beschreiben.

Schritt 2 – Thing Model definieren

Die festgelegten Capabilities werden als JSON-Struktur beschrieben und in die Datei ThingModel.h der Firmware eingetragen. Aufbau und verfügbare Felder sowie erweiterte Funktionen sind im Kapitel Thing Model dokumentiert.

Alternativ lässt sich das Modell im Thing-Model-Builder zusammenstellen.

Schritt 3 – Firmware anpassen

Die bestehende Gerätelogik bleibt erhalten und wird um die Aufrufe der ActionConnect Library ergänzt. Notwendig sind dabei lediglich zwei Aufrufe für die Kommunikation sowie einer pro Capability für den Datenaustausch:

#include <Actionconnectlibrary.h>

void setup() {
  // bestehende Initialisierung des Produkts …
  connectHubInit();               // WLAN, MQTT und BLE einrichten
}

void loop() {
  connectHubProcessTransport();   // eingehende Befehle verarbeiten

  connectHubSend("light_lux", String(lux));            // Wert melden
  String helligkeit = connectHubGetCapability("brightness");  // Befehl auslesen
}

Schritt 4 – Registrierung und Kommunikation prüfen

Nach dem Flashen erhält das Gerät seine WLAN-Zugangsdaten über BLE oder dem Access Point (siehe Provisioning). Danach meldet es sich selbstständig beim Backend an.

Der Ablauf lässt sich auch über die serielle Ausgabe des Geräts verfolgen. Sie zeigt den Verbindungsaufbau, die auf devices/register veröffentlichte Registrierung und jede gesendete Telemetrie.

Schritt 5 – Im Dashboard prüfen

Nach erfolgreicher Registrierung lässt sich das Gerät im Dashboard einbinden. Dazu werden unter „Geräte hinzufügen" → „Per Geräte-ID hinzufügen" die Device-ID und der Pairing-Code eingegeben.

Der Pairing-Code wird auf Website des Access Points oder im seriellen Monitor angezeigt.

Anschließend zeigt die Oberfläche für jede Capability das passende Bedienelement.

Typische Erweiterungsszenarien

Nach der ersten Anbindung kann ein Produkt um weitere Funktionen ergänzt werden. Der Aufwand unterscheidet sich dabei erheblich, je nachdem, ob die vorhandenen Grundtypen ausreichen.

Szenario Was zu tun ist Änderung an der Plattform
Eine Funktion ergänzen Capability im Thing Model eintragen, Wert in der Firmware senden bzw. auswerten keine
Ein weiteres Produkt anbinden Eigenes Thing Model erstellen, Firmware wie oben ergänzen keine
Eine Funktion anders darstellen display der Capability ändern, etwa gauge statt value keine
Ein Gerät ohne Internetzugang betreiben Gerät über BLE mit der App verbinden, Gateway-Mode nutzen keine
Geräte aufeinander reagieren lassen Regel über die Automationen anlegen keine
Einen neuen Grundtyp einführen Typ formal festlegen und als Plugin in der App umsetzen Oberfläche

Nur im Fall der Erweiterung der Platform um einen neuen Grundtyp ist ein Eingriff in die Plattform selbst notwendig. Solange sich eine Funktion auf einen vorhandenen Grundtyp abbilden lässt, genügt eine Anpassung des Thing Models.

Datenhaltung

Auch eine wachsende Zahl an Capabilities erfordert keine Änderung am Datenbankschema. Die Telemetrie wird schemafrei als JSONB gespeichert (siehe Datenbank).

Checkliste

  • Fähigkeiten des Produkts als Capabilities mit id, Typ und Richtung festgelegt
  • Thing Model erstellt und in ThingModel.h eingetragen
  • connectHubInit() im setup(), connectHubProcessTransport() im loop() aufgerufen
  • Bezeichner in Firmware und Thing Model stimmen überein
  • Firmware geflasht und WLAN-Zugang übergeben
  • Registrierung und Telemetrie über serielle Ausgabe geprüft
  • Gerät im Dashboard eingebunden und Steuerung getestet

Siehe auch