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 abegin(): 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 sollevaRbAmpNotSupportedError. 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 acquisisceavg_p_total,wh_netemodule_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)(unRbAmpStdLatch: P/Q/S, picchi, energia in mW·campioni, energia e potenza media per canale) eRbAmp.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 sollevanoRbAmpNotSupportedErrorsu un modulo STD invece di leggere o scrivere l'indirizzo sbagliato. set_ct_model_ch_force()su un modulo accoppiato in fabbrica segnalaRbAmpModeError(«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
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 sollevanoRbAmpNotSupportedErrorsu 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 valoreRbAmpStdEnergy/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.channelsrestituisce 5 o 7; tutti i lettori live/periodo funzionano in modo uniforme perch 0..channels-1. -
Modello TA per canale, qualsiasi canale:
dev.set_ct_model_ch(channel, code)edev.read_ct_model_ch(channel)accettano orachannel 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_ACCEPTEDmantenuto 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 tramiteCMD_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 MQTThome/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 morbidoRBAMP_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 byteA5 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_msdiagnostico del modulo (un timer diagnostico, non per l'energia). Su CPython usaretime.monotonic(); su MicroPythontime.ticks_ms()+time.ticks_diff(). Su una lettura non aggiornata (PERIOD_VALID = 0) la libreria sollevaRbAmpStaleErrore 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 solleviRbAmpParamErrorprima 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 cicloset_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 magica0xA5di 5 secondi;commit_address_change()emetteCMD_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()leggeREG_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
SMBusBackendespone un retry generico sui NACK (retry_attempts=3,retry_gap_ms=2) con le diagnosticheretry_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
MachineI2CBackendmantiene 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)