rbAmp
PT
Loja
Docs
Atualizado a · Editar no GitHub

11 · Registo de alterações

Histórico de versões do componente externo rbamp para ESPHome. Esta página espelha o CHANGELOG.md do repositório, que é a fonte canónica.

As versões públicas são retomadas com a v1.9.0; as versões intermédias listadas abaixo foram publicadas apenas internamente.

Contents:


v1.9.1 — 2026-11-01

Bancos de instantâneo STD no YAML, os modelos de pinça de 50 A e 100 A, e uma mensagem clara quando um módulo fornecido em par de fábrica recusa uma escrita de configuração.

Adicionado

  • Bancos de snapshot (period_banks:) para módulos que os anunciam (linha de 16 bits, imagem 0x7E e posteriores): potência média por período, energia, picos e duração do período em qualquer um dos oito bancos do módulo, capturados por um interval: e/ou pela nova ação rbamp.latch_bank. Os valores de energia por período são por período (state_class: measurement), não contadores. A primeira captura após o arranque ou um reinício do módulo apenas inicia o período. Exemplo: example/std_banks.yaml.

  • Testes no host para a lógica de bancos: tests/host/test_std_bank.cpp (g++ simples, sem framework).

  • Registo de modelos de sensor: os códigos 11 (50 A, 33 Ω) e 13 (100 A, 20 Ω) estão agora caracterizados e aceites sem a sugestão "reservado".

Fixo

  • Na versão 1.4.22 do firmware e posteriores, um módulo fornecido em par de fábrica (classe WIRED_CT / BUILTIN_CT) recusa escritas de classe e de modelo em funcionamento normal, mesmo com ct_model_force: true (a forçagem só funciona em modo de fábrica). O componente passa a reportar "factory-paired module: configuration locked" em vez de um erro genérico de parâmetro, e uma escrita recusada de ct_model: deixa de ser persistida ou seguida da correção de calibre.

v1.9.0 — 2026-10-21

As versões públicas retomam com esta versão; as versões intermédias foram lançadas apenas internamente.

Comutação de calibre SCT sem perder a precisão de fábrica (linha de 8 bits), mais as proteções de guarda das versões 1.8.x incorporadas nesta versão pública.

Adicionado

  • SCT-013-060 e -100 são aceites (antes eram recusados do lado do cliente por estarem reservados); os limites de corte do modelo de sensor foram atualizados para os valores medidos.
  • Correção de comutação de calibre SCT (módulos com a classe de sensor SCT-013, firmware ≤ 1.4.19). Cada módulo SCT é calibrado de fábrica com o sensor -030; selecionar outro ct_model: deixava a corrente/potência/energia na escala do -030. O componente passa agora a concluir a escrita do modelo com o reinício do módulo que o procedimento exige (guardar → reiniciar → nova deteção com verificação de UID), lê o ganho que o módulo aplica de facto e escala a corrente, a potência ativa e reativa e a integração de energia para o calibre do sensor selecionado — o ajuste de fábrica por unidade é preservado. A tensão e o fator de potência não são afetados. Um reinício do módulo (próprio ou externo) é detetado e a correção é recalculada automaticamente. Se o ganho aplicado estiver fora de ±5 % do valor do modelo de calibração, o componente avisa e não escala. Não é necessária nenhuma alteração ao YAML.

  • A firmware 1.4.20+ faz a comutação de calibre no próprio dispositivo e anuncia-o — o componente deteta-o e deixa as leituras intactas (escrita simples de modelo, sem reinício).

  • Teste de host para a lógica de decisão de correção de calibre: tests/host/test_sct_rating.cpp (g++ simples, sem framework).

v1.8.1 — 2026-10-18

Fixo

  • Proteção da calibração de fábrica de sensor_class: / ct_model: (linha de 8 bits). A firmware limpa os modelos de canal e as formas de linearidade em qualquer escrita de classe de sensor (mesmo com valor inalterado) e reaplica a predefinição genérica em qualquer escrita de modelo de CT — o componente agora nunca escreve um valor que o dispositivo já tem, e recusa alterações de classe/modelo a partir do YAML num módulo calibrado em par com o seu sensor incorporado (classes WIRED_CT / BUILTIN_CT), com uma linha de registo explícita. Nova opção de serviço ct_model_force: true reaplica deliberadamente a predefinição; o esquema rejeita-a sem uma chave de modelo, para que não fique armada no YAML.

  • Leitura fora dos limites em módulos de 5/7 canais (UI5/UI7): o ciclo de publicação de restauro no arranque indexava os arrays de exportação de 3 slots até ao canal 6 e podia publicar um valor lixo no sensor adjacente. Corrigido com o mesmo filtro de canal que os outros pontos de exportação já tinham; os tamanhos dos arrays estão agora fixados por asserções em tempo de compilação.

  • Documentação/comentários alinhados com a janela de medição familiar de 100 ms (firmware v1.2+; 200 ms apenas em imagens mais antigas).

