rbAmp
IT
Negozio
Docs
Aggiornato il · Modifica su GitHub (Edit on GitHub)

11 · Changelog

Questo capitolo rispecchia CHANGELOG.md nella radice del repository. I rilasci pubblici riprendono con la versione 1.7.2; le versioni intermedie sono state rilasciate solo internamente.

1.7.3 — L'energia STD resta sui contatori, modelli di pinza da 100 A e 50 A, messaggio di modulo bloccato (2026-11-01)

Fisso

  • I moduli STD che riportano sia i banchi di snapshot (bit di capacità 8) sia i contatori di energia on-device (bit 13), come l'immagine modulo 0x0001007E: energia e chiamate di periodo restano ora sui contatori persistenti. Prima, un modulo del genere veniva commutato sul banco 0 integrato dall'host senza alcun segnale. Le chiamate sui banchi di snapshot (rbamp_std_arm_banks, rbamp_std_latch, rbamp_std_read_latch) sono uno strumento separato che dipende solo dal bit 8 e funzionano su questi moduli come prima. rbamp_std_info_t.period_source riporta la sorgente effettivamente usata.

Aggiunto

  • README: sezione «Linea STD» con la versione minima del componente per l'immagine del modulo 0x0001007E e le chiamate ai banchi di snapshot.

  • L'esempio std_meter arma il proprio banco 1 su ogni modulo che segnala i banchi di latch, anche quando l'energia viene dai contatori.

  • Nome del firmware per BASIC REG_VERSION 0x0E: rbamp_basic_fw_name() restituisce "1.4.22" (tutte le varianti BASIC).

  • Registro dei modelli di sensore: le pinze 2000:1 con codice 11 (50 A) e 13 (100 A) sono ora modelli caratterizzati (portata nominale 50.0 A / 100.0 A, fondo scala 62.5 A / 116.5 A, picco 88.4 A / 164.7 A). Il codice 12 (80 A) resta per i moduli già associati.

Modificato

  • rbamp_set_ct_model_ch_force() su un modulo BASE di classe 2 o 3 restituisce ESP_ERR_INVALID_STATE con una riga di log che nomina la configurazione bloccata quando il modulo rifiuta la scrittura (il firmware 1.4.22 e successivi rifiuta le scritture di classe e modello su un modulo accoppiato in fabbrica fuori dalla modalità manutenzione). Prima il rifiuto appariva come un errore generico di parametro. Il percorso di force funziona su un modulo del genere solo in modalità manutenzione.

1.7.2 — Correzione del valore nominale SCT-013, ripresa dopo il downtime del master, letture di finestra in una sola transazione (2026-10-21)

