rbAmp
PT
Loja
Docs
Atualizado a · Editar no GitHub

06 · Livro de receitas YAML

Este capítulo abre com os cenários emblemáticos — os padrões de implementação reais para os quais o componente foi desenhado na v1.3 (rede + N sub-cargas num barramento com sincronização fleet_gc_enable, fluxo de provisionamento, CT misto multicanal, sincronização GC da frota). Seguem-se os cenários de módulo único, de um UI1 mínimo até uma implementação de produção com automações no HA.

Cada exemplo é autónomo: copie-o, preencha o nome da sua placa e as credenciais Wi-Fi, compile e grave. Sempre que um exemplo se afaste do modelo mínimo, uma explicação indica porquê.

Cross-references:

  • Esquema do componente, mapa de registos, protocolo de medição por período, topologia multi-módulo, sincronização GC da frota e a regra de sanidade permissiva do NACK: 09 · Referência da API
# Cenário Topologia Quando usar
1 Rede + N subcargas: o cânone dos 80 % UI1 + N× I2/I3 Medição da casa inteira com decomposição por sub-ramais
2 Fluxo de provisionamento (virgem → frota) sequencial simples Arranque de um novo lote de módulos
3 CT misto multicanal (UI3 com pinças diferentes) UI3 Medição de cargas mistas com otimização de precisão
4 Sincronização GC da frota (sincronia apertada) N× UI/I Clusters multi-inquilino e submedição
5 UI1 — canal único (mínimo) UI1 Olá mundo com um único módulo
6 UI1 com personalização UI1 Todos os ajustes padrão do ESPHome
7 UI3 — três canais com pinças mistas UI3 Módulo único multi-canal
8 Barramento com vários módulos (sincronização GC) N× UI/I fleet_gc_enable + group_id em três módulos
9 Alteração única de endereço I²C único Provisionar um módulo único
10..20 Integrações e automatismos do HA misto Padrões de implementação em produção
21 Módulo STANDARD (STD) — totais de energia no dispositivo qualquer Totais gerais, energia reativa, start_current_ua:
22 Mudar o calibre SCT, ct_model_force qualquer Mudança de calibre sem perder precisão
Nota

Os cenários 1-4 são os principais, dirigidos à implementação canónica da v1.3 do pacote. O seu código usa fleet_gc_enable + superfície de identidade + leitura-comparação-escrita e é exercitado numa montagem heterogénea UI1+I2+I3. Os cenários 5-22 são padrões de módulo único e compactos. O cenário 8 é a configuração compacta de barramento com três módulos.


1 · Rede + N sub-cargas (o cânone dos 80%) — sistema de medição integrado

Objetivo: a implementação canónica do pacote — um sistema de medição coerente numa frota heterogénea, fechado num único arranque do ESPHome (descoberta → configurar → ativar GC → loop[publish_state + tick GC de emissão automática]).

Hardware (montagem de teste UI1 + I2 + I3): UI1@0x50 + I2@0x51 + I3@0x52; carga de ~0.58 A; pull-ups conforme a linha de 3 módulos da tabela de 04_hardware.md (corte todos, um par externo de 2.7–3.3 kΩ).

YAML
esphome:
  name: home-fleet

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:
  level: INFO

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
ota:
  - platform: esphome

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

# Three rbAmp modules on shared bus, all with fleet_gc_enable + group_id=1
# for synchronized period snapshots (tight sync between mains + sub-meters).
rbamp:
  - id: mains_meter         # UI1 on the mains feed
    address: 0x50
    sensor_class: SCT_013
    ct_model: SCT_013_030
    fleet_gc_enable: true
    group_id: 1

  - id: boiler_meter        # I2 on the boiler + washing machine
    address: 0x51
    sensor_class: SCT_013
    ct_models: [SCT_013_020, SCT_013_010]
    fleet_gc_enable: true
    group_id: 1

  - id: panel_meter         # I3 on the distribution-panel branches
    address: 0x52
    sensor_class: SCT_013
    ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
    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", id: mains_power_state }
    power_factor: { name: "Mains PF" }
    energy:       { name: "Mains Energy" }
    frequency:    { name: "Mains Frequency" }

  - platform: rbamp
    rbamp_id: boiler_meter
    # I2 is a current-only module: it has no voltage input, so it reports currents only
    # (power and energy need a UI module with voltage).
    current:   { name: "Boiler Current" }       # 20A CT
    current_1: { name: "Washer Current" }       # 10A CT

  - platform: rbamp
    rbamp_id: panel_meter
    current:   { name: "Lighting Current" }     # 5A CT
    current_1: { name: "Appliances Current" }   # 30A CT
    current_2: { name: "Sub-panel Current" }    # 20A CT

  # Optional: template sensor for the household power (same sensor: list, not a second sensor: key)
  - platform: template
    name: "Household Total Power"
    update_interval: 60s
    accuracy_decimals: 0
    unit_of_measurement: "W"
    device_class: power
    lambda: |-
      // Sum of power from the mains meter only (sub-meters are a subset of the same mains)
      auto v = id(mains_power_state);
      return v.has_state() ? v.state : 0.0f;

Exemplo de saída (carga de ~0.58 A)

Text
[I][i2c:136]: Found i2c device at address 0x50
[I][i2c:136]: Found i2c device at address 0x51
[I][i2c:136]: Found i2c device at address 0x52
[C][rbamp:450]: mains_meter:  variant=UI1, capability=0x…, fleet_gc=on, group=1
[C][rbamp:450]: boiler_meter: variant=I2,  capability=0x…, fleet_gc=on, group=1
[C][rbamp:450]: panel_meter:  variant=I3,  capability=0x…, fleet_gc=on, group=1
[I][rbamp:493]: GC latch enabled fleet-wide: 3 modules in group 1

ITER 1 @ 60s: GC tick=1, 3/3 in_sync
  mains:   V=232.6  I=5.79  P=1259 W   E_total: 0 → 0.35 Wh
  boiler:  I=[11.58, 3.87]                                ; current-only
  panel:   I=[3.84, 2.55, 5.84]                           ; current-only

Notas de utilização

  • Um ciclo sincronizado — o sistema inteiro. A cada tick de update_interval, o ESP32 emite uma trama GC para 0x00 → os 3 módulos tiram um instantâneo dos seus acumuladores de período no mesmo instante do fio (validado 3/3 in_sync sob carga).

  • mains_power numa frota heterogénea = a potência ativa de UI1 (mains_meter). Os subcontadores (I2/I3) medem apenas corrente, sem P canónica. No cânone 80%, mains_power ≈ a potência total de todas as cargas (mains_meter cobre a alimentação).

  • As Wh nos módulos BASIC são integradas no ESP32 com o seu próprio relógio (o tempo entre instantâneos), por isso todos os módulos da frota partilham uma base de tempo. Os módulos STANDARD mantêm os seus próprios contadores de energia, que o componente acumula.

  • Resiliente a falhas (MISS). Se um módulo sair do barramento (provisionamento / corte de energia), os restantes continuam a funcionar; o HA mostra "Unavailable" para as suas entidades até recuperar.


2 · Fluxo de provisionamento (virgem → frota)

