MQTT-Anbindung

Die Open-Source-Version von FastBee enthält einen auf Netty basierenden MQTT-Broker, sodass keine zusätzliche Bereitstellung von EMQX erforderlich ist. Diese Seite beschreibt, wie Geräte über das MQTT-Protokoll an die Plattform angebunden werden.

Ablauf der Anbindung

Erstellen und veröffentlichen Sie in der Produktverwaltung ein MQTT-Produkt und notieren Sie Produkt-ID, Gerätenummer, MQTT-Konto und Passwort
Das Gerät oder MQTTX verbindet sich mit dem vereinbarten clientId, userName und password mit dem MQTT-Dienst
Nach erfolgreicher Verbindung wird zuerst /info/post veröffentlicht, danach /property/post oder /event/post
Auf der Plattformseite bestätigen Sie den geschlossenen Datenfluss über Laufzeitstatus, Ereignisprotokoll und Befehlsprotokoll in den Gerätedetails

Verbindungsinformationen

Parameter	TCP-Verbindung	WebSocket-Verbindung
Adresse	Server-IP	`ws://<Server-IP>:8083/mqtt`
Port	1883	8083
Protokoll	MQTT 3.1.1	MQTT over WebSocket

Geräteauthentifizierung

提示

Authentifizierungstypen: S = einfache Authentifizierung, E = verschlüsselte Authentifizierung
Wenn für ein Produkt der Geräte-Autorisierungscode aktiviert ist, darf der Autorisierungscode nicht leer sein
Die Benutzer-ID ist die ID des angemeldeten Benutzers; bei unterschiedlichen Benutzer-IDs gehören die Geräte unterschiedlichen Benutzern
Die Gerätenummer kann die von der Plattform erstellte Nummer sein oder eine eindeutige Kennung wie MAC/IMEI des Geräts (die Plattform registriert das Gerät dann automatisch)

Einfache Authentifizierung (für Tests empfohlen)

clientId = S&Gerätenummer&Produkt-ID&Benutzer-ID
userName = MQTT-Konto
password = MQTT-Passwort
password = MQTT-Passwort&Geräte-Autorisierungscode (wenn die Geräteautorisierung für das Produkt aktiviert ist)

Beispiel:

clientId = "S&D68329VL588&2&1"
userName = "fastbee"
password = "PHYFED93WSFF1DAS"

Verschlüsselte Authentifizierung (für die Produktion empfohlen)

clientId = E&Gerätenummer&Produkt-ID&Benutzer-ID
userName = MQTT-Konto
password = AES-verschlüsselt(MQTT-Passwort&Ablauf-Zeitstempel&Autorisierungscode(optional))

Das Passwort wird mit dem Produktschlüssel per AES-CBC verschlüsselt (Offset wumei-smart-open, Ausgabe Base64)
Der Ablauf-Zeitstempel ist auf Millisekunden genau; empfohlen werden maximal 24 Stunden

Beispiel:

clientId = "E&D68329VL588&2&1"
userName = "fastbee"
password = "/W2A/4MK+9cEGBhyBDgr2K5c62DAjAK4m0b5pvwxX6FFMzI3h1pUmaDY3BH1P2mI"

Hinweise zur AES-Verschlüsselung

Es wird der AES-CBC-Modus verwendet; für Tests können Sie das Online-Ver-/Entschlüsselungstool nutzen:

Parameter	Wert
Verschlüsselungsmodus	CBC
Padding	pkcs5padding
Datenblock	128 Bit
Offset	`wumei-smart-open`
Ausgabe	Base64
Passwort	Produktschlüssel
Zu verschlüsselnder Inhalt	`MQTT-Passwort&expireTime&Autorisierungscode(optional)`

Abonnierte Themen (Plattform → Gerät)