Prima release pubblica dalla 1.5.0. Include insieme 1.6.0 – 1.7.2: la linea di moduli STD dietro lo stesso handle, la linea data-ready, eventi, energia in µWh e grandezze di fase, un conteggio di canali che segue il modulo (1, 2, 3, 5 o 7), il registro dei modelli di sensore con limiti di clipping, letture di finestra in una sola transazione, ripresa dopo un'interruzione del master, e la correzione del valore nominale SCT-013 per i moduli di linea corrente il cui firmware mantiene la calibrazione da 30 A (il firmware che dichiara la capacità di auto-correzione si corregge da solo). La validazione hardware di questa linea è stata fatta su un host con ESP-IDF 5.4.1.

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.
  • Commutazione del valore nominale SCT-013: un modulo sensore di corrente di classe 1 è calibrato con il sensore da 30 A, e il firmware fino a 1.4.19 mantiene quella calibrazione dopo che l'utente associa un altro modello. La libreria ora legge il guadagno che il modulo applica a rbamp_begin(), dopo una scrittura del modello e dopo ogni riavvio del modulo rilevato, e scala la corrente, la corrente di picco, la potenza reale, la potenza media di periodo, l'energia che integra, il digest e le soglie di evento verso il modello selezionato. Tensione e fattore di potenza non vengono scalati. rbamp_sct_correction() riporta l'esito per canale (rbamp_sct_correction_t: stato, modello, scala, guadagno applicato) e rbamp_sct_refresh() rivaluta su richiesta. Un guadagno ancora uguale al preset grezzo (modello commutato in questo avvio senza riavvio) provoca un CMD_RESET; un guadagno applicato inatteso, un modello sconosciuto o un preset grezzo che sopravvive al reset lasciano le letture non scalate con un avviso. Un modulo che dichiara la capacità di auto-correzione (firmware 1.4.20 e successivi) si corregge da solo e ottiene scala 1 — rilevato dalla capacità, mai da VERSION. CONFIG_RBAMP_SCT_RATING_CORRECTION (predefinito attivo) disattiva il meccanismo.

  • rbamp_begin_resume() — rbamp_begin() senza il latch di innesco. Un modulo BASIC continua a mediare fino al latch successivo, quindi dopo un riavvio o un'interruzione del master il primo snapshot consumato integra la finestra propria del modulo e recupera l'energia del periodo di fermo. Gli snapshot successivi usano l'orologio del master come prima. I moduli STD si comportano esattamente come con rbamp_begin().

  • rbamp_period_snapshot_t: module_window_ms (la lunghezza propria del modulo della finestra bloccata, 0 su STD; il modulo conta i commit da 100 ms sul firmware attuale e da 200 ms sul firmware precedente alla v1.2 — la libreria lo distingue dallo snapshot stesso e lo riporta in module_commit_ms), module_uptime_s, window_from_boot (la finestra è iniziata all'avvio del modulo: un riavvio, oppure il primo latch dall'avvio) e window_long (oltre 6 h, dove la media del modulo perde precisione). Al primo snapshot dopo rbamp_begin_resume(), module_restarted = window_from_boot.

  • rbamp_read_uptime_s() — secondi dall'avvio del modulo (BASE e STD). Legge 0 sul firmware BASE che non lo pubblica; allora window_from_boot resta falso.

  • rbamp_read_digest() — una finestra di un modulo BASIC in un'unica transazione: stato, sequenza della finestra e i campi scelti (corrente, tensione, potenza attiva con segno in watt interi, fattore di potenza) per i canali 0-2. Pensata per leggere ogni finestra pubblicata sulla linea dati pronti. rbamp_set_digest_fields() sceglie i campi; la libreria scrive la scelta sul modulo e la riscrive dopo un riavvio del modulo rilevato. Richiede il firmware BASIC con la capacità digest; non disponibile su STD.

  • rbamp_basic_fw_name() — il nome di rilascio del firmware per un byte di versione BASIC ("1.4.19" per 0x0B, e così via).

  • rbamp_read_sensor_class() — la classe di sensore attuale del modulo.

  • rbamp_sensor_model_limits() — la corrente RMS nominale di un modello di sensore, la corrente RMS alla quale una sinusoide inizia a tagliarsi, e il tetto istantaneo di taglio, in A, dal registro dei modelli generato (0 se non noto). rbamp_sensor_model_rated_a() è la forma abbreviata per la portata nominale; nota che la portata può differire dagli ampere indicati nel nome del modello.

  • Registro dei modelli di sensore generato, aggiornato con quei limiti.

  • rbamp_set_ct_model_ch_force() — percorso di servizio che imposta il modello di un canale indipendentemente dalla classe del modulo e dal modello attuale. Sostituisce la calibrazione che l'unità porta per quel canale con il preset generico del modello; va seguito da una calibrazione.

