RBgrid

Aus dem Quellcode bauen

RBgrid ist eine Firmware-Anwendung für den ESP32, keine Bibliothek, die Sie in Ihre eigene Skizze einbinden. „Aus dem Quellcode bauen“ heißt, das Hub-Image so zu bauen, wie es ist, und auf das Board zu flashen; Sensoren und Units konfigurieren Sie danach zur Laufzeit in der Web-App oder über die API (siehe Concepts → Sensors & Units).

📦 Quellcode: Der Firmware-Quellcode wird unter github.com/rb-amp/RBgrid zusammen mit den Dateien LICENSE, COMMERCIAL.md und NOTICE veröffentlicht.

Voraussetzungen

  • Board: ein ESP32 mit PSRAM — zwingend (RBgrid nutzt PSRAM; ohne es läuft die Firmware auf einem ESP32 nicht). Ein ESP32-WROVER oder ab v1.1.8 ein ESP32-S3 mit dem Modul N16R8. 16 MB Flash, und beim WROVER ist 16 MB mit PSRAM die seltenere Variante. Prüfen Sie daher ein Board, das Sie bereits besitzen, bevor Sie darauf zählen — esptool.py -p <PORT> flash_id zeigt, was es hat (lassen Sie --chip weg, dann erkennt esptool das Board selbst).
  • Toolchain: ESP-IDF v5.5.1 — damit wird das Release ab v1.1.7 gebaut. v5.4.1 baut denselben Baum ebenfalls, daher müssen Sie eine vorhandene Installation nicht ändern. Target esp32, oder esp32s3 für einen ESP32-S3-Hub.
  • openssl auf dem Build-Rechner (wird einmal benötigt, um das Entwicklungszertifikat zu erzeugen).

Lizenz

Die RBgrid-Firmware ist source-available unter der Lizenz PolyForm Noncommercial 1.0.0 — kostenlos nutzbar, veränderbar und baubar für persönliche und nicht-kommerzielle Zwecke; kommerzielle Nutzung erfordert eine Lizenz (Kontakt: info@rbamp.com). Es ist keine OSI-„Open-Source“-Lizenz. Die Dateien LICENSE, COMMERCIAL.md und NOTICE liegen im Repository; der Quellcode der Web-App liegt in webapp/ unter derselben Lizenz.

Build-Schritte

  1. Klonen Sie das Repository: bash git clone https://github.com/rb-amp/RBgrid.git cd RBgrid
  2. Erzeugen Sie das Entwicklungszertifikat (einmal, vor dem ersten Build). Dies schreibt ein selbstsigniertes Entwicklungszertifikat, das der Build einbettet (rbgrid_dev_cert.pem + rbgrid_dev_key.pem, gültig 10 Jahre); der private Schlüssel wird nicht mit dem Repository ausgeliefert. Der Hub liefert die Web-App über einfaches HTTP im lokalen Netzwerk aus; HTTPS ist keine Funktion für Nutzer. bash components/rbpower/certs/gen_dev_cert.sh

  3. (Optional) Legen Sie Ihr eigenes Access-Point-Passwort für den ersten Login fest. Kopieren Sie die Vorlage und setzen Sie ein Passwort mit 8–63 Zeichen: bash cp components/rbpower/include/ap_provision.example.h components/rbpower/include/ap_provision.h # edit ap_provision.h and set your AP password Überspringen Sie dies, verwendet der Build den öffentlichen Vorlagenwert und gibt eine Warnung aus; Sie können Ihr eigenes Passwort später in der App festlegen (Settings → Hub access point).

  4. Bauen: bash idf.py build

  5. Flashen über USB (schreibt den Bootloader, die Partitionstabelle, die OTA-Daten und die App): bash idf.py -p <PORT> flash <PORT> ist der serielle Port des Boards (z. B. /dev/ttyUSB0, COM3).

Nach diesem ersten USB-Flash lässt sich der Hub über die Luft (OTA) aktualisieren — Sie laden ein neues Image aus der Web-App hoch. Die Firmware hält zwei OTA-Slots mit Rollback vor.

Keine Toolchain? Flashen Sie stattdessen die vier Dateien aus dem neuesten Release; der esptool-Befehl und der SHA-256 jeder Datei stehen in den Release-Notes.

Die Web-App installieren

Sie können diesen Schritt überspringen und die App stattdessen unter webapp.rbgrid.io öffnen (Chrome oder Edge, im selben Netzwerk wie der Hub). Um die App auf dem Hub selbst zu haben, installieren Sie sie einmal. Sie ist ein separates Paket auf der Release-Seite, rbgrid-ui_v1.1.5.zip (kit/ + ui-manifest.json nebeneinander). Entpacken Sie es und installieren Sie es über die API auf den Hub:

bash
HUB=http://<your-hub-address>     # e.g. http://192.168.4.1 on the hub's own Wi-Fi
cd kit                              # in the folder where you unpacked the zip
for f in $(find . -type f | sed 's|^\./||'); do
  curl -sf -X POST "$HUB/api/system/ui-upload?path=$f" \
       -H 'Content-Type: application/octet-stream' --data-binary "@$f" || { echo "upload failed: $f"; exit 1; }
done
curl -sf -X POST "$HUB/api/system/ui-commit" -H 'Content-Type: application/json' --data-binary @../ui-manifest.json

Haben Sie ein API-Token gesetzt, fügen Sie -H "Authorization: Bearer <token>" zu beiden Aufrufen hinzu. Um das Paket selbst aus webapp/ zu bauen: npm ci und danach npm run build:embedded (siehe webapp/README.md).

Der Browserzugriff auf den Hub ist auf eine Allow-Liste beschränkt: die eigenen Seiten des Hubs und die RBgrid-App (https://webapp.rbgrid.io, https://demo.rbgrid.io) sind immer erlaubt. Um die Web-App von Ihrer eigenen Adresse aus zu betreiben (zum Beispiel http://localhost:5173), fügen Sie sie in der App unter Settings → Browser access (CORS) hinzu; bis zu 8 Seiten.

Erster Start

  1. Der Hub startet sein eigenes WLAN-Netz, rbgrid-<mac4> (die letzten vier Zeichen seiner MAC), mit dem Passwort für den ersten Login.
  2. Verbinden Sie sich damit und öffnen Sie 192.168.4.1.
  3. Speichern Sie Ihr WLAN zu Hause, damit der Hub Ihrem Netzwerk beitritt.
  4. Optional legen Sie Ihren MQTT-Broker in der App fest (Settings → Home Assistant): Der Hub wird ohne Standard-Broker ausgeliefert.

Das eigene WLAN des Hubs bleibt eingeschaltet, damit Sie den Hub jederzeit erreichen. Ändern Sie sein Passwort in der App (Settings → Hub access point) und setzen Sie ein API-Token (Settings → Security), damit niemand in der Nähe Ihren Hub ändern kann.

Öffnen Sie von hier aus die App unter webapp.rbgrid.io oder installieren Sie sie auf dem Hub (siehe oben), fügen Sie Ihre rbAmp-Module hinzu und binden Sie Kanäle an Points, wie in Concepts → Sensors & Units und First Measurements beschrieben. Starten Sie den Hub nach dem Hinzufügen der Points neu, damit sie mit der Historie beginnen.

🔒 Im LAN sind Schreibzugriffe auf die API des Hubs offen, bis Sie ein Admin-Token setzen (POST /api/system/token). Das Setzen wird empfohlen.