RBgrid no HACS como repositório personalizado

Tem um Home Assistant, ouviu dizer que o RBgrid pode correr dentro dele como dispositivo ESPHome, e fez o óbvio: abriu o HACS e pesquisou por ele.

Não apareceu nada. O que é correto, e não lhe diz nada sobre se a integração existe.

O RBgrid não está na lista predefinida do HACS. Enquanto não o adicionar você mesmo, a pesquisa não encontra nada — por isso o resultado que acabou de obter não é prova de ausência; é o primeiro passo esperado de um caminho que ninguém lhe explicou. Este artigo é esse caminho, com os pontos onde ele corre mal identificados em vez de escondidos.

Algo já correu mal? As falhas estão reunidas numa tabela no fim — sintoma, causa, o que fazer.

O que precisa antes de começar

Placa	um ESP32 com 16 MB de flash e PSRAM — um WROVER, ou um ESP32-S3 no módulo N16R8. A mesma placa do firmware autónomo.
Módulos	os seus módulos rbAmp e pinças de corrente, como habitualmente.
Home Assistant	2026.1 ou posterior, com HACS.
ESPHome	apenas se construir o componente na sua própria configuração YAML: 2026.5.3 ou posterior, com o framework ESP-IDF. Para gravar a imagem pronta não é necessário nada disto.

⚠️ A versão do Home Assistant é determinante, não uma recomendação. O painel do RBgrid depende de respostas de ações, que as versões mais antigas não têm. Numa versão mais antiga do Home Assistant o painel simplesmente não funciona — e o que vê parece uma integração avariada, e não uma instalação antiga. Se o painel estiver em branco, verifique isto primeiro.

1. Grave o hub

Transfira a imagem de fábrica para a sua placa das versões de rb-amp/rbgrid-esphome — há duas, uma para o ESP32-WROVER e outra para o ESP32-S3. Depois abra web.esphome.io no Chrome ou no Edge, escolha Connect, selecione a porta série da sua placa, escolha Install e selecione o ficheiro que transferiu.

O Home Assistant não lhe pede aqui uma chave de encriptação da API: a imagem pronta é construída sem uma, por isso o dispositivo é adicionado com uma única confirmação. Só se pede uma chave se tiver construído a sua própria configuração com uma.

Configure o Wi-Fi logo após a gravação, pelo mesmo cabo USB, quando o instalador o oferecer. Se o fizer, o hub nunca precisa do seu ponto de acesso de configuração. Se optar por passar pelo ponto de acesso, altere a respetiva palavra-passe assim que o hub for adotado.

O esptool também funciona: a imagem de fábrica é escrita no deslocamento 0x0.

⚠️ Isto diz respeito à sua própria compilação em YAML, não à imagem pronta. O componente traz uma tabela de partições com a aplicação em 0x20000, enquanto as ferramentas USB do próprio ESPHome assumem o padrão 0x10000. Se gravar por USB com as ferramentas do ESPHome — esphome run para uma porta série, ou Manual download → Factory format — a sua compilação fica no endereço errado e a placa não arranca nada de novo: uma placa em branco não sobe, e uma placa com uma imagem antiga continua discretamente a correr a versão antiga.

Para uma primeira instalação por USB, use a imagem de fábrica pronta da página de versões (já está fundida com os deslocamentos reais e vai para 0x0), ou o esptool com os deslocamentos do flasher_args.json da sua compilação. Quando o hub estiver na rede, coloque as suas próprias compilações nele pelo ar — esphome run com o hub acessível, ou Install → Wirelessly. Pelo ar só é enviada a aplicação, e o dispositivo coloca-a usando a sua própria tabela de partições, pelo que o deslocamento está certo por construção.

Este é o passo que falha em silêncio. Já está dentro da ferramenta do ESPHome, esta oferece-lhe um download em formato de fábrica, o ficheiro parece correto, a gravação tem sucesso — e a placa não faz nada depois. Não há erro que pesquisar, por isso costuma ser interpretada como hardware morto.

Ou construa-o na sua própria configuração

Se já mantém os seus dispositivos ESPHome como YAML, adicione o componente como fonte externa em vez de gravar uma imagem de fábrica:

yaml

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. Adicione o RBgrid no HACS como repositório personalizado

Este é o passo para o qual o resultado da pesquisa no topo deste artigo servia de substituto, e são três ações, não uma:

no HACS, adicione https://github.com/rb-amp/rbgrid-ha como repositório personalizado, categoria Integration;
instale RBgrid a partir dele;
reinicie o Home Assistant.

O reinício não é opcional nem uma superstição — uma integração recém-instalada só é carregada no arranque.

3. Configure primeiro o ESPHome, depois o RBgrid

Depois do reinício, Settings → Devices & services deve mostrar dois cartões: ESPHome (o próprio dispositivo) e RBgrid (esta integração).

Configure primeiro o do ESPHome. O cartão do RBgrid espera por ele, porque o RBgrid comunica com um dispositivo que o Home Assistant já conhece; se configurar pela ordem inversa, não tem a que se ligar.

