rbAmp
PT
Loja
Docs
Atualizado · Editar no GitHub [Edit on GitHub]

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 em begin(): 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 levanta RbAmpNotSupportedError. 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 ganha avg_p_total, wh_net e module_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) (um RbAmpStdLatch: P/Q/S, picos, energia em mW·amostras, energia por canal e potência média) e RbAmp.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 agora RbAmpNotSupportedError num 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 reporta RbAmpModeError ("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

Nota

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çam RbAmpNotSupportedError num 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 valor RbAmpStdEnergy/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.channels devolve 5 ou 7; todos os leitores em tempo real e de período funcionam de forma uniforme para ch 0..channels-1.

  • Modelo de CT por canal, qualquer canal: dev.set_ct_model_ch(channel, code) e dev.read_ct_model_ch(channel) aceitam agora channel 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_ACCEPTED foi 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 via CMD_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 MQTT home/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ível RBAMP_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 bytes A5 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_ms de diagnóstico do módulo (um temporizador de diagnóstico, não para energia). Em CPython use time.monotonic(); em MicroPython use time.ticks_ms() + time.ticks_diff(). Numa leitura obsoleta (PERIOD_VALID = 0) a biblioteca lança RbAmpStaleError e 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çar RbAmpParamError antes 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 de set_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 magic 0xA5 de 5 segundos; commit_address_change() emite CMD_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 SMBusBackend expõe um retry genérico após NACK (retry_attempts=3, retry_gap_ms=2) com os diagnósticos retry_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: MachineI2CBackend manté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)