rbAmp
PT
Loja
Docs
Atualizado · Editar no GitHub (Edit on GitHub)

02 · Níveis de módulo

As duas linhas de módulos rbAmp, BASIC e STANDARD (STD), e onde a energia é calculada em cada uma.

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_exported existe no esquema YAML (por compatibilidade de configuração), mas no BASIC publica sempre 0.
  • 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ém voltage_angle_b, voltage_angle_c e phase_sequence.
  • Energia energy e energy_exported por canal (com bidirectional: 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.

Contabilidade de energia no BASIC (o mestre integra a potência média do período) versus STANDARD (o mestre lê os contadores acumulados do módulo).

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
Nota

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

YAML
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

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

YAML
rbamp:
  id: meter1
  ct_model: SCT_013_030   # all channels — SCT-013-030

Ou um perfil por canal (para UI3 com pinças mistas):

YAML
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 com ct_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) — use ct_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

YAML
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

YAML
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

YAML
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

YAML
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


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