05 · Arranque rápido — do zero ao Home Assistant
Cerca de 5 minutos de trabalho manual, mais o tempo de compilação e gravação (a primeira compilação também descarrega a toolchain do ESP32, até ~15 minutos numa ligação lenta), levam-no de um ESP32 nu e um módulo rbAmp a sensores ativos no Home Assistant.
O que vai precisar
Hardware
- Placa ESP32 — qualquer placa com dois pinos I²C livres funciona. Os exemplos usam
GPIO21(SDA) eGPIO22(SCL) — os valores padrão da DevKitC. Se a sua placa for diferente, ajuste os números dos pinos no YAML. - Módulo rbAmp — qualquer SKU UI ou I. Para uma primeira execução, a UI1 é a mais fácil: uma tensão + um canal de corrente, o menor número de fios.
- Alimentação de 5 V para o rbAmp — o módulo funciona entre 4.5 e 5.5 V. A alimentação USB do ESP32 funciona se a placa expuser a linha de 5 V.
- Pinça de CT — uma pinça de corrente SCT-013 de núcleo dividido ligada à ficha de CT do módulo. Leia o calibre na etiqueta (por exemplo
SCT-013-030= 30 A); precisa dele paract_model:abaixo. - Ligação (lado de baixa tensão): VCC → +5 V, GND → GND, SDA → GPIO21, SCL → GPIO22. Não são necessárias resistências de pull-up externas para um único módulo (as de 4.7 kΩ integradas já estão na placa). Para o esquema completo, ver 04_hardware.md.
- Cablagem (lado da rede): a L e o N da rede ligam aos terminais L/N do módulo (para a leitura de tensão), e a pinça CT envolve apenas o condutor L, com a seta apontada para a carga. Ver 04_hardware.md e 03_sensor_selection.md.
os terminais L/N transportam tensão de rede. Desligue e bloqueie o circuito antes de ligar, faça com que uma pessoa qualificada trate da cablagem da rede e de qualquer trabalho dentro de um quadro, prenda APENAS UM condutor (L) e nunca deixe a pinça CT num condutor com a tomada CT desligada.
- Cabo USB do ESP32 para o computador para gravação.
Software
| Requisito | Nota |
|---|---|
| ESPHome ≥ 2025.3.0 | O componente usa a sintaxe moderna ota: (lista de plataformas) e o hashing de object-id do ESPHome 2025.x. Verificado até ao ESPHome 2026.5 e posteriores. |
| Python 3.11..3.13 para a CLI | A camada PlatformIO interna do ESPHome (penv) não aceita Python 3.14. Se usar o add-on do HA, este ponto não se aplica. |
| Home Assistant | Qualquer versão recente. A descoberta automática funciona via mDNS (Avahi / Bonjour). |
Dois caminhos de compilação:
- Add-on ESPHome do HA (recomendado para a maioria dos utilizadores) — coloque o YAML na pasta de configuração do add-on e clique em Compile. Não é necessário ambiente Python local.
- Ambiente virtual CLI local — para desenvolvimento e CI. Instale com
pip install esphomenum venv Python 3.11–3.13.
Configurar um venv (apenas via CLI)
# Windows PowerShell — adjust the Python path to your 3.11 / 3.13
& "C:\Python311\python.exe" -m venv .venv-esphome
.\.venv-esphome\Scripts\Activate.ps1
pip install esphome
esphome version # should print 2025.3.0 or newer
Em Linux / macOS:
python3.11 -m venv .venv-esphome
source .venv-esphome/bin/activate
pip install esphome
esphome version
Passo 1 — Localizar o componente
Existem duas formas para o bloco external_components — escolha uma consoante o seu ambiente.
Forma A — github (predefinido, funciona no add-on do HA)
external_components:
- source: github://rb-amp/rbamp-esphome@v1.9.0 # pin a release tag
components: [rbamp]
refresh: 1d # 1 day for production. If you track @main during
# development, change this to `0s`, otherwise ESPHome will
# cache the copy and ignore new commits.
Esta forma é a única que funciona no Add-on ESPHome do HA (o Add-on não tem acesso de shell a diretorias irmãs). É também cómoda para a CLI: não é preciso clonar nada localmente.
Forma B — caminho local (para desenvolvimento)
Se clonou rb-amp/rbamp-esphome e trabalha diretamente com as fontes do componente, aponte o ESPHome para um caminho local:
external_components:
- source:
type: local
path: /absolute/path/to/rbamp-esphome/components
components: [rbamp]
Em example/ui1.yaml o bloco já está configurado para um caminho relativo (../components), que funciona quando executa esphome compile a partir da diretoria example/:
cd rbamp-esphome/example
esphome compile ui1.yaml
⚠ Um caminho local não funciona no add-on do HA — o add-on mantém o YAML em /config/esphome/ sem acesso de shell ao resto do sistema de ficheiros. Os utilizadores do add-on escolhem a forma A.
Passo 2 — Criar o YAML
Copie example/ui1.yaml como ponto de partida (usa a forma B de caminho local; a listagem abaixo usa a forma A, para funcionar também no Add-on). Abra-o em qualquer editor e preencha as credenciais WiFi e o nome do dispositivo. O ficheiro completo é mostrado abaixo com comentários linha a linha.
Regra: power, energy, power_factor, reactive_power e apparent_power requerem voltage E current declarados no mesmo bloco sensor: (adicione internal: true a um sensor que não queira como entidade do Home Assistant); caso contrário, esphome config para com "power requires current to also be declared". O mesmo aplica-se aos sensores de canal numerados (power_1 precisa de current_1 e voltage).
esphome:
name: rbamp-ui1 # node name — sets the mDNS hostname (rbamp-ui1.local)
esp32:
board: esp32dev # your board (e.g. nodemcu-32s, lolin_d32)
framework:
type: arduino # arduino or esp-idf — both work with the component
logger:
level: DEBUG # DEBUG shows I²C reads; after the first run you can use INFO
wifi:
ssid: !secret wifi_ssid # see secrets.yaml below
password: !secret wifi_password
ap:
ssid: "rbAmp UI1 Fallback" # fallback AP if the connection fails
password: !secret ap_password
captive_portal: # config page on the fallback AP
api: # Home Assistant native API on port 6053
# encryption:
# key: "BASE64_KEY" # optional — see 08_has_integrations.md
ota:
- platform: esphome # over-the-air updates
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # IMPORTANT: 100 kHz causes intermittent NACKs from the module;
# 50 kHz reduces them ~5-10x (see 10 · troubleshooting → NACK-discipline)
scan: true # logs every I²C address found at boot
external_components:
- source: github://rb-amp/rbamp-esphome@v1.9.0 # works in the HA Add-on and the CLI
components: [rbamp]
# Working from a local clone instead? Use Form B above.
rbamp:
id: meter1
address: 0x50 # factory default address
update_interval: 60s # how often to close the period and publish sensors
# minimum 1 s (v1.3); below this → cv.Invalid
ct_model: SCT_013_030 # CT clamp model — change it to match yours
# (SCT_013_005 / _010 / _020 / _030 / _050 / _060 / _100)
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage" # entity ID in HA: sensor.rbamp_ui1_mains_voltage
current:
name: "Mains Current"
power:
name: "Mains Power"
energy:
name: "Mains Energy" # state_class: total_increasing — ready for the Energy dashboard
frequency:
name: "Mains Frequency"
power_factor:
name: "Mains Power Factor"
A chave ct_model: carrega os coeficientes de fábrica do modelo de pinça escolhido. Se não tiver uma SCT-013-030, altere para o modelo que tem. Para mais sobre a escolha, ver 03_sensor_selection.md.
secrets.yaml
Crie secrets.yaml na mesma pasta que o YAML (fica excluído pelo .gitignore por predefinição em example/.gitignore, para que as credenciais não vazem para um commit):
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"
Passo 3 — Compilação
# from the example/ directory with the venv active
esphome compile ui1.yaml
O que acontece:
- O ESPHome descompacta
external_componentse carrega o pacote Pythonrbampa partir de../components. - O PlatformIO descarrega a plataforma ESP32 na primeira execução (~1–2 GB, em cache). Este é o passo mais lento — até 15 minutos numa ligação lenta.
- O componente C++ compila e liga-se. Uma conclusão bem-sucedida tem este aspeto:
SUCCESS Took 58.71 seconds
Wrote .esphome/build/rbamp-ui1/.pioenvs/rbamp-ui1/firmware.factory.bin
Se a compilação falhar com Error: Failed to install Python dependencies, o host está muito provavelmente a correr Python 3.14. Use o add-on do HA ou um venv com 3.11 / 3.13 (ver "O que vai precisar"). Trata-se de uma incompatibilidade entre o resolvedor uv do PlatformIO e certos modelos de CPU, não de um erro do componente.
Passo 4 — Primeira gravação
esphome upload grava o binário por USB. Primeiro, encontre a porta correta:
- Windows: Gestor de Dispositivos → Portas (COM e LPT). Normalmente
COM3–COM9. - Linux / macOS:
ls /dev/tty*— normalmente/dev/ttyUSB0ou/dev/ttyACM0.
esphome upload --device COM6 ui1.yaml # Windows
esphome upload --device /dev/ttyUSB0 ui1.yaml # Linux
Para o caminho do Add-on do HA:
- Abra o Home Assistant → Definições → Complementos → ESPHome. [Settings → Add-ons → ESPHome]
- Abra a interface web do add-on ESPHome.
- Encontre o seu dispositivo (ou clique em "New Device") → Install → Ligue a este computador.
A ferramenta de gravação (esptool.py por dentro) reinicia o ESP32 automaticamente após a escrita. O tempo total de gravação costuma ser de 30–60 segundos.
Passo 5 — O que esperar no log de arranque
4.7 Espelhos de verificação do modelo de TC (0x51..0x53) (api-reference) · 8.10 Releitura do espelho de verificação do modelo de TC (sanidade pós-associação) (api-reference)
Execute esphome logs para acompanhar o arranque em tempo real:
esphome logs ui1.yaml --device COM6
Um primeiro arranque saudável produz aproximadamente estas linhas (valores e tempos aproximados):
[D][i2c]: Found i2c device at address 0x50
[C][rbamp]: Setting up rbAmp at 0x50 ...
[C][rbamp]: Firmware version: 0x04
[C][rbamp]: Variant: UI1
[C][rbamp]: UID: 0x1A2B3C4D5E6F708192A3
[C][rbamp]: sensor_class: matches → skipped (nothing to write)
[C][rbamp]: ct_model[0]: matches → skipped (nothing to write)
[C][rbamp]: rbAmp:
[C][rbamp]: Address: 0x50
[C][rbamp]: Firmware version: 1.3
[C][rbamp]: Topology: SINGLE, channels: 1, voltage: yes
[C][rbamp]: Bidirectional: NO
[C][rbamp]: Wh persistence: NVS every 300s
[C][component]: Setup rbamp took 67ms
A linha i2c: scan: true aparece antes das linhas dos componentes e confirma que o módulo está fisicamente visível no barramento. Se Found i2c device at address 0x50 estiver em falta, veja a secção "O que fazer se" abaixo.
Dentro de um update_interval (60 s por predefinição) aparecem as publicações dos sensores — aguarde cerca de 60 s, ou defina update_interval: 5s durante os testes:
[D][sensor]: 'Mains Voltage': Sending state 226.70 V
[D][sensor]: 'Mains Current': Sending state 0.755 A
[D][sensor]: 'Mains Power': Sending state 92.80 W
[D][sensor]: 'Mains Power Factor': Sending state 0.542
[D][sensor]: 'Mains Frequency': Sending state 50.0 Hz
[D][sensor]: 'Mains Energy': Sending state 0.026 Wh
Valores de referência na bancada com um SKU UI1 e uma carga indutiva: U ≈ 225 V, I ≈ 0.78 A, P ≈ 110 W, PF ≈ 0.62. Os valores exatos dependem da carga ligada.
Passo 6 — Descoberta no Home Assistant
mDNS (automático)
O HA encontra os nós ESPHome com um bloco api: configurado por si próprio, na mesma rede local. Em 30–60 segundos após o primeiro arranque do ESP32:
- O HA mostra uma notificação: Novos dispositivos descobertos.
- Definições (Settings) → Dispositivos e Serviços (Devices & Services) → ESPHome (ou clique na notificação).
- Selecione o novo nó (por exemplo
rbamp-ui1). - Introduza o IP local do dispositivo (visível nos registos como
[I][wifi]: IP: 192.168.0.xxx) se o HA não o tiver encontrado por si. - Add.
Todas as entidades de sensores são registadas de imediato. O entity ID segue o padrão sensor. (espaços substituídos por sublinhados, tudo em minúsculas). Para o YAML acima: sensor.rbamp_ui1_mains_voltage, sensor.rbamp_ui1_mains_energy, e assim por diante.
Adição manual (se o mDNS estiver bloqueado)
Definições → Dispositivos e Serviços → Adicionar integração → ESPHome → endereço IP e porta da API (6053). Se for definida uma chave em api: encryption: key:, introduza-a quando for pedida.
Painel de Energia
O sensor energy já está configurado para a Energia do HA:
device_class: energystate_class: total_increasingunit_of_measurement: Wh
Definições (Settings) → Painéis (Dashboards) → Energia (Energy) → Adicionar consumo (Add Consumption) → selecione "Mains Energy". O HA começa imediatamente a acompanhar o consumo acumulado.
Passo 7 — Escalar para uma frota (implementação canónica multi-módulo)
Uma única UI1 na rede dá os totais da casa inteira. Para obter a decomposição por sub-ramais (caldeira, ar condicionado, VE), adicione módulos I2/I3 no mesmo barramento I²C. Esta é a implementação canónica de 80% (ver 01_overview.md).
Extensão mínima do YAML
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
# external_components: ... as in Step 1
rbamp:
- id: mains_meter
address: 0x50
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true # NEW v1.3 — capability-gated GC snapshot
group_id: 1 # cluster id
- id: boiler_meter # I2 sub-meter, address 0x51 after provisioning
address: 0x51
sensor_class: SCT_013
ct_models: [SCT_013_020, SCT_013_010] # 20A boiler + 10A washing machine
fleet_gc_enable: true
group_id: 1 # same group → synchronized snapshots
- id: panel_meter # I3 sub-meter, address 0x52
address: 0x52
sensor_class: SCT_013
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020] # mixed CT sizes
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: mains_meter
voltage: { name: "Mains Voltage" }
current: { name: "Mains Current" }
power: { name: "Mains Power" }
energy: { name: "Mains Energy" }
- platform: rbamp
rbamp_id: boiler_meter
current: { name: "Boiler Current" } # SCT_013_020 channel 0
current_1: { name: "Washer Current" } # SCT_013_010 channel 1
- platform: rbamp
rbamp_id: panel_meter
current: { name: "Lighting Current" } # SCT_013_005 channel 0
current_1: { name: "Appliances Current" } # SCT_013_030 channel 1
current_2: { name: "Sub-panel Current" } # SCT_013_020 channel 2
O que fazer antes do primeiro arranque
-
Provisionamento de endereços — todos os módulos saem de fábrica em 0x50. Veja 04_hardware.md Confirmação de endereço em duas fases para o procedimento sequencial (um virgem de cada vez no barramento).
-
Pull-ups — siga a tabela de pull-ups em 04_hardware.md Barramento multi-módulo. Para 3 módulos: corte os jumpers de pull-up em todos eles e acrescente um par externo de 2.7–3.3 kΩ (SDA e SCL para 3.3 V) no ESP32.
-
Alimentação externa de 5 V — 3 módulos × ~15 mA = ~45 mA + ESP32 ~200 mA. O VBUS do USB costuma chegar para o arranque; para uma implementação de produção use uma SMPS de 5 V separada.
O que esperar no log após o arranque
[D][i2c]: Found i2c device at address 0x50
[D][i2c]: Found i2c device at address 0x51
[D][i2c]: Found i2c device at address 0x52
[C][rbamp]: rbAmp 0x50: variant=UI1, fleet_gc=on, group=1
[C][rbamp]: rbAmp 0x51: variant=I2, fleet_gc=on, group=1
[C][rbamp]: rbAmp 0x52: variant=I3, fleet_gc=on, group=1
[I][rbamp]: GC latch enabled fleet-wide: 3 modules in group 1
Verificação de sincronização
6.3 Snapshot de difusão GC — sincronização de frota por adesão (api-reference) · 8.4 Snapshot de difusão GC + recuo de testemunha (api-reference)
Com UI1@0x50 + I2@0x51 + I3@0x52 e fleet_gc_enable: true:
[D][rbamp]: GC frame emit: group=1, tick=42, all 3 modules ACK'd
[D][rbamp]: check_sync(tick=42) → 3/3 in_sync ; fleet in sync
Veja a secção de frota em 09_api_reference.md para a emissão programática e a verificação de sincronização através de serviços da API nativa.
O que fazer se
| Sintoma | Causa provável | O que fazer |
|---|---|---|
Found i2c device at address 0x50 em falta |
Módulo sem alimentação ou mal ligado, pinos GPIO errados | Verifique VCC (deve ser 4.5–5.0 V), GND, SDA / SCL; confirme que os jumpers de pull-up do módulo estão intactos |
Probe failed at 0x50 nos logs |
O módulo está visível no scan mas não responde às leituras de registos | Verifique frequency: 50kHz no YAML; confirme que o módulo não está a meio de uma escrita em flash (~700 ms) |
| Os sensores leem 0 ou NaN | O módulo ainda está a arrancar; durante os primeiros ~250 ms após ligar os registos leem 0 | Aguarde o primeiro ciclo update_interval; o componente salta a leitura até o registo de estado estar pronto |
| O HA não encontra o dispositivo | mDNS bloqueado pelo router / VLAN; bloco api: em falta |
Adicione api:; tente a adição manual por IP |
Aviso update() took 406ms |
O componente recuou do caminho de leitura em rajada da v1.3 para leituras por registo (4 transações × 9 floats a 50 kHz) | Não é um problema; verifique se a versão do firmware é 0x04 e se os pull-ups do barramento seguem a tabela de 04_hardware.md (puxados para 3.3 V limpos) — um ciclo v1.3 saudável fica abaixo de 30 ms |
| Recua para o modo AP | SSID / palavra-passe errados; AP fora de alcance | Verifique o secrets.yaml; aproxime-se do AP; 2.4 GHz vs 5 GHz |
Para problemas que não constem desta lista, ver 10_troubleshooting.md.
O que vem a seguir
- Configuração de três canais: 06_examples.md — YAML do UI3 com três canais de corrente independentes e todas as grandezas derivadas.
- Vários módulos no mesmo barramento: 06_examples.md — a secção de multi-módulo.
- Um aprofundamento sobre o Energia do HA: 08_has_integrations.md.
- Integrações DIY (Grafana, MQTT, automatismos): 07_diy_integrations.md.
- Referência completa de configuração: 09_api_reference.md.
- Diagnosticar problemas durante a sua primeira execução com o rbAmp: 10_troubleshooting.md.
Fonte e problemas: rb-amp/rbamp-esphome · esta página no repositório: docs/05_quickstart.md (v1.9.1)