Thema (Topic)	Beschreibung
`/{productId}/{deviceNum}/function/get`	Plattformbefehle abonnieren (Eigenschaft setzen, Funktionsaufruf)
`/{productId}/{deviceNum}/info/get`	Anfrage für Geräteinformationen abonnieren (nach Empfang Geräteinformationen veröffentlichen)
`/{productId}/{deviceNum}/monitor/get`	Anfrage für Echtzeitüberwachung abonnieren (liefert Anzahl und Intervall zurück)
`/{productId}/{deviceNum}/ntp/get`	Zeitsynchronisierung abonnieren (optional)
`/{deviceNum}/http/upgrade/set`	OTA-Updates per HTTPS abonnieren
`/{deviceNum}/fetch/upgrade/set`	OTA-Updates als Binärpaket abonnieren

Veröffentlichte Themen (Gerät → Plattform)

Thema (Topic)	Beschreibung
`/{productId}/{deviceNum}/property/post`	Eigenschaften-/Funktionsdaten veröffentlichen (Echtzeitanzeige und Speicherung)
`/{productId}/{deviceNum}/event/post`	Ereignisse veröffentlichen
`/{productId}/{deviceNum}/info/post`	Geräteinformationen veröffentlichen
`/{productId}/{deviceNum}/monitor/post`	Echtzeit-Überwachungsdaten veröffentlichen (nur Echtzeitdiagramme, keine Speicherung)
`/{productId}/{deviceNum}/ntp/post`	Zeitsynchronisierung veröffentlichen (optional)
`/{deviceNum}/http/upgrade/reply`	OTA-Update per HTTPS beantworten
`/{deviceNum}/fetch/upgrade/reply`	OTA-Update als Binärpaket beantworten

提示

{productId} ist die Produkt-ID (nicht die Produktnummer), die Sie in den Produktdetails der Plattform finden
{deviceNum} ist die Gerätenummer und muss exakt mit dem Gerät auf der Plattform übereinstimmen

Datenformat

Gerät und Plattform tauschen Daten im JSON-Format aus.

Eigenschaften/Funktionen/Ereignisse veröffentlichen — `/property/post`, `/event/post`

json

[{
    "id": "temperature",
    "value": "27.43",
    "remark": "Temperatur normal"
}, {
    "id": "switch",
    "value": "1",
    "remark": "Schalter eingeschaltet"
}]

id: Thing-Modell-Kennung, in den Produktdetails einsehbar, innerhalb des Produkts eindeutig
value: Werte werden als String übertragen; boolesche Typen verwenden "0"/"1"; Enumerationstypen entsprechen den Enum-Schlüsseln; Array-Typen werden durch Kommas getrennt
remark: Anmerkung, im Gerätelog einsehbar

Plattformbefehle abonnieren — `/function/get`

json

[{
    "id": "gear",
    "value": "1",
    "remark": "Ausgelöst durch Szenenverknüpfung"
}, {
    "id": "switch",
    "value": "0",
    "remark": "Zeitgesteuertes Ausschalten"
}]

Geräteinformationen veröffentlichen — `/info/post`

json

{
    "rssi": -43,
    "firmwareVersion": 1.2,
    "status": 3,
    "userId": 1,
    "longitude": 0,
    "latitude": 0,
    "summary": {
        "name": "FastBee",
        "chip": "ESP32"
    }
}

Feld	Beschreibung
rssi	Signalstärke (ausgezeichnet [-55~0], gut [-70~-55], mäßig [-85~-70], schlecht [-100~-85])
firmwareVersion	Firmware-Versionsnummer
status	Gerätestatus, fest auf 3 (online) gesetzt
userId	Benutzer-ID
longitude/latitude	Optional, Geräteposition
summary	Optional, zusammenfassende Geräteinformationen

Echtzeitüberwachung — `/monitor/get`, `/monitor/post`

Die Plattform sendet eine Überwachungsanfrage:

json

{
    "count": 60,
    "interval": 1000
}

Das Gerät meldet die Daten mit der angegebenen Anzahl und im angegebenen Intervall:

json

[{
    "id": "temperature",
    "value": "27.43",
    "remark": ""
}]

Zeitsynchronisierung — `/ntp/post`, `/ntp/get`

Das Gerät veröffentlicht:

json

{
    "deviceSendTime": "1592361428000"
}

Die Plattform antwortet:

json

{
    "deviceSendTime": "1592361428000",
    "serverRecvTime": "1592366463548",
    "serverSendTime": "1592366463548"
}

