11 · Registo de alterações
Esta página espelha CHANGELOG.md do repositório.
1.6.1 — 2026-11-01
A medição por período funciona agora em módulos STD com as mesmas chamadas que em BASIC; acrescentam-se as chamadas do banco de latch, e as chamadas exclusivas de BASIC são recusadas de forma limpa em módulos STD.
Adicionado
- Medição por período em módulos STD (
read_period_snapshot,read_period_avg_power/read_period_avg_p,read_period_max_power,is_period_valid,latch_period,dev.energy). A fonte é decidida uma vez embegin(): um módulo com contadores no dispositivo usa a diferença de duas leituras de contadores no calendário do mestre (não é enviado nenhum comando de latch); um módulo só com bancos de latch faz latch do banco 0 (latch a latch, com estabilização de pelo menos 300 ms); um módulo sem nenhum dos dois levantaRbAmpNotSupportedError. Uma mudança de geração dos contadores, ou um banco que perdeu a armação após reset do módulo, é reancorada e esse período é ignorado (RbAmpStaleError). O snapshot por período ganhaavg_p_total,wh_netemodule_restarted. Um período baseado em contadores não tem potência de pico, e uma média por canal só existe num módulo de canal único. - Chamadas de banco de latch, disponíveis sempre que o módulo reporta bancos:
dev.std_arm_banks(mask),dev.std_latch(bank),dev.std_read_latch(bank)(umRbAmpStdLatch: P/Q/S, picos, energia em mW·amostras, energia por canal e potência média) eRbAmp.std_latch_wh(snap, dt_ms, ch). A flag de válido de um banco é pegajosa, não uma flag de atualidade: leia um banco pelo menos 300 ms depois de o fazer latch. - Os modelos de sensor 11 (50 A) e 13 (100 A) da classe de pinças estão caracterizados, com limites nominais / de escala total / de pico. O modelo 12 (80 A) não mudou.
Fixo
- Chamadas que existem apenas no mapa de registos BASIC (configuração de classe de sensor / modelo TC, reinício e mudança de endereço, registos de identidade, canal de erros / eventos, auxiliares de frota e General-Call,
read_period_latch_ms,wait_ready) lançam agoraRbAmpNotSupportedErrornum módulo STD, em vez de lerem ou escreverem no endereço errado. set_ct_model_ch_force()num módulo emparelhado de fábrica reportaRbAmpModeError("factory-paired module: configuration locked") quando o firmware recusa a escrita. O caminho de força só funciona em modo de fábrica.
1.6.0 — 2026-10-22
As versões públicas são retomadas com esta versão; as versões intermédias (1.4.x, 1.5.x) foram lançadas apenas internamente.
Adiciona a linha de módulos STD (mapa de registos de 16 bits) junto aos módulos existentes, energia por período por canal em módulos de 5/7 canais e uma correção de comutação de calibre SCT-013. Uma única classe RbAmp serve ambas as linhas; o tipo de módulo é detetado automaticamente em begin().
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.
- Linha de módulos STD (mapa de 16 bits), detetada automaticamente. As leituras comuns (
voltage,current,power,power_factor,frequency) funcionam em todos os módulos; as chamadas exclusivas de STD lançamRbAmpNotSupportedErrornum módulo que não as oferece. - Energia no dispositivo:
dev.read_std_energy()(importação/exportação ativa/líquida + reativa, Wh/mWh/µWh, por canal);RbAmp.std_energy_delta(prev, now)(à prova de corte de energia). - Multifásico:
dev.read_voltage_angle(phase),dev.read_phase_sequence(),dev.read_reactive(ch),dev.read_apparent(ch). - Corrente de arranque:
dev.get_start_current()/dev.set_start_current(µA)+dev.save_config(). dev.read_std_voltage/channel/totals/config/health(),dev.set_time(),dev.is_std; objetos de valorRbAmpStdEnergy/Voltage/Channel/Config/Health;RbAmpNotSupportedError.- Validado em CPython (
smbus2); o caminho de 16 bits do MicroPython está implementado mas ainda não validado em hardware. - Energia de período por canal em módulos de 5/7 canais:
dev.read_period_avg_power(ch)resolve cada canal; o snapshot de período e o acumulador de Wh cobrem todos os canais. - Correção de troca de classificação do TC SCT-013: quando um canal é trocado para um modelo de sensor diferente, corrente, potência e energia são corrigidas para o modelo selecionado em relação ao ganho aplicado pelo módulo; fator de potência e tensão ficam inalterados. Automático;
dev.set_rating_correction(),dev.ct_rating_scale(ch),dev.ct_rating_status(ch). O firmware que faz isto por si é detetado e deixado em paz. - Guarda de leitura-antes-de-escrita nas escritas de classe de sensor / modelo TC;
dev.set_ct_model_ch_force(),dev.read_sensor_class().
Fixo
- O snapshot por período em módulos de 5/7 canais deixou de dar erro nos canais além do terceiro.
1.5.0 — 2026-09-04
Atribuição de modelo TC por canal para todos os canais, suporte a SKUs superiores (UI5/UI7), registo de modelos de sensor e correção de persistência. Firmware: v1.4.18+.
Adicionado
-
Suporte UI5 / UI7 (SKUs superiores): detetado automaticamente via
REG_TOPOLOGY+REG_HW_VARIANT;dev.channelsdevolve 5 ou 7; todos os leitores em tempo real e de período funcionam de forma uniforme parach 0..channels-1. -
Modelo de CT por canal, qualquer canal:
dev.set_ct_model_ch(channel, code)edev.read_ct_model_ch(channel)aceitam agorachannel 0..channels-1. Os canais 0-2 usam o caminho plano de registos; os canais 3+ usam a janela de acesso a canais (campo 15). -
Validação de modelo orientada pelo registo: o registo de modelos é agora a fonte única dos códigos de modelo de CT. Gerado automaticamente em
rbamp/_sensor_models.py; o antigo dicionário mantido à mão_CT_ACCEPTEDfoi removido. -
RbAmpWindowField.CT_MODEL = 15(enum público). RbAmpFleet.aligned_snapshot()preenche listas por canal para a largura total de canais do módulo.
Fixo
- O modelo de CT / a classe de sensor passam agora a persistir em produção. Versões anteriores persistiam estes valores via
CMD_SAVE_GAINS, que está limitado à fábrica — num módulo de produção o save era um no-op silencioso, pelo que a associação ficava em RAM mas perdia-se no reboot. Agora persiste viaCMD_SAVE_USER_CONFIG(sem restrição). Os utilizadores de versões anteriores em produção perderam silenciosamente a associação do modelo de CT em cada reboot — atualize antes de enviar dispositivos.
1.4.0 — 2026-08-19
Suporte para SKUs sénior (UI5/UI7), métricas RT de canais sénior, snapshots alinhados por frota para módulos multicanal.
1.3.1 — 2026-07-30
Alterado
- Atualizados os exemplos multi-módulo (
examples_cpython/03_multi_module_broadcast.py,examples_upy/03_multi_module.py) e os exemplos de balanço energético da casa inteira (examples_cpython/07_home_energy_balance.py,examples_upy/08_home_energy_balance.py) para o latch General-Call coerente da v1.3 (CAP_GC_LATCH):RbAmpFleet.enable_gc_all()→gc_latch()→check_sync(), substituindo o latch sequencial por dispositivo da versão anterior à v1.3. O exemplo da casa inteira publica agora também um tópico MQTThome/energy/sync/in_sync. Correção apenas nos exemplos — API da biblioteca inalterada.
1.3.0 — Frota + protocolo v1.3
Alinhou o pacote Python rbamp com o contrato de fios do rbAmp v1.3 e com o modelo de referência multiplataforma (Arduino / ESP-IDF / ESPHome / STM32 HAL). Suite de testes mock: 179/179 PASS.
Adicionado
-
RbAmpFleet— gestor de múltiplos módulos do lado do host:scan()(com deteção de conflitos + canary de bloqueio Tier-2),add(),find(),count, iteração;poll_all()em lote (isolado a falhas, resiliente a MISS);total_power()/total_energy_wh()/poll_errors()para toda a frota; sincronização General-Call (enable_gc_all()/gc_latch()/check_sync());assign_address()/check_conflict(). Limite flexívelRBAMP_FLEET_MAX_MODULES = 16. -
Estruturas POD:
RbAmpFleetPoll(resultado de poll por membro),RbAmpFleetSync(testemunha de sincronização GC por membro). -
Identidade / capacidade:
read_variant()(byte HW_VARIANT 0x55, 1..6 = UI1/UI2/UI3/I1/I2/I3),read_capability()(mapa de funcionalidades u16 LE; ramifique pelos bits, não por heurísticas de versão),read_product_id()(0x01 = família de sensores rbAmp),read_uid()(12 bytes),read_label()/set_label()(ASCII de 8 bytes via escrita byte a byte). -
Canal de eventos / erros (modelo de dois canais da v1.3):
read_last_error()(byte REG_ERROR do dispositivo, uma leitura de fio),read_event_flags(),clear_event_flags(mask),has_error()(auxiliar sticky do bit3),clear_error()(CMD_CLEAR_ERROR). -
Configuração TC por canal:
configure_channels(class, models, n)(em bloco, uma única gravação final na flash; limitado pela variante; validação no cliente por classe via_validate_ct_code);read_ct_model_ch(ch)(leitura do espelho do modelo aplicado, de 0x51 a 0x53). -
Primitivas de frota por dispositivo:
enable_gc(enable=True)(leitura-modificação-escrita da flag GC_ENABLE de FLEET_CONFIG + guardar + reset; ~1 s bloqueante; no-op idempotente se já estiver correto),read_fleet_config(),set_group_id()/read_group_id(),read_gc_tick()(testemunha u16; 0xFFFF = nunca recebido),RbAmp.broadcast_latch_group(bus, group, tick)estático (trama GC de 5 bytesA5 27 g tl th). -
Hierarquia de exceções: base
RbAmpError+RbAmpIOError,RbAmpTimeoutError,RbAmpStaleError,RbAmpParamError,RbAmpModeError,RbAmpVersionError.
Alterado
-
A energia é integrada contra o relógio de parede do mestre, nunca contra o
latch_msde diagnóstico do módulo (um temporizador de diagnóstico, não para energia). Em CPython usetime.monotonic(); em MicroPython usetime.ticks_ms()+time.ticks_diff(). Numa leitura obsoleta (PERIOD_VALID = 0) a biblioteca lançaRbAmpStaleErrore NÃO repõe a âncora; o snapshot válido seguinte cobre o intervalo completo e o firmware preserva o acumulador → a matemática da integração mantém-se exata, sem contagem a mais nem a menos. -
Os códigos de modelo TC são um conjunto aceite por classe (
SCT_013 {1,2,3,4,5,6,7},WIRED_CT {1,2,3},BUILTIN_CT ∅); um código fora do conjunto da classe faz a biblioteca lançarRbAmpParamErrorantes de qualquer operação I²C.REG_CT_MODELé apenas fila: a ligação faz-se por um comando por canal, e as ligações de vários canais são independentes da ordem no firmware v1.3 (no legado v1.x o padrão defensivo de ordem descendente mantém-se no ciclo deset_ct_model_ch). -
A alteração de endereço é um commit mágico em duas fases aceitável em produção; o modo de fábrica não é necessário.
prepare_address_change()arma o candidato + a janela magic0xA5de 5 segundos;commit_address_change()emiteCMD_COMMIT_ADDR+ reset. A biblioteca garante que o estado de armação é limpo via try/finally em caso de falha parcial; uma janela expirada →RbAmpTimeoutError. Compatível com firmware legado v1.x através de um fallback condicionado por capacidade. -
Deteção de variante —
read_variant()lêREG_HW_VARIANT(o byte canónico de SKU da v1.3). O caminho de sondagem por NACK foi removido (o firmware nunca dá NACK em leituras; leituras não mapeadas →0x00). -
Escrita de vários bytes byte a byte. O
set_label()da biblioteca escreve os 8 bytes de LABEL com um ciclo de bytes automaticamente (o rbAmp não faz auto-incremento nas escritas).
Robustez em bancada (Etapa 1B)
-
CPython
SMBusBackendexpõe um retry genérico após NACK (retry_attempts=3,retry_gap_ms=2) com os diagnósticosretry_count_total+retry_exhaustion_count. É usado em todas as operações de barramento (as escritas de configuração seguem a mesma disciplina das leituras — caso contrário, uma escrita de configuração descartada em silêncio num barramento disputado ficaria invisível). -
MicroPython em ESP32:
MachineI2CBackendmantém a disciplina de spin i2c_master de 50 kHz do IDF (retry após NACK com espera curta entre tentativas, para que um barramento disputado não descarte silenciosamente uma escrita). Veja 09 · Referência da API → "Detalhes do protocolo de fios" para o contrato completo.
Notas
- Barramento marginal / anfitriões baseados em ESP32: o mesmo driver IDF i2c_master usado nos projetos ESP-IDF nativos — pode bloquear num barramento retido abaixo do nível da biblioteca. Recomendamos pull-ups externos de ~4.7 kΩ, sem NRST de depurador em produção, e um watchdog de tarefa ao nível da aplicação na tarefa de polling como postura de recuperação. Veja o capítulo 10 · Resolução de problemas.
1.1.0 — snapshot de período alargado
Snapshot de período alargado (máx. P, diagnóstico latch_ms), contabilização de Wh no mestre.
1.0.0 — Versão inicial
Medição RT de um único dispositivo (U / I / P / PF / frequência RMS), integração de energia por período (Wh), configuração de modelo TC + classe do sensor, e mudança de endereço I²C. Backend duplo (CPython smbus2 / MicroPython machine.I2C).
Fonte e problemas: rb-amp/rbamp-python · esta página no repositório: docs/11_changelog.md (v1.6.1)