Objetivo: o procedimento de arranque canónico para módulos novos, desde o 0x50 de fábrica até endereços únicos da frota. Demonstra a confirmação de endereço em duas fases (v1.3, pronto para produção) e a disciplina obrigatória de "um virgem de cada vez no barramento".

Passo 2.1 — provisionar a rede da UI1 (0x50 → 0x50, sensor_class + ct_model)

YAML
# Connect ONLY the UI1 to the bus. Flash this YAML.
rbamp:
  - id: provisioning_target
    address: 0x50
    # new_address not needed — 0x50 is already fine for UI1
    sensor_class: SCT_013
    ct_model: SCT_013_030
    fleet_gc_enable: true
    group_id: 1

sensor:
  - platform: rbamp
    rbamp_id: provisioning_target
    voltage:      { name: "Provision UI1 Voltage" }
    current:      { name: "Provision UI1 Current" }

text_sensor:
  - platform: template
    name: "Provision UI1 variant"
    update_interval: 5s
    lambda: 'return id(provisioning_target).get_variant_str();'
  - platform: template
    name: "Provision UI1 UID"
    update_interval: 5s
    lambda: 'return id(provisioning_target).get_uid_hex();'
  - platform: template
    name: "Provision UI1 capability"
    update_interval: 5s
    lambda: 'return id(provisioning_target).get_capability_hex();'

Verificação: no HA deve ver sensor.provision_ui1_variant == "UI1" + sensor.provision_ui1_capability a mostrar um bitmap hex não nulo ("0x0000" significa firmware antigo). Registe o UID para o inventário.

Passo 2.2 — provisionar I2 (0x50 → 0x51 via commit em duas fases)

Desligue o UI1 do barramento (caso contrário haverá conflito de endereço). Ligue o módulo I2. Grave o YAML atualizado:

YAML
rbamp:
  - id: provisioning_target
    address: 0x50            # virgin address
    new_address: 0x51        # ⚠ two-phase commit — production-OK on v1.3
    sensor_class: SCT_013
    ct_models: [SCT_013_020, SCT_013_010]
    fleet_gc_enable: true
    group_id: 1

O que acontece no arranque:

Text
[I][rbamp:xxx]: provisioning_target: probe at 0x50 → OK (variant=I2)
[I][rbamp:xxx]: provisioning_target: new_address=0x51 requested
[I][rbamp:xxx]: provisioning_target: two-phase address change supported → production path
[D][rbamp:xxx]: provisioning_target: stage REG_I2C_ADDRESS=0x51
[D][rbamp:xxx]: provisioning_target: write REG_ADDR_COMMIT_MAGIC=0xA5
[D][rbamp:xxx]: provisioning_target: send CMD_COMMIT_ADDR → wait 700ms
[I][rbamp:xxx]: provisioning_target: re-probe 0x51 → OK, re-enumeration complete
[I][rbamp:xxx]: provisioning_target: i2c address handle updated to 0x51

Após o êxito: atualize o YAML para address: 0x51 e remova new_address:. O próximo arranque não executará o fluxo de alteração.

Passo 2.3 — provisionar I3 (0x50 → 0x52) + repetir para os restantes

Mesmo padrão que 2.2: desligue o I2, ligue o I3 virgem, grave o YAML com new_address: 0x52, aguarde a reenumeração e atualize o YAML para address: 0x52.

Nota

🛑 OBRIGATÓRIO: um módulo virgem de cada vez no barramento. Se dois módulos virgens estiverem ambos em 0x50, ambos responderão na fase de endereço e puxarão o SDA um contra o outro → estado indeterminado, e nenhum procedimento de provisionamento funcionará.

Passo 2.4 — montar a frota

Quando o provisionamento de todos os módulos estiver concluído, atualize o YAML para a configuração final da frota (ver o cenário §1 acima), desligue os pull-ups internos em todos os módulos (3 módulos = corte todos) e acrescente um par externo de 2.7–3.3 kΩ no ESP32 — ver a tabela de pull-ups em 04_hardware.md. Grave o YAML final — todos os módulos devem ser descobertos:

Text
[D][i2c:136]: Found i2c device at address 0x50
[D][i2c:136]: Found i2c device at address 0x51
[D][i2c:136]: Found i2c device at address 0x52

Modos de falha (provisionamento)

Sintoma Causa Recuperação
Probe failed at 0x50 após gravação Módulo sem alimentação ou contacto partido Verifique a conectividade de VCC + GND + SDA + SCL
[W] alteração de endereço em duas fases não suportada Módulo com firmware legado (v1.0-v1.2) O fallback monofásico requer o modo de provisionamento de fábrica (ver 04_hardware.md)
[E] address change committed but re-probe at 0x51 failed Barramento marginal ou commit abortado Repita o arranque; se se repetir, o pull-up externo é demasiado fraco ou há uma rajada de EMI
[W] WARN_FACTORY_MODE_REQUIRED Firmware legado sem alteração de endereço em duas fases O fornecedor ativa o modo de fábrica (fora do âmbito da biblioteca)

3 · CT misto multicanal (UI3 com pinças diferentes)

Objetivo: mostrar que o modelo de CT em diferentes canais de um único módulo pode ser misto, conforme a característica da carga. O componente associa os canais um a um; a ordem não importa.

YAML
rbamp:
  - id: panel_meter
    address: 0x52
    sensor_class: SCT_013
    # Mixed-CT: small/medium/large on channels 0/1/2
    ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
    # The component binds channels one by one; the order does not matter.
    # Each channel keeps its own model: ch0 = 5 A, ch1 = 30 A, ch2 = 20 A
    fleet_gc_enable: true
    group_id: 1

sensor:
  - platform: rbamp
    rbamp_id: panel_meter
    current:    { name: "Panel Lighting (5A CT)" }       # ch0
    current_1:  { name: "Panel Appliances (30A CT)" }    # ch1
    current_2:  { name: "Panel Boiler (20A CT)" }        # ch2
    # No voltage / power — this is an I3 SKU, current-only

text_sensor:
  - platform: template
    name: "Panel last error"
    update_interval: 30s
    lambda: 'return id(panel_meter).get_last_error_str();'
    # → "OK" in a healthy state; "ERR_PARAM" if a CT model code is rejected

Verificar a associação do CT no arranque

Após gravação e arranque, no log:

Text
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH0 mirror = 1 (SCT_013_005)
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH1 mirror = 3 (SCT_013_030)
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH2 mirror = 6 (SCT_013_020)
[I][rbamp:xxx]: panel_meter: CT binding verified, all mirrors match YAML request
[C][component:246]: Setup panel_meter took ~2100ms (cold install: 3 × 700ms flash + verify)

Num arranque a quente (os espelhos coincidem), sem escrita na flash:

Text
[I][rbamp:xxx]: panel_meter: CT_MODEL[0..2] match YAML → SKIP flash erase
[C][component:246]: Setup panel_meter took 72ms (warm boot: read-compare only)

