Installing RBgrid inside Home Assistant: the walkthrough, including the three ways it goes wrong

You have a Home Assistant, you have heard RBgrid can run inside it as an ESPHome device, and you have done the obvious thing: opened HACS and searched for it.

Nothing came back. Which is correct, and tells you nothing about whether the integration exists.

RBgrid is not in the HACS default list. Until you add it yourself, searching finds nothing — so the search result you just got is not evidence of absence, it is the expected first step of a path nobody told you about. This article is that path, with the places it goes wrong named rather than hidden.

Something already went wrong? The failures are collected in one table at the end — symptom, cause, what to do.

What you need before starting

⚠️ The Home Assistant version is load-bearing, not a recommendation. The RBgrid panel relies on action responses, which older versions do not have. On an older Home Assistant the panel simply does not work — and what you will see is something that looks like a broken integration rather than an old installation. If the panel is blank, check this first.

1. Flash the hub

Download the factory image for your board from the releases of rb-amp/rbgrid-esphome — there are two, one for the ESP32-WROVER and one for the ESP32-S3. Then open web.esphome.io in Chrome or Edge, choose Connect, pick your board's serial port, choose Install, and select the file you downloaded.

Home Assistant does not ask you for an API encryption key here: the ready-made image is built without one, so the device is added with a single confirmation. A key is only asked for if you built your own configuration with one.

Set Wi-Fi right after flashing, over the same USB cable, when the installer offers it. Do that and the hub never needs its setup access point at all. If you do go through the access point instead, change its password once the hub is adopted.

esptool works too: the factory image is written at offset 0x0.

⚠️ This is about your own YAML build, not the ready-made image. The component brings a partition table with the application at 0x20000, while ESPHome's own USB tools assume the standard 0x10000. Flashed over USB with ESPHome's own tools — esphome run to a serial port, or Manual download → Factory format — your build lands at the wrong address and the board boots nothing new: a blank board does not come up, and a board with an older image quietly keeps running the old one.

For a first install over USB, use the ready-made factory image from the releases page (it is merged with the real offsets and goes to 0x0), or esptool with the offsets from your build's own flasher_args.json. Once the hub is on the network, put your own builds on it over the air — esphome run with the hub reachable, or Install → Wirelessly. Over the air only the application is sent, and the device places it using its own partition table, so the offset is right by construction.

This is the step that fails silently. You are already inside the ESPHome tool, it offers you a factory-format download, the file looks right, the flash succeeds — and the board does nothing afterwards. There is no error to search for, which is why it is usually read as dead hardware.

Or build it into your own configuration

If you already keep your ESPHome devices as YAML, add the component as an external source instead of flashing a factory image:

external_components:
  - source:
      type: git
      url: https://github.com/rb-amp/rbgrid-esphome
      ref: v1.2.0   # the tag of the release you are installing — see the repository's Releases
      path: esphome/components
    components: [rbgrid]

2. Add RBgrid in HACS as a custom repository

This is the step the search result at the top of this article was standing in for, and it is three actions, not one:

1. in HACS, add https://github.com/rb-amp/rbgrid-ha as a custom repository, category Integration;
2. install RBgrid from it;
3. restart Home Assistant.

The restart is not optional and not a superstition — a newly installed integration is loaded at start-up.

3. Set up ESPHome first, then RBgrid

After the restart, Settings → Devices & services should show two cards: ESPHome (the device itself) and RBgrid (this integration).

Configure the ESPHome one first. The RBgrid card waits for it, because RBgrid talks to a device Home Assistant already knows; set up in the other order, it has nothing to attach to.

Then press Configure on the RBgrid card. Along the way ESPHome offers its own Name and assign dialog, listing the hub and its slots — press Skip; the names come from the points themselves.

The last step has two tick-boxes worth reading rather than clicking past:

• Configure the Energy dashboard with this hub — on by default when your Energy dashboard is empty. This is what puts the hub's entities on the dashboard.
• Set the hub's tariff plan to Home Assistant's currency — leave it on. The hub and Home Assistant must count in one currency, because nothing converts between them: the Energy dashboard simply labels the hub's numbers with its own currency. If the two ever differ, the panel's Tariff tab says so and offers a one-click fix.

When it finishes, the RBgrid Hub panel is in your sidebar (also at /rbgrid), the statistics import starts within a minute, and the Energy dashboard shows the hub after the next full hour, because those statistics are written a couple of minutes past each hour.

⚠️ No RBgrid card at all? mDNS does not reach Home Assistant on every network — a Docker bridge network is the usual case. Use Add integration → RBgrid instead: it lists the hubs the ESPHome integration already has. The same applies after you remove a hub: Home Assistant will not rediscover it by itself, so either restart it or use Add integration.

4. What you see after adoption, and why it looks sparse

A point is one named measurement — a circuit you define in the RBgrid panel, tied to a clamp on a module channel. A slot is the place that point occupies in Home Assistant. A hub exposes twelve measurement slots — the same twelve the hub keeps history for. Each slot's name is there from the start; the rest of a slot's entities appear once a point is bound to it, which you do on the panel's Points tab.

So what you see after adoption is twelve names, not twelve devices' worth of empty sensors. That is the third thing people read as a fault: an integration that added almost nothing. It added the structure; the entities arrive as you give the slots work to do.

Two consequences worth knowing before you start rearranging things:

• If you free a slot and give it to a different point, that slot's lifetime totals carry on from where they were — so Home Assistant's statistics can show a step at the changeover. The per-point series the integration imports is the clean view of it.
• One currency throughout. Whatever your tariff is in, every money entity is in.

The energy entities go straight onto the Energy dashboard: they are the cumulative kind it expects, so no template sensor or utility_meter is needed in between.

The four failures, in one place

What this doesn't do

• It does not make the hub need Home Assistant. This is one of two ways to run the same metering core; the other is the hub's own app. Switching between them later means reflashing and starting the history from zero, so it is worth choosing deliberately.
• It does not switch anything on or off. The hub measures and prices; automations decide.
• It does not give Home Assistant 15-minute resolution. The hub's periods are the hub's; what reaches Home Assistant's statistics is hourly.

Where to read more

• Run it inside Home Assistant — the reference for this route, including what the panel does.
• Two ways to run RBgrid, and how to choose — if you are not yet sure this is your route.
• Quick start — first power-up, the access point and its password.
• Market prices — day-ahead prices work on this route too.