v1.8.0 — 2026-10-17

Energia acumulada no dispositivo para a linha de 16 bits.

Adicionado

  • Energia dos contadores do próprio dispositivo (módulos de mapa de 16 bits que os anunciam no bitmap de capacidades): o componente deixa de integrar Wh por conta própria e acumula os contadores do próprio módulo — os totais sobrevivem a reinícios do ESP32 e do módulo, sem deriva de integração. Microresolução (µWh/µvarh) no firmware que a publica, com fallback grosso automático caso contrário. Cada instantâneo é lido numa única transação I²C coerente, e as somas publicadas mantêm-se monotónicas através de reinícios do módulo e reposições de contadores.

  • Novos sensores de total geral: energy_total, energy_exported_total, energy_net (importação − exportação, pode descer), reactive_energy, reactive_energy_exported.

  • Chave de configuração start_current_ua: (0 = desligado, 10..2540 em passos de 10 µA): abaixo desta corrente um canal não acumula energia — em vazio, a potência medida é ruído de sinal qualquer que se acumularia nos contadores de importação e exportação. As leituras não são afetadas. Validada pelo esquema; persistida no dispositivo com gravação verificada.

  • Superfícies trifásicas: voltage_angle_b / voltage_angle_c (graus, em relação à fase A) e phase_sequence (1 direta · 2 inversa · 3 anómala), publicadas na firmware que as fornece; "unknown" caso contrário.

  • Acessores lambda: get_std_image_version(), get_phase_sequence_str(), read_start_current_ua().

v1.7.0 — 2026-09-30

Suporte para a nova linha de módulos com mapa de registos de 16 bits, detetada automaticamente no mesmo YAML.

Adicionado

  • Suporte de linha dupla: uma sondagem de identidade no arranque deteta módulos com mapa de 16 bits e muda o transporte (ponteiro big-endian, leituras em rajada com auto-incremento). O número de canais, a variante e as capacidades vêm do bloco de descoberta do dispositivo — topology: e as contagens de slots no YAML já não são necessárias para dimensionar a superfície de entidades. Módulos de 8 bits comportam-se exatamente como antes.

  • Os sensores em tempo real na linha de 16 bits são publicados a partir dos registos de ponto fixo do dispositivo; a energia usa os snapshots de latch atómicos do dispositivo com integração pelo relógio do mestre e a mesma persistência NVS.

  • As chaves de configuração (sensor_class:, ct_model:, new_address:) funcionam na linha de 16 bits através do seu bloco de configuração preparado, com gravação verificada de forma síncrona. Os ct_models: por canal nesta linha exigem que o dispositivo anuncie mapas persistentes por canal (bit de capacidade); o componente recusa de forma ruidosa em vez de perder a escrita em silêncio.

  • Recuperação automática após um reinício do módulo a meio da execução: o componente deteta a perda do armamento do acumulador, volta a armar e a preparar, saltando uma janela em vez de parar a acumulação de energia em silêncio.

  • Descarga da NVS em desligamento limpo (reinício/OTA deixa de perder até ao último intervalo de gravação de energia).

v1.6.0 — 2026-09-04

ct_models: por canal para todos os canais (0..15), registo de modelos de sensor e correção de persistência. Firmware: v1.4.18+ necessário para os canais sénior 3+.

v1.5.0 — 2026-08 (apenas interno)

Adicionado

  • Suporte dos SKUs senior UI5/UI7: os canais 3–6 são lidos pela janela de acesso aos canais (métricas em tempo real e energia por período por canal), slots de energia NVS alargados a 7 canais.

