rbAmp
IT
Negozio
Docs
Aggiornato · Modifica su GitHub [Edit on GitHub]

11 · Changelog

Questa pagina riflette CHANGELOG.md del repository.

1.6.1 — 2026-11-01

La misura di periodo ora funziona sui moduli STD con le stesse chiamate dei BASIC, le chiamate dei banchi latch sono aggiunte e le chiamate solo-BASIC vengono rifiutate in modo pulito sui moduli STD.

Aggiunto

  • Misura per periodo sui moduli STD (read_period_snapshot, read_period_avg_power / read_period_avg_p, read_period_max_power, is_period_valid, latch_period, dev.energy). La sorgente viene decisa una volta a begin(): un modulo con contatori on-device usa la differenza di due letture dei contatori secondo la pianificazione del master (non viene inviato alcun comando di latch); un modulo con soli banchi di latch esegue il latch del banco 0 (da latch a latch, con almeno 300 ms di stabilizzazione); un modulo con nessuno dei due solleva RbAmpNotSupportedError. Un cambio di generazione dei contatori, o un banco che ha perso l'armamento dopo un reset del modulo, viene riancorato e quel periodo viene saltato (RbAmpStaleError). L'istantanea di periodo acquisisce avg_p_total, wh_net e module_restarted. Un periodo basato sui contatori non ha potenza di picco, e una media per canale solo su un modulo a canale singolo.
  • Chiamate sui banchi latch, disponibili ogni volta che il modulo riporta i banchi: dev.std_arm_banks(mask), dev.std_latch(bank), dev.std_read_latch(bank) (un RbAmpStdLatch: P/Q/S, picchi, energia in mW·campioni, energia e potenza media per canale) e RbAmp.std_latch_wh(snap, dt_ms, ch). Il flag di validità di un banco è persistente, non un indicatore di freschezza: leggere un banco almeno 300 ms dopo averlo latchato.
  • I modelli di sensore 11 (50 A) e 13 (100 A) della classe pinza sono caratterizzati, con i limiti nominali / di fondo scala / di picco. Il modello 12 (80 A) è invariato.

Fisso

  • Chiamate che esistono solo sulla mappa registri BASIC (configurazione di classe/modello TA, reset e cambio di indirizzo, registri di identità, canale di errore/eventi, helper di flotta e General-Call, read_period_latch_ms, wait_ready) ora sollevano RbAmpNotSupportedError su un modulo STD invece di leggere o scrivere l'indirizzo sbagliato.
  • set_ct_model_ch_force() su un modulo accoppiato in fabbrica segnala RbAmpModeError («modulo accoppiato in fabbrica: configurazione bloccata») quando il firmware rifiuta la scrittura. Il percorso force funziona solo in modalità fabbrica.

1.6.0 — 2026-10-22

Nota

Le versioni pubbliche riprendono con questa versione; le versioni intermedie (1.4.x, 1.5.x) sono state rilasciate solo internamente.

Aggiunge la linea di moduli STD (mappa dei registri a 16 bit) accanto ai moduli esistenti, energia per periodo per canale su moduli a 5/7 canali e una correzione dello switch di rating SCT-013. Un'unica classe RbAmp serve entrambe le linee di moduli; il tipo di modulo viene rilevato automaticamente in begin().

Aggiunto

  • SCT-013-060 e -100 sono accettati (in precedenza rifiutati lato client come riservati); i limiti di clip del modello di sensore aggiornati ai valori misurati.
  • Linea di moduli STD (mappa a 16 bit), rilevata automaticamente. Le letture comuni (voltage, current, power, power_factor, frequency) funzionano su ogni modulo; le chiamate solo-STD sollevano RbAmpNotSupportedError su un modulo che non le fornisce.
  • Energia sul dispositivo: dev.read_std_energy() (attiva import/export/netta + reattiva, Wh/mWh/µWh, per canale); RbAmp.std_energy_delta(prev, now) (sicura in caso di interruzione di alimentazione).
  • Multifase: dev.read_voltage_angle(phase), dev.read_phase_sequence(), dev.read_reactive(ch), dev.read_apparent(ch).
  • Corrente di avviamento: 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; oggetti valore RbAmpStdEnergy/Voltage/Channel/Config/Health; RbAmpNotSupportedError.
  • Validato su CPython (smbus2); il percorso MicroPython a 16 bit è implementato ma non ancora validato su hardware.
  • Energia di periodo per canale sui moduli a 5/7 canali: dev.read_period_avg_power(ch) risolve ogni canale; lo snapshot di periodo e l'accumulatore Wh coprono tutti i canali.
  • Correzione del cambio di portata del TA SCT-013: quando un canale passa a un modello di sensore diverso, corrente/potenza/energia vengono corretti al modello selezionato rispetto al guadagno che il modulo applica; fattore di potenza e tensione invariati. Automatico; dev.set_rating_correction(), dev.ct_rating_scale(ch), dev.ct_rating_status(ch). Il firmware che esegue questa correzione da sé viene rilevato e lasciato invariato.
  • Guardia di lettura-prima-della-scrittura sulle scritture di classe del sensore / modello TA; dev.set_ct_model_ch_force(), dev.read_sensor_class().