Aktuelle Gerätezeit = (serverRecvTime + serverSendTime + deviceRecvTime - deviceSendTime) / 2

Regeln für Thing-Modell-Kennungen

Alle Kennungen sind innerhalb eines Produkts eindeutig, bestehen vorwiegend aus Buchstaben und Ziffern und vermeiden Sonderzeichen
Kennungen von Untermodellen eines Objekttyps haben das Format: parentId_childId
Kennungen von Array-Typen beginnen mit array_Index (Index zweistellig, z. B. array_00_power_switch); die Array-Länge darf 100 nicht überschreiten

AP-Netzwerkkonfiguration des Geräts (optional, nur für WLAN-Geräte)

Das Gerät öffnet einen Hotspot (Adresse 192.168.4.1); die mobile App überträgt die Konfigurationsinformationen über den Webdienst des Geräts.

Gerät erkennen

GET http://192.168.4.1/api/wifi/status

HTTP 200 bedeutet, dass das Gerät erkannt wurde; die Antwort enthält Geräteinformationen und den aktuellen Netzwerkstatus.

Konfigurationsschnittstelle

POST http://192.168.4.1/api/wifi/config?SSID=<WLAN-Name>&password=<WLAN-Passwort>&userId=<Benutzer-ID>

Parameter	Beschreibung
SSID	WLAN-Name (erforderlich, kompatibel mit ssid in Kleinbuchstaben)
password	WLAN-Passwort (erforderlich, kompatibel mit dem Alias pwd)
userId	Benutzer-ID (erforderlich)
deviceNum	Gerätenummer (optional)
extra	Produktnummer (optional)

HTTP 200 bedeutet erfolgreiche Netzwerkkonfiguration (das Gerät wechselt anschließend automatisch in den STA-Modus), 400 bedeutet fehlende Pflichtparameter, 500 bedeutet, dass das Speichern fehlgeschlagen ist. Eine ausführliche Beschreibung der Schnittstelle finden Sie in „Netzwerkkonfiguration · AP-Provisioning-API für Smartphone/Mobile" (Chinesisch).

Test mit MQTTX

Laden Sie den MQTTX-Client herunter
Neue Verbindung anlegen:
- Host: mqtt://<Server-IP>, Port: 1883
- Client ID: S&Gerätenummer&Produkt-ID&1
- Username: MQTT-Konto
- Password: MQTT-Passwort
Abonnieren Sie /{productId}/{deviceNum}/function/get
Veröffentlichen Sie Geräteinformationen an /{productId}/{deviceNum}/info/post
Veröffentlichen Sie Eigenschaftsdaten an /{productId}/{deviceNum}/property/post
Beobachten Sie Online-Status und Laufzeitdaten des Geräts in der Plattformkonsole

Abnahmecheckliste für die Integration

Schritt	Prüfinhalt	Erfolgskriterium
1	Produkt veröffentlicht	Produktstatus ist „veröffentlicht"
2	MQTTX-Verbindung	Gerätedetails zeigen „online"
3	`/info/post`	Geräteinformationen, Signal- und Versionsfelder aktualisiert
4	`/property/post`	Laufzeitstatus zeigt Thing-Modell-Eigenschaftswerte
5	`/event/post`	Gemeldete Ereignisse erscheinen im Ereignisprotokoll
6	`/function/get`	Gerät empfängt den von der Plattform gesendeten Befehl
7	Ergebnisrückmeldung	Gerät meldet das Ergebnis zurück, Plattformstatus wird aktualisiert
8	Regeln/Szenen	Zugehörige Regeln, Szenen und Alarme werden ausgelöst

Häufige Fehler

Verbindung abgelehnt

Ist der Port 1883 auf dem Server geöffnet?
Ist der integrierte MQTT-Broker gestartet?
Hat das clientId das richtige Format (S&Gerätenummer&Produkt-ID&Benutzer-ID)?
Ist für das Produkt der Geräte-Autorisierungscode aktiviert?
Ist das Gerät deaktiviert?

Gerät online, aber Eigenschaften aktualisieren sich nicht

