Koppeln mit hello

Mit POST /device/hello holt sich ein Gerät seinen eigenen Token. Es bekommt einen Kopplungscode, der Eigentümer gibt diesen Code im Portal ein, und das nächste hello liefert den Token. Niemand muss einen Schlüssel von Hand übertragen.

Willst du das lieber nicht bauen? Erstelle einen Schlüssel im Portal und übertrage ihn selbst auf das Gerät: siehe das Ende dieser Seite.

Der Ablauf#

1. Das Gerät erzeugt einmalig eine zufällige UUID (Version 4) und behält sie, auch über Neustarts hinweg.

2. Es sendet POST /device/hello, ohne Token:

   {"device_uuid": "7b0e2f4c-1d3a-4e5b-9c6d-8f7a6b5c4d3e", "hw_serial": "00000000abcd1234", "firmware_version": "0.3.0"}
   

   Nur device_uuid ist Pflicht; hw_serial darf bis zu 64 Zeichen lang sein, firmware_version bis zu 32.

3. Solange niemand das Gerät gekoppelt hat, bekommt es einen Kopplungscode:

   {"claimed": false, "pairing_code": "BB-7KQ4-M2XD", "expires_at": "2026-10-10T12:00:00+00:00"}
   

   Das Gerät zeigt den Code an, zum Beispiel auf einem Display oder in einem Log.

4. Der Eigentümer gibt den Code ein: auf der Seite des Geräts mit Mit Code koppeln, oder unter Neues Gerät bei Kopplungscode (optional).

5. Beim nächsten hello bekommt das Gerät seinen Token:

   {"claimed": true, "token": "bb_live_42_Xk3…"}
   

6. Das Gerät speichert den Token und nutzt ihn. Ab dann antwortet hello nur noch {"claimed": true}.

Die UUID und der Code#

• Eine UUID einer anderen Version als 4, etwa eine aus Uhrzeit und MAC-Adresse, bekommt 422.
• Halte die UUID geheim, bis der Token benutzt wurde: Wer sie kennt, kann den Token abholen, sobald das Gerät gekoppelt ist. Druck sie also nicht auf einen Aufkleber und schreib sie nicht in ein Log, das andere lesen können.
• Sende während des Wartens etwa alle 15 Sekunden ein hello. Dieselbe UUID bekommt denselben Code, bis er abläuft, 24 Stunden nach der ersten Antwort.
• Ein Code besteht aus BB- und zwei Gruppen von vier Zeichen, ohne 0, O, 1 und I. Groß- und Kleinschreibung, Leerzeichen und Bindestriche spielen im Portal keine Rolle. Nach zehn falschen Codes in einer Stunde lehnt das Portal jeden Code ab, bis die Stunde vorbei ist.

Erst speichern, dann nutzen#

Bis der Token einmal benutzt wurde, liefert jedes hello einen neuen Token, und der vorige funktioniert nicht mehr. Eine verlorene Antwort ist also kein Problem: Frag einfach noch einmal. Halte diese Reihenfolge ein:

1. Speichere den Token so, dass er einen Stromausfall übersteht: in eine temporäre Datei schreiben und sie dann umbenennen.
2. Nutze ihn sofort, mit GET /device/config oder POST /device/status. Damit ist das Koppeln abgeschlossen.
3. Sende danach kein hello mehr. Tust du es vor der ersten Nutzung des Tokens, funktioniert dein gespeicherter Token nicht mehr.

Token nach der Nutzung verloren? Dann hilft hello mit derselben UUID nicht mehr. Erzeuge eine neue UUID, hol dir einen neuen Code und gib ihn mit Mit Code koppeln auf der Seite desselben Geräts ein. Oder erstelle einen Schlüssel von Hand.

Was das Koppeln im Portal bewirkt#

• Einen Code kann nur jemand eingeben, der das Gerät verwaltet, nicht jemand, mit dem es nur geteilt ist.
• Koppeln mit einem Code schaltet den aktuellen API-Schlüssel des Geräts sofort ab. Das Gerät holt sich mit seinem nächsten hello einen neuen.
• Löschst du das Gerät, beginnt hello mit derselben UUID von vorn, mit einem neuen Code.
• Ein simuliertes Gerät lässt sich nicht mit einem Code koppeln.

Ein Schlüssel von Hand#

Auf der Seite des Geräts gibt es in den Einstellungen unter Verbindung die Schaltfläche Schlüssel erstellen, oder Neuer Schlüssel, wenn es schon einen gibt. Das Portal fragt zuerst nach deinem Passwort und zeigt den Schlüssel einmal an. Fügst du ein Gerät ohne Kopplungscode hinzu, bekommst du sofort einen Schlüssel.

Ein Schlüssel von Hand beendet das Koppeln. Das nächste hello mit dieser UUID bekommt einen neuen Code, und nichts, was das Gerät mit hello tut, schaltet deinen Schlüssel ab.

Limits#

Was	Limit
hello pro UUID	10 pro Minute
hello pro IP-Adresse	30 pro Minute. Ein IPv6-/64-Netz zählt als eine Adresse

Über einem Limit bekommst du 429 mit einem Retry-After-Header: Warte so viele Sekunden. 422 bedeutet eine fehlende oder ungültige device_uuid oder ein zu langes Feld. Siehe auch Limits und Fehlercodes und die API-Referenz.