Comportamento observado

  • Vinculação CT mista: códigos [1, 3, 6] num módulo de três canais em 0x52 ficam cada um no seu canal.
  • Rejeição de código inválido: uma tentativa de código fora do conjunto aceite pela classe → esphome config rejeita o esquema (cv.Invalid). Se o YAML passar pelo validador (edição manual / build antiga), a firmware devolve REG_ERROR = 0xFE DEV_ERR_PARAM, mantendo o espelho no valor anterior.

  • Tempo de instalação a frio: ~2.1 s na UI3 (3 × ~700 ms de apagamento de flash).

  • Tempo de arranque a quente: ~70 ms (a leitura-comparação-escrita salta todo o apagamento de flash).
  • Medição de latência: ~1.4 s desde o início de setup() até à primeira publicação (bancada).

4 · Sincronização GC da frota (sincronia apertada)

Objetivo: mostrar que a sincronização de frota 3/3 não é académica, mas um requisito real para implementações multi-inquilino (subcontagem de apartamentos num quadro partilhado) e para subcontagem precisa (a rede da UI1 tem de corresponder à soma das potências dos subcontadores dentro da duração de um único período).

YAML
# Fleet config — all modules in one group for synchronized snapshots:
rbamp:
  - id: tenant1_mains
    address: 0x50
    sensor_class: SCT_013
    ct_model: SCT_013_030
    fleet_gc_enable: true
    group_id: 1

  - id: tenant1_panel
    address: 0x51
    sensor_class: SCT_013
    ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
    fleet_gc_enable: true
    group_id: 1

  - id: tenant2_mains       # Independent tenant (separate group)
    address: 0x52
    sensor_class: SCT_013
    ct_model: SCT_013_030
    fleet_gc_enable: true
    group_id: 2             # ⚠ different group → independent sync timeline

# Native API services for manual sync verification:
api:
  port: 6053
  services:
    - service: emit_gc_tenant1
      then:
        - lambda: 'id(tenant1_mains).transmit_gc_frame();'  # group = tenant1_mains group_id
    - service: emit_gc_tenant2
      then:
        - lambda: 'id(tenant2_mains).transmit_gc_frame();'  # group = tenant2_mains group_id
    - service: check_sync_all
      then:
        - lambda: |-
            uint16_t t1m = id(tenant1_mains).read_gc_tick_received();
            uint16_t t1p = id(tenant1_panel).read_gc_tick_received();
            uint16_t t2m = id(tenant2_mains).read_gc_tick_received();
            ESP_LOGI("rbamp", "GC tick state: tenant1[mains=%u, panel=%u]  tenant2[mains=%u]",
                     t1m, t1p, t2m);

text_sensor:
  - platform: template
    name: "Tenant1 GC tick (mains)"
    update_interval: 30s
    lambda: 'return std::to_string(id(tenant1_mains).read_gc_tick_received());'
  - platform: template
    name: "Tenant1 GC tick (panel)"
    update_interval: 30s
    lambda: 'return std::to_string(id(tenant1_panel).read_gc_tick_received());'

Exemplo de saída (teste de sincronização de 10 iterações)

Text
[I][rbamp:572]: GC frame emit: group=1, tick=42, all 2 tenant1 modules ACK'd
[I][rbamp:580]: check_sync: tenant1_mains.tick=42  tenant1_panel.tick=42  → 2/2 in_sync
[I][rbamp:572]: GC frame emit: group=2, tick=42, tenant2 module ACK'd
[I][rbamp:580]: check_sync: tenant2_mains.tick=42  → 1/1 in_sync (tenant2 isolated)

ROUND 0: GC tick=1   →  tenant1[1, 1]  tenant2[1]   → 3/3 in_sync
ROUND 1: GC tick=2   →  tenant1[2, 2]  tenant2[2]   → 3/3 in_sync
ROUND 2: GC tick=3   →  tenant1[3, 3]  tenant2[3]   → 3/3 in_sync
...
ROUND 9: GC tick=10  →  tenant1[10,10] tenant2[10]  → 3/3 in_sync

L8 soak: 180 cycles, 0 sync drops, 0 identity drops

Como o group_id ajuda em multi-inquilino

Sem group_id não há separação de inquilinos — todos os módulos reagem a qualquer trama GC. Com group_id:

  • Os módulos do inquilino 1 respondem apenas a tramas GC com group=1 (ou ao all-call group=0)
  • Os módulos do inquilino 2 respondem apenas a tramas GC com group=2

Isto permite ao mestre emitir tramas GC separadas para os inquilinos em momentos independentes — por exemplo, por período de inquilino:

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
automation:
  - alias: "Tenant 1 period snapshot"
    trigger:
      platform: time_pattern
      seconds: "/60"            # every 60 s
    action:
      - service: esphome._emit_gc_tenant1

  - alias: "Tenant 2 period snapshot"
    trigger:
      platform: time_pattern
      seconds: "/15"            # every 15 s (high-resolution tenant)
    action:
      - service: esphome._emit_gc_tenant2

Validação em produção

  • Sensor template do HA"mains_minus_subsum" — um indicador de discrepância:
    YAML
    sensor:
      - platform: template
        name: "Mains - SubSum (W)"
        update_interval: 60s
        unit_of_measurement: "W"
        lambda: |-
          // here the sub-meters are current-only, so this is a rough estimate:
          // mains_power - sum(sub_currents × V_mains)
          float v_mains = id(mains_voltage_state).state;
          float sub_i = id(sub_i0).state + id(sub_i1).state + id(sub_i2).state;
          return id(mains_power_state).state - sub_i * v_mains;
    

Uma discrepância < 1% de mains_power na bancada = sincronização correta.

  • Integração pelo relógio de parede — mesmo com sincronização GC 3/3, os módulos BASIC são integrados com o relógio do próprio ESP32, pelo que uma pequena diferença entre módulos não distorce os Wh.

5 · UI1 — canal único (mínimo)

Fonte: ../example/ui1.yaml

A configuração mais simples e útil: um canal de tensão, um canal de corrente e seis grandezas derivadas delas. Um ponto de partida para qualquer nova implementação — amplie-a com mais campos conforme necessário.

YAML
esphome:
  name: rbamp-ui1

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:
  level: DEBUG

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "rbAmp UI1 Fallback"
    password: !secret ap_password

captive_portal:
api:
ota:
  - platform: esphome

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz    # recommended on ESP32; 100 kHz causes periodic NACKs due to ESP-IDF i2c_master driver interaction;
                      # 50 kHz reduces them ~5-10× — see the chapter end link.
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

rbamp:
  id: meter1
  address: 0x50
  update_interval: 60s
  ct_model: SCT_013_030    # CT clamp model — change it to match yours

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy:
      name: "Mains Energy"
    frequency:
      name: "Mains Frequency"
    power_factor:
      name: "Mains Power Factor"

O que demonstra: a configuração mínima viável. Os seis sensores cobrem o caso central — medição de toda a casa ou de uma única carga. O sensor energy já tem device_class: energy + state_class: total_increasing definidos, pelo que vai diretamente para o painel de Energia do HA sem configuração extra. O protocolo de medição por período (snapshot / 50 ms de estabilização / leitura da potência média, integrada no relógio do mestre) está documentado em 09 · Referência da API.


6 · UI1 com personalização — todos os ajustes padrão do ESPHome

O rbAmp é um componente ESPHome "bom cidadão". Cada slot (voltage, current, power, …) é um objeto sensor: ESPHome comum. Todo o conjunto standard de propriedades e filtros funciona sobre ele. Não precisa de lambda: nem de modelos personalizados — tudo o que faz com pzemac / atm90e32 / cse7766 funciona aqui exatamente da mesma forma. O exemplo mostra as personalizações mais comuns num único bloco:

YAML
esphome:
  name: rbamp-ui1-tuned

esp32:
  board: esp32dev
  framework:
    type: arduino

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
ota:
  - platform: esphome

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

rbamp:
  id: meter1
  address: 0x50
  update_interval: 10s        # ↑ Poll once / 10 s instead of the default 60 s —
                              # a denser graph, ~6× the I²C traffic.
  ct_model: SCT_013_030

sensor:
  - platform: rbamp
    rbamp_id: meter1

    # ──────────── Customizing names + precision + filters ────────────
    voltage:
      name: "Mains voltage"              # Any name — it becomes the HA entity_id
      accuracy_decimals: 1               # 226.7 instead of the default 226.70
      filters:
        # Linear calibration against a reference multimeter:
        - calibrate_linear:
            - 0.0 -> 0.0
            - 230.0 -> 230.5
        # Smoothing of sharp spikes (standard ESPHome):
        - exponential_moving_average:
            alpha: 0.3
            send_every: 1

    current:
      name: "Load current"
      accuracy_decimals: 3               # 0.755 instead of 0.75
      filters:
        # Mask the noise floor — drop values below 50 mA (50 mW at 230 V).
        # The equivalent of the `noise_floor` option in pzemac / cse7766.
        - lambda: 'return x < 0.05 ? 0.0f : x;'

    power:
      name: "Power"
      accuracy_decimals: 1
      filters:
        # Throttle publications: no more than once / 30 s, even with update_interval 10 s.
        - throttle: 30s

    energy:
      name: "Energy (Wh)"
      # The standard device_class: energy + state_class: total_increasing
      # are already set by the component — the Energy dashboard works.
      filters:
        # Convert Wh → kWh for a more familiar scale in Lovelace.
        # (The HA Energy dashboard itself expects Wh, but if you want a graph in kWh,
        #  declare a second template sensor with a division rather than changing units here.)
        - multiply: 0.001
      unit_of_measurement: "kWh"         # ← overrides the default "Wh"
      accuracy_decimals: 3

    frequency:
      name: "Mains frequency"
      accuracy_decimals: 2

    power_factor:
      name: "Power factor"
      accuracy_decimals: 3
      # Optional: a filter to hide PF at zero load (P ~ 0)
      filters:
        - lambda: 'return isnan(x) ? 0.0f : x;'

O que demonstra:

  • Nomes personalizados (name:) tornam-se o entity_id do HA — por exemplo, sensor.rbamp_ui1_tuned_mains_voltage. Nomes em qualquer idioma, incluindo cirílico, funcionam.

  • Precisão de saída (accuracy_decimals:) é independente do módulo; o módulo devolve float32 com a máxima precisão, e o ESPHome trunca-o para a interface.

  • update_interval: não precisa de ser alterado por sensor — é uma propriedade do componente (PollingComponent), definida uma vez no bloco rbamp:. Se quiser publicações mais raras de sensores individuais, adicione filters: - throttle: .

  • filters: — o conjunto completo do ESPHome:

  • calibrate_linear — calibração por pontos contra a sua referência (multímetro, amperímetro de referência).

  • exponential_moving_average / sliding_window_moving_average — suavização.

  • lambda — uma transformação arbitrária (máscara de ruído de fundo, zero condicional).
  • multiply / offset — aritmética (por exemplo, Wh → kWh).
  • throttle / delta — reduzir a taxa de publicação.
  • unit_of_measurement: pode ser sobreposta (por exemplo para kWh com multiply: 0.001). O HA deteta a nova unidade automaticamente.

  • Sem lambda: para o funcionamento básico — todos os cálculos de RMS, potência, frequência e PF são feitos pelo módulo. O ESP32 apenas renomeia, formata e filtra.

Segurança

⚠ Não substitua o device_class: de energy — o painel de Energia do HA exige estritamente device_class: energy + state_class: total_increasing. A conversão de unidades com multiply + unit_of_measurement: mantém a compatibilidade, mas alterar o device_class quebra o painel.

A lista completa de propriedades e filtros padrão dos sensores está na documentação oficial do Sensor Component do ESPHome. Essa documentação é totalmente aplicável aos slots rbAmp — não há desvios em relação ao padrão.


7 · UI3 — três canais com pinças mistas

Origem: ../example/ui3.yaml

O SKU UI3 tem uma entrada de tensão e três canais de corrente independentes. O cenário canónico é aplicar modelos de pinça diferentes em canais diferentes: uma pinça pequena em consumidores de baixa corrente (para máxima resolução) e uma grande na alimentação principal (para margem nos picos).

YAML
esphome:
  name: rbamp-ui3

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:
  level: DEBUG

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
ota:
  - platform: esphome

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

rbamp:
  id: meter1
  address: 0x50
  update_interval: 60s
  # drdy_pin: GPIO15
  ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
  # CH0=5A for standby consumers and LED lighting,
  # CH1=30A for the main household loads,
  # CH2=20A for the boiler / a medium-power branch (~3-5 kW)
  # For currents above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A).

sensor:
  - platform: rbamp
    rbamp_id: meter1
    # Common (topology-independent)
    voltage:
      name: "Mains Voltage"
    frequency:
      name: "Mains Frequency"
    apparent_power:
      name: "CH0 Apparent Power"

    # Channel 0 — primary current input (small consumers, 5A)
    current:
      name: "CH0 Current"
    power:
      name: "CH0 Power"
    energy:
      name: "CH0 Energy"
    power_factor:
      name: "CH0 Power Factor"
    reactive_power:
      name: "CH0 Reactive Power"

    # Channel 1 — main loads (30A)
    current_1:
      name: "CH1 Current"
    power_1:
      name: "CH1 Power"
    energy_1:
      name: "CH1 Energy"
    power_factor_1:
      name: "CH1 Power Factor"
    reactive_power_1:
      name: "CH1 Reactive Power"

    # Channel 2 — boiler / medium-power branch (20A)
    current_2:
      name: "CH2 Current"
    power_2:
      name: "CH2 Power"
    energy_2:
      name: "CH2 Energy"
    power_factor_2:
      name: "CH2 Power Factor"
    reactive_power_2:
      name: "CH2 Reactive Power"

O que demonstra: todos os três canais do SKU UI3 + modelos de pinça mistos através de ct_models:. O validador do esquema verifica que power_N e energy_N (e power_factor_N, reactive_power_N) requerem current_N e voltage — se declarar power_1 sem current_1, a compilação falha com uma mensagem clara. Cada canal tem o seu próprio acumulador energy_* persistido em NVS. Se todos os canais usarem o mesmo modelo de pinça, use o ct_model: global em vez de ct_models:.


8 · Barramento multi-módulo (três rbAmp em 0x50 / 0x51 / 0x52)

Origem: ../example/multi_module.yaml

Três módulos num só barramento I²C — a alimentação principal da casa, a saída de geração solar e o carregamento de VE. Cada um tem o seu próprio bloco rbamp: (no esquema do componente, MULTI_CONF = True).

