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
- v1.9.0 — 2026-10-21
- v1.8.1 — 2026-10-18
- v1.8.0 — 2026-10-17
- v1.7.0 — 2026-09-30
- v1.6.0 — 2026-09-04
- v1.5.0 — 2026-08 (apenas interno)
- v1.4.0
- v1.3.0
- Política de obsolescência
- Guia de atualização
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 uminterval:e/ou pela nova açãorbamp.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 comct_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 dect_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 (classesWIRED_CT/BUILTIN_CT), com uma linha de registo explícita. Nova opção de serviçoct_model_force: truereaplica 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) ephase_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. Osct_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)
- Defina
ref: v1.9.0emexternal_components:. - 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. - 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). - Se o seu YAML definir
sensor_class:ouct_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. - 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. ct_model_force: trueé apenas uma opção de serviço; o esquema rejeita-a semct_model:/ct_models:.- 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
- Atualize
ref:. SCT_013_100(código 5) eSCT_013_060(código 7) são aceites.- 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)