rbAmp
PT
Loja
Docs
Atualizado · Editar no GitHub (Edit on GitHub)

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) e GPIO22 (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 para ct_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.
DANGER

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:

  1. 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.
  2. Ambiente virtual CLI local — para desenvolvimento e CI. Instale com pip install esphome num venv Python 3.11–3.13.

Configurar um venv (apenas via CLI)

Shell
# 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:

Shell
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)

YAML
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:

YAML
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/:

Shell
cd rbamp-esphome/example
esphome compile ui1.yaml
Segurança

⚠ 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).

YAML
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"
Nota

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):

YAML
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"

Passo 3 — Compilação

Shell
# from the example/ directory with the venv active
esphome compile ui1.yaml

O que acontece:

  1. O ESPHome descompacta external_components e carrega o pacote Python rbamp a partir de ../components.
  2. 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.
  3. O componente C++ compila e liga-se. Uma conclusão bem-sucedida tem este aspeto:
Text
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/ttyUSB0 ou /dev/ttyACM0.
Shell
esphome upload --device COM6 ui1.yaml             # Windows
esphome upload --device /dev/ttyUSB0 ui1.yaml     # Linux

Para o caminho do Add-on do HA:

  1. Abra o Home Assistant → Definições → Complementos → ESPHome. [Settings → Add-ons → ESPHome]
  2. Abra a interface web do add-on ESPHome.
  3. 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

Execute esphome logs para acompanhar o arranque em tempo real:

Shell
esphome logs ui1.yaml --device COM6

Um primeiro arranque saudável produz aproximadamente estas linhas (valores e tempos aproximados):

Text
[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:

Text
[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:

  1. O HA mostra uma notificação: Novos dispositivos descobertos.
  2. Definições (Settings) → Dispositivos e Serviços (Devices & Services) → ESPHome (ou clique na notificação).
  3. Selecione o novo nó (por exemplo rbamp-ui1).
  4. 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.
  5. 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: energy
  • state_class: total_increasing
  • unit_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

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

  1. 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).

  2. 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.

  3. 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

Text
[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

Com UI1@0x50 + I2@0x51 + I3@0x52 e fleet_gc_enable: true:

Text
[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


Fonte e problemas: rb-amp/rbamp-esphome · esta página no repositório: docs/05_quickstart.md (v1.9.1)