RBgrid

Compilar desde el código fuente

RBgrid es una aplicación de firmware para el ESP32, no una biblioteca que se enlaza en su propio sketch. «Compilar desde el código fuente» significa compilar la imagen del hub tal cual y grabarla en la placa; después configura sensores y unidades en tiempo de ejecución desde la aplicación web o la API (véase Concepts → Sensors & Units).

📦 Código fuente: el código del firmware se publica en github.com/rb-amp/RBgrid junto con los archivos LICENSE, COMMERCIAL.md y NOTICE.

Requisitos

  • Placa: un ESP32 con PSRAM, obligatorio (RBgrid usa PSRAM; no funciona en un ESP32 sin ella). Un ESP32-WROVER o, desde v1.1.8, un ESP32-S3 con el módulo N16R8. 16 MB de flash; y en un WROVER, la variante de 16 MB con PSRAM es la menos habitual, así que compruebe una placa que ya tenga antes de contar con ella. esptool.py -p <PORT> flash_id muestra lo que tiene (omita --chip y esptool detectará la placa por sí mismo).
  • Cadena de herramientas: ESP-IDF v5.5.1, con la que se compila la versión desde v1.1.7. v5.4.1 también compila el mismo árbol, así que no hace falta cambiar una instalación que ya tenga. Destino esp32, o esp32s3 para un hub con ESP32-S3.
  • openssl en la máquina de compilación (se usa una vez para generar el certificado de desarrollo).

Licencia

El firmware de RBgrid es de tipo source-available bajo la licencia PolyForm Noncommercial 1.0.0: se puede usar, modificar y compilar sin coste para uso personal y no comercial; el uso comercial requiere una licencia (contacte con info@rbamp.com). No es una licencia OSI de «código abierto». Los archivos LICENSE, COMMERCIAL.md y NOTICE están en el repositorio; el código de la aplicación web está en webapp/ bajo la misma licencia.

Pasos de compilación

  1. Clone el repositorio: bash git clone https://github.com/rb-amp/RBgrid.git cd RBgrid
  2. Genere el certificado de desarrollo (una vez, antes de la primera compilación). Esto escribe un certificado de desarrollo autofirmado que la compilación incrusta (rbgrid_dev_cert.pem + rbgrid_dev_key.pem, válido 10 años); la clave privada no se incluye en el repositorio. El hub sirve la aplicación web por HTTP simple en su red local; HTTPS no es una función para el usuario. bash components/rbpower/certs/gen_dev_cert.sh

  3. (Opcional) configure su propia contraseña del punto de acceso de primer inicio. Copie la plantilla y configure una contraseña de 8–63 caracteres: bash cp components/rbpower/include/ap_provision.example.h components/rbpower/include/ap_provision.h # edit ap_provision.h and set your AP password Si lo omite, la compilación usa el valor público de la plantilla y muestra un aviso; puede configurar su propia contraseña más tarde en la aplicación (Settings → Hub access point).

  4. Compile: bash idf.py build

  5. Grabe por USB (escribe el bootloader, la tabla de particiones, los datos OTA y la aplicación): bash idf.py -p <PORT> flash <PORT> es el puerto serie de la placa (por ejemplo /dev/ttyUSB0, COM3).

Tras este primer grabado por USB, el hub puede actualizarse por el aire (OTA): suba una imagen nueva desde la aplicación web. El firmware mantiene dos ranuras OTA con reversión.

¿Sin toolchain? Grabe en su lugar los cuatro archivos de la última versión; el comando de esptool y el SHA-256 de cada archivo están en las notas de la versión.

Instalar la aplicación web

Puede omitir este paso y abrir la aplicación en webapp.rbgrid.io (Chrome o Edge, en la misma red que el hub). Para tener la aplicación en el propio hub, instálela una vez. Es un paquete aparte en la página de versiones, rbgrid-ui_v1.1.5.zip (kit/ + ui-manifest.json juntos). Descomprímalo e instálelo en el hub por su 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

Si ha configurado un token de API, añada -H "Authorization: Bearer <token>" a ambas llamadas. Para compilar el paquete usted mismo desde webapp/: npm ci y después npm run build:embedded (véase webapp/README.md).

El acceso del navegador al hub está limitado a una lista de permitidos: las propias páginas del hub y la aplicación RBgrid (https://webapp.rbgrid.io, https://demo.rbgrid.io) siempre están permitidas. Para ejecutar la aplicación web desde su propia dirección (por ejemplo http://localhost:5173), añádala en la aplicación, en Settings → Browser access (CORS); hasta 8 sitios.

Primer arranque

  1. El hub inicia su propia red Wi-Fi, rbgrid-<mac4> (los últimos cuatro caracteres de su MAC), con la contraseña de primer inicio de sesión.
  2. Únase a ella y abra 192.168.4.1.
  3. Guarde su Wi-Fi doméstica para que el hub se una a su red.
  4. Opcionalmente, configure su broker MQTT en la aplicación (Settings → Home Assistant): el hub no trae ningún broker por defecto.

La Wi-Fi propia del hub sigue activa para que siempre pueda llegar al hub. Cambie su contraseña en la aplicación (Settings → Hub access point) y configure un token de API (Settings → Security), para que nadie cercano pueda cambiar su hub.

A partir de aquí, abra la aplicación en webapp.rbgrid.io o instálela en el hub (arriba), añada sus módulos rbAmp y vincule canales a puntos como en Concepts → Sensors & Units y First Measurements. Tras añadir puntos, reinicie el hub para que empiecen a guardar historial.

🔒 En la red local, las escrituras en la API del hub están abiertas hasta que configure un token de administrador (POST /api/system/token). Se recomienda configurarlo.