Fisso

  • L'istantanea di periodo su moduli a 5/7 canali non dava più errore sui canali oltre il terzo.

1.5.0 — 2026-09-04

Assegnazione del modello TA per canale su tutti i canali, supporto alle SKU di fascia alta (UI5/UI7), registro dei modelli di sensore e correzione della persistenza. Firmware: v1.4.18+.

Aggiunto

  • Supporto UI5 / UI7 (SKU di fascia alta): rilevati automaticamente tramite REG_TOPOLOGY + REG_HW_VARIANT; dev.channels restituisce 5 o 7; tutti i lettori live/periodo funzionano in modo uniforme per ch 0..channels-1.

  • Modello TA per canale, qualsiasi canale: dev.set_ct_model_ch(channel, code) e dev.read_ct_model_ch(channel) accettano ora channel 0..channels-1. I canali 0-2 usano il percorso dei registri piatti; i canali 3 e oltre usano la finestra di accesso al canale (campo 15).

  • Validazione dei modelli guidata dal registro: il registro dei modelli è ora l'unica fonte per i codici modello TA. Generato automaticamente in rbamp/_sensor_models.py; il vecchio dizionario _CT_ACCEPTED mantenuto a mano non esiste più.

  • RbAmpWindowField.CT_MODEL = 15 (enum pubblico).

  • RbAmpFleet.aligned_snapshot() compila le liste per canale sull'intera larghezza di canali del modulo.

Fisso

  • Il modello TA e la classe del sensore ora persistono in produzione. Le versioni precedenti li salvavano tramite CMD_SAVE_GAINS, che è riservato alla fabbrica — su un modulo di produzione il salvataggio era un no-op silenzioso, quindi l'associazione si applicava alla RAM ma andava persa al riavvio. Ora persiste tramite CMD_SAVE_USER_CONFIG (senza restrizioni). Gli utenti delle versioni precedenti in produzione hanno perso silenziosamente l'associazione del modello TA a ogni riavvio — aggiorni prima di spedire i dispositivi.

1.4.0 — 2026-08-19

Supporto per gli SKU senior (UI5/UI7), metriche RT dei canali senior, istantanee allineate al fleet per moduli multi-canale.

1.3.1 — 2026-07-30

Modificato

  • Aggiornati gli esempi multi-modulo (examples_cpython/03_multi_module_broadcast.py, examples_upy/03_multi_module.py) e gli esempi di bilancio energetico dell'intera casa (examples_cpython/07_home_energy_balance.py, examples_upy/08_home_energy_balance.py) al latch coerente General-Call della v1.3 (CAP_GC_LATCH): RbAmpFleet.enable_gc_all() → gc_latch() → check_sync(), al posto del latch sequenziale per dispositivo della versione precedente alla v1.3. L'esempio sull'intera casa ora pubblica anche il topic MQTT home/energy/sync/in_sync. Solo modifica agli esempi — API della libreria invariata.

1.3.0 — Flotta + protocollo v1.3

Allineato il pacchetto Python rbamp al contratto di protocollo rbAmp v1.3 e al modello di riferimento multipiattaforma (Arduino / ESP-IDF / ESPHome / STM32 HAL). Suite di test mock: 179/179 PASS.

Aggiunto

  • RbAmpFleet — gestore lato host di più moduli: scan() (con rilevamento conflitti + canarino di blocco Tier-2), add(), find(), count, iterazione; poll_all() a lotti (isolamento dei guasti, resiliente a MISS); total_power() / total_energy_wh() / poll_errors() su tutto il fleet; sincronizzazione General-Call (enable_gc_all() / gc_latch() / check_sync()); assign_address() / check_conflict(). Limite morbido RBAMP_FLEET_MAX_MODULES = 16.

  • Strutture POD: RbAmpFleetPoll (risultato di interrogazione per membro), RbAmpFleetSync (testimone di sincronizzazione GC per membro).

  • Identità / capacità: read_variant() (byte HW_VARIANT 0x55, 1..6 = UI1/UI2/UI3/I1/I2/I3), read_capability() (mappa delle funzioni u16 LE; ramificare sui bit, non su euristiche di versione), read_product_id() (0x01 = famiglia di sensori rbAmp), read_uid() (12 byte), read_label() / set_label() (ASCII a 8 byte tramite scrittura byte per byte).

  • Canale di eventi / errori (modello a due canali v1.3): read_last_error() (byte REG_ERROR del dispositivo, una lettura sul filo), read_event_flags(), clear_event_flags(mask), has_error() (funzione di comodo per il bit3 persistente), clear_error() (CMD_CLEAR_ERROR).

  • Configurazione TA per canale: configure_channels(class, models, n) (in blocco, un unico SAVE terminale in flash; limitato alla variante; validazione lato client per classe con _validate_ct_code); read_ct_model_ch(ch) (lettura del mirror del modello applicato da 0x51-0x53).

  • Primitive per dispositivo del fleet: enable_gc(enable=True) (RMW del REG_the GC_ENABLE flag di FLEET_CONFIG + salvataggio + reset; ~1 s bloccante; no-op idempotente se già corretto), read_fleet_config(), set_group_id() / read_group_id(), read_gc_tick() (testimone u16; 0xFFFF = mai ricevuto), RbAmp.broadcast_latch_group(bus, group, tick) statico (frame GC di 5 byte A5 27 g tl th).

  • Gerarchia delle eccezioni: base RbAmpError + RbAmpIOError, RbAmpTimeoutError, RbAmpStaleError, RbAmpParamError, RbAmpModeError, RbAmpVersionError.

