09 · Referência do esquema YAML
Este capítulo é a referência completa do esquema YAML do componente externo rbamp para o ESPHome. Se uma chave não estiver listada aqui, não existe no esquema.
Um YAML para as duas linhas de módulos. No arranque, o componente identifica qual linha de módulos está ligada (BASIC ou STANDARD (STD)) e adapta-se automaticamente: o número de canais, a variante e as funcionalidades disponíveis vêm do próprio módulo, por isso não é necessária a chave topology: nem uma troca de nível no YAML. As chaves que se aplicam a apenas uma geração estão marcadas abaixo; uma chave que o módulo ligado não consegue cumprir é ignorada com uma linha de log, nunca com uma falha grave.
Contents:
- Bloco do componente —
rbamp: - Plataforma de sensores —
sensor.platform: rbamp - Fluxo de dados e temporização
- Definições do barramento I²C
1. Bloco do componente — rbamp:
Configuração de vários módulos (initialization) · Consulta de vários módulos — três estratégias (realtime-polling) · Problemas com vários módulos (troubleshooting)
O bloco de topo rbamp: regista uma instância de componente. Herda de PollingComponent (que fornece update_interval) e de i2c.I2CDevice (que fornece address e o handle do barramento I²C). MULTI_CONF: True significa que qualquer número de blocos rbamp: pode coexistir no mesmo YAML, cada um a referenciar o seu próprio escravo I²C.
rbamp:
id: meter1
address: 0x50
update_interval: 60s
drdy_pin: GPIO4
sensor_class: SCT_013
ct_model: SCT_013_030
# or, for a UI3 with mixed clamps:
# ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
bidirectional: false
new_address: 0x51
fleet_gc_enable: false
group_id: 0
latch_interval: 60s
start_current_ua: 400 # STANDARD only, see below
# ct_model_force: true # service option, see below
Todas as chaves são opcionais. topology: e broadcast_latch: continuam aceites por compatibilidade com versões anteriores (ver as respetivas entradas).
id
| Atributo | Valor |
|---|---|
| Tipo | id (identificador do ESPHome) |
| Predefinido | Gerado automaticamente |
| Obrigatório | Não |
Atribui um identificador estável à instância. Os sensores referem-no através de rbamp_id: meter1. Com vários blocos rbamp:, é obrigatório um id explícito.
rbamp:
id: kitchen_meter
address
02 · Inicialização e arranque (initialization) · 3.6 Algoritmo canónico de deteção (api-reference) · 6 · Sequências de protocolo (api-reference)
| Atributo | Valor |
|---|---|
| Tipo | i2c_address (7 bits, 0x08..0x77) |
| Predefinido | 0x50 |
| Obrigatório | Não |
O endereço I²C atual do módulo rbAmp. O endereço de fábrica é 0x50. Depois de aplicar uma alteração de endereço (via new_address), atualize esta chave para o novo valor e remova new_address.
Gama válida: 0x08..0x77 (os endereços I²C reservados de 7 bits são excluídos).
rbamp:
address: 0x52 # three modules on the bus: 0x50, 0x51, 0x52
Referência cruzada: o protocolo do barramento I²C na referência da API; alteração de endereço em runtime para mudar o endereço após o arranque.
update_interval
04 · Medição por período e contabilização tarifária (period-metering) · Ciclo de consulta contínuo (recomendado) (period-metering) · Registos de snapshot de período (period-metering)
| Atributo | Valor |
|---|---|
| Tipo | time (string de duração do ESPHome) |
| Predefinido | 60s |
| Obrigatório | Não |
Com que frequência update() corre. Cada chamada:
- Envia o comando de snapshot e agenda um timeout não bloqueante de 50 ms para ler o snapshot do período (módulos BASIC; nos módulos STANDARD a energia vem dos próprios contadores do módulo, ver
energy_total). - Verifica o registo de estado; se o módulo estiver pronto, publica todos os sensores instantâneos associados.
A predefinição de 60 s é razoável: o módulo atualiza internamente a sua potência média por período por volta de cada ~100 ms, mas integrar a energia do lado do mestre exige uma janela suficientemente longa para ser correta. Com 60 s e uma carga média de 60 W, um snapshot perdido custa ≤ 1 Wh.
O valor mínimo permitido é 1s: o esquema rejeita qualquer valor inferior, e esphome config reporta um diagnóstico. Valores abaixo de 5-10 s não trazem benefício para uma sincronização apertada e apenas sobrecarregam o barramento.
rbamp:
update_interval: 30s # more frequent dashboard updates, more traffic
latch_interval
Ciclo de consulta contínuo (recomendado) (period-metering) · 4.11 Bloco de período V03 (0xBE..0xCF) (api-reference) · 6.4 Sincronização de período — duas estratégias (api-reference)
| Atributo | Valor |
|---|---|
| Tipo | time (string de duração do ESPHome) |
| Predefinido | Igual a update_interval |
| Obrigatório | Não |
| Desde | v1.4 |
Com que frequência o componente envia o comando de snapshot e integra uma amostra de Wh. Quando definido, separa o ciclo de snapshot da cadência de leitura RT — update_interval: continua a controlar com que frequência os registos V/I/P/PF/Q são lidos e publicados, enquanto latch_interval: controla com que frequência o acumulador de período é capturado e os Wh são integrados.
A integração de energia não acrescenta erro próprio além da precisão de potência ativa do módulo, seja qual for a razão: a integração no mestre usa o dt de relógio real entre eventos de snapshot consecutivos, pelo que intervalos de snapshot mais longos só produzem passos de integração mais grosseiros.
Tem de ser >= update_interval (defini-lo mais curto é rejeitado na validação da configuração — os instantâneos extra não produziriam dados observáveis).
Quando não definido, o instantâneo corre em cada chamada update() (comportamento de cadência única da v1.3, compatível com versões anteriores).
rbamp:
update_interval: 3s # RT V/I/P/PF refreshed every 3 s
latch_interval: 60s # snapshot + Wh integration once a minute
Útil quando a carga do barramento ou a concorrência de CPU do lado do mestre importa — frotas com vários módulos, 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.
drdy_pin
01 · Ligação de hardware (hardware-connection) · 03 · Consulta em tempo real (realtime-polling)
| Atributo | Valor |
|---|---|
| Tipo | gpio_input_pin_schema |
| Predefinido | Nenhum (opcional) |
| Obrigatório | Não |
Liga a saída open-drain DRDY do módulo a um GPIO do ESP32. Quando especificado, o pino é configurado em setup() no arranque.
O pino é registado em dump_config, mas não é usado como disparo de leitura — os registos instantâneos são consultados a cada update_interval. Declarar o pino não altera o comportamento.
rbamp:
drdy_pin: GPIO4
sensor_class
Definir a classe do sensor e o modelo de TC (initialization) · 4.3 Sistema (0x20..0x25) (api-reference) · 6.2 Associação do modelo de TC — preparação pura + CMD por canal (api-reference)
| Atributo | Valor |
|---|---|
| Tipo | enum (SCT_013, WIRED_CT, BUILTIN_CT) |
| Predefinido | SCT_013 |
| Obrigatório | Não |
Fixa a família do sensor de corrente no lado do módulo. Na firmware v1.2+ o valor é gravado na flash e torna-se uma pré-condição para gravar o modelo de CT: o módulo recusará gravar o modelo se a classe não estiver definida. Em firmware anterior o valor é aceite pelo esquema e aplicado automaticamente na atualização.
| Valor | Significado |
|---|---|
SCT_013 |
Pinças SCT-013 de núcleo dividido — o padrão |
WIRED_CT |
Módulo fornecido calibrado juntamente com o seu próprio sensor ajustado |
BUILTIN_CT |
Módulo fornecido calibrado em conjunto com o respetivo sensor incorporado |
Proteção de escrita. O componente nunca escreve uma classe que o módulo já tem (um arranque repetido não escreve nada). Num módulo calibrado em par com o seu sensor ajustado (WIRED_CT / BUILTIN_CT), uma alteração de classe ou de modelo a partir do YAML é recusada com uma linha de log explícita — a escrita substituiria a calibração individual por uma definição genérica. Deixe sensor_class: e ct_model: fora do YAML nestes módulos, ou veja ct_model_force.
rbamp:
sensor_class: SCT_013 # default; may be omitted
Para mais sobre a escolha da pinça e da família, ver 03_sensor_selection.md.
ct_model
Definir a classe de sensor e o modelo de CT (initialization) · 6.2 Associação do modelo de CT — preparação pura + CMD por canal (api-reference) · 8.6 Provisionamento de primeira gravação (api-reference)
| Atributo | Valor |
|---|---|
| Tipo | enum (SCT_013_005, _010, _020, _030, _050) |
| Predefinido | Nenhum (opcional) |
| Obrigatório | Não |
Escreve o identificador do modelo de pinça de CT na flash do módulo. Na firmware v1.2+ isto carrega automaticamente os coeficientes de fábrica do modelo escolhido — não são necessários passos de calibração adicionais. Um valor igual ao que o módulo já tem não é escrito.
| Valor YAML | Código | Corrente nominal | Estado v1.3 |
|---|---|---|---|
SCT_013_005 |
1 | 5 A | produção |
SCT_013_010 |
2 | 10 A | produção |
SCT_013_020 |
6 | 20 A | produção (novo na v1.3) |
SCT_013_030 |
3 | 30 A | produção (SKU predefinido) |
SCT_013_050 |
4 | 50 A | produção |
O conjunto de códigos aceites por classe para SCT_013 é {1, 2, 3, 4, 5, 6, 7} (SCT_013_100 é o código 5, SCT_013_060 é o código 7; a ordem dos códigos não é a ordem dos calibres). Valores não correspondentes são rejeitados em esphome config através de cv.Invalid. Para mais, ver 03 · Seleção do sensor de corrente.
rbamp:
ct_model: SCT_013_030
Aplicado uma vez em setup(). Cada escrita é acompanhada de uma gravação em flash de ~700 ms (o módulo faz NACK a todas as operações I²C durante este tempo — o componente alimenta o watchdog automaticamente).
Mudar o calibre SCT mantém a precisão. Cada módulo SCT é calibrado de fábrica com o SCT-013-030. Quando escolhe outro calibre, a corrente, a potência e a energia continuam corretas: na firmware até 1.4.19 o componente conclui a escrita do modelo com um reinício do módulo (faz parte do fluxo normal e aparece no registo) e depois escala as leituras para o sensor selecionado; firmware mais recente faz a comutação no módulo e o componente deixa as leituras intactas. A tensão e o fator de potência não são afetados. Não é necessária nenhuma alteração ao YAML para isto.
Guarda de escrita. Um valor igual nunca é escrito, e num módulo emparelhado de fábrica (sensor_class: WIRED_CT / BUILTIN_CT) a escrita é recusada com uma linha de registo — ver sensor_class.
Mutuamente exclusivas com ct_models: — só uma das duas pode ser usada por bloco rbamp:.
Para mais, veja 03_sensor_selection.md. Referência cruzada: a referência de ct_model.
ct_models
| Atributo | Valor |
|---|---|
| Tipo | lista de 1–16 valores enum |
| Predefinido | Nenhum (opcional) |
| Obrigatório | Não |
Modelos de pinça de CT por canal — para módulos com pinças mistas em canais diferentes. Aceita os mesmos valores enumerados que ct_model:. O esquema aceita de 1 a 16 entradas; a posição na lista é o índice do canal. O componente aplica tantas entradas quantos canais o módulo tiver (1 para UI1, 2 para UI2, 3 para UI3, e assim por diante); entradas extra são ignoradas com um aviso.
rbamp:
id: ui3_meter
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
# CH0=5A for standby loads (maximum resolution),
# CH1=30A for main household loads,
# CH2=20A for a water heater / medium-power branch (~3-5 kW)
# For currents above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A)
Na firmware v1.2+ cada canal tem o seu próprio conjunto de coeficientes de fábrica, de forma independente. O tempo total de configuração no arranque é de ~2-3 segundos (~700 ms de escrita na flash por canal).
Módulos STANDARD. Os modelos por canal são guardados apenas por módulos que anunciam armazenamento persistente por canal. Num módulo que não o faça, o componente recusa de forma ruidosa (um aviso de que ct_models: não é suportado por este dispositivo, chaves ignoradas) em vez de escrever um valor que reverteria silenciosamente após um corte de energia — use aí o ct_model: único.
Aplicam-se as mesmas proteções de escrita que para ct_model: (valores iguais não são escritos; módulos fornecidos em par de fábrica recusam a alteração).
Mutuamente exclusivo com ct_model:.
ct_model_force
| Atributo | Valor |
|---|---|
| Tipo | bool |
| Predefinido | false |
| Obrigatório | Não |
Opção de serviço. Sobrepõe-se à guarda de escrita: o componente aplica então a predefinição de ct_model: / ct_models: mesmo quando o módulo está emparelhado de fábrica ou já tem o mesmo valor. Isto substitui a calibração individual do módulo pela predefinição genérica desse modelo, por isso use-a apenas de forma deliberada, execute-a uma vez e remova-a.
O esquema rejeita ct_model_force: true a menos que ct_model: ou ct_models: também estejam presentes, pelo que a flag não pode ficar armada no YAML à espera de uma linha de modelo posterior.
rbamp:
ct_model: SCT_013_030
ct_model_force: true # one-off; remove both lines after the operation
start_current_ua
| Atributo | Valor |
|---|---|
| Tipo | inteiro, microampères |
| Valores permitidos | 0 (desligado) ou 10..2540 em passos de 10 |
| Predefinido | Nenhum (aplica-se a predefinição do próprio módulo) |
| Obrigatório | Não |
| Aplica-se a | Módulos STANDARD com contadores de energia no dispositivo; ignorado com aviso noutros casos |
Corrente de arranque para a contabilização de energia. Enquanto a corrente de um canal estiver abaixo deste valor, o módulo não conta energia nesse canal. Sem ela, em vazio a potência medida é ruído de qualquer sinal e vai-se acumulando lentamente nos contadores de importação e de exportação. As leituras instantâneas (corrente, potência, ...) não são afetadas — apenas os contadores de energia.
Valores fora do conjunto permitido (por exemplo 15 ou 3000) são rejeitados pelo esquema, pelo que um valor inválido nunca chega ao barramento. A definição fica guardada no módulo e é verificada após a escrita; um valor igual ao guardado não é reescrito.
rbamp:
start_current_ua: 400
Pode ler o valor guardado a partir de um lambda com id(meter1).read_start_current_ua() (devolve 65535 quando indisponível).
period_banks
| Atributo | Valor |
|---|---|
| Tipo | lista de entradas de banco |
| Entradas por lista | 1..8, cada bank: (0..7) listado uma vez |
| Predefinido | Nenhum |
| Obrigatório | Não |
| Aplica-se a | Módulos STANDARD que anunciam bancos de instantâneos (imagem 0x7E e posteriores); em qualquer outro módulo as entradas ficam indisponíveis e o log indica-o uma vez no arranque |
O módulo mantém oito bancos de snapshot independentes. Cada entrada mede um período — o tempo entre duas capturas do mesmo banco, medido pelo relógio do ESP32 — e publica as médias, os picos e a energia do período. Use-o para "energia por hora", "pico de corrente desde a última pressão" e perguntas semelhantes que os totais acumulados não respondem.
| Chave | Significado |
|---|---|
bank |
Número do banco 0..7. O banco 0 está livre nos módulos com contadores de energia no dispositivo; num módulo sem contadores o componente usa o próprio banco 0 e a entrada é ignorada com um aviso. |
interval |
Cadência automática opcional de latch, de pelo menos 1s. Sem ela, o banco só é capturado pela ação rbamp.latch_bank. |
power, reactive_power, apparent_power |
Média ao longo do período. |
energy, energy_exported |
Wh importadas / exportadas no período (não contadores — têm state_class: measurement). |
max_power, max_current, max_voltage, min_voltage |
Extremos dentro do período. |
period_length |
A duração do período em segundos, conforme medida pelo ESP32. |
channels |
Lista opcional, uma entrada por canal de corrente (primeira entrada = canal 0), cada uma com power, energy, energy_exported. |
O primeiro latch de um banco após o arranque, ou após o reinício do módulo, apenas inicia o período; os seus valores são descartados e os sensores publicam a partir do latch seguinte. Os latches de bancos diferentes ficam separados por pelo menos 150 ms.
rbamp:
id: meter1
period_banks:
- bank: 1
interval: 1h
power: {name: "Hour average power"}
energy: {name: "Hour energy"}
max_current: {name: "Hour peak current"}
- bank: 2 # latched by hand
energy: {name: "Energy since last press"}
period_length: {name: "Since last press, s"}
button:
- platform: template
name: "Latch bank 2"
on_press:
- rbamp.latch_bank:
id: meter1
bank: 2
Um exemplo completo está em example/std_banks.yaml.
bidirectional
| Atributo | Valor |
|---|---|
| Tipo | bool |
| Predefinido | false |
| Obrigatório | Não |
Ativa o caminho de energia exportada por canal (energy_exported, energy_exported_1, energy_exported_2). Quando true, a energia exportada é acumulada separadamente da energia importada.
Num módulo STANDARD a energia exportada vem dos contadores do próprio módulo, pelo que sobrevive a reinícios e é monótona. Num módulo BASIC a linha é unidirecional: os sensores energy_exported_* são aceites pelo esquema, mas publicam 0.
Declare energy_exported (ou _1 / _2) em sensor.platform: rbamp apenas quando bidirectional: true estiver definido. Os sensores de total geral energy_exported_total e energy_net não precisam desta chave.
rbamp:
bidirectional: true # needed for the per-channel energy_exported* sensors
new_address
Alteração de endereço (initialization) · 4.5 Endereço (0x30..0x31) (api-reference) · 6.1 Alteração de endereço — commit em duas fases (aprovado para produção) (api-reference)
| Atributo | Valor |
|---|---|
| Tipo | i2c_address (0x08..0x77) |
| Predefinido | Nenhum (opcional) |
| Obrigatório | Não |
Dispara uma alteração de endereço I²C única no arranque. Tem de ser diferente de address — o validador gera um erro se forem iguais.
Na firmware v1.3 é usado um commit em duas fases — produção OK sem controlo de provisionamento de fábrica. Comportamento de compatibilidade:
| Firmware | Comportamento |
|---|---|
| Anuncia commit de endereço em duas fases (v1.3+) | Caminho de produção — escrita preparada, confirmação explícita, commit, nova enumeração. |
| Não anuncia (legado v1.0-v1.2) | Recuo legado — escrita de fase única, exige o modo de provisionamento de fábrica. Regista WARN_FACTORY_MODE_REQUIRED se não estiver em provisionamento. |
Os módulos STANDARD também suportam new_address:; o componente aplica-o e volta a associar-se ao novo endereço da mesma forma.
O fluxo completo executa-se uma vez em setup():
- Sonde o
addressatual. Se o módulo não responder aí mas responder emnew_address, o componente adapta-se ao novo endereço com um aviso (assumindo que um arranque anterior já aplicou a alteração) e salta a escrita. - Verifique se a firmware anuncia o commit em duas fases. Sim → caminho de produção (ver abaixo). Não → caminho legado com verificação do modo de provisionamento.
- Caminho de produção (v1.3): preparar o novo endereço, confirmar, fazer commit → aguardar ~700 ms → voltar a sondar
new_address. Não é necessário nenhum controlo do modo de fábrica. - Caminho legado (v1.0-v1.2): escrita monofásica, requer o modo de provisionamento de fábrica do lado do módulo.
- O componente muda o seu endereço I²C interno através de
i2c::I2CDevice::set_i2c_address()paranew_addresse verifica que o módulo responde. - Se o módulo não responder após a alteração, o componente chama
mark_failed()e para.
Após uma alteração bem-sucedida: atualize o YAML para address: e remova new_address:. Se o módulo estiver no novo endereço no próximo arranque mas new_address: ainda estiver no YAML, a sondagem de arranque do endereço antigo falha, a sondagem do novo endereço tem êxito, o componente adapta-se com um aviso e não há nova escrita.
⚠ Apenas em modo de fábrica no firmware legado (v1.0-v1.2).
Os módulos de produção standard com firmware antigo saíram de fábrica com o modo de provisionamento desativado. Escrever new_address: num destes módulos sem o modo de fábrica será rejeitado (aviso WARN_FACTORY_MODE_REQUIRED). Na firmware v1.3 esta restrição deixa de existir — o componente deteta automaticamente o caminho de produção OK.
⚠ Reenumeração após commit. Após um commit bem-sucedido o módulo reinicia e reenumera no novo endereço. As chamadas seguintes dentro do mesmo setup() são encaminhadas para o novo endereço de forma transparente — mas qualquer outro mestre no barramento (uma ferramenta I²C bruta, uma sonda de depuração, outro ESP32) continua a considerar o módulo no endereço antigo até atualizar o seu próprio estado.
rbamp:
address: 0x50
new_address: 0x51 # remove this line after the first successful boot
Recuperação: se a alteração de endereço foi aplicada mas o módulo não responde, veja 10_troubleshooting.md → "Endereço alterado, mas o módulo não responde".
Referência cruzada: a referência de alteração de endereço em tempo de execução.
fleet_gc_enable (NOVO na v1.3)
General Call (difusão no endereço 0x00) (inicialização) · Multi-módulo — instantâneo simultâneo (medição por período) · 4.4 Configuração da frota (0x27..0x2F) (referência da API)
| Atributo | Valor |
|---|---|
| Tipo | bool |
| Predefinido | false |
| Obrigatório | Não |
| Aplica-se a | Módulos BASIC com suporte a instantâneo por General Call (firmware v1.3+); ignorado com uma linha de log no STANDARD |
Opcional: ativa a receção do instantâneo por General-Call enviado pelo mestre. Quando o ESP32 emite uma trama GC de 5 bytes para o endereço 0x00, todos os módulos com fleet_gc_enable: true (e um group_id: correspondente) tiram de forma atómica um instantâneo dos acumuladores do período num único instante do fio. Isto proporciona sincronização apertada entre subcontadores.
Comportamento de capacidade: no arranque o componente verifica se o firmware anuncia o instantâneo por General Call. Se não anunciar → aviso + ignorar sem aplicar:
[W][rbamp:xxx]: fleet_gc_enable requested but the module does not advertise general-call latch;
firmware v1.0-v1.2 doesn't support General-Call. Falling back to sequential
latch (~270 µs × N inter-module skew at 50 kHz).
Persistência: ao aplicar, o componente escreve REG_FLEET_CONFIG.bit0, guarda na flash via CMD_SAVE_USER_CONFIG e REPÕE o dispositivo — o modo GC é configurado na inicialização, não é alterável em tempo real. Através de leitura-comparação-escrita isto acontece uma vez no primeiro arranque; os arranques seguintes saltam-no.
rbamp:
- id: mains
fleet_gc_enable: true # opt-in, capability-gated
group_id: 1 # see below
- id: boiler
fleet_gc_enable: true
group_id: 1 # same group → synchronized
Referência cruzada: a referência Fleet Group-Commit, 04_hardware.md Frota com vários módulos.
group_id (NOVO na v1.3)
General Call (difusão no endereço 0x00) (inicialização) · Multi-módulo — instantâneo simultâneo (medição por período) · 4.4 Configuração da frota (0x27..0x2F) (referência da API)
| Atributo | Valor |
|---|---|
| Tipo | uint8_t (0..255) |
| Predefinido | 0 |
| Obrigatório | Não |
| Aplica-se a | Módulos BASIC; ignorado com uma linha de registo no STANDARD |
Um identificador de agrupamento para snapshot GC seletivo. O módulo aceita uma trama GC apenas se o campo de grupo da trama corresponder a este group_id OU for igual a 0x00 (all-call).
Casos de utilização:
-
Multi-inquilino: um ESP32 controla vários agrupamentos independentes de módulos (por exemplo, 3 apartamentos num mesmo quadro). Agrupamento 1 =
group_id: 1, agrupamento 2 =group_id: 2. O mestre emite uma trama GC com group=1 → só o agrupamento 1 tira um snapshot. -
Mono-inquilino: deixe
group_id: 0(chamada geral) ou definagroup_id: 1como etiqueta — o comportamento é idêntico, todos os módulos tiram instantâneo.
Persistência: escrito em REG_GROUP_ID e guardado na flash através de ler-comparar-escrever. Alterá-lo exige um arranque.
rbamp:
- id: apt1_mains
group_id: 1
- id: apt2_mains
group_id: 2
broadcast_latch (obsoleto, legado v0.4.0)
| Atributo | Valor |
|---|---|
| Tipo | bool |
| Predefinido | false |
| Obrigatório | Não |
| Estado | Obsoleto — substituído por fleet_gc_enable: (v1.3+). |
Um alias legado para o snapshot de difusão General-Call. Na v1.3 esta chave é aceite pelo esquema como sem efeito (para migração sem quebras a partir do YAML v0.4.0), mas não tem efeito. Para código novo, use fleet_gc_enable: — é condicionado por capacidade e funciona na firmware v1.3.
Será removida numa versão menor futura; aparece um aviso de descontinuação no log:
[W][rbamp:xxx]: 'broadcast_latch:' is deprecated since v1.3 — use
'fleet_gc_enable:' instead. This key has no effect.
Referência cruzada: a referência de commit de grupo da frota.
topology
| Atributo | Valor |
|---|---|
| Tipo | enum (SINGLE, SPLIT_PHASE, THREE_PHASE) |
| Predefinido | SINGLE |
| Obrigatório | Não |
Sugestão opcional, mantida por compatibilidade com versões anteriores. Não é necessária nos módulos STANDARD: o componente lê o número de canais, a variante e as capacidades do próprio módulo e dimensiona o conjunto de entidades a partir daí. Nos módulos BASIC, o número de canais deriva dos slots current[_1/_2] que declarar, e topology: só altera a linha impressa por dump_config.
rbamp:
topology: SINGLE # cosmetic; may be omitted
2. Plataforma de sensores — sensor.platform: rbamp
Cada bloco sensor: declara um conjunto de sensores com nome, associados ao componente pai rbamp:. A única chave obrigatória do bloco é rbamp_id.
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"
Todos os campos sob o bloco sensor: são opcionais, com uma regra: power, energy, power_factor, reactive_power e apparent_power requerem voltage E current declarados no mesmo bloco (os sensores de canal numerados power_N, energy_N, power_factor_N, reactive_power_N requerem current_N e voltage); caso contrário, esphome config falha com "power requires current to also be declared". Adicione internal: true a um sensor obrigatório que não queira como entidade do Home Assistant. Declare apenas as grandezas de que o seu cenário precisa — o componente lê apenas os registos correspondentes aos sensores declarados.
rbamp_id
| Atributo | Valor |
|---|---|
| Tipo | use_id(RbAmpComponent) |
| Obrigatório | Sim |
Referencia o bloco rbamp: ao qual este grupo de sensores está associado.
2.1 Campos simples
Corrente multicanal (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Janela de acesso aos canais (0x32 + 0x3C..0x3F) (api-reference)
Usado para módulos de tensão única (UI1, UI2, UI3, I1, I2, I3 e variantes de mais canais). Todos os campos são opcionais. Misturá-los com campos por fase (voltage_a, voltage_angle_b, etc.) gera um erro de validação.
Existem slots para até sete canais de corrente: current e current_1 ... current_6, e de forma semelhante power, energy e power_factor com os mesmos sufixos (power_3, energy_5, ...). energy_exported existe para os canais 0..2 (energy_exported, energy_exported_1, energy_exported_2). Um slot além do número de canais que o módulo reporta nunca publica. reactive_power existe apenas para os canais 0..2 (reactive_power, reactive_power_1, reactive_power_2); reactive_power_3 ... reactive_power_6 são aceites pelo esquema mas nunca publicam.
Cada campo aceita as subchaves padrão sensor.sensor_schema do ESPHome: name, id, filters, unit_of_measurement, accuracy_decimals, icon, e assim por diante.
voltage
Referência de registos RT (realtime-polling) · 4.10 Bloco em tempo real V03 (0x86..0xBD) (api-reference)
| Atributo | Valor |
|---|---|
| Unidade | V |
device_class |
voltage |
state_class |
measurement |
accuracy_decimals |
1 |
| Fonte | Tensão RMS da rede (registo instantâneo do módulo) |
Tensão RMS da rede. Lida em cada update() assim que o módulo estiver pronto. O float de 4 bytes é lido com repetição por byte (3 tentativas × 5 ms) e passa na verificação std::isfinite() e em |val| < 10000.
Zero é um valor válido para publicar: um evento de falha da rede ou de subtensão produz U ≈ 0 V e passa para o HA sem filtragem — o filtro de sanidade descarta apenas NaN/Inf, não zeros legítimos.
voltage:
name: "Mains Voltage"
filters:
- sliding_window_moving_average:
window_size: 3
send_every: 1
current / current_1 ... current_6
| Atributo | Valor |
|---|---|
| Unidade | A |
device_class |
current |
state_class |
measurement |
accuracy_decimals |
3 |
Corrente RMS para os canais 0, 1, 2, ... O canal 0 é a pinça CT principal; os canais 1 e 2 estão presentes nas variantes UI2 / UI3 e I2 / I3, e os canais 3..6 nas variantes de mais canais.
Num módulo BASIC, o número de canais ativos deriva do número de slots declarados: se só current estiver declarado, o componente usa 1 canal; com current e current_1, 2; ao acrescentar current_2, 3. Num módulo STANDARD, o número de canais vem do próprio módulo; slots declarados além dele simplesmente nunca são publicados.
current:
name: "Phase Current"
current_1:
name: "Load 1 Current"
current_2:
name: "Load 2 Current"
power / power_1 ... power_6
Referência de registos RT (realtime-polling) · 4.10 Bloco em tempo real V03 (0x86..0xBD) (api-reference)
| Atributo | Valor |
|---|---|
| Unidade | W |
device_class |
power |
state_class |
measurement |
accuracy_decimals |
1 |
| Dependências | power requer current + voltage; power_N requer current_N + voltage |
Potência ativa em watts, com sinal. Valores negativos = fluxo inverso (injeção na rede) nos módulos STANDARD. No BASIC, os valores instantâneos negativos dentro da janela do período são limitados a 0 ao nível da firmware — a média do período é ≥ 0. A potência ativa instantânea pode continuar negativa no momento da produção.
Declarar power sem current + voltage gera um erro de validação: power requires current to also be declared.
power:
name: "Active Power"
energy / energy_1 ... energy_6
Algoritmo do lado do mestre (period-metering) · 7 · Semântica (api-reference)
| Atributo | Valor |
|---|---|
| Unidade | Wh |
device_class |
energy |
state_class |
total_increasing |
accuracy_decimals |
3 |
| Dependências | energy requer current + voltage; energy_N requer current_N + voltage |
Energia consumida (importação) acumulada em Wh para o canal.
- Módulos 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 são monotónicos (não retrocedem quando o módulo reinicia ou um contador é reposto).
- Módulos BASIC — calculado no ESP32 a partir da potência média do período devolvida pelo módulo após cada instantâneo:
E_Wh[ch] += avg_P_W[ch] * master_dt_s / 3600
Em ambos os casos o valor é guardado na flash do ESP32 (NVS) a cada 5 minutos e num encerramento limpo (reinício / OTA), e restaurado antes do primeiro publish_state no arranque — isto evita que o painel Energia do HA interprete um 0 instantâneo como uma reposição do contador. No BASIC, uma falha súbita de energia perde no máximo os últimos 5 minutos de energia (≈ 5 Wh com uma média de 60 W). Quando o layout da NVS muda (subida de versão), o contador começa em 0.
state_class: total_increasing é obrigatório para o painel Energia do HA (Energy dashboard). O valor sobe de forma monótona; não diminui em funcionamento normal.
energy:
name: "Mains Energy"
energy_exported / energy_exported_1 / energy_exported_2
| Atributo | Valor |
|---|---|
| Unidade | Wh |
device_class |
energy |
state_class |
total_increasing |
accuracy_decimals |
3 |
| Dependências | Requer current + voltage + bidirectional: true |
Energia exportada (geração) em Wh para os canais 0..2, acumulada separadamente de energy. Defina bidirectional: true no bloco rbamp: ao declarar estes sensores. Nos módulos STANDARD os valores vêm dos contadores do módulo (persistentes, monótonos). Nos módulos BASIC os sensores são aceites mas publicam 0.
power_factor / power_factor_1 ... power_factor_6
| Atributo | Valor |
|---|---|
| Unidade | (dimensionless) |
device_class |
power_factor |
state_class |
measurement |
accuracy_decimals |
3 |
| Dependências | Exige current + voltage para o slot correspondente |
Fator de potência no intervalo −1..+1. Um PF negativo significa carga capacitiva ou indutiva; a convenção de sinal é definida pelo firmware. O filtro de sanidade (§B.5) descarta valores fora de |pf| > 10000; não há limite inferior.
power_factor:
name: "Power Factor"
reactive_power / reactive_power_1 / reactive_power_2
| Atributo | Valor |
|---|---|
| Unidade | VAr |
device_class |
reactive_power |
state_class |
measurement |
accuracy_decimals |
1 |
| Dependências | Exige current + voltage para o slot correspondente |
Potência reativa em var. Sem sinal (≥ 0), calculada como √(S² − P²), inclui distorção; sem precisão declarada. Cargas indutivas e capacitivas não são distinguidas. Lida do módulo em cada ciclo update(); publicada apenas para os canais 0..2 (reactive_power_3 ... reactive_power_6 são aceites pelo esquema, mas nunca publicam). Não é declarada precisão para a potência reativa.
reactive_power:
name: "Reactive Power"
Nota sobre device_class: reactive_power — o ESPHome aceita-o (a constante DEVICE_CLASS_REACTIVE_POWER) e o valor passa para o Home Assistant. No entanto, a lista oficial de device_class do Home Assistant mudou ao longo do tempo: em algumas versões reactive_power está disponível na interface e funciona com a unidade VAr, enquanto noutras é apresentado como sensor genérico sem ícone especializado nem conversão de unidade. Os dados são sempre publicados (são apenas um state); a única questão é como o HA apresenta o sensor no Lovelace. Se o sensor aparecer como unknown na sua versão do HA, é cosmético, não uma regressão funcional. Remova a chave reactive_power: do YAML se não usar o sensor.
apparent_power
| Atributo | Valor |
|---|---|
| Unidade | VA |
device_class |
apparent_power |
state_class |
measurement |
accuracy_decimals |
1 |
| Fonte | Calculado no mestre: S = V_rms × I_rms[0] |
| Dependências | Requer current + voltage |
Potência aparente em VA. Calculada pelo componente a partir dos valores U_rms e I0_rms lidos no mesmo ciclo update() — não é lido nenhum registo separado. As duas leituras têm de ter êxito no mesmo ciclo; se uma falhar (repetições esgotadas), nenhum estado é publicado nesse ciclo e o último valor no HA é mantido.
apparent_power está em SHARED_FIELDS e funciona com qualquer topologia, mas depende de voltage e current para o cálculo V × I.
apparent_power:
name: "Apparent Power"
2.2 Campos faseados (variantes multi-tensão)
Para módulos com mais de uma entrada de tensão (variantes bifásicas e trifásicas) os sensores são declarados por fase. O esquema aceita o grupo faseado em qualquer módulo; um slot só publica quando o módulo ligado reporta efetivamente o canal correspondente, caso contrário fica sem valor.
Campos simples e faseados são mutuamente exclusivos dentro de um mesmo bloco sensor:. O validador gera um erro:
Cannot mix single-phase fields (voltage, current, current_1, ...) with
phased fields (voltage_a/b/c, current_a/b/c, ...).
Todos os campos faseados partilham os mesmos valores predefinidos de sensor_schema que os seus equivalentes monofásicos (as mesmas unidades, device_class, state_class, accuracy_decimals).
| Campo | Unidade | device_class |
|---|---|---|
voltage_a / _b / _c |
V | voltagem |
current_a / _b / _c |
A | corrente |
power_a / _b / _c |
W | potência |
power_total |
W | potência |
energy_a / _b / _c |
Wh | energia |
energy_exported_a / _b / _c |
Wh | energia |
power_factor_a / _b / _c |
— | power_factor |
reactive_power_a / _b / _c |
VAr | reactive_power |
voltage_angle_b / _c |
° | — |
voltage_angle_b e voltage_angle_c publicam o ângulo de fase das tensões B e C em graus, em relação à fase A (a fase A é a referência de 0°, por isso não existe voltage_angle_a). Precisam de firmware do módulo que forneça os ângulos; em firmware mais antigo o componente regista um aviso no arranque e os sensores nunca publicam. Enquanto o ângulo não puder ser determinado, o valor é "unknown".
A validação de dependências por fase não é aplicada aos campos por fase (apenas _SINGLE_SLOT_DEPS para monofásico).
Example:
rbamp:
id: panel_meter
address: 0x50
sensor:
- platform: rbamp
rbamp_id: panel_meter
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_total:
name: "Total Active Power"
voltage_angle_b:
name: "Phase B Angle"
voltage_angle_c:
name: "Phase C Angle"
2.3 Campos partilhados (independentes da topologia)
Estes campos funcionam em qualquer grupo de topologia, incluindo o caso em que não é declarado nenhum sensor de corrente monofásico ou faseado (uma implementação apenas de tensão ou apenas de frequência).
frequency
| Atributo | Valor |
|---|---|
| Unidade | Hz |
device_class |
frequency |
state_class |
measurement |
accuracy_decimals |
0 |
Frequência da rede. Valores implausíveis (o módulo indica "ainda não medido") são descartados sem publicação, o que evita uma transição "Unknown" → 0 Hz → 50 Hz na entidade do HA durante o aquecimento.
frequency:
name: "Mains Frequency"
apparent_power
Veja a entrada sob os campos individuais acima. apparent_power requer current e voltage, por isso pertence a um bloco de sensor monofásico.
energy_total / energy_exported_total / energy_net
| Sensor | Unidade | state_class |
Significado |
|---|---|---|---|
energy_total |
Wh | total_increasing |
Energia importada, todos os canais do módulo |
energy_exported_total |
Wh | total_increasing |
Energia exportada, todos os canais do módulo |
energy_net |
Wh | total |
Importação menos exportação. Pode diminuir. |
Totais gerais sobre todos os canais do módulo, obtidos dos contadores de energia do próprio módulo (módulos STANDARD). Sobrevivem a reinícios do ESP32 e do módulo, são monotónicos através de reinícios do módulo e reposições de contadores (exceto energy_net, que é a diferença de dois valores monotónicos), e são também guardados na NVS a cada 5 minutos e num desligamento limpo. Não precisam da chave bidirectional: nem de declaração complementar de current/voltage.
Num módulo sem contadores de energia no dispositivo (BASIC) estas chaves validam mas nunca publicam; o componente regista um aviso no arranque. Use aí os sensores energy por canal.
sensor:
- platform: rbamp
rbamp_id: meter1
energy_total:
name: "Energy Imported"
energy_exported_total:
name: "Energy Exported"
energy_net:
name: "Energy Net"
reactive_energy / reactive_energy_exported
| Atributo | Valor |
|---|---|
| Unidade | varh |
state_class |
total_increasing |
accuracy_decimals |
3 |
Energia reativa (importação / exportação) sobre todos os canais, a partir dos mesmos contadores do dispositivo e com a mesma persistência de energy_total. Apenas módulos STANDARD; nos outros as chaves validam mas nunca publicam.
phase_sequence
| Atributo | Valor |
|---|---|
| Unidade | — |
accuracy_decimals |
0 |
Rotação de fase de um módulo de três tensões: 1 = direta, 2 = inversa, 3 = anómala. "Unknown" enquanto não puder ser determinada (menos de três entradas de tensão ativas). Requer um firmware do módulo que a forneça; caso contrário o componente regista um aviso no arranque e o sensor nunca publica. Num lambda, id(meter1).get_phase_sequence_str() devolve "forward", "reverse", "abnormal", "n/a" ou "unavailable".
2.4 Regras de validação do esquema
O validador Python _validate_topology_consistency aplica duas classes de regras durante o esphome config / compilação — antes de qualquer código C++ correr.
Exclusão mútua de topologia
Campos monofásicos (voltage, current, current_1, etc.) e campos faseados (voltage_a, voltage_b, etc.) não podem coexistir num mesmo bloco sensor:. Uma tentativa de os misturar:
Cannot mix single-phase fields (voltage, current, current_1, ...) with
phased fields (voltage_a/b/c, current_a/b/c, ...). Pick one group based
on your rbAmp SKU.
O grupo faseado inclui voltage_angle_b / voltage_angle_c.
Requisitos complementares por slot (apenas monofásico)
Cada campo derivado exige os campos de entrada de que o módulo precisa para o calcular:
| Campo declarado | Complementos obrigatórios |
|---|---|
power / _1 ... _6 |
current (ou _1 ... _6, mesmo sufixo) + voltage |
energy / _1 ... _6 |
current (ou _1 ... _6, mesmo sufixo) + voltage |
power_factor / _1 ... _6 |
current (ou _1 ... _6, mesmo sufixo) + voltage |
reactive_power / _1 / _2 |
current (ou _1 ... _6, mesmo sufixo) + voltage |
apparent_power |
current + voltage |
energy_exported*, energy_total, energy_exported_total, energy_net, reactive_energy* e phase_sequence não têm requisitos de sensor complementar no esquema.
A falta de um complemento gera:
`power` requires `current` to also be declared — the underlying chip
cannot compute it without that input.
Outras regras ao nível do bloco rbamp:
| Regra | Descrição |
|---|---|
ct_model: ↔ ct_models: mutuamente exclusivos |
Apenas um dos dois pode ser usado por bloco rbamp: — caso contrário, um erro de validação. |
new_address ≠ address |
Se coincidirem — cv.Invalid. |
address no intervalo 0x08..0x77 |
cv.i2c_address é aplicado. |
update_interval ≥ 1s |
Intervalos mais curtos são recusados. |
latch_interval ≥ update_interval |
Um intervalo de snapshot mais curto é rejeitado. |
ct_models: tem 1..16 entradas |
Listas mais longas são rejeitadas. |
group_id está entre 0..255 |
Valores fora de intervalo são rejeitados. |
start_current_ua é 0 ou 10..2540 em passos de 10 |
Qualquer outro valor é rejeitado. |
ct_model_force: true requer ct_model: ou ct_models: |
Rejeitado por si só. |
period_banks: — cada bank uma vez, interval ≥ 1s |
Um banco duplicado, um banco fora de 0..7 ou um intervalo mais curto é rejeitado. |
Código de modelo de pinça válido para o sensor_class fixado |
Um código não permitido para a classe é rejeitado, com a lista dos valores permitidos. |
Todos os erros de validação são reportados durante esphome compile com uma mensagem legível que aponta para a chave com problema. Não é preciso gravar o hardware para encontrar um erro de configuração.
3. Fluxo de dados e temporização
Polling — módulo único (realtime-polling) · 3. DATA_VALID (0xCE) nunca passa a 1 (resolução de problemas) · 4 · Mapa de registos (produção v1.3) (referência da API)
O fluxo conceptual de um único ciclo update():
Module (autonomous) ESP32 (ESPHome component)
───────────────────────────────── ────────────────────────────────────────────
Measures & computes the
instantaneous block (RMS / P / PF / Q)
↓ (~100 ms per cycle)
Atomically publishes the block update() fires every update_interval (60 s)
of instantaneous registers ↓
↓ phase 1 — snapshot:
write the snapshot command
Closes the period accumulator, 50 ms timeout (non-blocking)
opens a new one ↓ (main loop keeps running)
↓
wait 50 ms phase 2 — period snapshot:
read the valid flag
read per-channel average powers
E_Wh[ch] += avg_P × dt_s / 3600
save to NVS if 5 minutes elapsed
↓
phase 3 — instantaneous values:
read the status register
read U_rms, I[0..n]_rms, P[0..n],
PF[0..n], Q[0..n], frequency
publish all bound sensors
↓
Push state to HA over the native API
O diagrama mostra o fluxo BASIC baseado em snapshots. Um módulo STANDARD mantém os seus próprios contadores de energia: em cada update() o componente lê os valores instantâneos e o snapshot do contador (uma transação coerente) e soma a diferença aos seus totais acumulados, pelo que o passo de snapshot não é usado para a energia.
Temporizações características:
| Evento | Cadência |
|---|---|
| Confirmação interna do bloco instantâneo pelo módulo | ~100 ms |
Chamada update() |
update_interval (60 s por predefinição) |
| Timeout de estabilização após o comando de snapshot | 50 ms (não bloqueante) |
| Guardar na NVS | A cada 5 minutos |
| Pausa entre repetições por byte | 5 ms, até 3 tentativas |
| Janela de escrita na flash ao gravar o modelo | ~700 ms (o módulo responde NACK durante todo o tempo) |
O timeout de estabilização do instantâneo não bloqueia — o agendador cooperativo do ESPHome continua a servir o Wi-Fi, a API e os outros componentes durante os 50 ms de espera. As restantes fases de update() (leitura dos registos instantâneos) correm imediatamente após regressar da fase de instantâneo.
O aviso [W][component:522]: rbamp took a long time for an operation (XXX ms) é esperado e inofensivo quando aparece. Na firmware v1.3 o componente lê o bloco de valores instantâneos com uma única leitura em rajada (auto-incremento READ), pelo que um ciclo saudável fica bem abaixo de 30 ms. O aviso surge quando o caminho em rajada recua para leituras por registo (4 transações por float, até 36 transações a 50 kHz, mais repetições) — normalmente devido a um barramento marginal ou a firmware antigo sem a capacidade de leitura em rajada.
4. Definições do barramento I2C
O componente rbamp herda o barramento I²C configurado no bloco de topo i2c:. Definições recomendadas no firmware atual:
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # 100 kHz causes periodic NACKs; 50 kHz reduces them ~5x
scan: true # optional: logs the addresses found at boot
Velocidade do barramento: use 50kHz em mestres baseados em ESP-IDF (ESP32 com ESPHome ou Arduino). O módulo faz NACK periodicamente a 100 kHz (uma parte notável das transações) devido a uma interação conhecida com o driver i2c_master do ESP-IDF (confirmada em esp-idf issue #9426, marcada "Won't Do" pela Espressif). O firmware v1.1/v1.3 reforçou o lado do módulo, mas a interação com o driver persiste — 50 kHz é a recomendação permanente. A mitigação em três camadas do componente (repetição + sanidade + 50 kHz) reduz a taxa efetiva de leituras más para abaixo de 1%.
Resistências de pull-up: recomenda-se 4.7 kΩ para 3.3 V em SDA e SCL. Valores maiores (10 kΩ) aumentam o tempo de subida e a taxa de NACK a 100 kHz.
Vários dispositivos: o barramento I²C do ESP32 suporta até 112 dispositivos em endereços distintos de 7 bits. Use address: e new_address: para atribuir um endereço único a cada módulo. scan: true no bloco i2c: regista cada endereço que responde no arranque — verifique que todos os módulos são detetados antes de ativar a medição por período.
O mapa completo de registos a nível de fios e o conjunto de comandos do módulo estão na página pública de referência da API. Para o utilizador típico do esquema YAML este capítulo é suficiente — cada registo fica oculto atrás da interface declarativa do componente.
5. Superfície de identidade (NOVO na v1.3) — métodos públicos C++
Deteção automática da variante do módulo (inicialização) · 3. DATA_VALID (0xCE) nunca passa a 1 (resolução de problemas) · Códigos de erro (REG_ERROR = 0x02) (resolução de problemas)
O componente v1.3 expõe getters de identidade / diagnóstico acessíveis a partir de um lambda: no YAML e através da plataforma template. Todos os métodos devolvem uma std::string (por compatibilidade com text_sensor) ou tipos primitivos — sem lançamento de exceções; tudo através de estado em cache.
| Método | Tipo de retorno | Fonte | Descrição |
|---|---|---|---|
get_variant_str() |
std::string |
REG_HW_VARIANT (0x55) |
"UI1"/"UI2"/"UI3"/"I1"/"I2"/"I3"/"UNK" — a variante do módulo |
get_capability_hex() |
std::string |
registo de capacidades | "0xNNNN" — o mapa de bits de capacidades de 16 bits, para diagnóstico |
get_uid_hex() |
std::string |
REG_UID (0x5C × 12 bytes) |
hex de 24 caracteres (UID de 96 bits do chip) |
get_last_error_str() |
std::string |
REG_ERROR (0x02) |
"OK"/"ERR_PARAM"/"ERR_BUSY"/"ERR_LATCH"/"ERR_CRC" |
get_event_flags() |
uint8_t |
REG_EVENT_FLAGS (0x03) |
bits persistentes: bit3=ERR_LATCH, bit5=ADDR_CHANGED, etc. |
get_firmware_version() |
uint8_t |
REG_VERSION (0x01) |
o byte de versão do módulo (por exemplo, 0x04 na firmware BASIC v1.3) |
get_std_image_version() |
uint32_t |
Apenas STANDARD | Versão da imagem do módulo em execução; 0 = desconhecida ou BASIC |
get_phase_sequence_str() |
std::string |
Apenas STANDARD | "forward"/"reverse"/"abnormal"/"n/a"/"unavailable" |
read_start_current_ua() |
uint16_t |
Apenas STANDARD | Leitura atual da corrente de arranque guardada, em µA; 65535 = indisponível |
read_gc_tick_received() |
uint16_t |
REG_GC_LAST_TICK (0x58) |
último valor de tick capturado da trama GC |
get_capability_cached() |
uint16_t |
mapa de bits de capacidades em cache | o mapa de bits lido no arranque, sem transação no barramento |
Cache: variant / capability / uid / firmware_version são lidos uma vez em setup() e guardados em cache — chamadas repetidas não vão ao barramento. last_error_str() / event_flags() / gc_tick são lidos em cada chamada para estarem atualizados.
Usar através de um text_sensor template
text_sensor:
- platform: template
name: "Mains variant"
update_interval: 30s
lambda: 'return id(mains_meter).get_variant_str();'
# → entity_id: sensor.mains_variant, value: "UI1"
- platform: template
name: "Mains capability"
update_interval: 30s
lambda: 'return id(mains_meter).get_capability_hex();'
# → the capability bitmap as hex, "0xNNNN" (diagnostics only)
- platform: template
name: "Mains UID"
update_interval: 30s
lambda: 'return id(mains_meter).get_uid_hex();'
- platform: template
name: "Mains last error"
update_interval: 30s
lambda: 'return id(mains_meter).get_last_error_str();'
- platform: template
name: "Mains firmware version"
update_interval: 30s
lambda: 'char b[8]; snprintf(b, sizeof(b), "0x%02X", id(mains_meter).get_firmware_version()); return std::string(b);'
Estes text_sensors aparecem no HA como sensor.mains_variant e assim por diante — úteis para painéis de inventário, cenários de rastreamento de ativos e verificação pós-gravação.
Usar através de lambda: em automações
sensor:
- platform: rbamp
rbamp_id: mains
energy: { name: "Mains Energy" }
# Read the stored values from a lambda (e.g. in an on_boot automation)
esphome:
on_boot:
then:
- lambda: |-
ESP_LOGI("meter", "variant=%s", id(mains).get_variant_str().c_str());
6. Sincronização de frota e GC (NOVO na v1.3)
transmit_gc_frame() — emissão GC programática
bool transmit_gc_frame();
Emite uma trama de snapshot General-Call de 5 bytes para o endereço do barramento 0x00. O byte de grupo é o group_id: da instância e o tick é um contador de auto-incremento; o método devolve true quando a escrita no barramento tem êxito. Apenas módulos BASIC — num módulo STANDARD regista um aviso e não faz nada:
START | 0x00 | A | 0xA5 | A | 0x27 | A | group | A | tick_lo | A | tick_hi | A | STOP
Todos os módulos com fleet_gc_enable: true + um group_id: correspondente (ou group_id: 0) tiram um snapshot dos seus acumuladores de período de forma síncrona, num único instante no fio. O valor do tick é guardado por cada módulo para verificação de sincronização (read_gc_tick_received()).
Emissão automática: o componente emite uma trama GC automaticamente em update() se fleet_gc_enable: true e o firmware anunciar instantâneo por General Call. É necessária uma emissão manual apenas para sincronização extra (por exemplo, num acionador de evento do lado do HA).
Verificação de capacidade: se a firmware não anunciar o snapshot general-call — aviso, sem emissão.
fleet_apply_now() — força nova aplicação de leitura-comparação-escrita
bool fleet_apply_now();
Repete à força a leitura-comparação-escrita das definições da frota: relê a configuração de frota do módulo e o group id, compara-os com fleet_gc_enable: / group_id: do YAML e escreve a diferença. Devolve false (e não faz nada) num módulo STANDARD.
Caso de uso: depois de um módulo ser reposto com as predefinições com uma ferramenta de depuração, ou para verificação pós-OTA de que a configuração da frota foi aplicada.
7. Serviços da API nativa (NOVO na v1.3) — automações de recuperação
Códigos de erro (REG_ERROR = 0x02) (troubleshooting) · 6.7 Recuperação do estado de erro — árvore de decisão (api-reference)
O componente v1.3 não regista serviços automaticamente — quem o faz é o YAML. Mas os métodos públicos write_clear_error() / write_reset() / transmit_gc_frame() foram concebidos para serem usados através do padrão api: services:. Receitas canónicas:
api:
port: 6053
services:
# Recovery: clear REG_ERROR + EVENT_FLAGS bit3
- service: mains_clear_error
then:
- lambda: 'id(mains).write_clear_error();'
# Maintenance: soft reset (preserves flash)
- service: mains_reset
then:
- lambda: 'id(mains).write_reset();'
# Fleet: manual GC snapshot (beyond the auto-emit in update())
- service: fleet_latch_now
then:
- lambda: 'id(mains).transmit_gc_frame();' # group = this instance's group_id, tick auto-increments
# Maintenance: force fleet-config re-apply (post-OTA verify)
- service: mains_fleet_apply
then:
- lambda: 'id(mains).fleet_apply_now();'
Depois disto, o HA pode chamar os serviços a partir de automatismos:
automation:
- alias: "Auto-clear meter error on detection"
trigger:
platform: state
entity_id: sensor.mains_last_error
from: "OK"
action:
- delay: 60s # wait one update_interval to confirm a persistent error
- service: esphome._mains_clear_error
- condition: state
entity_id: sensor.mains_last_error
state: "ERR_PARAM"
- service: persistent_notification.create
data:
title: "Meter parameter error"
message: "Meter at {{ states('sensor.mains_capability') }} reports ERR_PARAM after auto-clear retry. Check YAML config."
8. Erro e recuperação (v1.3) — REG_ERROR vs bit3 de EVENT_FLAGS
Na v1.3 o módulo tem dois canais de erro independentes:
| Canal | Registo | Semântica do latch | A limpar |
|---|---|---|---|
| Sincronização (última escrita) | REG_ERROR (0x02) |
a última escrita prevalece, sobrescrita pela operação seguinte | write_clear_error() ou a operação bem-sucedida seguinte |
| Assíncrono durável | REG_EVENT_FLAGS bit3 (0x03) |
persistente, volta a fixar-se durante algumas centenas de milissegundos se a causa não for resolvida | write_clear_error() (uma operação limpa ambos) |
Padrão de leitura
// Sync — fresh after the last operation
std::string err = id(mains).get_last_error_str(); // "ERR_PARAM" / "OK" / ...
// Durable — sticky bit3, sees errors even between polls
uint16_t flags = id(mains).get_event_flags();
bool latched_error = (flags & (1 << 3)) != 0;
Semântica de recuperação
Limpar apenas o REG_ERROR não é suficiente se a firmware voltar a fixar o bit3:
id(mains).write_clear_error(); // clears REG_ERROR + EVENT bit3
delay(300); // wait for the re-latch window
uint16_t flags_after = id(mains).get_event_flags();
if (flags_after & (1 << 3)) {
// Root cause not resolved — firmware re-latched bit3
ESP_LOGW("rbamp", "ERROR persists after clear — check config / param");
}
Para uma recuperação completa:
- Elimine a causa (corrija o código do modelo CT no YAML, corrija o sensor_class).
write_clear_error()— limpa REG_ERROR + bit3 de EVENT_FLAGS.- Verifique via
get_event_flags()após ~300 ms que o bit3 não voltou a ser fixado.
Ver 10_troubleshooting.md §6 Erro e recuperação.
Origem e problemas: rb-amp/rbamp-esphome · esta página no repositório: docs/09_api_reference.md (v1.9.1)