Mit dem Hub über HTTP sprechen

⚠️ Diese Seite betrifft die eigenständige Hub-Firmware. Ein Hub mit dem ESPHome-Paket hat keine REST-API, keinen WebSocket und kein MQTT – er ist ein ESPHome-Gerät, und Home Assistant spricht mit ihm über das RBgrid-Panel und die Aktion rbgrid_cmd. Alles Folgende setzt voraus, dass der Hub seine eigene Web-App ausliefert. → Im Home Assistant betreiben

Alles, was die App tut, tut sie über HTTP gegen den Hub in Ihrem eigenen Netzwerk. Dazwischen gibt es keine Cloud und kein Konto: Wenn Sie den Hub erreichen, können Sie ihn lesen, und mit seinem Token können Sie ihn ändern.

Diese Seite ist der Teil, den eine Routentabelle nicht sagen kann – welches Token, wie oft man fragt und die Handvoll Fehler, die wie Hub-Defekte aussehen und keine sind. Die Routen selbst stehen in der generierten API-Referenz, einer Datei im Repository, die der Hub aus seinem eigenen Schema erzeugt und die bei jeder Version neu erzeugt wird. Diese Liste wird hier absichtlich nicht wiederholt: Eine von Hand kopierte Routentabelle ist eine Version später falsch, und zwar stillschweigend.

---

Die zwei Tokens

Setzen Sie sie in der App unter Settings → Security. Solange kein Admin-Token gesetzt ist, kann jeder, der den Hub erreicht, ihn ändern – deshalb zeigt die App eine Warnung auf dem Bildschirm, bis dies und das Passwort des Access Points erledigt sind. → Settings

Senden Sie ein Token als Bearer-Token mit der Anfrage. Die generierte Referenz markiert jede Route, die für Schreibzugriffe das Admin-Token braucht.

⚠️ Was die generierte Referenz nicht sagt, ist, welche Lesezugriffe das Read-Token brauchen – sie sagt es selbst in ihrem Kopf. Die Regel, der die App folgt, lautet: Hat der Hub beide Tokens gesetzt, brauchen auch Lesezugriffe das Read-Token. Wenn Sie etwas bauen, das nur liest, setzen Sie ein Read-Token und senden Sie es; ein 401 auf einer Route, von der Sie erwartet haben, dass sie offen ist, bedeutet fast immer genau das.

Für die fünf Preisrouten ist die Aufteilung festgelegt: GET nimmt das Read-Token, POST nimmt das Admin-Token. Ein Dashboard, das nur Preise und das Protokoll der angewendeten Preise liest, braucht also nie das Admin-Token – und sollte es auch nicht bekommen.

Ein Browser-Client sollte kein Token in einer URL mitführen

Bei einer Seite, die einen WebSocket öffnet, landen Tokens in Protokollen, im Verlauf und auf Screenshots, sobald man sie in die Adresse schreibt. Der Hub bietet einen Ausweg: POST /api/v1/ws-ticket liefert ein einmalig verwendbares Ticket, gültig für 30 Sekunden, das der Socket stattdessen vorlegt. → Live data over WebSocket

Einem Browser auf einer anderen Herkunft den Aufruf des Hubs erlauben

Eine Seite, die von woanders kommt, blockiert der Browser, nicht der Hub. Unter /api/system/security erlauben Sie eine Herkunft – bis zu acht davon. Das ist eine bewusste Tür: Öffnen Sie sie also nur für die Herkünfte, die Sie betreiben, und für keine weiteren.

---

Was Sie abfragen und was nicht

Fragen Sie Live-Werte nicht ab. Der Hub schiebt sie hinaus: über WebSocket und über MQTT, im eigenen Takt des Hubs. Wer /api/v1/summary in einer Schleife abfragt, bekommt dieselben Zahlen später, kostet den Hub Arbeit, die er für Messungen bräuchte, und bekommt ein Abtastintervall, das gegen das des Hubs driftet.

Fragen Sie Dinge ab, die sich langsam ändern, und passen Sie die Rate an, wie schnell sie sich tatsächlich ändern:

⚠️ Eine Schleife ohne Backoff ist das eine Muster, das Sie ein Wochenende kosten wird. Schlägt eine Route fehl, ist die ehrliche Antwort, vor dem nächsten Versuch länger zu warten, nicht stärker zu drängen. Der Hub ist ein Mikrocontroller, der gleichzeitig eine Web-App, eine Broker-Verbindung, die Messschleife und Sie bedient; ein Client, der ihn in einer engen Wiederholung bombardiert, ist aus Sicht des Hubs nicht von einem Client zu unterscheiden, der es absichtlich tut.

---

Lesen, was der Hub gemessen hat

History gibt es pro Point und pro Periode, und es sind dieselben Daten, die die Seite History der App zeigt – einschließlich der Qualität jedes Datensatzes. Das ist der Teil, den Integratoren am häufigsten weglassen und dann einen Wert nicht erklären können. Ein Datensatz trägt Bits, die sagen, ob er teilweise ist, neu berechnet, geschätzt oder einen Ausfall abdeckt. Reichen Sie sie an alles weiter, was Sie bauen; ein Wert, dessen Qualität Sie verworfen haben, ist ein Wert, den Sie nicht verteidigen können. → History

Economics sind Kosten und Exportwert, vom Hub berechnet mit dem Preis, der für jede Periode galt – nicht aus einem aktuellen Satz neu berechnet. → How cost is calculated

export.csv liefert Ihnen dasselbe als Datei, nach Point, Periode und Typ. Für alles, was eine Tabellenkalkulation oder ein langes Archiv braucht, ist das der günstigere Weg: eine Anfrage statt einer Schleife.