YAML
esphome:
  name: rbamp-multi

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:
  level: INFO

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
ota:
  - platform: esphome

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz    # recommended: at 100 kHz the ESP-IDF i2c_master driver interaction causes periodic
                      # NACKs are almost inevitable on every cycle
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

# Three independent rbamp: blocks — MULTI_CONF = True in the schema.
# On v1.3 firmware the general-call snapshot is opt-in via fleet_gc_enable +
# group_id (capability-gated on the firmware side). Modules in the same
# group snapshot in a single transaction, with ~540 µs skew per module. On legacy
# firmware (v1.0..v1.2) the component falls back to a sequential snapshot
# and logs an informational line. (The old broadcast_latch: key is still
# accepted by the schema but has no effect.)
rbamp:
  - id: meter_house
    address: 0x50
    update_interval: 60s
    fleet_gc_enable: true
    group_id: 1

  - id: meter_solar
    address: 0x51
    update_interval: 60s
    fleet_gc_enable: true
    group_id: 1
    bidirectional: true     # needed for energy_exported_*; on BASIC it
                             # publishes 0, on STANDARD it is real export energy

  - id: meter_evcharger
    address: 0x52
    update_interval: 60s
    fleet_gc_enable: true
    group_id: 1

sensor:
  - platform: rbamp
    rbamp_id: meter_house
    voltage:
      name: "House Voltage"
    current:
      name: "House Current"
    power:
      name: "House Power"
    energy:
      name: "House Energy"
    frequency:
      name: "Mains Frequency"

  - platform: rbamp
    rbamp_id: meter_solar
    voltage:
      name: "Solar Voltage"
      internal: true        # hidden from HA — the same mains as House Voltage
    current:
      name: "Solar Current"
    power:
      name: "Solar Power"
    energy:
      name: "Solar Energy"
    energy_exported:
      name: "Solar Energy Exported"

  - platform: rbamp
    rbamp_id: meter_evcharger
    voltage:
      name: "EV Charger Voltage"
      internal: true
    current:
      name: "EV Charger Current"
    power:
      name: "EV Charger Power"
    energy:
      name: "EV Charger Energy"

O que demonstra: o padrão MULTI_CONF = True — declare tantos blocos rbamp: quantos módulos tiver no barramento. Cada um mantém o seu próprio acumulador NVS, cuja chave deriva do endereço I²C, pelo que os três contadores se mantêm independentes entre reinícios. A flag internal: true nos sensores de tensão duplicados oculta as três entidades de tensão da rede, quase idênticas, no HA quando todos os módulos medem a mesma fase. Para o procedimento de atribuição de endereços, ver o Exemplo 2 abaixo.

Nota

Semântica de internal: true. A flag não desativa a leitura do registo do módulo — o componente continua a ler a tensão de cada módulo em cada update_interval (isto é necessário para o cálculo da potência). A flag apenas oculta o sensor da API do Home Assistant: não é criada entidade, não aparece no Lovelace e não é contada no painel Energia. Se quiser reduzir o tráfego I²C, não declare o slot voltage: em sensor.platform: rbamp — o componente então não consulta o registo. Se o declarar, a flag internal: é puramente cosmética.

Uma segunda restrição diz respeito à unicidade dos endereços no barramento:

Segurança

⚠ Os endereços únicos são responsabilidade da configuração. O esquema do componente (MULTI_CONF = True) não valida sobreposição de valores address: entre blocos rbamp:. Se dois blocos indicarem o mesmo address: 0x50, ambas as declarações são aceites e, no barramento, os dois alvos respondem ao mesmo tempo — espere conflitos I²C, respostas corrompidas ou sintomas semelhantes a um módulo em falta. Antes de confirmar o YAML, verifique que todos os valores address: são únicos (e não colidem com outros dispositivos I²C do barramento). Após cada atribuição new_address:, atualize a secção rbamp: para o novo endereço — a entrada antiga não é invalidada automaticamente.

Pull-ups num barramento multi-módulo

Os três módulos saem de fábrica com pull-ups de 4.7 kΩ. Num barramento de três módulos, a combinação em paralelo é ~1.6 kΩ — maior consumo de corrente e integridade de sinal marginal a 50 kHz. Corte os jumpers de solda de pull-up nos três módulos e coloque um par externo de 2.7–3.3 kΩ junto ao ESP32 (a linha de 3 módulos da tabela em 04_hardware.md).

Avançado: cadência de snapshot desacoplada para frotas multi-módulo (v1.4+)

As instalações de frotas pagam o custo do ciclo de instantâneo por módulo e por ciclo: num barramento de 3 módulos com polling a update_interval: 10s, são 3× a escrita do instantâneo + 3× a janela de estabilização de 50 ms a cada 10 s — mais as leituras do bloco RT por cima. Em hosts ESP8266 (núcleo único; as ISR do Wi-Fi competem pela CPU durante transações I²C) ou barramentos I²C partilhados com outros dispositivos, esta sobrecarga torna-se visível como falhas de Wi-Fi ou leituras desatualizadas em entidades não-rbAmp.

latch_interval: (disponível desde a v1.4, módulos BASIC) separa as duas cadências: as leituras do bloco RT (V/I/P/PF/Q) mantêm-se em update_interval: — quem lê continua a ver valores atualizados no painel — enquanto a integração snapshot → Wh só corre a cada latch_interval:. A integração usa o tempo de relógio real entre eventos de snapshot, pelo que um intervalo de snapshot de 60 s produz apenas passos de integração de 60 s de largura (e continuam corretos). latch_interval tem de ser ≥ update_interval.

YAML
rbamp:
  - id: mod_mains
    address: 0x50
    update_interval: 10s     # dashboard: fresh V/I/P/PF every 10 s
    latch_interval: 60s      # bus: snapshot + Wh integration once a minute
    ct_models: [SCT_013_050, SCT_013_030, SCT_013_030]
    fleet_gc_enable: true
    group_id: 1
  - id: mod_branches
    address: 0x51
    update_interval: 10s
    latch_interval: 60s
    ct_models: [SCT_013_005, SCT_013_030, SCT_013_050]
    fleet_gc_enable: true
    group_id: 1

Redução da carga do barramento face ao mesmo conjunto sem latch_interval:: com update_interval: 10s, cada módulo contribui com ~15 ms de leitura RT + ~65 ms de instantâneo+estabilização por ciclo → ~80 ms por módulo por ciclo. Com latch_interval: 60s, o instantâneo+estabilização dispara apenas uma vez por minuto → as leituras RT continuam baratas a cada 10 s + uma rajada curta de instantâneo a cada 60 s, aproximadamente 3× menos ocupação média do barramento. Frotas maiores veem poupanças proporcionalmente maiores.

Quando omitir latch_interval:: implementações com um só módulo em hosts ESP32, em que a carga de base não tem custo — a cadência única predefinida da v1.3 é mais simples e igualmente correta.


9 · Alteração única do endereço I²C (0x50 → 0x51)

Fonte: ../example/address_change.yaml

Todos os módulos rbAmp saem de fábrica no endereço 0x50. Para colocar vários módulos num barramento, tem de reflashar cada um para o seu endereço único antes de os ligar em paralelo.

