RBgrid

Compilar a partir do código-fonte

O RBgrid é uma aplicação de firmware para o ESP32, não uma biblioteca que se liga ao seu próprio sketch. "Compilar a partir do código-fonte" significa compilar a imagem do hub tal como está e gravá-la na placa; depois configura os sensores e as unidades em tempo de execução a partir da aplicação web ou da API (veja Concepts → Sensors & Units).

📦 Código-fonte: o código-fonte do firmware é publicado em github.com/rb-amp/RBgrid juntamente com os ficheiros LICENSE, COMMERCIAL.md e NOTICE.

Requisitos

  • Placa: um ESP32 com PSRAM — obrigatório (o RBgrid usa PSRAM; não funciona num ESP32 sem ela). Um ESP32-WROVER, ou, a partir da v1.1.8, um ESP32-S3 no módulo N16R8. 16 MB de flash, e num WROVER 16 MB com PSRAM é a variante menos comum, por isso verifique uma placa que já tenha antes de contar com ela — esptool.py -p <PORT> flash_id mostra o que tem (deixe de fora --chip e o esptool deteta a placa por si).
  • Toolchain: ESP-IDF v5.5.1 — com que a versão é compilada a partir da v1.1.7. O v5.4.1 também compila a mesma árvore, por isso não é preciso mudar uma instalação que já tenha. Alvo esp32, ou esp32s3 para um hub ESP32-S3.
  • openssl na máquina de compilação (usado uma vez para gerar o certificado de desenvolvimento).

Licença

O firmware do RBgrid é source-available sob a licença PolyForm Noncommercial 1.0.0 — gratuito para usar, modificar e compilar para fins pessoais e não comerciais; o uso comercial exige uma licença (contacte info@rbamp.com). Não é uma licença OSI «open source». Os ficheiros LICENSE, COMMERCIAL.md e NOTICE estão no repositório; o código-fonte da aplicação web está em webapp/ sob a mesma licença.

Passos de compilação

  1. Clone o repositório: bash git clone https://github.com/rb-amp/RBgrid.git cd RBgrid
  2. Gere o certificado de desenvolvimento (uma vez, antes da primeira compilação). Isto escreve um certificado de desenvolvimento autoassinado que a compilação incorpora (rbgrid_dev_cert.pem + rbgrid_dev_key.pem, válido 10 anos); a chave privada não é distribuída no repositório. O hub serve a aplicação web por HTTP simples na sua rede local; o HTTPS não é uma funcionalidade para o utilizador. bash components/rbpower/certs/gen_dev_cert.sh

  3. (Opcional) defina a sua própria palavra-passe do ponto de acesso de primeiro login. Copie o modelo e defina uma palavra-passe 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 Se não o fizer, a compilação usa o valor público do modelo e imprime um aviso; pode definir a sua própria palavra-passe mais tarde na aplicação (Settings → Hub access point).

  4. Compile: bash idf.py build

  5. Grave por USB (escreve o bootloader, a tabela de partições, os dados OTA e a aplicação): bash idf.py -p <PORT> flash <PORT> é a porta série da placa (por exemplo /dev/ttyUSB0, COM3).

Depois desta primeira gravação por USB, o hub pode ser atualizado por via aérea (OTA) — envia uma nova imagem a partir da aplicação web. O firmware mantém duas partições OTA com reversão.

Sem toolchain? Grave os quatro ficheiros da versão mais recente; o comando esptool e o SHA-256 de cada ficheiro estão nas notas da versão.

Instalar a aplicação web

Pode saltar este passo e abrir a aplicação em webapp.rbgrid.io (Chrome ou Edge, na mesma rede que o hub). Para ter a aplicação no próprio hub, instale-a uma vez. É um pacote separado na página de versões, rbgrid-ui_v1.1.5.zip (kit/ + ui-manifest.json lado a lado). Descompacte-o e instale-o no hub através da 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 tiver definido um API token, acrescente -H "Authorization: Bearer <token>" a ambas as chamadas. Para compilar o pacote você mesmo a partir de webapp/: npm ci e depois npm run build:embedded (veja webapp/README.md).

O acesso do navegador ao hub está limitado a uma lista de permissões: as próprias páginas do hub e a aplicação RBgrid (https://webapp.rbgrid.io, https://demo.rbgrid.io) estão sempre permitidas. Para executar a aplicação web a partir do seu próprio endereço (por exemplo http://localhost:5173), acrescente-o na aplicação em Settings → Browser access (CORS); até 8 sites.

Primeiro arranque

  1. O hub inicia a sua própria rede Wi-Fi, rbgrid-<mac4> (os últimos quatro caracteres do seu MAC), usando a palavra-passe de primeiro login.
  2. Ligue-se a ela e abra 192.168.4.1.
  3. Guarde a sua Wi-Fi doméstica para que o hub se ligue à sua rede.
  4. Opcionalmente, defina o seu broker MQTT na aplicação (Settings → Home Assistant): o hub não traz nenhum broker predefinido.

A Wi-Fi própria do hub mantém-se ativa para que possa sempre chegar ao hub. Altere a palavra-passe na aplicação (Settings → Hub access point) e defina um API token (Settings → Security), para que ninguém por perto possa alterar o seu hub.

A partir daqui, abra a aplicação em webapp.rbgrid.io ou instale-a no hub (acima), acrescente os seus módulos rbAmp e associe canais a pontos como em Concepts → Sensors & Units e First Measurements. Depois de acrescentar pontos, reinicie o hub para que passem a guardar histórico.

🔒 Na rede local, as escritas na API do hub ficam abertas até definir um admin token (POST /api/system/token). É recomendado definir um.