Modificato

  • rbamp_set_ct_model(), rbamp_set_ct_model_ch() e rbamp_configure_channels() su un modulo di classe 1 senza la capacità di autocorrezione (firmware fino alla 1.4.19) terminano con un riavvio del modulo (CMD_RESET, stesso UID verificato, circa un secondo): l'unico modo in cui il modulo torna al proprio guadagno calibrato dopo una scrittura di modello. La libreria riapplica ciò che possiede (latch di innesco, maschera del digest al prossimo uso); gli accumulatori di periodo ripartono come dopo un qualsiasi reset del modulo.

  • Il trasporto non chiama più i2c_master_bus_reset() autonomamente prima dell'ultimo tentativo di una transazione fallita. Il driver resetta già la propria macchina a stati dopo ogni transazione fallita, e il reset esplicito non prende il lock del bus: quando un altro task ha una transazione in volo pilota uno STOP sui pin attivi, che il gestore di interrupt del driver può prendere per la fine di una lettura e causare un crash nell'ISR (osservato su un host con un modulo collegato a caldo). CONFIG_RBAMP_BUS_RESET_ON_RETRY_EXHAUSTION ripristina il vecchio comportamento per un master monotask.

  • rbamp_set_sensor_class(), rbamp_set_ct_model(), rbamp_set_ct_model_ch() e rbamp_configure_channels() leggono prima di scrivere. Una classe o un modello già detenuti dal modulo non vengono riscritti (nessuna scrittura sul bus): sul modulo una scrittura di classe azzera i modelli di CT anche quando il valore è invariato, e una scrittura di modello riapplica il preset generico sopra la calibrazione propria dell'unità anche quando il modello è invariato; quindi ri-applicare una configurazione memorizzata a ogni riconnessione degradava le letture. Un modulo di classe 2 o 3 (fornito e calibrato insieme al proprio sensore) non viene riconfigurato: ESP_ERR_INVALID_STATE. rbamp_configure_channels() decide l'intera richiesta prima della prima scrittura, quindi su un tale modulo non resta nulla applicato a metà.

  • Documentazione di latch_ms: solo diagnostica, può leggere basso sotto carico; la finestra di integrazione dell'energia è master_dt_ms o module_window_ms.

  • La documentazione e l'help di Kconfig ora indicano la finestra di pubblicazione del modulo come 100 ms per tutta la famiglia (immagini più vecchie: 200 ms). L'assestamento di 300 ms che la libreria applica dopo un latch STD è descritto per quello che è: un limite superiore sicuro. Nessun comportamento temporale è cambiato.