Adicionado

  • Modelos de pinça por canal em todos os canais. ct_models: no YAML aceita agora até 16 entradas. A deteção da variante do módulo determina quantas são aplicadas; entradas extra geram um aviso, não uma falha.

  • Registo de modelos de sensor — a lista de modelos vem de um único registo. As duas listas codificadas (dicionário CT_MODELS + CT_MODEL_ALLOWED_PER_CLASS) são substituídas por uma única consulta ao registo. Adicionar um novo SKU de pinça CT passa a ser uma edição do registo — sem necessidade de nova versão da biblioteca.

Fixo

  • A v1.6.0 acrescenta SAVE após o ciclo de aplicação. Versões anteriores usavam um caminho de persistência condicionado pela fábrica para o modelo CT e a classe do sensor — num módulo de produção a associação era aplicada na RAM mas perdia-se no reinício. A v1.6.0 persiste via CMD_SAVE_USER_CONFIG (sem condicionamento). Os utilizadores de versões anteriores em produção perderam silenciosamente a associação do modelo CT em cada reinício — atualize antes de expedir dispositivos.

v1.4.0

Deteção de SKU sénior (variantes de 5/7 canais), janela de acesso a canais para métricas em tempo real, e a chave opcional latch_interval: que desacopla a cadência do latch/energia da cadência de leitura (update_interval:). A energia mantém-se monotónica e exata: a integração usa o tempo real de relógio decorrido entre eventos de latch.

v1.3.0

Primeira versão pública. Implementação multi-canal e multi-módulo com sincronização de latch general-call (fleet_gc_enable: + group_id:), commit de endereço em duas fases (produção OK, sem modo de provisionamento de fábrica), arranque de ler-comparar-escrever, deteção de funcionalidades condicionada por capacidade, superfície de identidade para lambdas (get_variant_str(), get_uid_hex(), ...), persistência de energia na NVS.


Política de obsolescência

O que o componente promete não quebrar sem aviso, e o que pode:

Superfície Estabilidade O que prometemos
Chaves YAML do bloco rbamp: Estável A remoção ou renomeação só é possível num incremento maior. Aparece um aviso de obsolescência no registo antes da remoção. broadcast_latch: e topology: são mantidos no esquema por compatibilidade retroativa.
Chaves YAML de sensor.platform: rbamp (slots) Estável As mesmas regras. Os nomes voltage/current/power/energy/frequency/power_factor são fixos como contrato com o painel de Energia do HA.
O conjunto de entidades do HA e os seus device_class / state_class Estável Não o alteraremos sem aviso prévio; afeta o entity_id no HA.
Métodos RbAmpComponent::* acessíveis a partir de lambda Instável Estes podem mudar em versões menores. Se escrever ações lambda contra eles, fixe a versão do componente (ref: em external_components:).
Formato da estrutura NVS Versionado As alterações vêm acompanhadas de um incremento da versão de layout — os dados antigos são descartados, nunca lidos de forma errada.
Nomes e comportamento do bloco i2c: Externo Isto é o núcleo do ESPHome, não é nosso — siga a política a montante.

Guia de atualização

Para a v1.9.0 (a partir de qualquer versão anterior)

  1. Defina ref: v1.9.0 em external_components:.
  2. Não é necessária nenhuma alteração ao YAML. O mesmo YAML funciona para as duas linhas de módulos; o componente identifica o módulo ligado no arranque. topology: não é necessário.
  3. Se quiser totais de energia sobre todos os canais num módulo STANDARD (STD), adicione energy_total / energy_exported_total / energy_net (ver 09 §2.3).
  4. Se o seu YAML definir sensor_class: ou ct_model: num módulo fornecido calibrado juntamente com o sensor ajustado, o componente passa a recusar a alteração e regista-a no log. Remova essas chaves nesses módulos.
  5. Se mudou o calibre do SCT via ct_model:, as leituras ficam agora precisas; um reinício do módulo durante a troca é normal no firmware até 1.4.19.
  6. ct_model_force: true é apenas uma opção de serviço; o esquema rejeita-a sem ct_model: / ct_models:.
  7. Os valores de energia por canal em NVS são preservados na atualização; os novos sensores de total geral começam em 0 no primeiro arranque e depois acumulam (o respetivo slot de NVS é separado).

A partir da v1.3 / v1.4

  1. Atualize ref:.
  2. SCT_013_100 (código 5) e SCT_013_060 (código 7) são aceites.
  3. Opcionalmente, adicione fleet_gc_enable: / group_id: para snapshots sincronizados numa implementação com vários módulos (módulos BASIC).

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