YAML
esphome:
  name: rbamp-addr-change

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:
  level: DEBUG    # DEBUG shows the address-change lines

api:
ota:
  - platform: esphome

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

rbamp:
  id: meter1
  address: 0x50          # current address — before the change
  new_address: 0x51      # one-time target — DELETE this line after success

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "rbAmp Voltage (post-relocate)"
    current:
      name: "rbAmp Current (post-relocate)"

O que demonstra: o fluxo de alteração de endereço única. Gravar este YAML faz com que o componente execute o procedimento uma vez no arranque:

  1. Sonde 0x50. Se 0x50 estiver em silêncio e 0x51 já responder, a alteração foi aplicada num arranque anterior; o componente adapta-se e regista um aviso a pedir que limpe o YAML.

  2. Verifique se o módulo está pronto a aceitar uma operação de provisionamento.

  3. Escreva o novo endereço na flash (~700 ms), um reset suave (~300 ms), e volte a travar no ciclo CA.

  4. Confirme no novo endereço. Em caso de sucesso — o log Address change confirmed at 0x51 e IMPORTANTE: atualize o YAML para address: 0x51 e remova new_address:.

Compatibilidade do firmware: no firmware v1.3+ a alteração de endereço está pronta para produção — o componente usa o protocolo de commit em duas fases (preparar → armar → commit → reiniciar) sem qualquer modo especial. No firmware legado (v1.0-v1.2) o fallback monofásico exige o modo de provisionamento de fábrica; consulte a documentação do módulo ou o seu fornecedor para o procedimento de o ativar temporariamente.

Após o êxito: edite o YAML para address: 0x51 e remova a linha new_address: 0x51. Grave de novo. A partir do próximo arranque, o componente usa 0x51 normalmente e o procedimento de alteração deixa de correr.

Lista de verificação de reversão após um provisionamento bem-sucedido

Para não deixar uma variante de provisionamento "pendente" no repositório (duas alternativas, nunca colar ambas no mesmo ficheiro):

YAML
# BEFORE (provisioning):
rbamp:
  id: meter1
  address: 0x50               # the module's current address
  new_address: 0x51           # the provisioning target
  update_interval: 60s
YAML
# AFTER (production — applied next flash):
rbamp:
  id: meter1
  address: 0x51               # ← replaced with the new address
  # new_address: 0x51         # ← DELETE the line (do not comment it out)
  update_interval: 60s

Exatamente três alterações:

  1. Altere o valor de address: do antigo para o novo.
  2. Apague (não comente) a linha new_address:.
  3. Volte a gravar via OTA ou USB.

Depois do passo 3, o registo deve mostrar uma linha normal de dump_config sem o aviso address change requested but current address matches new_address — o que significa que a reversão foi correta. Veja também 10_troubleshooting §4 "OTA logo após o provisionamento de new_address: não carrega" se o primeiro OTA depois da reversão não arrancar.


10 · Configuração de bancada com secrets

Origem: ../example/bench-ui1.yaml

O padrão bench-*.yaml destina-se a máquinas de desenvolvimento onde as credenciais Wi-Fi são necessárias na configuração mas não devem acabar num commit. example/.gitignore exclui bench-*.yaml e secrets.yaml do controlo de versões.

YAML
esphome:
  name: rbamp-ui1

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:
  level: DEBUG

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "rbAmp UI1 Fallback"
    password: !secret ap_password

captive_portal:
api:
ota:
  - platform: esphome

web_server:
  port: 80
  version: 3           # optional: a local HTTP UI — handy for bench testing

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

rbamp:
  id: meter1
  address: 0x50
  update_interval: 60s
  ct_model: SCT_013_030

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy:
      name: "Mains Energy"
    frequency:
      name: "Mains Frequency"
    power_factor:
      name: "Mains Power Factor"

O secrets.yaml correspondente (em example/, não controlado por versão):

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

O que demonstra: separar as credenciais de compilação do YAML versionado através de !secret do ESPHome. Listar bench-*.yaml em .gitignore permite manter quantas variantes de bancada quiser sem risco de fuga. Use esphome run --device 192.168.0.173 example/bench-ui1.yaml para OTA após a primeira ligação à rede, ou esphome run --device COM6 example/bench-ui1.yaml para a primeira gravação por USB.


11 · Quebra de tensão e perda da rede

Quando a rede é interrompida, o front-end analógico isolado do módulo deixa de receber sinal. O registo de tensão desce para 0.0 V — um float IEEE 754 finito e válido que passa o filtro de sanidade isfinite() do componente. A política de filtragem do componente é intencional:

Segurança

Sem limites físicos inferiores — quebra de tensão (U=0 V com corte da rede), queda de tensão, teste fora da rede / UPS e disparo de disjuntor DEVEM passar para o HA, para que o utilizador veja o estado real.

Não é necessário YAML especial para detetar falha da rede — o próprio sensor voltage lê 0.0 V.

YAML
sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"    # reads 0.0 V when mains is disconnected
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy:
      name: "Mains Energy"

Automatismo do HA: alertar na perda da rede

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
# configuration.yaml or the Automations UI
automation:
  - alias: "rbAmp mains loss alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.rbamp_ui1_mains_voltage
        below: 10          # U < 10 V = mains disconnected or a severe brownout
        for:
          seconds: 5       # debounce: sustained, not transient
    action:
      - service: notify.mobile_app_your_phone
        data:
          title: "Mains power lost"
          message: >
            Voltage dropped to {{ states('sensor.rbamp_ui1_mains_voltage') }} V
            at {{ now().strftime('%H:%M:%S') }}.

O que demonstra: usar o comportamento de passagem de 0 V como fonte de um evento de "perda da rede". Como o componente publica 0.0 V em vez de saltar a publicação, os automatismos do HA e o painel Energia veem o evento de subtensão em tempo real. A condição for: 5 seconds bloqueia disparos falsos durante o aquecimento de ~250 ms no arranque (quando os registos leem 0 antes da primeira medição válida).


12 · Painel Energia do HA

O sensor energy (e energy_1, energy_2, energy_exported, etc.) fica configurado automaticamente com device_class: energy e state_class: total_increasing — exatamente o que o painel Energia do HA espera para sensores de consumo acumulado. Não é necessário YAML extra.

Após a descoberta:

  1. Definições → Painéis → Energia. [Settings → Dashboards → Energy]
  2. Adicionar consumo → escolha "Mains Energy" (ou a entidade de medição de importação que quiser). [Mains Energy]

  3. Se tiver solar — Add Production → escolha Solar Energy (a partir de meter_solar no exemplo multi-módulo). [Adicionar produção → Energia solar]

Os valores de energia estão em Wh. O HA converte-os para kWh para apresentação. A persistência NVS no componente garante que o acumulador sobrevive a um reinício do ESP32 sem um falso "reinício do contador" nas estatísticas do HA.