Depois carregue em Configure no cartão do RBgrid. Pelo caminho, o ESPHome oferece a sua própria janela Name and assign, que lista o hub e as suas posições — carregue em Skip; os nomes vêm dos próprios pontos.

O último passo tem duas caixas de seleção que vale a pena ler em vez de passar por cima:

Configure the painel de energia with this hub — ativada por predefinição quando o seu painel de energia está vazio. É isto que coloca as entidades do hub no painel de energia.
Definir o plano tarifário do hub para a moeda do Home Assistant — deixe-a ativada. O hub e o Home Assistant têm de contar numa só moeda, porque nada faz a conversão entre elas: o painel de energia limita-se a rotular os números do hub com a sua própria moeda. Se alguma vez as duas diferirem, o separador Tariff do painel di-lo e oferece uma correção com um clique.

Quando terminar, o painel RBgrid Hub fica na sua barra lateral (também em /rbgrid), a importação das estatísticas começa dentro de um minuto, e o painel de energia mostra o hub a partir da hora seguinte, porque essas estatísticas são escritas alguns minutos depois de cada hora.

⚠️ Sem nenhum cartão RBgrid? O mDNS não chega ao Home Assistant em todas as redes — uma rede bridge do Docker é o caso habitual. Use Add integration → RBgrid em vez disso: lista os hubs que a integração ESPHome já tem. O mesmo se aplica depois de remover um hub: o Home Assistant não o redescobre sozinho, por isso ou reinicie-o ou use Add integration.

4. O que vê depois da adoção, e porque parece escasso

Um ponto é uma medição com nome — um circuito que define no painel do RBgrid, ligado a uma pinça num canal do módulo. Uma posição é o lugar que esse ponto ocupa no Home Assistant. Um hub expõe doze posições de medição — as mesmas doze para as quais o hub mantém histórico. O nome de cada posição existe desde o início; as restantes entidades de uma posição aparecem quando um ponto lhe fica associado, o que faz no separador Points do painel.

Portanto, o que vê depois da adoção são doze nomes, e não doze dispositivos de sensores vazios. É a terceira coisa que as pessoas leem como falha: uma integração que quase não acrescentou nada. Acrescentou a estrutura; as entidades chegam à medida que dá às posições trabalho a fazer.

Duas consequências que vale a pena conhecer antes de começar a reorganizar as coisas:

Se libertar uma posição e a der a um ponto diferente, os totais acumulados dessa posição continuam de onde estavam — por isso as estatísticas do Home Assistant podem mostrar um degrau na mudança. A série por ponto que a integração importa é a visão limpa disso.
Uma só moeda em tudo. Seja qual for a moeda da sua tarifa, todas as entidades monetárias estão nessa moeda.

As entidades de energia vão diretamente para o painel de energia: são do tipo acumulado que ele espera, pelo que não é preciso nenhum template sensor nem utility_meter pelo meio.

As quatro falhas, num só lugar

O que vê	O que é	O que fazer
A pesquisa no HACS não devolve nada	esperado — o RBgrid não está na lista predefinida	adicione-o como repositório personalizado, instale-o e reinicie (passo 2)
Nenhum cartão RBgrid aparece	o mDNS não chega ao Home Assistant — muitas vezes uma rede bridge do Docker	Add integration → RBgrid, que lista os hubs que o ESPHome já tem (passo 3)
A placa não faz nada depois de uma gravação bem-sucedida	a sua compilação foi por USB, onde o ESPHome assume `0x10000` e esta tabela de partições põe a aplicação em `0x20000`	grave a imagem de fábrica pronta, ou o `esptool` com os deslocamentos do `flasher_args.json` da sua compilação; coloque as compilações seguintes pelo ar (passo 1)
O painel está em branco, ou a integração parece avariada	Home Assistant anterior a 2026.1: o painel precisa de respostas de ações	atualize o Home Assistant
Depois da adoção, quase nenhuma entidade	doze nomes de posições ainda sem pontos associados	associe pontos no separador Points do painel; as entidades seguem (passo 4)

O que isto não faz

Não faz com que o hub precise do Home Assistant. Esta é uma de duas formas de correr o mesmo núcleo de medição; a outra é a aplicação própria do hub. Mudar entre elas mais tarde significa regravar e recomeçar o histórico do zero, por isso vale a pena escolher com deliberação.
Não liga nem desliga nada. O hub mede e valoriza; as automatizações decidem.
Não dá ao Home Assistant resolução de 15 minutos. Os períodos do hub são os do hub; o que chega às estatísticas do Home Assistant é horário.

Para saber mais

Corra-o dentro do Home Assistant — a referência deste percurso, incluindo o que o painel faz.
Duas formas de correr o RBgrid, e como escolher — se ainda não tem certeza de que este é o seu percurso.
Quick start — primeira ligação, o ponto de acesso e a sua palavra-passe.
Preços de mercado — os preços diários do mercado também funcionam nesta rota.