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 |
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Ω).
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)
[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_powernuma 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)
# 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:
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:
[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.
🛑 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:
[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.
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:
[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:
[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 configrejeita o esquema (cv.Invalid). Se o YAML passar pelo validador (edição manual / build antiga), a firmware devolveREG_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).
# 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)
[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-callgroup=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ó.
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.
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:
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 oentity_iddo 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 blocorbamp:. Se quiser publicações mais raras de sensores individuais, adicionefilters: - 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 parakWhcommultiply: 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.
⚠ 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).
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).
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.
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:
⚠ 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.
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.
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:
-
Sonde
0x50. Se0x50estiver em silêncio e0x51já responder, a alteração foi aplicada num arranque anterior; o componente adapta-se e regista um aviso a pedir que limpe o YAML. -
Verifique se o módulo está pronto a aceitar uma operação de provisionamento.
-
Escreva o novo endereço na flash (~700 ms), um reset suave (~300 ms), e volte a travar no ciclo CA.
-
Confirme no novo endereço. Em caso de sucesso — o log
Address change confirmed at 0x51eIMPORTANTE: 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):
# BEFORE (provisioning):
rbamp:
id: meter1
address: 0x50 # the module's current address
new_address: 0x51 # the provisioning target
update_interval: 60s
# 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:
- Altere o valor de
address:do antigo para o novo. - Apague (não comente) a linha
new_address:. - 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.
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):
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:
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.
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ó.
# 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:
- Definições → Painéis → Energia. [Settings → Dashboards → Energy]
-
Adicionar consumo → escolha "Mains Energy" (ou a entidade de medição de importação que quiser). [Mains Energy]
-
Se tiver solar — Add Production → escolha Solar Energy (a partir de
meter_solarno 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.
# 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
8.8 Fluxo de eventos de limiar — escrever limiar → disparo → limpeza W1C (api-reference)
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ó.
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ó.
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ó.
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ó.
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ó.
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ó.
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ó.
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ó.
# 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ó.
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ó.
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ó.
# 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é
# 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.
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).
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
: 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:.
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:
# 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"
# 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.
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
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:
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)