rbAmp
PT
Loja
Docs
Atualizado a · Editar no GitHub

09 · Referência do esquema YAML

Mapa de registos rbAmp — espaço de endereços da página 0 (0x00..0xFF)

Instantâneo atómico do período — uma escrita fecha o período e abre o seguinte

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:

  1. Bloco do componente — rbamp:
  2. Plataforma de sensores — sensor.platform: rbamp
  3. Fluxo de dados e temporização
  4. Definições do barramento I²C

1. Bloco do componente — rbamp:

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.

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

YAML
rbamp:
  id: kitchen_meter

address

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

YAML
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

Atributo Valor
Tipo time (string de duração do ESPHome)
Predefinido 60s
Obrigatório Não

Com que frequência update() corre. Cada chamada:

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

YAML
rbamp:
  update_interval: 30s   # more frequent dashboard updates, more traffic

latch_interval

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

YAML
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

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.

Nota

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.

YAML
rbamp:
  drdy_pin: GPIO4

sensor_class

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.

YAML
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

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
Nota

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.

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

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

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

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

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

YAML
rbamp:
  bidirectional: true   # needed for the per-channel energy_exported* sensors

new_address

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

  1. Sonde o address atual. Se o módulo não responder aí mas responder em new_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.
  2. 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.
  3. 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.
  4. Caminho legado (v1.0-v1.2): escrita monofásica, requer o modo de provisionamento de fábrica do lado do módulo.
  5. O componente muda o seu endereço I²C interno através de i2c::I2CDevice::set_i2c_address() para new_address e verifica que o módulo responde.
  6. 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.

Segurança

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

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

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:

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

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

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 defina group_id: 1 como 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.

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

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

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

YAML
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

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

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.

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

YAML
current:
  name: "Phase Current"
current_1:
  name: "Load 1 Current"
current_2:
  name: "Load 2 Current"

power / power_1 ... power_6

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.

YAML
power:
  name: "Active Power"

energy / energy_1 ... energy_6

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

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

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

YAML
reactive_power:
  name: "Reactive Power"
Nota

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.

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

Text
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".

Nota

A validação de dependências por fase não é aplicada aos campos por fase (apenas _SINGLE_SLOT_DEPS para monofásico).

Example:

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

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

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

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

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

O fluxo conceptual de um único ciclo update():

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

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:

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

Nota

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++

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

YAML
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

YAML
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

C++
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:

Text
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

C++
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

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:

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

YAML
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

C++
// 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:

C++
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:

  1. Elimine a causa (corrija o código do modelo CT no YAML, corrija o sensor_class).
  2. write_clear_error() — limpa REG_ERROR + bit3 de EVENT_FLAGS.
  3. 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)