02 · Níveis de módulo
O rbAmp é fornecido em duas linhas de módulos: BASIC e STANDARD (STD). Cada nível é uma combinação completa de revisão de hardware e versão de firmware, não apenas uma flag no firmware. Mudar de nível exige substituir fisicamente o módulo, não uma atualização de firmware.
O componente ESPHome funciona com as duas linhas de módulos a partir de um único YAML: o esquema é partilhado e o componente identifica automaticamente a linha de módulo ligada (BASIC ou STANDARD (STD)) no arranque. As diferenças estão nos dados que o módulo exporta de facto e nas chaves YAML que têm significado em cada linha.
Níveis
BASIC — nível de entrada
A firmware mantém a medição de consumo unidirecional: a potência ativa média num período nunca pode ser negativa — os segmentos reversos dentro da janela são zerados antes da integração. Em termos de comportamento, isto assemelha-se a um contador mecânico de disco clássico.
- A energia é integrada no ESP32 a partir da potência média do período que o módulo devolve após cada instantâneo, e guardada na flash do ESP32 (NVS).
- O sensor
energy_exportedexiste no esquema YAML (por compatibilidade de configuração), mas no BASIC publica sempre0. - Os sensores de energia de total geral (
energy_total,energy_exported_total,energy_net,reactive_energy,reactive_energy_exported) validam mas nunca publicam no BASIC. - Aplicações típicas: apartamentos sem geração no local, subcontagem de cargas específicas (esquentadores, motores, eletrodomésticos, AVAC).
STANDARD (STD) — bidirecional, energia no dispositivo
STANDARD (STD) é a linha de módulos atual. Mede importação e exportação separadamente e mantém os seus próprios contadores de energia acumulada dentro do módulo.
- Mesmo YAML. O componente reconhece um módulo STANDARD (STD) no arranque e obtém o número de canais, a variante e as funcionalidades disponíveis a partir do módulo. Não define um nível nem precisa de
topology:. - Energia a partir dos contadores do módulo. O componente acumula os contadores do módulo em vez de integrar a potência por si, pelo que os totais sobrevivem a reinícios do ESP32 e do módulo, mantêm-se monótonos entre reinícios do módulo e reposições de contadores, e não derivam. Os valores são ainda guardados na flash do ESP32 (NVS) a cada 5 minutos e no encerramento limpo (reinício / OTA).
- Novos sensores:
energy_total,energy_exported_total,energy_net(importação − exportação, pode diminuir),reactive_energy,reactive_energy_exported— totais gerais sobre todos os canais; em variantes de três tensões tambémvoltage_angle_b,voltage_angle_cephase_sequence. - Energia
energyeenergy_exportedpor canal (combidirectional: true) vêm dos mesmos contadores. start_current_ua:define uma corrente de arranque abaixo da qual um canal não conta energia, para que o ruído em vazio não se acumule nos contadores.- Aplicações típicas: casas com geração solar/eólica, armazenamento em bateria, carregadores de VE, qualquer instalação em que a importação e a exportação tenham de ser medidas separadamente e instalações em que os totais de energia têm de sobreviver a reinícios.
Num módulo STD a energia vem dos contadores próprios do módulo; latch_interval aplica-se apenas ao BASIC.
As chaves que existem apenas para a linha de módulos BASIC (fleet_gc_enable:, group_id:, broadcast_latch:, latch_interval: para o caminho de energia do lado do mestre) são ignoradas num módulo STANDARD, com uma linha de registo.
Matriz de capacidades
| Capacidade | BASIC | STANDARD |
|---|---|---|
| Tensão RMS | sim | sim |
| Corrente RMS (1..3 canais, mais nas variantes de mais canais) | sim | sim |
| Potência ativa (float com sinal) | sim | sim |
| Fator de potência | sim | sim |
| Potência reativa (lida do módulo, canais 0..2; sem sinal, calculada como √(S² − P²), inclui distorção; sem precisão declarada) | sim | sim |
| Potência aparente (apenas CH0) | sim (U × I[0], calculado no ESP32) |
sim (a partir do módulo) |
| Frequência da linha | sim | sim |
Sensor energy (Wh importados), guardado na NVS |
sim (integrado no ESP32) | sim (a partir dos contadores do dispositivo) |
Sensor energy_exported (requer bidirectional: true) |
sempre 0 | sim |
| A energia sobrevive a reinícios do ESP32 e do módulo | Apenas ESP32 | sim |
Totais gerais: energy_total, energy_exported_total, energy_net |
não | sim |
Energia reativa: reactive_energy, reactive_energy_exported |
não | sim |
start_current_ua: |
não | sim |
voltage_angle_b/_c, phase_sequence (variantes de três tensões) |
não | sim |
ct_models: por canal |
sim | apenas se o módulo guardar modelos por canal; caso contrário recusado com uma linha de log |
fleet_gc_enable: / group_id: sincronização general-call |
sim (firmware v1.3+) | ignorado |
O componente lê apenas aquilo para que os sensores estão declarados — um registo não declarado nunca é pedido.
Chaves YAML por nível
bidirectional: (predefinido false)
Ativa os sensores de energia exportada por canal (energy_exported, energy_exported_1, energy_exported_2).
rbamp:
id: solar_meter
address: 0x51
bidirectional: true # meaningful on STANDARD; on BASIC the export sensors read 0
No STANDARD a energia exportada vem dos contadores do módulo. No BASIC a chave é aceite pelo esquema sem erro, mas energy_exported devolve sempre 0. Os sensores de total geral energy_exported_total e energy_net não precisam desta chave.
sensor_class: — fixar a família do sensor
rbamp:
id: meter1
sensor_class: SCT_013 # default SCT_013
Aceite em ambas as linhas de módulos. Na firmware v1.2+ o valor é escrito na flash e torna-se uma pré-condição para gravar o modelo de CT: o módulo recusa gravar o modelo se a classe não estiver definida. Um valor que o módulo já tem não é escrito novamente.
Valores enumerados: SCT_013 (pinças SCT-013 de núcleo dividido, predefinido), WIRED_CT e BUILTIN_CT (módulos fornecidos calibrados em conjunto com o respetivo sensor incorporado). Num módulo emparelhado de fábrica destes, uma alteração de classe ou de modelo a partir do YAML é recusada com uma linha de registo, para proteger a calibração individual.
ct_model: / ct_models: — modelo de pinça CT
Um único perfil global para todos os canais:
rbamp:
id: meter1
ct_model: SCT_013_030 # all channels — SCT-013-030
Ou um perfil por canal (para UI3 com pinças mistas):
rbamp:
id: meter_ui3
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
Aceite em ambas as linhas de módulos, mutuamente exclusivas. No firmware v1.2+ o módulo carrega automaticamente os coeficientes de fábrica para o modelo selecionado — não são necessários passos adicionais de calibração. No firmware anterior o valor é guardado como marcador de modelo.
- Trocar o calibre do SCT mantém a precisão de fábrica: o componente conclui a troca (um reinício do módulo no fluxo é normal no firmware até 1.4.19; o firmware mais recente corrige no módulo) e escala as leituras para o sensor selecionado.
- Proteções de escrita: um valor igual não é escrito; num módulo fornecido em par de fábrica a alteração é recusada com uma linha de log.
ct_model_force: true(opção de serviço, válida apenas em conjunto comct_model:/ct_models:) sobrepõe-se a isto deliberadamente. ct_models:por canal num módulo STANDARD exige que o módulo guarde modelos por canal; caso contrário, o componente recusa de forma ruidosa (aviso, chaves ignoradas) — usect_model:.
Para mais sobre a seleção de um modelo, veja 03_sensor_selection.md.
new_address: — atribuição única de endereço I²C
rbamp:
id: meter1
address: 0x50
new_address: 0x51 # one-shot; remove after a successful boot
Aceite em ambas as linhas de módulos. Na firmware v1.3+ a alteração de endereço é produção OK — o componente usa um protocolo de commit em duas fases (preparar → armar → commit → reiniciar) sem necessidade de modo especial. Na firmware legada (v1.0-v1.2) o recurso de fase única exige o modo de provisionamento de fábrica; consulte a documentação do módulo ou o fornecedor para o procedimento de ativação. O modo de provisionamento de fábrica continua a ser necessário em todas as versões de firmware para as operações de calibração (saveGains) e reposição de fábrica.
Fluxo de execução numa única passagem de arranque: o componente sonda o endereço atual, escreve o novo endereço e guarda-o na flash, reinicia o módulo e verifica a resposta no novo endereço. Após o êxito, atualize o YAML para address: 0x51 e remova new_address:. Se o componente verificar que o endereço antigo está silencioso e o novo responde, adapta-se automaticamente com um aviso no registo (caso um arranque anterior já tenha aplicado a alteração).
fleet_gc_enable: / group_id: — instantâneo síncrono para um barramento com vários módulos
rbamp:
- id: meter1
fleet_gc_enable: true # v1.3 production path — recommended
group_id: 1 # cluster id (modules in the same group snapshot together)
Quando ativado, o componente envia uma trama de general-call de 5 bytes para o endereço de difusão I²C — sincronizando o snapshot do período em todos os módulos do mesmo group_id numa única transação.
No firmware BASIC v1.3 o instantâneo por General Call é opt-in e condicionado por capacidade. O componente verifica no arranque se o firmware o anuncia e ativa o caminho automaticamente quando a chave YAML e o firmware estão de acordo. Em firmware antigo (v1.0..v1.2) não é anunciado; o componente recorre a um instantâneo sequencial para cada módulo individualmente e regista uma linha informativa. Num módulo STANDARD estas chaves são ignoradas com uma linha de log.
A chave legada broadcast_latch: continua aceite pelo esquema por compatibilidade retroativa, mas não tem efeito. Use fleet_gc_enable: + group_id:.
A diferença entre módulos num barramento de 50 kHz é da ordem de ~540 µs × N, que é inferior a 0.003% de um período de 60 segundos. Nos totais diários do HA esta irregularidade é impercetível.
topology: — sugestão de topologia
rbamp:
id: meter1
topology: SINGLE # SINGLE / SPLIT_PHASE / THREE_PHASE
Opcional e não necessário nos módulos STANDARD, em que o número de canais e a variante vêm do próprio módulo. Nos módulos BASIC o componente deduz o número de canais a partir dos slots de sensor declarados (se current_1 estiver declarado, há pelo menos 2 canais). A chave é cosmética e aparece na linha de log dump_config.
drdy_pin: — interrupção opcional de dados prontos
rbamp:
id: meter1
drdy_pin: GPIO15
Aceite em ambas as linhas de módulos. Liga-se à saída DRDY open-drain opcional do módulo. O pino é configurado e registado, mas os registos instantâneos são consultados em update_interval independentemente disso. Com um update_interval: 60s típico, a chave pode ser omitida.
Requer uma resistência de pull-up de 10 kΩ no GPIO do mestre para 3.3 V (a saída é open-drain; não há pull-up interno do lado do módulo). Ver 04_hardware.md.
Tabela-resumo — chave YAML × linha de módulo
| Chave YAML | BASIC | STANDARD | Notas |
|---|---|---|---|
address: |
sim | sim | — |
update_interval: |
sim | sim | Mínimo 1s |
latch_interval: |
sim | n/a | Separa a cadência de snapshot/energia da cadência de leitura; o STANDARD lê os seus contadores em cada update() |
drdy_pin: |
sim | sim | Opcional, precisa de um pull-up de 10 kΩ; não usado como acionador de leitura |
topology: |
sim | não necessário | Sugestão informativa |
sensor_class: |
sim | sim | Não reescrito quando igual; recusado em módulos fornecidos em par de fábrica |
ct_model: / ct_models: |
sim | sim | Mutuamente exclusivas; a lista por canal em STANDARD exige um módulo que a guarde |
ct_model_force: |
sim | sim | Opção de serviço; o esquema exige uma chave de modelo |
bidirectional: |
aceite (a exportação lê 0) | funciona | Necessário para os sensores por canal energy_exported* |
start_current_ua: |
ignorado com um aviso | funciona | 0 ou 10..2540 em passos de 10 |
new_address: |
sim | sim | Produção OK na firmware BASIC v1.3+; única vez |
fleet_gc_enable: / group_id: / broadcast_latch: |
sim | ignorado | A sincronização por General-Call é uma funcionalidade da linha BASIC |
Sensor energy_exported |
sempre 0 | funciona | Requer bidirectional: true |
energy_total, energy_exported_total, energy_net, reactive_energy[_exported] |
nunca publica | funciona | Totais gerais a partir de contadores do próprio dispositivo |
voltage_angle_b/_c, phase_sequence |
nunca publica | funciona em variantes de três tensões com um firmware que as disponibilize | Ver 09 §2.2–2.3 |
Sensores por fase (voltage_a/b/c, current_a/b/c, …) |
sem valores | publicar para os canais que o módulo reporta | Detalhes em 09 §2.2 |
Próximos passos
- 03_sensor_selection.md — escolha de uma pinça de CT e comportamento de
ct_model:/ct_models: - 04_hardware.md — cablagem física, seleção de GPIO
Fonte e problemas: rb-amp/rbamp-esphome · esta página no repositório: docs/02_tiers.md (v1.9.1)