Modificato

  • L'energia è integrata sull'orologio a parete del master, mai sul latch_ms diagnostico del modulo (un timer diagnostico, non per l'energia). Su CPython usare time.monotonic(); su MicroPython time.ticks_ms() + time.ticks_diff(). Su una lettura non aggiornata (PERIOD_VALID = 0) la libreria solleva RbAmpStaleError e NON azzera l'ancora; lo snapshot valido successivo copre l'intero intervallo e il firmware conserva l'accumulatore → il calcolo dell'integrazione resta esatto, senza doppio conteggio né conteggio mancante.

  • I codici del modello TA sono un insieme accettato per classe (SCT_013 {1,2,3,4,5,6,7}, WIRED_CT {1,2,3}, BUILTIN_CT ∅); un codice fuori dall'insieme della classe fa sì che la libreria sollevi RbAmpParamError prima di qualsiasi operazione I²C. REG_CT_MODEL è solo predisposizione: il collegamento avviene tramite un comando per canale, e i collegamenti multi-canale sono indipendenti dall'ordine sul firmware v1.3 (sulle v1.x precedenti lo schema difensivo in ordine decrescente resta nel ciclo set_ct_model_ch).

  • Il cambio di indirizzo è un commit magico in due fasi ammesso in produzione; la modalità fabbrica non è richiesta. prepare_address_change() arma il candidato + la finestra magica 0xA5 di 5 secondi; commit_address_change() emette CMD_COMMIT_ADDR + reset. La libreria garantisce che lo stato di armamento venga azzerato tramite try/finally in caso di errore parziale; una finestra scaduta → RbAmpTimeoutError. Compatibile con il firmware v1.x legacy tramite un ripiego controllato dalla capacità.

  • Rilevamento della variante — read_variant() legge REG_HW_VARIANT (il byte SKU canonico della v1.3). Il percorso di sondaggio con NACK è stato rimosso (il firmware non risponde mai con NACK alle letture; le letture non mappate → 0x00).

  • Scrittura multi-byte byte per byte. La set_label() della libreria scrive gli 8 byte di LABEL con un ciclo sui byte automaticamente (rbAmp non auto-incrementa le scritture).

Robustezza al banco (Fase 1B)

  • CPython SMBusBackend espone un retry generico sui NACK (retry_attempts=3, retry_gap_ms=2) con le diagnostiche retry_count_total + retry_exhaustion_count. È usato su tutte le operazioni sul filo (le scritture di configurazione seguono la stessa disciplina delle letture — altrimenti una scrittura di configurazione silenziosamente scartata su un bus conteso sarebbe invisibile).

  • MicroPython su ESP32 MachineI2CBackend mantiene la disciplina i2c_master IDF a 50 kHz (retry sui NACK con attesa stretta tra i tentativi, così un bus conteso non perde silenziosamente una scrittura). Vedi 09 · Riferimento API → «Dettagli del protocollo sul filo» per il contratto completo.

Note

  • Bus marginale / host basati su ESP32: lo stesso driver IDF i2c_master usato nei progetti ESP-IDF nativi — può bloccarsi su un bus tenuto basso sotto il livello della libreria. Si consigliano pull-up esterni da ~4.7 kΩ, nessun NRST del debugger in produzione, e un watchdog a livello applicativo sul task di polling come postura di recupero. Vedi il capitolo 10 · Risoluzione dei problemi.

1.1.0 — istantanea di periodo estesa

Istantanea estesa del periodo (potenza massima P, diagnostica latch_ms), contabilità dei Wh lato master.

1.0.0 — Prima versione

Misura RT su singolo dispositivo (U / I / P / PF / frequenza RMS), integrazione dell'energia per periodo (Wh), configurazione di modello TA + classe del sensore e cambio di indirizzo I²C. Doppio backend (CPython smbus2 / MicroPython machine.I2C).


Sorgente e segnalazioni: rb-amp/rbamp-python · questa pagina nel repository: docs/11_changelog.md (v1.6.1)