YAML
# Example: consumption + solar export for the HA Energy dashboard
# (assumes the rbamp: blocks meter_house and meter_solar from the multi-module example)
# energy / energy_exported need voltage AND current in the same block;
# internal: true keeps them out of Home Assistant.
sensor:
  - platform: rbamp
    rbamp_id: meter_house
    voltage:
      name: "House Voltage"
      internal: true
    current:
      name: "House Current"
      internal: true
    energy:
      name: "House Grid Import"    # → HA Energy: grid consumption

  - platform: rbamp
    rbamp_id: meter_solar
    voltage:
      name: "Solar Voltage"
      internal: true
    current:
      name: "Solar Current"
      internal: true
    energy:
      name: "Solar Production"     # → HA Energy: solar production
    energy_exported:
      name: "Solar Grid Export"    # → HA Energy: return to grid
                                   # needs bidirectional: true in rbamp:;
                                   # real values on STANDARD (STD) modules,
                                   # reads 0 on BASIC

13 · Automações do HA sobre os sensores rbAmp

Corte de carga: um relé desliga quando um limiar é ultrapassado

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
automation:
  - alias: "Load shedding — turn off non-critical loads at 3 kW"
    trigger:
      - platform: numeric_state
        entity_id: sensor.rbamp_multi_house_power
        above: 3000        # 3 kW threshold
        for:
          seconds: 10
    action:
      - service: switch.turn_off
        target:
          entity_id: switch.ev_charger_relay   # the non-critical load relay

  - alias: "Load shedding — restore when it drops below 2 kW"
    trigger:
      - platform: numeric_state
        entity_id: sensor.rbamp_multi_house_power
        below: 2000
        for:
          seconds: 30
    action:
      - service: switch.turn_on
        target:
          entity_id: switch.ev_charger_relay

Lembrete sobre correção do fator de potência

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
automation:
  - alias: "Poor power factor notification"
    trigger:
      - platform: numeric_state
        entity_id: sensor.rbamp_ui1_mains_power_factor
        below: 0.7
        for:
          minutes: 5
    action:
      - service: persistent_notification.create
        data:
          title: "Low power factor"
          message: >
            Power factor is {{ states('sensor.rbamp_ui1_mains_power_factor') }}.
            Check for large inductive loads (motors, old lighting ballasts).

Alerta de excesso do orçamento diário

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
automation:
  - alias: "Daily energy budget — warning at 10 kWh"
    trigger:
      - platform: template
        value_template: >
          {{ states('sensor.energy_daily') | float(0) > 10000 }}
    action:
      - service: notify.mobile_app_your_phone
        data:
          message: "Daily energy usage exceeded 10 kWh."

14 · Cartões Lovelace

Medidor — potência em tempo real

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
type: gauge
entity: sensor.rbamp_ui1_mains_power
min: 0
max: 3600
name: "Live Power"
segments:
  - from: 0
    color: green
  - from: 1500
    color: orange
  - from: 2500
    color: red

Apex Charts — potência ao longo do tempo

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
type: custom:apexcharts-card
header:
  title: "Power (W)"
  show: true
graph_span: 4h
series:
  - entity: sensor.rbamp_ui1_mains_power
    name: Power
    stroke_width: 2
    curve: smooth

Apex Charts — comparação de energia entre três canais

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
type: custom:apexcharts-card
header:
  title: "Channel Energy (Wh)"
  show: true
graph_span: 24h
series:
  - entity: sensor.rbamp_ui3_ch0_energy
    name: CH0
  - entity: sensor.rbamp_ui3_ch1_energy
    name: CH1
  - entity: sensor.rbamp_ui3_ch2_energy
    name: CH2

Mini gráfico — tensão

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
type: custom:mini-graph-card
entities:
  - sensor.rbamp_ui1_mains_voltage
name: "Mains Voltage"
hours_to_show: 12
points_per_hour: 4
line_width: 2

15 · Contador de utilidade — agregação por dia / semana / mês

O ESPHome publica totais acumulados em Wh. A integração utility_meter do HA repõe o contador em intervalos configuráveis e publica o delta como um sensor separado — útil para repartições diárias ou mensais.

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
# configuration.yaml
utility_meter:
  energy_daily:
    source: sensor.rbamp_ui1_mains_energy
    cycle: daily
    name: "Daily Energy"

  energy_monthly:
    source: sensor.rbamp_ui1_mains_energy
    cycle: monthly
    name: "Monthly Energy"

  energy_weekly:
    source: sensor.rbamp_ui1_mains_energy
    cycle: weekly
    name: "Weekly Energy"

O HA cria três entidades: sensor.energy_daily, sensor.energy_monthly, sensor.energy_weekly. Cada uma repõe-se a 0 no início do respetivo período e acumula o delta do sensor de origem total_increasing.

Sensor derivado de kWh/dia

utility_meter devolve Wh por predefinição. Para apresentar em kWh, adicione um sensor template:

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
template:
  - sensor:
      - name: "Daily Energy kWh"
        unit_of_measurement: "kWh"
        state_class: total_increasing
        device_class: energy
        state: >
          {{ (states('sensor.energy_daily') | float(0) / 1000) | round(3) }}

Sensor de custo diário

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
template:
  - sensor:
      - name: "Daily Energy Cost"
        unit_of_measurement: "EUR"
        icon: mdi:currency-eur
        state: >
          {% set kwh = states('sensor.energy_daily') | float(0) / 1000 %}
          {% set rate = 0.28 %}    # EUR/kWh — set your own tariff
          {{ (kwh * rate) | round(2) }}

16 · Sub-medição por carga (3 módulos em 0x50 / 0x51 / 0x52)

Instalar três módulos rbAmp num quadro de distribuição permite medição de energia por circuito sem painel inteligente nem hardware extra.

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
# Extending the multi-module example with per-circuit utility meters

utility_meter:
  kitchen_daily:
    source: sensor.rbamp_multi_house_energy
    cycle: daily
    name: "Kitchen Circuit Daily"

  solar_monthly:
    source: sensor.rbamp_multi_solar_energy
    cycle: monthly
    name: "Solar Production Monthly"

  ev_daily:
    source: sensor.rbamp_multi_ev_charger_energy
    cycle: daily
    name: "EV Charging Daily"

Combinado com o painel de Energia do HA, obtém extratos mensais por circuito sem cálculos extra de kWh × tarifa.


17 · rbAmp + um relé — controlo em malha fechada

Um termoacumulador com controlo por relé

YAML
# ESPHome YAML on the same ESP32 as rbAmp
switch:
  - platform: gpio
    pin: GPIO5
    id: heater_relay
    name: "Water Heater"

Com o rbAmp e um relé no mesmo ESP32, pode construir um ciclo fechado no próprio ESPHome (via Lambda ou on_value) sem passar pelo HA:

Pressupõe que já tem uma entrada switch: com o id usado abaixo.

YAML
sensor:
  - platform: rbamp
    rbamp_id: meter1
    power:
      name: "House Power"
      on_value:
        then:
          - if:
              condition:
                lambda: 'return x > 3000.0f;'
              then:
                - switch.turn_off: heater_relay
              else:
                - switch.turn_on: heater_relay

O que demonstra: usar o callback on_value de um sensor rbAmp para controlar um relé sem intervenção do HA. O callback dispara no ESP32 a cada update_interval (60 s) e atualiza o estado do relé a partir da leitura de potência mais recente. Para um controlo mais apertado (ciclo < 60 s), reduza update_interval para 10s — isto aumenta proporcionalmente a carga do barramento I²C. Um exemplo de malha fechada mais completo para uma caldeira está em 07_diy_integrations.md.


