RBgrid

Compilazione dal codice sorgente

RBgrid è una applicazione firmware per ESP32, non una libreria da collegare al proprio sketch. "Compilare dal sorgente" significa compilare l'immagine dell'hub così com'è e flasharla sulla scheda; poi configuri sensori e unità a runtime dall'app web o dall'API (vedi Concepts → Sensors & Units).

📦 Sorgente: il sorgente del firmware è pubblicato su github.com/rb-amp/RBgrid insieme ai file LICENSE, COMMERCIAL.md e NOTICE.

Requisiti

  • Scheda: un ESP32 con PSRAM, obbligatoria (RBgrid usa la PSRAM; non gira su un ESP32 senza). Un ESP32-WROVER, oppure, dalla v1.1.8, un ESP32-S3 con modulo N16R8. 16 MB di flash, e su un WROVER la variante da 16 MB con PSRAM è quella meno comune, quindi verifica una scheda che già possiedi prima di contarci: esptool.py -p <PORT> flash_id mostra cosa ha (ometti --chip e esptool rileva da solo la scheda).
  • Toolchain: ESP-IDF v5.5.1, con cui la release è compilata dalla v1.1.7. La v5.4.1 compila lo stesso albero, quindi non serve cambiare un'installazione già presente. Target esp32, oppure esp32s3 per un hub ESP32-S3.
  • openssl sulla macchina di compilazione (usato una volta per generare il certificato di sviluppo).

Licenza

Il firmware RBgrid è a sorgente disponibile sotto la licenza PolyForm Noncommercial 1.0.0: gratuito da usare, modificare e compilare per uso personale e non commerciale; l'uso commerciale richiede una licenza (contatta info@rbamp.com). Non è una licenza OSI «open source». I file LICENSE, COMMERCIAL.md e NOTICE sono nel repository; il sorgente dell'app web si trova in webapp/ sotto la stessa licenza.

Passaggi di compilazione

  1. Clona il repository: bash git clone https://github.com/rb-amp/RBgrid.git cd RBgrid
  2. Genera il certificato di sviluppo (una volta, prima della prima compilazione). Questo scrive un certificato di sviluppo autofirmato che la compilazione incorpora (rbgrid_dev_cert.pem + rbgrid_dev_key.pem, valido 10 anni); la chiave privata non è distribuita nel repository. L'hub serve l'app web via HTTP semplice sulla tua rete locale; HTTPS non è una funzione per l'utente. bash components/rbpower/certs/gen_dev_cert.sh

  3. (Facoltativo) imposta la tua password del punto di accesso per il primo accesso. Copia il modello e imposta una password di 8–63 caratteri: bash cp components/rbpower/include/ap_provision.example.h components/rbpower/include/ap_provision.h # edit ap_provision.h and set your AP password Se salti questo passaggio, la compilazione usa il valore pubblico del modello e stampa un avviso; puoi impostare la tua password in seguito nell'app (Settings → Hub access point).

  4. Compila: bash idf.py build

  5. Flash via USB (scrive bootloader, tabella delle partizioni, dati OTA e l'applicazione): bash idf.py -p <PORT> flash <PORT> è la porta seriale della scheda (per esempio /dev/ttyUSB0, COM3).

Dopo questo primo flash via USB, l'hub può essere aggiornato via OTA (over the air): carichi una nuova immagine dall'app web. Il firmware mantiene due slot OTA con rollback.

Niente toolchain? Installa invece i quattro file dalla ultima release; il comando esptool e lo SHA-256 di ogni file sono nelle note di rilascio.

Installa l'app web

Puoi saltare questo passaggio e aprire l'app su webapp.rbgrid.io (Chrome o Edge, sulla stessa rete dell'hub). Per avere l'app sull'hub stesso, installala una volta. È un pacchetto separato nella pagina delle release, rbgrid-ui_v1.1.5.zip (kit/ + ui-manifest.json affiancati). Decomprimilo e installalo sull'hub tramite la sua API:

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

Se hai impostato un token API, aggiungi -H "Authorization: Bearer <token>" a entrambe le chiamate. Per costruire il pacchetto tu stesso da webapp/: npm ci poi npm run build:embedded (vedi webapp/README.md).

L'accesso del browser all'hub è limitato a una lista di siti consentiti: le pagine dell'hub e l'app RBgrid (https://webapp.rbgrid.io, https://demo.rbgrid.io) sono sempre permesse. Per eseguire l'app web dal tuo indirizzo (per esempio http://localhost:5173), aggiungilo nell'app sotto Settings → Browser access (CORS); fino a 8 siti.

Primo avvio

  1. L'hub avvia una propria rete Wi-Fi, rbgrid-<mac4> (le ultime quattro cifre del suo MAC), usando la password del primo accesso.
  2. Collegati e apri 192.168.4.1.
  3. Salva la tua Wi-Fi di casa perché l'hub si unisca alla tua rete.
  4. Facoltativamente, imposta il tuo broker MQTT nell'app (Settings → Home Assistant): l'hub viene fornito senza broker predefinito.

La Wi-Fi propria dell'hub resta attiva, così puoi sempre raggiungerlo. Cambia la sua password nell'app (Settings → Hub access point) e imposta un token API (Settings → Security), così nessuno nei paraggi può modificare il tuo hub.

Da qui, apri l'app su webapp.rbgrid.io oppure installala sull'hub (sopra), aggiungi i tuoi moduli rbAmp e associa i canali ai punti come in Concepts → Sensors & Units e First Measurements. Dopo aver aggiunto i punti, riavvia l'hub perché inizino a conservare la cronologia.

🔒 Sulla LAN, le scritture sull'API dell'hub restano aperte finché non imposti un token di amministrazione (POST /api/system/token). Ne è consigliata l'impostazione.