⚠️ Der stündliche Verlauf wird 60 Tage aufbewahrt, danach täglich, monatlich und jährlich. Brauchen Sie die Stunden eines ganzen Abrechnungszeitraums im Nachhinein, holen Sie sie ab, bevor sie weiterrollen – ein geplanter export.csv ist der übliche Weg.

---

Die Preisrouten (Firmware 1.2.0 und neuer)

Drei Routen, und sie beantworten drei verschiedene Fragen:

/api/v1/price ist auch ein Schreibzugriff. Ein Client, der Ihre Preise kennt – eine Home-Assistant-Integration, Ihr eigenes Skript –, kann bis zu 200 Perioden in den Hub schieben, und der Hub bepreist die Energie damit. Das ist der Weg für einen Versorger, für den der Hub keine Quelle hat. Sie geben an, ob das, was Sie schieben, ein Spotpreis oder ein All-in-Preis ist; das falsch anzugeben ist der teuerste Fehler, der hier möglich ist, weil er jede Kostenangabe stillschweigend vervielfacht. → Woher Ihr Preis kommt

Für die Benachrichtigung bevorzugen Sie das retained MQTT-Topic gegenüber dem Abfragen von /api/v1/signal. Es ist ein Zustand: Der Hub veröffentlicht ihn bei jeder 15-Minuten-Grenze und in dem Moment, in dem sich etwas ändert, und eine retained-Nachricht gibt den aktuellen Zustand an einen Client weiter, der sich später verbindet. Ein Abfragender bekommt dasselbe, verspätet, und verpasst nichts nur, wenn er ständig fragt. → Wann Energie am günstigsten ist

---

Dinge ändern

Schreibzugriffe brauchen das Admin-Token, und manche Routen brauchen einen Neustart, bevor sie wirken – die generierte Referenz hat eine Spalte, die sagt welche. Ein paar Regeln, die in keiner Tabelle stehen:

• Ein abgelehnter Schreibzugriff nennt das Feld. Der Hub antwortet mit 400 und dem Feld, das er nicht akzeptiert hat, was weit nützlicher ist als ein Statuscode. Lesen Sie es: Meist sagt es Ihnen etwas Zutreffendes über Ihre Konfiguration, etwa dass eine Preiszone in einer Währung handelt, in der Ihr Tarif nicht ist.
• Namen sind in Byte begrenzt, nicht in Zeichen – 24 Byte für einen kurzen Namen, 31 für einen Namen. Ein kyrillischer oder akzentuierter Buchstabe braucht zwei, daher kann ein Name, der kurz aussieht, trotzdem abgelehnt werden.
• Konfiguration ist auf manchen Routen ein ganzes Dokument. Wo eine Route einen Konfigurationsabschnitt annimmt, ersetzt das Senden eines Teils den Abschnitt. Lesen Sie ihn, ändern Sie, was Sie ändern wollen, und senden Sie ihn zurück.

---

Was die API nicht tut

• Keine Cloud, kein Konto, kein Fernzugriff. Der Hub bedient Ihr Netzwerk. Alles darüber hinaus ist Ihr Tunnel, Ihr VPN, Ihre Verantwortung.
• Sie steuert nichts. Es gibt keine Route, die eine Last schaltet. Der Hub misst, bepreist und veröffentlicht; darauf zu reagieren ist Aufgabe dessen, was Sie bauen. → Wann Energie am günstigsten ist
• Keine Ratenbegrenzung pro Route, auf die Sie sich stützen könnten. Dass es keine gibt, ist keine Erlaubnis; siehe die Backoff-Warnung oben.

---

Wenn ein Aufruf nicht tut, was Sie erwarten: was zu prüfen ist

401 bei etwas, das gestern funktioniert hat. Seitdem wurde ein Token auf dem Hub gesetzt. Lesezugriffe brauchen das Read-Token, sobald beide Tokens existieren; Schreibzugriffe brauchen das Admin-Token.

Admin token required. bei einem Schreibzugriff, von dem Sie sicher sind, dass er autorisiert ist. Das Token ist gesetzt, erreicht den Hub aber nicht – prüfen Sie, ob es ein Bearer-Token in der Anfrage selbst ist und kein Query-Parameter.

Ein Browser meldet einen CORS-Fehler, curl funktioniert problemlos. Das lehnt der Browser ab, nicht der Hub. Tragen Sie Ihre Herkunft unter /api/system/security ein; Platz ist für acht.

Ein Schreibzugriff liefert 400 und nennt ein Feld, das Sie nicht gesendet haben. Manche Routen nehmen einen ganzen Konfigurationsabschnitt. Das Feld steht im Abschnitt, den Sie ersetzt haben, und war im aktuellen Zustand des Hubs nicht gültig – eine Zone, deren Währung nicht zu der des Tarifs passt, ist der häufigste Fall.

Eine Einstellung wurde gespeichert, aber nichts hat sich geändert. Manche Routen brauchen einen Neustart, um zu wirken; die generierte Referenz sagt in ihrer eigenen Spalte, welche.

Der Verlauf hat Lücken. Lücken sind Datensätze, die der Hub nicht hat, nicht Datensätze, die er verloren hat: Er wurde neu gestartet, aktualisiert oder war ohne Strom. Die Qualitätsbits der benachbarten Datensätze sagen, was geschehen ist. → History

Das Preisprotokoll hat für einen Tag weniger als 96 Zeilen. Gleiche Ursache, gleiche Bedeutung: Das Protokoll enthält die Perioden, in denen der Hub lief. Eine fehlende Periode ist kein fehlender Preis.

Live-Werte kommen langsam oder nicht im Gleichschritt mit der App an. Sie fragen ab, wo Sie abonnieren sollten. → Live data over WebSocket

⚠️ Für jede Arbeit im Inneren eines Elektrokastens einen qualifizierten Elektriker rufen.