Lautet das Veröffentlichungsthema /{productId}/{deviceNum}/property/post?
Verwenden Sie für productId die Produkt-ID (nicht die Produktnummer)?
Stimmt deviceNum exakt mit der Gerätenummer überein?
Hat der Nachrichtentext das JSON-Array-Format?
Stimmt id exakt mit der Thing-Modell-Kennung überein?
Entspricht value dem Datentyp?

Gerät empfängt Plattformbefehle nicht

Hat das Gerät /{productId}/{deviceNum}/function/get abonniert?
Ist das Gerät noch online?
Handelt es sich beim Thing-Modell um eine beschreibbare Funktion oder eine setzbare Eigenschaft?
Hat der Benutzer die Berechtigung für Gerätedetails und Befehlsausgabe?

Regel oder Alarm wurde nicht ausgelöst

Gelangen die Gerätedaten in den Laufzeitstatus der Plattform?
Sind Produkt, Gerät und Variable, die an die Szene oder Regel gebunden sind, korrekt?
Stimmt der Bedingungsausdruck mit dem Typ des gemeldeten Werts überein?
Ist die Alarmkonfiguration aktiviert?

Umwandlung mit Regelskripten

Wenn das Gerät ein eigenes Datenformat verwendet, können Sie im Regelskript eine Umwandlungslogik schreiben, die die Rohdaten in das Standardformat der Plattform überführt. Details siehe Regelskripte (Chinesisch).

MQTT-Anbindung ​

Ablauf der Anbindung ​

Verbindungsinformationen ​

Geräteauthentifizierung ​

Einfache Authentifizierung (für Tests empfohlen) ​

Verschlüsselte Authentifizierung (für die Produktion empfohlen) ​

Hinweise zur AES-Verschlüsselung ​

Abonnierte Themen (Plattform → Gerät) ​

Veröffentlichte Themen (Gerät → Plattform) ​

Datenformat ​

Eigenschaften/Funktionen/Ereignisse veröffentlichen — /property/post, /event/post ​

Plattformbefehle abonnieren — /function/get ​

Geräteinformationen veröffentlichen — /info/post ​

Echtzeitüberwachung — /monitor/get, /monitor/post ​

Zeitsynchronisierung — /ntp/post, /ntp/get ​

Regeln für Thing-Modell-Kennungen ​

AP-Netzwerkkonfiguration des Geräts (optional, nur für WLAN-Geräte) ​

Gerät erkennen ​

Konfigurationsschnittstelle ​

Test mit MQTTX ​

Abnahmecheckliste für die Integration ​

Häufige Fehler ​

Verbindung abgelehnt ​

Gerät online, aber Eigenschaften aktualisieren sich nicht ​

Gerät empfängt Plattformbefehle nicht ​

Regel oder Alarm wurde nicht ausgelöst ​

Umwandlung mit Regelskripten ​

Verwandte Dokumente ​

MQTT-Anbindung

Ablauf der Anbindung

Verbindungsinformationen

Geräteauthentifizierung

Einfache Authentifizierung (für Tests empfohlen)

Verschlüsselte Authentifizierung (für die Produktion empfohlen)

Hinweise zur AES-Verschlüsselung

Abonnierte Themen (Plattform → Gerät)

Veröffentlichte Themen (Gerät → Plattform)

Datenformat

Eigenschaften/Funktionen/Ereignisse veröffentlichen — `/property/post`, `/event/post`

Plattformbefehle abonnieren — `/function/get`

Geräteinformationen veröffentlichen — `/info/post`

Echtzeitüberwachung — `/monitor/get`, `/monitor/post`

Zeitsynchronisierung — `/ntp/post`, `/ntp/get`

Regeln für Thing-Modell-Kennungen

AP-Netzwerkkonfiguration des Geräts (optional, nur für WLAN-Geräte)

Gerät erkennen

Konfigurationsschnittstelle

Test mit MQTTX

Abnahmecheckliste für die Integration

Häufige Fehler

Verbindung abgelehnt

Gerät online, aber Eigenschaften aktualisieren sich nicht

Gerät empfängt Plattformbefehle nicht

Regel oder Alarm wurde nicht ausgelöst

Umwandlung mit Regelskripten

Verwandte Dokumente