Fisso

  • rbamp_read_all() / rbamp_read_all_ready() su un modulo con più di tre canali (UI5/UI7, BASIC o STD) scrivevano i canali 3+ oltre gli array a tre elementi di rbamp_snapshot_t: frequency, topology e channels venivano sovrascritti (l'host vedeva quindi channels = 0) e l'ultimo canale finiva quattro byte oltre la struct, nello stack del chiamante. Ora la chiamata riempie solo ch0-2 (RBAMP_SNAPSHOT_CHANNELS), esattamente come fa lo snapshot di periodo; i canali 3+ restano su rbamp_read_channel() / rbamp_read_all_channels(). Trovato su un host con un modulo a 7 canali. Una simulazione host dell'intero componente contro un'immagine di registri fittizia ora esegue read_all per 1/3/5/7 canali con parole di guardia dopo la struct.

1.7.1 — Il numero di canali segue il modulo (2026-10-18)

Fisso

  • rbamp_new() creava un handle il cui numero di canali era fissato a tre, quindi un modulo a canale singolo (UI1, I1) risultava ancora con tre canali dopo rbamp_begin(). Il costruttore predefinito ora adotta il numero di canali e la presenza di tensione dal registro varianti del modulo; tre canali restano solo come ripiego per il firmware che non pubblica una variante. rbamp_new_with_topology() continua a fissare il conteggio come prima (viene registrato un avviso quando il modulo non è d'accordo). Segnalato da un host che esegue una UI1; validato lì: una UI1 riporta un canale e la variante UI1 dopo rbamp_begin().

  • rbamp_read_variant() sulla linea BASE restituiva UNKNOWN per i codici UI5 / UI7; ora mappa ogni codice noto.

Aggiunto

  • rbamp_variant_t rbamp_variant(rbamp_handle_t dev) — la variante memorizzata da rbamp_begin(), senza traffico sul bus. RBAMP_VARIANT_UNKNOWN prima di rbamp_begin() o quando il modulo non pubblica la propria variante.

  • Test unitari host per la policy di variante di entrambi i costruttori (test/host/test_std_decode.c).

1.7.0 — energia in µWh, corrente di avviamento, angoli di fase e sequenza (2026-10-17)

Supporto per la versione immagine modulo 0x0001007A / 0x0001007B. Ogni aggiunta è vincolata a quanto riporta il modulo; i moduli più vecchi si comportano esattamente come prima.

Validato su moduli STD con versione immagine modulo 0x0001007B su un'applicazione host: get/set della corrente di avviamento e rilettura, angoli di fase e sequenza di fase su un modulo trifase, flag di energia fine, delta di energia attraverso i riavvii del modulo.

Aggiunto

  • Energia con risoluzione µWh / µvarh in rbamp_std_energy_t: act_import_uwh, act_export_uwh, act_net_uwh, rea_import_uvarh, rea_export_uvarh, ch_import_uwh[], ch_export_uwh[], più fine / fine_reactive. I campi sono riempiti su ogni modulo: dai contatori µ del modulo stesso quando li pubblica (versione di immagine 0x0001007A; reattiva da 0x0001007B), altrimenti scalati dai contatori grossolani con fine false — i chiamanti possono usare i campi µ senza condizioni. Letti come snapshot coerenti (una transazione per blocco). rbamp_std_energy_delta applica le stesse regole (cambio di generazione → nessun delta, calo di uptime = riavvio, contatore sotto la lettura precedente → 0, netto = importazione − esportazione). rbamp_read_period_snapshot sul percorso a contatori usa la differenza in µWh quando disponibile.

  • Corrente di avvio per l'energia: rbamp_std_get_start_current / rbamp_std_set_start_current (µA; 0 = disattivata; un valore fuori dall'insieme ammesso dal modulo → ESP_ERR_INVALID_ARG senza scrittura sul bus; viene riletto e confermato; rbamp_save_user_config lo rende persistente). Sotto questa corrente di canale il modulo non conta energia; le letture non sono influenzate. Anche in rbamp_std_config_t (start_ua, start_ua_supported). ESP_ERR_NOT_SUPPORTED senza traffico sul bus prima della versione di immagine del modulo 0x0001007B.

  • Angolo di fase della tensione: rbamp_std_voltage_t.angle_deg / angle_valid (gradi rispetto all'ingresso di tensione 0; versione immagine modulo 0x0001007A+, moduli trifase; altrimenti angle_valid falso). Stessa lettura a raffica singola di prima.

  • Sequenza di fase: rbamp_std_read_phase_seq → rbamp_std_phase_seq_t (RBAMP_STD_PHASE_SEQ_NA / FORWARD / REVERSE / ABNORMAL); ESP_ERR_NOT_SUPPORTED senza traffico sul bus prima della versione immagine modulo 0x0001007A.

  • Test unitario su host delle sole funzioni di decodifica: test/host/run.sh (gcc, senza ESP-IDF). Le regole del delta di energia ora risiedono in src/rbamp_std_decode.c.

Modificato

  • rbamp_is_provisioned (linea STD) documenta il marcatore di calibrazione della versione di immagine del modulo 0x0001007A: un'unità calibrata con un firmware precedente risulta false dopo l'aggiornamento, finché non si esegue una volta rbamp_save_gains.

Nota di aggiornamento

  • La struttura dello snapshot di energia (rbamp_std_energy_t) ha acquisito campi in questa versione. Se la sua applicazione la salva come blob binario grezzo (NVS, file), memorizzi solo i campi che le servono in un proprio formato fisso; un blob salvato da una versione precedente non corrisponderà alla nuova dimensione.

1.6.1 — Completamento dei comandi, letture coerenti, controlli di sessione OTA (2026-10-11)

Correzioni lato libreria dall'audit di firmware/libreria del 2026-10-11. Nessuna nuova API; il comportamento delle chiamate esistenti sulla linea STD è reso più rigoroso.

Modificato

  • Il completamento del comando è il registro di stato del comando (flag di occupato azzerato e contatore dei comandi completati avanzato), mai il solo registro degli errori; il verdetto viene letto solo dopo il completamento. I salvataggi (rbamp_save_gains, rbamp_save_user_config), rbamp_std_cal_thd_floor, rbamp_reset, il cambio di indirizzo e ogni comando OTA lo usano — nessuna pausa fissa di assestamento sui moduli che pubblicano il registro, con timeout di almeno 1 s (3 s per il commit OTA). Un comando scritto mentre il modulo è occupato viene prima atteso; un comando che il modulo ha scartato (overrun) fallisce con ESP_ERR_INVALID_STATE invece di restituire il verdetto del comando precedente.

  • Una scrittura di comando non viene mai ritentata in caso di errore di trasporto (un retry potrebbe consegnare due volte l'opcode). Letture e scritture dei registri dati mantengono il retry.

  • Le letture a blocchi sono una sola transazione — il modulo serve ogni lettura da uno snapshot coerente, quindi i contatori di energia, i blocchi di canale e i totali non si disallineano più tra le raffiche. rbamp_read_all su un modulo STD legge per intero il blocco di tensione e ogni blocco di canale invece di farlo campo per campo.

  • OTA: dopo ogni pagina la sessione deve restare aperta (stato 1); altrimenti ESP_ERR_INVALID_STATE con il motivo del modulo registrato nel log — ripartire da begin. I poll durante un blocco di flash non reimpostano più il bus. rbamp_std_ota_activate regge per la finestra di prova di ~10 s del modulo e conferma che l'immagine in esecuzione è la versione in staging e che lo scambio non è più in attesa. rbamp_std_ota_write_image (immagine costruita sull'host, non firmata) restituisce ESP_ERR_NOT_SUPPORTED prima di toccare il modulo — il firmware del modulo accetta solo immagini preparate dal fornitore.

  • Cambio di indirizzo (rbamp_commit_address_change, STD): il salvataggio della configurazione è sincrono (limite di frequenza → ESP_ERR_NOT_FINISHED, riprovi dopo circa 5 s), e l'handle passa al nuovo indirizzo solo dopo che un modulo risponde lì; altrimenti ESP_ERR_NOT_FOUND e l'handle mantiene il vecchio indirizzo.

  • rbamp_std_read_totals: i campi di energia dei blocchi aggregati valgono 0 (non popolati dal modulo — usi rbamp_std_read_energy).

  • rbamp_read_frequency (STD): 0 dal modulo significa nessuna rete → ESP_ERR_INVALID_RESPONSE / NaN (rbamp_read_all lo segnala come non plausibile).

  • rbamp_is_provisioned (STD): documentato come affidabile dalla versione immagine modulo 0x00010079 (le immagini più vecchie riportano anche calibrazione valida sui guadagni predefiniti).

1.6.0 — linea di moduli STD, linea data-ready, eventi (2026-10-11)

Aggiunto

  • Linea di moduli STD (mappa registri a 16 bit) dietro lo stesso handle e la stessa API della linea originale: rbamp_std_probe / rbamp_std_identify / rbamp_std_info, letture in tempo reale per canale incl. potenza reattiva e apparente (rbamp_read_reactive_power, rbamp_read_apparent_power, rbamp_std_read_channel, rbamp_std_read_voltage), totali per fase e generali (rbamp_std_read_totals), configurazione e armoniche (rbamp_std_read_config, rbamp_std_set_harmonics, rbamp_std_cal_thd_floor).

  • Energia sui moduli senza banchi di latch: la sorgente del periodo viene scelta dalle capacità del modulo in rbamp_begin (rbamp_std_info_t.period_source); l'energia di periodo è la differenza di due letture dei contatori persistenti, con regole di riavvio e di reset del contatore. rbamp_std_read_energy (Wh / varh, più mWh per canale e per gruppo sulla mappa 0x36+), rbamp_std_energy_delta, rbamp_energy_add_wh, RBAMP_ENERGY_CH_TOTAL. rbamp_period_snapshot_t ha acquisito avg_p_total, wh_net e module_restarted.

  • Banchi di latch sui moduli che li hanno: rbamp_std_arm_banks, rbamp_std_latch, rbamp_std_read_latch, rbamp_std_latch_wh.

  • Orologio del modulo, storico e registro eventi: rbamp_std_set_time, rbamp_std_read_time, rbamp_std_read_image_version, rbamp_std_hist_info, rbamp_std_hist_read, rbamp_std_hist_read_raw, rbamp_std_event_read, rbamp_std_hist_flush (il buffer orario è persistente; il record da 15 minuti è solo l'ultimo).

  • Salute: rbamp_std_read_health esteso con bit di stato, durata di vita e fonti di calibrazione, contatori dei frame, uptime, e causa del reset + numero di avvii (versione di immagine del modulo 0x00010076 e successive, RBAMP_STD_RST_*).

  • Comandi e servizio: rbamp_std_command, rbamp_std_wait_idle, rbamp_std_locate, rbamp_std_read_board_id, rbamp_std_ota_board_ok (verifica della scheda prima di un flusso OTA), rbamp_std_set_address_by_uid.

  • OTA: aggiornamento dell'immagine a doppio banco, incluse le immagini firmate preparate (rbamp_std_ota_begin … rbamp_std_ota_activate, rbamp_std_ota_write_prepared, rbamp_std_ota_write_prepared_pair, rbamp_std_ota_diag, rbamp_std_ota_staged_version, rbamp_std_ota_abort).

  • Certificato e attestazione: rbamp_std_read_certificate, rbamp_std_attest (la verifica della firma è fatta dall'applicazione).

  • Linea dati pronti (DRDY), entrambe le linee di moduli: rbamp_set_drdy_gpio, rbamp_wait_data_ready, rbamp_read_all_ready, rbamp_read_data_seq. Una linea open-drain può essere condivisa da più moduli; la libreria verifica la sequenza di pubblicazione, conta le finestre mancate, riporta la latenza e rileva un allarme con linea tenuta bassa. Ripiego a interrogazione tramite CONFIG_RBAMP_DRDY_POLL_MS. I moduli STD richiedono la versione di immagine 0x00010075 o successiva.

  • Eventi su entrambe le linee: rbamp_read_event_mask, rbamp_set_event_mask, rbamp_set_event_thresholds, rbamp_begin_event_flags, RBAMP_EVENT_NVM_FAULT; rbamp_read_event_flags / rbamp_clear_event_flags / rbamp_has_error / rbamp_clear_error ora coprono la linea STD.

  • Kconfig: RBAMP_I2C_SCL_WAIT_US (budget di clock-stretch, predefinito 10 ms) e RBAMP_DRDY_POLL_MS.

  • Esempio std_meter.

Modificato

  • Le chiamate di periodo su moduli senza banchi di latch restituiscono ESP_ERR_NOT_SUPPORTED invece di riportare silenziosamente un periodo non valido.

  • rbamp_set_ct_model_ch restituisce ESP_ERR_NOT_SUPPORTED sui moduli STD la cui mappa dei canali non è scrivibile.

  • rbamp_err_to_str copre ESP_ERR_NOT_FOUND, ESP_ERR_NOT_FINISHED e ESP_ERR_INVALID_CRC.

  • rbamp_period_snapshot_t e rbamp_std_health_t hanno acquisito campi (compatibili con il sorgente; ricompilare i dipendenti).

  • Il componente ora richiede esp_driver_gpio (componente IDF integrato).

1.5.0 — Modello di CT per canale su ogni canale (2026-09-04)

Aggiunto

  • rbamp_set_ct_model_ch / rbamp_read_ct_model_ch / rbamp_configure_channels accettano qualsiasi canale fino al numero di canali rilevato (canali 3+ attraverso la finestra dei canali).

  • I codici modello e i descrittori provengono dal file generato rbamp_sensor_models.h (rbamp_sensor_model_lookup); i codici sconosciuti vengono rifiutati dal modulo e segnalati al chiamante.

Fisso

  • Classe del sensore e modello di CT ora persistono sui moduli di produzione: il precedente opcode di salvataggio non scriveva in flash sul firmware di produzione, per cui l'associazione restava in RAM e andava persa al riavvio successivo. Nessuna modifica di API, stesso assestamento di ~700 ms.

1.4.0 — Moduli a cinque e sette canali

Aggiunto

  • Topologia FIVE_CH / SEVEN_CH, varianti UI5 / UI7, RBAMP_MAX_CHANNELS = 7; rbamp_read_channel, rbamp_read_all_channels, rbamp_read_commit_seq. Il periodo di snapshot integra tutti i canali.

1.3.0 (2026-06-16) — Rilascio pubblico

Prima versione pubblica del componente rbamp per ESP-IDF v5.x.

Caratteristiche principali

  • Gestore della flotta: gestisce un gruppo di moduli su un unico bus I²C tramite un unico handle rbamp_fleet_t. Scoperta con rilevamento dei conflitti e canarino wedge di Tier-2, _poll_all resiliente ai MISS, aggregazione di potenza totale / energia totale / errori, broadcast-latch per una sincronia stretta. Vedi il capitolo 09 · Riferimento API, sezione "Gestore della flotta".

  • Messa in servizio: rbamp_provision — un flusso in una sola chiamata per riassegnare un modulo vergine al suo indirizzo di lavoro, con salvataggio facoltativo della configurazione in flash. Disciplina: un vergine alla volta sul bus (un OBBLIGO normativo).

  • Configurazione multi-canale: rbamp_configure_channels — impostazione atomica per canale dei modelli CT in una singola operazione con un unico ciclo finale di scrittura in flash (favorevole alla flash).

  • Modello di errore v1.3: separa l'esito dell'ultima scrittura (REG_ERROR (0x02) — canale sincrono, validato dai setter) dal segnale asincrono persistente (EVENT_FLAGS.bit3 — sticky, per i fatti a runtime). Le funzioni corrispondenti sono rbamp_read_last_error, rbamp_has_error, rbamp_clear_error, rbamp_read_event_flags.

  • Identità / rilevamento delle funzionalità: rbamp_read_variant, rbamp_read_capability (mappa delle funzionalità), rbamp_has_voltage, rbamp_read_product_id, rbamp_read_uid, rbamp_is_provisioned.

Canone riflesso nella documentazione

  • La topologia multi-modulo è la modalità operativa principale della libreria. Lo scenario "un modulo sul bus" è il caso minimo, non il canone. Il deployment canonico è un modulo di rete all'ingresso di servizio più N moduli sui singoli carichi, tutti su un unico bus I²C sotto un unico handle della flotta.

  • SKU supportati sull'hardware attuale: UI1 (contatore di rete: tensione + corrente + potenza + PF + energia), I1 / I2 / I3 (sotto-contatori: solo corrente, per canale). UI2 / UI3 arriveranno con firmware successivo.

  • Energia e potenza sono calcolate solo sulle varianti UI (che hanno un front-end di tensione). Sulle varianti I, rbamp_read_power / _power_factor restituiscono 0.0f; l'aggregazione di flotta di potenza totale / energia somma correttamente e ignora i contributi zero.

  • L'associazione del CT è pura predisposizione (canone v1.3): scrivere REG_CT_MODEL NON applica automaticamente il valore; l'associazione avviene tramite il CMD_SET_CT_MODEL_CHn per canale. L'ordine di associazione è arbitrario (le anomalie «ordine crescente/decrescente» della versione pre-v1.3 sono state rimosse).

  • Il cambio di indirizzo è accettabile in produzione: commit in due fasi + magic + reset funziona in produzione (non serve la modalità di fabbrica).

  • L'orologio a parete del master = base temporale canonica per il Wh: il timer software del chip PERIOD_LATCH_MS (0xEC) è solo diagnostico; non lo usi per l'energia. Il master usa il proprio esp_timer_get_time() oppure l'orologio a parete.

Documentazione — capitoli nuovi / rielaborati

  • 01_overview — introduzione rielaborata in ottica multi-modulo; aggiunto un diagramma ASCII dello scenario 80%.

  • 03_sensor_selection — scansione dell'ordine dei CT; nuova sezione «Moduli multicanale — I2 e I3 (solo corrente)» con uno schema di disaggregazione UI1+I3.

  • 04_hardware — la sezione "Bus multi-modulo — topologia primaria" promossa a modalità operativa principale; requisito esplicito di pull-up esterni da ~4.7 kΩ sul bus della flotta; flusso di provisioning tramite rbamp_provision.

  • 09_api_reference — sezioni aggiunte: "Identità e provisioning", "Modello di errore v1.3", "Configurazione multi-canale", "Gestore della flotta — gestione di più moduli", "Configurazione della flotta per dispositivo".

  • 10_troubleshooting — sezioni aggiunte "Il bus i2c_master di IDF si blocca su un bus marginale — mitigazione a tre livelli" (con una tabella dei tassi di blocco validata su HW), "Flotta: un modulo è finito in excluded", "Flotta: rbamp_fleet_scan ha restituito INVALID_STATE", "Flotta: rbamp_provision ha restituito un errore".

  • 11_changelog — questo file.


Fonte e segnalazioni: rb-amp/rbamp-esp-idf · questa pagina nel repository: docs/11_changelog.md (v1.7.3)