Verbinden Sie Ihr erstes Gerät

Diese Seite verbindet ein Gerät, das sich mit einem Zugriffstoken anmeldet. Es dauert etwa fünf Minuten. Sie können das echte Gerät verwenden oder einen Computer mit einem MQTT-Client oder curl, der es ersetzt. Für LoRaWAN-Sensoren folgen Sie stattdessen Connect your first LoRaWAN sensor; für lizenzierte Geräte siehe Adding and claiming devices.

Was Sie benötigen

• Die Rolle Admin oder Owner (Berechtigung, Geräte anzulegen und Gerätezugangsdaten zu verwalten).
• Einen MQTT-3.1.1-Client mit TLS oder curl. Die Beispiele verwenden mosquitto_pub, den Client, den auch die Geräteseite anzeigt.
• Ausgehenden Zugriff auf TCP-Port 8883 (MQTT über TLS) oder 443 (HTTPS).

1. Gerät hinzufügen

1. Öffnen Sie Devices im IoT-Menü.
2. Wählen Sie New device. Wenn mehrere Wege angeboten werden, fragt die Seitenleiste What are you adding?; wählen Sie Other device („Any other device: give it a name and a profile, and it gets an access token.“).
3. Füllen Sie das Formular aus:

Feld	Was einzutragen ist
Name	Ein Name, der in Ihrer Organisation eindeutig ist, zum Beispiel boiler-07. Pflichtfeld, bis zu 128 Zeichen.
Label	Optionaler Freitext, zum Beispiel Boiler room, north.
Device profile	Belassen Sie vorerst The default profile. Sie können das Gerät später in ein anderes Profil verschieben.
This device is a gateway	Lassen Sie es ausgeschaltet. Aktivieren Sie es nur für ein Gerät, das für andere Geräte meldet.

1. Wählen Sie Create device.

Die Seitenleiste zeigt New secret: Copy it now: it is shown once and cannot be read back. mit dem Access token des Geräts sowie eine Karte Connection details, deren Beispielzeilen das Token bereits enthalten.

Wird kein Token angezeigt, hat Ihre Organisation Issue an access token for new devices deaktiviert (Devices > ⋯ > Settings). Das Gerät wird dann ohne Zugangsdaten angelegt; siehe Device credentials.

2. Verbindungsdetails lesen

Die Karte Connection details enthält:

Eintrag	Bedeutung
MQTT broker	Der Host und Port, mit denen sich das Gerät verbindet.
Security	TLS (mqtts): the server certificate is a public one, oder einfaches MQTT, wenn das Profil dies erlaubt.
Login	Username = the access token, password empty, any client ID
Telemetry topic und Attributes topic	Wohin das Gerät veröffentlicht.
Commands (subscribe)	Wo das Gerät auf Befehle wartet.
HTTPS telemetry und Header	Die Adresse und der Header für Geräte, die stattdessen HTTPS verwenden.
Example message (JSON), Send it with mosquitto_pub, Send it with curl	Zeilen, die Sie kopieren und ausführen können.

Später finden Administratoren dieselbe Karte auf dem Reiter Credentials des Geräts (mit einem Platzhalter statt des Tokens).

3. Nachricht über MQTT senden

Melden Sie sich mit dem Token als Benutzername und leerem Passwort an und veröffentlichen Sie dann ein JSON-Objekt auf v1/telemetry mit QoS 1:

mosquitto_pub -h <broker host> -p 8883 \
  --capath /etc/ssl/certs \
  -u "<ACCESS_TOKEN>" \
  -i boiler-07 \
  -q 1 \
  -t v1/telemetry \
  -m '{"temperature": 21.5, "humidity": 40}'

• Verwenden Sie den auf der Karte angezeigten Hostnamen. TLS benötigt den Namen, nicht eine IP-Adresse.
• Die Client-ID kann aus 1 bis 64 Zeichen aus A–Z a–z 0–9 . _ : - bestehen.
• Hermetry speichert jeden Schlüssel als eigene Zeitreihe und versieht die Werte mit dem Zeitpunkt des Empfangs.

3b. Oder über HTTPS senden

curl -X POST "https://<device host>/api/v1/telemetry" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"temperature": 21.5, "humidity": 40}'

Eine Antwort 200 mit leerem Body bedeutet, dass die Nachricht angenommen wurde. Siehe Device HTTP API.

4. Prüfen, ob sie angekommen ist

1. Öffnen Sie Devices und wählen Sie den Namen des Geräts.
2. Die Spalte Connection und der Gerätekopf zeigen Online, solange eine MQTT-Sitzung offen ist (bei der Regel Live connection des Standardprofils). Ein reines HTTP-Gerät mit dieser Regel wird nie als online angezeigt; siehe Connection status and activity.
3. Öffnen Sie den Reiter Telemetry. Die Tabelle Latest values listet temperature und humidity mit ihrer Zeit auf.
4. Markieren Sie einen numerischen Schlüssel und verwenden Sie Chart, um seinen Verlauf von Last hour bis Last 7 days zu sehen.

Senden Sie einige weitere Nachrichten mit anderen Werten, damit sich das Diagramm verändert.

Wenn nichts ankommt

Symptom	Wahrscheinliche Ursache
Der Client meldet „bad username or password“ (CONNACK 4).	Das Token ist falsch oder wurde rotiert.
Der Client meldet „not authorised“ (CONNACK 5).	Das Gerät ist deaktiviert, oder das Profil erlaubt diesen Anmeldetyp oder dieses Netzwerk nicht, oder es verlangt TLS. Der Grund steht im Reiter Log des Geräts.
Die Verbindung über Port 1883 wird abgelehnt.	Das Profil verlangt TLS. Verwenden Sie Port 8883.
Der TLS-Handshake schlägt fehl.	Sie haben über eine IP-Adresse verbunden, oder Ihrem Client fehlt ein CA-Bundle. Verwenden Sie den Hostnamen und den CA-Speicher des Systems.
HTTP antwortet mit 401.	Der Header Authorization: Bearer fehlt oder das Token ist falsch.
Das Gerät wird als online angezeigt, aber es erscheint kein Wert.	Die Nutzlast ist kein JSON-Objekt, oder ein Schlüssel verletzt die Schlüsselregeln (zum Beispiel beginnt er mit _ oder fw_). Siehe MQTT topics and payload reference.

Weitere Ursachen finden Sie unter A device does not connect und Data does not arrive.

Was Sie getan haben

• Sie haben ein Gerät im Standardprofil angelegt, das TLS verlangt und Zugriffstoken akzeptiert.
• Das Gerät hat sich mit seinem Token angemeldet und Telemetrie veröffentlicht.
• Jede Nachricht zählt auf das monatliche Nachrichtenkontingent Ihrer Organisation. Siehe Message quota and usage.

Nächster Schritt

Build your first dashboard.