Build from Source

RBgrid is a firmware application for the ESP32, not a library you link into your own sketch. "Building from source" means building the hub image as it is and flashing it to the board; you then configure sensors and units at runtime from the web app or the API (see Concepts → Sensors & Units).

📦 Source: the firmware source is published at github.com/rb-amp/RBgrid together with the LICENSE, COMMERCIAL.md and NOTICE files.

Requirements

  • Board: an ESP32 with PSRAM — required (RBgrid uses PSRAM; it will not run on an ESP32 without it). An ESP32-WROVER, or, from v1.1.8, an ESP32-S3 on the N16R8 module. 16 MB of flash, and on a WROVER 16 MB with PSRAM is the less common variant, so check a board you already own before you count on it — esptool.py -p <PORT> flash_id prints what it has (leave --chip out and esptool detects the board itself).
  • Toolchain: ESP-IDF v5.5.1 — what the release is built with from v1.1.7. v5.4.1 also builds the same tree, so there is no need to change an installation you already have. Target esp32, or esp32s3 for an ESP32-S3 hub.
  • openssl on the build machine (used once to generate the development certificate).

Licence

RBgrid firmware is source-available under the PolyForm Noncommercial 1.0.0 licence — free to use, modify and build for personal and non-commercial use; commercial use requires a licence (contact info@rbamp.com). It is not an OSI "open source" licence. The LICENSE, COMMERCIAL.md and NOTICE files are in the repository; the web app's source is in webapp/ under the same licence.

Build steps

  1. Clone the repository: bash git clone https://github.com/rb-amp/RBgrid.git cd RBgrid
  2. Generate the development certificate (once, before the first build). This writes a self-signed development certificate that the build embeds (rbgrid_dev_cert.pem + rbgrid_dev_key.pem, valid 10 years); the private key is not shipped in the repository. The hub serves the web app over plain HTTP on your local network; HTTPS isn't a user feature. bash components/rbpower/certs/gen_dev_cert.sh
  3. (Optional) set your own first-login access-point password. Copy the template and set a password of 8–63 characters: bash cp components/rbpower/include/ap_provision.example.h components/rbpower/include/ap_provision.h # edit ap_provision.h and set your AP password If you skip this, the build uses the public template value and prints a warning; you can set your own password later in the app (Settings → Hub access point).

  4. Build: bash idf.py build

  5. Flash over USB (writes the bootloader, partition table, OTA data and the app): bash idf.py -p <PORT> flash <PORT> is the board's serial port (e.g. /dev/ttyUSB0, COM3).

After this first USB flash, the hub can be updated over the air (OTA) — you upload a new image from the web app. The firmware keeps two OTA slots with rollback.

No toolchain? Flash the four files from the latest release instead; the esptool command and each file's SHA-256 are in the release notes.

Install the web app

You can skip this step and open the app at webapp.rbgrid.io instead (Chrome or Edge, on the same network as the hub). To have the app on the hub itself, install it once. It's a separate package on the release page, rbgrid-ui_v1.1.5.zip (kit/ + ui-manifest.json side by side). Unpack it and install it onto the hub over its 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

If you've set an API token, add -H "Authorization: Bearer <token>" to both calls. To build the package yourself from webapp/: npm ci then npm run build:embedded (see webapp/README.md).

Browser access to the hub is limited to an allow-list: the hub's own pages and the RBgrid app (https://webapp.rbgrid.io, https://demo.rbgrid.io) are always allowed. To run the web app from your own address (for example http://localhost:5173), add it in the app under Settings → Browser access (CORS); up to 8 sites.

First boot

  1. The hub starts its own Wi-Fi network, rbgrid-<mac4> (the last four of its MAC), using the first-login password.
  2. Join it and open 192.168.4.1.
  3. Save your home Wi-Fi so the hub joins your network.
  4. Optionally, set your MQTT broker in the app (Settings → Home Assistant): the hub ships with no default broker.

The hub's own Wi-Fi stays on so you can always reach the hub. Change its password in the app (Settings → Hub access point) and set an API token (Settings → Security), so nobody nearby can change your hub.

From here, open the app at webapp.rbgrid.io or install it on the hub (above), add your rbAmp modules and bind channels to points as in Concepts → Sensors & Units and First Measurements. After adding points, restart the hub so they start keeping history.

🔒 On the LAN, writes to the hub's API are open until you set an admin token (POST /api/system/token). Setting one is recommended.