18 · Integração DRDY

O pino DRDY de dreno aberto do módulo gera um impulso LOW de ~10 µs a cada ~100 ms após a atualização dos registos instantâneos. Pode ligá-lo a um GPIO do ESP32. O componente regista o pino DRDY; as leituras são controladas por temporizador (update_interval).

YAML
rbamp:
  id: meter1
  address: 0x50
  update_interval: 60s        # energy integration still happens every 60 s
  drdy_pin:
    number: GPIO15
    mode:
      input: true
      pullup: true            # DRDY is open-drain; it needs a pull-up
    inverted: true            # the DRDY pulse is LOW; inverted=true gives a rising edge
Nota

: na firmware atual o componente regista drdy_pin em dump_config, mas não implementa leituras RT acionadas por interrupção — o update_interval continua a definir a cadência de polling.


19 · Sensores faseados (variantes bifásicas / trifásicas)

Para módulos com mais de uma entrada de tensão, o componente oferece um grupo de sensores faseados (voltage_a/b/c, current_a/b/c, power_a/b/c, energy_a/b/c, power_factor_a/b/c, reactive_power_a/b/c, power_total, mais voltage_angle_b/c). Um slot só publica quando o módulo ligado reporta o canal correspondente; num módulo de tensão única os slots faseados ficam sem valor. O esquema verifica que os grupos simples e faseados não são misturados num mesmo bloco sensor:.

YAML
sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage_a:
      name: "Phase A Voltage"
    voltage_b:
      name: "Phase B Voltage"
    voltage_c:
      name: "Phase C Voltage"
    current_a:
      name: "Phase A Current"
    current_b:
      name: "Phase B Current"
    current_c:
      name: "Phase C Current"
    power_a:
      name: "Phase A Power"
    power_b:
      name: "Phase B Power"
    power_c:
      name: "Phase C Power"
    power_total:
      name: "Total Power"
    voltage_angle_b:
      name: "Phase B Angle"        # degrees vs phase A
    voltage_angle_c:
      name: "Phase C Angle"
    phase_sequence:
      name: "Phase Sequence"       # 1 forward, 2 reverse, 3 abnormal
    frequency:
      name: "Grid Frequency"

O que demonstra: o grupo de campos faseados. Misturar campos monofásicos e faseados num único bloco sensor: produz um erro em tempo de compilação — escolha o grupo que corresponde ao seu módulo. Os detalhes estão em 09 · Referência da API §2.2.


20 · Migração a partir de outros componentes de medição ESPHome

A partir de pzem004t

A plataforma pzem004t exporta os mesmos nomes de campos que o rbamp para as grandezas CA comuns. A troca é bloco a bloco, com nomes de sensores idênticos:

YAML
# Before (pzem004t, UART)
uart:
  rx_pin: GPIO16
  tx_pin: GPIO17
  baud_rate: 9600

sensor:
  - platform: pzem004t
    voltage:
      name: "Mains Voltage"
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy:
      name: "Mains Energy"
    frequency:
      name: "Mains Frequency"
    power_factor:
      name: "Mains Power Factor"
YAML
# After (rbamp, I²C) — the same sensor names → the same entity IDs in HA
# (replaces the block above; do not paste both)
i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz

rbamp:
  id: meter1
  address: 0x50
  ct_model: SCT_013_030

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy:
      name: "Mains Energy"
    frequency:
      name: "Mains Frequency"
    power_factor:
      name: "Mains Power Factor"

Campos name: idênticos dão IDs de entidade idênticos no HA. O histórico do painel de Energia é preservado na troca: o sensor total_increasing retoma de onde ficou. Remova o bloco uart: se não for partilhado com outro componente.

A partir de cse7766 (Sonoff POW R2)

Mesmo padrão. cse7766 fornece voltage, current, power, energy, power_factor, apparent_power — todos presentes em rbamp. Substitua platform: cse7766 por platform: rbamp, adicione rbamp_id: meter1, remova uart: e adicione i2c: e o bloco rbamp:.


21 · Módulo STANDARD — totais de energia no dispositivo

Num módulo STANDARD o componente acumula os contadores de energia do próprio módulo. Os totais sobrevivem a reinícios do ESP32 e do módulo e mantêm-se monótonos. O mesmo YAML funciona também num módulo BASIC, exceto que as chaves de total geral nunca publicam.

YAML
rbamp:
  id: meter1
  address: 0x50
  update_interval: 30s
  bidirectional: true          # per-channel energy_exported
  start_current_ua: 400        # no energy counted below 400 µA per channel

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy_total:
      name: "Energy Imported"          # all channels, total_increasing
    energy_exported_total:
      name: "Energy Exported"          # all channels, total_increasing
    energy_net:
      name: "Energy Net"               # import - export, may decrease
    reactive_energy:
      name: "Reactive Energy Imported" # varh
    reactive_energy_exported:
      name: "Reactive Energy Exported"

O que demonstra: os sensores de total geral, que não precisam de uma declaração de current/voltage associada; start_current_ua: (0 = desligado, caso contrário 10..2540 em passos de 10) para que o ruído em vazio não se acumule nos contadores de importação e exportação (as leituras instantâneas não são afetadas). Para o painel de Energia do HA use energy_total como consumo da rede e energy_exported_total como retorno à rede.


22 · Trocar o calibre SCT e sobreposição de serviço

YAML
rbamp:
  id: meter1
  ct_model: SCT_013_010      # module was delivered with the SCT-013-030

As leituras mantêm-se exatas após a comutação: na firmware do módulo até 1.4.19 o componente conclui a escrita do modelo com o reinício necessário do módulo (visível no registo) e escala a corrente, a potência e a energia para o sensor selecionado; firmware mais recente faz isto no módulo. Um valor que o módulo já tem nunca é reescrito, e num módulo fornecido calibrado em conjunto com o respetivo sensor incorporado (sensor_class: WIRED_CT / BUILTIN_CT) a alteração é recusada com uma linha de registo. Apenas para uma nova aplicação deliberada de predefinição:

YAML
rbamp:
  id: meter1
  ct_model: SCT_013_010
  ct_model_force: true       # one-off service option; remove both lines afterwards

Resumo das regras de validação YAML

Regra Imposto por
power / energy / power_factor / reactive_power requerem current Validador do esquema (_SINGLE_SLOT_DEPS)
P/Q/PF/E de qualquer canal exigem voltage Validador de esquema
Grupos simples e faseados não são misturados num mesmo sensor: _validate_topology_consistency
new_address ≠ address _validate_new_address
address no intervalo 0x08..0x77 cv.i2c_address
update_interval mínimo 1s, aplicado Validador de esquema
latch_interval ≥ update_interval Validador de esquema
ct_model: e ct_models: são mutuamente exclusivos Validador de esquema
ct_models: tem 1..16 entradas Validador de esquema
ct_model_force: true requer ct_model: ou ct_models: Validador de esquema
start_current_ua é 0 ou 10..2540 em passos de 10 Validador de esquema
O código do modelo de pinça é válido para o sensor_class fixado Validador de esquema

Os erros de validação são reportados em esphome compile com uma mensagem legível que aponta para a chave com problema. Não precisa de gravar o hardware para encontrar um erro de configuração.


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