Riferimento del protocollo a fili rbAmp (v1.3)
rbAmp è un modulo hardware compatto per la misura dei parametri della rete in corrente alternata tramite interfaccia I²C. Il modulo si comporta come uno slave I²C standard con una mappa di registri fissa (pagina 0, 0x00..0xFF). Questo documento descrive il protocollo sul filo a livello di registri, comandi e sequenze.
: integratori terzi e avanzati che scrivono i propri driver I²C per il modulo rbAmp senza usare le librerie client (Arduino / ESP-IDF / Python / ESPHome).
Ambito: protocollo canonico sul filo del modulo rbAmp alla versione v1.3 — mappa dei registri, sequenze di protocollo, garanzie di comportamento. È il riferimento completo a livello di contratto di filo.
Versione: "v1.3" è la versione del protocollo sul filo (il registro VERSION 0x03 riporta 0x04), non la versione di questo documento. È il protocollo di tutti i firmware BASIC attuali (1.4.x); i moduli STANDARD (STD) usano una mappa di registri diversa — vedi il riferimento tecnico STD.
NON incluso nell'ambito: integrazione con una specifica libreria / sistema operativo / framework — consulti la documentazione di quella libreria.
1 · Introduzione
1.1 Gamma dei SKU
Le varianti del modulo (SCT-UI1 … SCT-I3, con i loro canali di tensione e corrente) sono elencate in overview.md → Varianti del modulo.
Le varianti I (I1/I2/I3) non hanno hardware di tensione — i registri U_RMS, U_PEAK e P restituiscono 0.0. La frequenza (AC_FREQ) è disponibile su tutte le varianti (derivata dal passaggio per lo zero).
La calibrazione è di fabbrica. Il master del consumatore NON configura il livello di rumore (NF), il guadagno, la compensazione di fase né altri parametri di fabbrica — sono tutti calibrazione di fabbrica impressa nel modulo (vedi §4.0 intervalli riservati). Sui moduli BASIC della serie SCT (usati con sensori SCT-013) il consumatore scrive solo SENSOR_CLASS + CT_MODEL (vedi §6.2) — il modulo applica tutto il resto automaticamente dalla tabella di preset. I moduli BASIC della serie CT e STANDARD (STD) sono forniti in coppia con i loro sensori, preimpostati e calibrati in fabbrica: non si scrive nulla.
1.2 Versionamento
| Campo | Valore |
|---|---|
protocol_version |
1.3 |
schema_version |
2 |
Registro VERSION (0x03) |
0x04 per la v1.3 |
| Contratto della pagina 0 | congelato alla release v1.3 |
2 · Nozioni di base del protocollo di bus
2.0 Alimentazione e alimentazione del modulo
| Parametro | Valore |
|---|---|
VCC nominale |
+5 V |
Intervallo di VCC |
4.5..5.5 V |
| Assorbimento di corrente tipico | ~15 mA |
| Assorbimento di corrente di picco (snapshot + scrittura flash) | ~25 mA |
| Corrente di spunto all'avvio | ≤ 50 mA @ 5 ms |
| Sequenza | VCC può essere applicato in contemporanea a I²C; i pull-up (3.3 V) sono ammessi prima di applicare VCC |
| Isolamento | il modulo è tutto a bassa tensione: la pinza si accoppia magneticamente e la presa di tensione UI è isolata galvanicamente |
Quattro fili sono obbligatori sul lato LV: VCC, GND, SDA, SCL. DRDY (open-drain) è opzionale. Vedi §2.3 per i pull-up e le indicazioni multi-modulo.
2.1 Parametri I²C
- Indirizzo predefinito:
0x50(7 bit). - Intervallo di indirizzi consentito:
0x08..0x77(limiti I²C standard riservati). - Livelli logici: 3.3 V (tolleranti a 5 V sui pull-up verso 3.3 V).
- Pull-up di bordo: 4.7 kΩ su SDA/SCL verso 3.3 V (modulo).
- Clock stretching: il modulo NON usa lo stretching del clock SCL come normale controllo di flusso. Tra una transazione e l'altra il master deve rispettare un intervallo tra transazioni ≥ 100 µs (
tBUF). Transazioni consecutive senza pausa (START ripetuto senzatBUF) sono permesse ma sconsigliate — alcuni stack host (ESP-IDF i2c_master) mostrano un tasso di NACK più alto. Vedi separatamente la sezione §5 su accettazione / EMI.
2.2 Velocità del bus
| Velocità | Applicabilità | Nota |
|---|---|---|
| 50 kHz | consigliato su host ESP32 ed ESP8266 | Il driver I²C di ESP-IDF mostra un tasso di NACK di ~20 % a 100 kHz — un limite del driver host, non del modulo; 50 kHz + 3 tentativi danno un tasso di errore < 0.8 %. |
| 100 kHz | raccomandato su altri host | utilizzabile anche su ESP32/ESP8266 con retry 3× a livello applicativo. |
| 400 kHz | non consigliato | la velocità è una scelta dell'utente. |
2.3 Bus multi-modulo
Più moduli rbAmp possono condividere un solo bus:
- Fino a ~16 moduli (limitato dalla capacità totale del bus ≤ 400 pF a 100 kHz).
- Pull-up: con 2–3 moduli su un bus fino a 15 cm lasci invariate le pull-up di bordo; con quattro o più, oppure su un bus più lungo, le pull-up da 4.7 kΩ in parallelo sovraccaricano il sink. Tagli le pull-up di bordo su tutti i moduli tranne uno (oppure usi un buffer I²C PCA9515/9615).
- Lunghezza: fino a 0.15 m semplice → 100 kHz; 0.15–1 m doppino intrecciato (SDA+GND e SCL+GND in coppie separate) → 100 kHz; oltre 1 m — buffer I²C; oltre 3 m — bus differenziale (PCA9615 / LTC4332).
2.4 Budget di polling del bus
A 50 kHz una singola transazione di lettura di un registro dura ≈ 200–400 µs. Il blocco RT completo per un canale (U + I + P + PF, 4 float = 16 byte in burst) dura ≈ 5–8 ms per canale.
| Configurazione | Bus per ciclo | Frequenza massima di polling |
|---|---|---|
| 1× UI1, blocco RT | ~5 ms | 100+ Hz (ma il modulo aggiorna a 10 Hz) |
| 5× UI1, blocco RT | ~25 ms | 10 Hz |
| 16× I3, RT + periodo | ~400 ms | non riesce a stare al passo — legge ogni ~4 finestre da 100 ms |
Regola pratica: a 50 kHz i limiti comodi sono 8–10× I3 o 15–16× UI1 interrogando ogni altra finestra (5 Hz); dimezzi il numero dei moduli per interrogare ogni finestra (10 Hz).
3 · Modello delle varianti
3.1 HW_VARIANT (reg 0x55, u8, sola lettura)
Byte SKU autorevole:
| Valore | SKU | N_I | HW della tensione |
|---|---|---|---|
0x01 |
UI1 | 1 | sì |
0x02 |
UI2 | 2 | sì |
0x03 |
UI3 | 3 | sì |
0x04 |
I1 | 1 | no |
0x05 |
I2 | 2 | no |
0x06 |
I3 | 3 | no |
0x07 |
UI5 | 5 | sì |
0x08 |
UI7 | 7 | sì |
Qualsiasi altro valore → il dispositivo non è identificato come rbAmp.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readVariant() |
legga la variante hardware (SKU) |
| ESP-IDF | rbamp_read_variant() |
legga la variante hardware (SKU) |
| Python | dev.read_variant() |
legga la variante hardware (SKU) |
| ESPHome | get_variant_str() |
legga la variante hardware (SKU) |
3.2 CAPABILITY (registri 0x57/0x58, u16 LE, sola lettura)
Mappa di bit di rilevamento delle funzioni. È il modo canonico per rilevare le funzioni supportate — senza confronto numerico di versione.
| bit | Flag | Significato |
|---|---|---|
| 0 | EXT_ADDRESSING | indirizzamento esteso a 16 bit (prefisso 0xFF) |
| 1 | GC_LATCH | Lo snapshot General-Call è supportato |
| 2 | GC_GROUP_FILTER | Il filtro GROUP_ID è attivo |
| 3 | DIGEST | il blocco digest (0x70..0x85) è esposto |
| 4 | EVENTS | EVENT_FLAGS è supportato |
| 5 | UID_ARBITRATION | Arbitraggio degli indirizzi basato su UID (nessun comando pubblico) |
| 6 | SEAL | riservato — non implementato |
| 7 | TWO_PHASE_ADDR | modifica dell'indirizzo a due fasi (two-phase commit) |
| 8 | ZC_PHASE_OFFSET = hardware-tensione | il modulo ha un canale U |
| 9 | SAVE_USER_CONFIG | CMD_SAVE_USER_CONFIG è disponibile |
| 10 | CLEAR_ERROR | CMD_CLEAR_ERROR è disponibile |
| 11 | IAP | programmazione in-application (solo livelli F4) |
| 12 | SCT_RATING_SELF | fw 1.4.20+: un cambio di modello SCT mantiene la calibrazione dell'unità e sopravvive a un riavvio; le librerie saltano la propria correzione di portata |
3.2.1 Rilevamento delle funzioni
Rilevi ogni funzione tramite il suo singolo bit — mai confrontando l'intero registro con una costante attesa: la mappa di bit cresce con il firmware (ad es. il bit 12 è comparso nel fw 1.4.20), quindi il confronto del valore completo si rompe sui moduli più recenti.
3.2.2 Layout dei byte di CAPABILITY u16 LE
CAPABILITY occupa 2 byte agli indirizzi 0x57 (byte basso) e 0x58 (byte alto), little-endian:
register layout (byte-addressed):
0x57 0x58
┌──────┬──────┐
│ LO │ HI │
└──────┴──────┘
bits bits
0-7 8-15
full u16 = (read_u8(0x58) << 8) | read_u8(0x57)
Mappatura dei bit:
- il byte
0x57(LO) contiene i bit 0..7: EXT_ADDRESSING, GC_LATCH, GC_GROUP_FILTER, DIGEST, EVENTS, UID_ARBITRATION, SEAL, TWO_PHASE_ADDR. - il byte
0x58(HI) contiene i bit 8..15: ZC_PHASE_OFFSET (= HW della tensione), SAVE_USER_CONFIG, CLEAR_ERROR, IAP, SCT_RATING_SELF (bit 12, fw 1.4.20+), bit 13-15 riservati.
3.2.3 Ricetta canonica di has_voltage
cap_hi = read_u8(0x58) # high byte holds bits 8..15
has_voltage = bool(cap_hi & 0x01) # bit 8 of the u16 = bit 0 of byte 0x58
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readCapability(out) / RbAmp::hasVoltageHw() |
legga la mappa delle funzioni a 16 bit; verifichi la presenza di un canale di tensione |
| ESP-IDF | rbamp_read_capability() / rbamp_has_voltage() |
legga la mappa delle funzioni a 16 bit; verifichi la presenza di un canale di tensione |
| Python | dev.read_capability() / dev.has_voltage() |
legga la mappa delle funzioni a 16 bit; verifichi la presenza di un canale di tensione |
| ESPHome | get_capability_hex() |
legga la mappa delle funzioni |
3.3 Tabella del profilo di variante — invariante
| SKU | HW_VARIANT (0x55) | N_I | hardware-tensione | CAPABILITY bit 8 (hardware-tensione) |
|---|---|---|---|---|
| UI1 | 1 | 1 | sì | bit 8 impostato |
| UI2 | 2 | 2 | sì | bit 8 impostato |
| UI3 | 3 | 3 | sì | bit 8 impostato |
| I1 | 4 | 1 | no | bit 8 a zero |
| I2 | 5 | 2 | no | bit 8 a zero |
| I3 | 6 | 3 | no | bit 8 a zero |
| UI5 | 7 | 5 | sì | bit 8 impostato |
| UI7 | 8 | 7 | sì | bit 8 impostato |
Coerenza HW_VARIANT ⟷ CAPABILITY: HW_VARIANT da 1 a 3 e da 7 a 8 (UI) → bit 8 impostato; HW_VARIANT da 4 a 6 (I) → bit 8 a zero. Una discrepanza indica un'anomalia hardware o firmware (dispositivo difettoso o flash errato).
3.4 SENSOR_CLASS ≠ discriminatore di variante
⚠ SENSOR_CLASS (0x25) NON è un discriminatore di variante. È un registro di configurazione utente (selettore della classe del sensore CT: Unset/Sct013/WiredCT/BuiltinCT) e non riflette la variante hardware. Per rilevare la variante usi solo HW_VARIANT (0x55) + CAPABILITY (0x57/0x58).
3.5 PRODUCT_ID (0x54, u8, sola lettura)
Discriminatore della famiglia di prodotto:
| Valore | Famiglia |
|---|---|
0x01 |
sensore rbAmp (questo documento) |
0x02 |
rbDimmer (mappa dei registri separata; non coperta da questo documento) |
Il master DEVE leggere PRODUCT_ID prima di interpretare qualsiasi registro specifico della famiglia.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readProductId() |
legga il byte dell'ID famiglia |
| ESP-IDF | rbamp_read_product_id() |
legga il byte dell'ID famiglia |
| Python | dev.read_product_id() |
legga il byte dell'ID famiglia |
| ESPHome | — | non esposto |
3.6 Algoritmo canonico di rilevamento
if not i2c_addr_acks(addr):
return NO_DEVICE
product = read_u8(addr, 0x54)
if product != 0x01:
return NOT_RBAMP_SENSOR
hw = read_u8(addr, 0x55)
if 1 <= hw <= 8:
cap_hi = read_u8(addr, 0x58)
has_voltage = bool(cap_hi & 0x01)
return {sku: SKU[hw], N_I: N_I_TABLE[hw], has_voltage: has_voltage}
return UNKNOWN_DEVICE
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::begin() / RbAmp::readVariant() |
interroghi il modulo e ne rilevi la linea; legga la variante |
| ESP-IDF | rbamp_begin() / rbamp_read_variant() |
interroghi il modulo e ne rilevi la linea; legga la variante |
| Python | dev.begin() / dev.read_variant() |
interroghi il modulo e ne rilevi la linea; legga la variante |
| ESPHome | rbamp: address: / get_variant_str() |
indirizzo del modulo impostato nel YAML; la variante come testo |
4 · Mappa dei registri (produzione v1.3)
Filtro applicato: build: production(registri di build di calibrazione esclusi). I registri di calibrazione di fabbrica (NF, GAIN, PHASE) sononon documentato— appartengono al banco di fabbrica, non alla superficie per il consumatore.
4.0 Intervalli riservati (interni)
Gli intervalli seguenti sono riservati all'uso interno/di fabbrica e non sono descritti in questo documento. Le letture restituiscono dati non rilevanti per la logica del consumatore oppure 0x00 per indirizzi inesistenti (vedi §5.2). Le scritture su questi indirizzi vengono o scartate in silenzio o rispondono con ERR_PARAM:
0x04— indicatore interno di modalità (controllato dalla fabbrica, non impostabile dall'utente).0x06,0x26— parametri di calibrazione interni (banco di fabbrica).0x08..0x0F— vista di debug della LUT (diagnostica di fabbrica).0x1B..0x1F— pagina 0 riservata (0x18..0x1Asono diagnostica di produzione, vedi §4.2).0x36..0x3B,0x40..0x45— pagina 0 riservata (0x32+0x3C..0x3Fsono la finestra di accesso ai canali, vedi §4.14).0x4F,0x50— riservati (prenotazione preventiva del blocco identità).0xE4..0xEB,0xF0..0xFF— calibrazione di fabbrica (NF, GAIN); scritture riservate alla fabbrica.
Nota su 0xD0..0xE3: nella build di produzione questo intervallo è occupato dal blocco V03 Q (vedi §4.12). Nel firmware di calibrazione separato (non distribuito al consumatore) lo stesso intervallo è sovrapposto dal blocco di calibrazione (build:cal). Il master del consumatore vede solo la sovrapposizione di produzione — il blocco Q.
Gli integratori 3rd-party devono ignorare questi intervalli.
4.1 Blocco di controllo (0x00..0x07)
| Ind. | Nome | Dimensione | Tipo | Accesso | Persistenza | Note |
|---|---|---|---|---|---|---|
0x00 |
STATUS |
1 | u8 | r | ram | bit0=READY, bit1=ERROR (specchio di REG_ERROR != 0), bit2=EVENTS_PENDING (specchio di EVENT_FLAGS != 0) |
0x01 |
COMMAND |
1 | u8 | w | ram | Scriva un opcode CMD_* (vedi §5.2) |
0x02 |
ERROR |
1 | u8 | r | ram | esito dell'ultima scrittura; 0x00 = OK; 0xFA..0xFF classi di errore. Si cancella con CMD_CLEAR_ERROR. Vedi §5.3 |
0x03 |
VERSION |
1 | u8 | r | rom | Versione del protocollo. 0x04 = v1.3 |
0x05 |
CT_MODEL |
1 | u8 | rw | user_config | Codice SKU SCT-013 (preparazione pura v1.3 — vedi §6.2) |
0x07 |
V03_PERIOD_VALID |
1 | u8 | r | ram | Impostato da CMD_LATCH_PERIOD: 1 = aggiornato, 0 = vuoto/non aggiornato. NON si cancella alla lettura. Vedi §6.3.3 (testimone) + §7.5 (conservazione dello snapshot fallito) |
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::waitReady(timeout_ms) / RbAmp::readLastError() |
attenda il flag di pronto; legga il codice di errore del dispositivo |
| ESP-IDF | rbamp_wait_ready() / rbamp_read_last_error() |
attenda il flag di pronto; legga il codice di errore del dispositivo |
| Python | dev.wait_ready(timeout_ms=1000) / dev.read_last_error() |
attenda il flag di pronto (solleva un errore al timeout); legga il codice di errore del dispositivo |
| ESPHome | update() verifica di prontezza / get_last_error_str() |
le letture vengono pubblicate quando il modulo segnala di essere pronto; il codice di errore come testo |
4.2 Diagnostica — medie degli ingressi grezzi e finestra di cattura (0x10..0x1C)
| Ind. | Nome | Dimensione | Tipo | Accesso | Persistenza | Note |
|---|---|---|---|---|---|---|
0x10 |
ADC_MEAN_U |
2 | u16 LE | r | ram | Media del grezzo di ingresso, canale U (~2048 centrato) |
0x12 |
ADC_MEAN_I0 |
2 | u16 LE | r | ram | Media dell'ingresso grezzo, I0 |
0x14 |
ADC_MEAN_I1 |
2 | u16 LE | r | ram | Media dell'ingresso grezzo, I1 (UI2/I2/I3/UI3) |
0x16 |
ADC_MEAN_I2 |
2 | u16 LE | r | ram | Media del grezzo di ingresso, I2 (UI3/I3) |
0x18 |
CAPTURE_STATUS |
1 | u8 | r | ram | Cattura dei campioni grezzi: bit0=pronto |
0x19 |
CAPTURE_PAGE |
1 | u8 | rw | ram | Pagina 0..15 → 16 campioni grezzi I0 in CAPTURE_WINDOW |
0x1A |
CAPTURE_WINDOW |
32 | byte | r | ram | 16×u16 LE codici I0 pre-LUT. Lettura in burst di 32 byte. |
4.3 Sistema (0x20..0x25)
| Ind. | Nome | Dimensione | Tipo | Accesso | Persistenza | Note |
|---|---|---|---|---|---|---|
0x20 |
AC_FREQ |
1 | u8 | r | ram | Derivato dal passaggio per lo zero. 50 o 60 Hz interi. Il passaggio per lo zero è attivo su tutte le varianti (incluse le I*) |
0x21 |
AC_PERIOD |
2 | u16 LE | r | ram | Semiperiodo di rete, µs |
0x23 |
CALIBRATION |
1 | u8 | r | ram | Byte di stato della calibrazione legacy |
0x24 |
TOPOLOGY |
1 | u8 | r | rom | Numero di canali di corrente (= V03_N_I): 1, 2 o 3; 5 = UI5, 7 = UI7 |
0x25 |
SENSOR_CLASS |
1 | u8 | rw | user_config | 0 = UNSET, 1 = SCT_013, 2 = WIRED_CT (serie di pinze CT, modelli 1..13: 1..5 legacy; accoppiate in fabbrica sugli SKU CT- — con firmware 1.4.22 e successivi il modulo rifiuta le scritture di classe e modello in funzionamento normale con ERR_PARAM (0xFE); le librerie client le rifiutano su tutti i firmware), 3 = BUILTIN_CT (calibrazione di fabbrica per unità, codice modello non usato). Un cambio di classe riporta CT_MODEL = 0. Non è un discriminatore di variante (vedi §3.4) |
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::setSensorClass(cls) / RbAmp::readSensorClass(out) |
imposti la classe del sensore; la rilegga |
| ESP-IDF | rbamp_set_sensor_class() / rbamp_read_sensor_class() |
imposti la classe del sensore; la rilegga |
| Python | dev.set_sensor_class(cls) / dev.read_sensor_class() |
imposti la classe del sensore; la rilegga |
| ESPHome | sensor_class: |
Opzione YAML che fissa la classe del sensore |
4.4 Configurazione della flotta (0x27..0x2F)
| Ind. | Nome | Dimensione | Tipo | Accesso | Persistenza | Note |
|---|---|---|---|---|---|---|
0x27 |
FLEET_CONFIG |
1 | u8 | rw | user_config | bit0 = GC_ENABLE (ricezione dello snapshot General-Call; ha effetto dopo il reset). bit 1-7 riservati |
0x28 |
GROUP_ID |
1 | u8 | rw | user_config | Filtro di gruppo dello snapshot GC. 0 = risponde a tutti-chiamata. Il byte di gruppo del frame GC deve coincidere oppure essere 0x00 |
0x29 |
DIGEST_CONFIG |
1 | u8 | rw | ram | Maschera di composizione della finestra digest (vedi §4.9); scrivere un bit non supportato → ERR_PARAM. Predefinito 0x00 (digest disattivato) dopo il reset; riscriverlo a ogni inizializzazione |
0x2A |
EVENT_FLAGS |
1 | u8 | w1c | ram | Flag di evento persistenti (vedi §5.3 modello degli errori). Predefinito 0x00 dopo il reset (ma il bit5 RESET_OCCURRED viene impostato all'avvio) |
0x2B |
EVENT_MASK |
1 | u8 | rw | ram | Quali bit di EVENT_FLAGS tengono DRDY fisso a LOW |
0x2C |
THRESH_I_HI |
2 | u16 LE | rw | ram | Soglia di corrente → EVENT_FLAGS.THRESH_I. Unità: 0.01 A. 0xFFFF = disattivata |
0x2E |
THRESH_P_HI |
2 | u16 LE | rw | ram | Soglia di potenza → EVENT_FLAGS.THRESH_P. Unità: W. 0xFFFF = disattivata |
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::enableGc(enable) / RbAmp::setEventThresholds(i_amps, p_watts) |
attivi la General Call su un modulo; imposti le soglie di corrente e di potenza |
| ESP-IDF | rbamp_enable_gc() / rbamp_set_event_thresholds() |
attivi la General Call su un modulo; imposti le soglie di corrente e di potenza |
| Python | dev.enable_gc(enable=True) / dev.read_event_flags() |
abiliti General Call su un modulo; legga i flag di evento (nessun setter di soglia per dispositivo) |
| ESPHome | fleet_gc_enable: / group_id: |
Opzioni YAML per l'attivazione della General Call e l'ID di gruppo |
4.5 Indirizzo (0x30..0x31)
| Ind. | Nome | Dimensione | Tipo | Accesso | Persistenza | Note |
|---|---|---|---|---|---|---|
0x30 |
I2C_ADDRESS |
1 | u8 | rw | user_config | Commit a due fasi: scriva l'indirizzo candidato 0x08..0x77 → preparazione in RAM; armi ADDR_COMMIT_MAGIC; poi CMD_COMMIT_ADDR; si applica dopo il reset. All'avvio viene riletto l'indirizzo attivo (v1.3 Fix 4) |
0x31 |
ADDR_COMMIT_MAGIC |
1 | u8 | w | ram | Scriva 0xA5 per armare CMD_COMMIT_ADDR. Viene consumato (azzerato) al tentativo di commit. Le letture restituiscono 0x00 |
Per la sequenza vedi §6.1.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::prepareAddressChange(new_addr) / RbAmp::readActiveAddress(out) |
prepari e armi il nuovo indirizzo; legga l'indirizzo attivo |
| ESP-IDF | rbamp_prepare_address_change() / rbamp_read_active_address() |
prepari e armi il nuovo indirizzo; legga l'indirizzo attivo |
| Python | dev.prepare_address_change(new_addr) / dev.commit_address_change() |
imposti e armi il nuovo indirizzo, poi lo confermi |
| ESPHome | new_address: |
modifica di indirizzo una tantum all'avvio; rimuova l'opzione in seguito |
4.6 Salute / diagnostica (0x46..0x4F)
| Ind. | Nome | Dimensione | Tipo | Accesso | Persistenza | Note |
|---|---|---|---|---|---|---|
0x46 |
UPTIME_S |
4 | u32 LE | r | ram | Contatore di uptime proprio del modulo (in secondi dall'avvio, in teoria) — solo rilevatore di riavvio: sul firmware fino alla 1.4.21 va più lento del tempo di parete (misurato 0.58–0.80×), quindi non lo usi mai come orologio. Rilevamento del riavvio per un master: il valore è diminuito, oppure è inferiore al tempo trascorso dallo snapshot precedente del master |
0x4A |
RESET_CAUSE |
1 | u8 | r | ram | Flag della causa di reset (bit0=PIN, bit1=POR/BOR, bit2=SW, bit3=IWDG, bit4=WWDG, bit5=LPWR). Solo per il logging — la gestione del riavvio è identica qualunque sia la causa |
0x4B |
I2C_ERR_COUNT |
2 | u16 LE | r | ram | Errori di bus (BERR+OVR) dall'avvio, con saturazione |
0x4D |
I2C_REINIT_COUNT |
1 | u8 | r | ram | Numero di ripristini dal blocco BUSY del periferico I²C, con saturazione |
0x4E |
ZC_OFFSET |
2 | u16 LE | r | ram | µs dal fronte STOP dell'ultimo snapshot GC al successivo passaggio per lo zero della tensione — usato per la compensazione di fase U/I nel calcolo della potenza. Forzato dal firmware a 0xFFFF sulle varianti solo-I (nessun front-end di tensione → nessuno zero di tensione). Questo non è la sorgente di passaggio per lo zero della frequenza di rete — AC_FREQ (0x20) deriva da un pin dedicato allo zero della rete ed è disponibile su tutte le varianti. |
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | — | Registri di salute BASIC non esposti (solo linea STD) |
| ESP-IDF | rbamp_read_uptime_s() |
legga l'uptime del modulo in secondi |
| Python | — | Registri di salute BASIC non esposti (solo linea STD) |
| ESPHome | — | nessuna entità di uptime o salute |
4.7 Specchi di verifica del modello CT (0x51..0x53)
Specchi in sola lettura del preset del modello CT applicato per canale. Il protocollo di scrittura sul filo non cambia (vedi §6.2) — è solo una rilettura per la verifica.
| Ind. | Nome | Dimensione | Tipo | Accesso | Persistenza | Note |
|---|---|---|---|---|---|---|
0x51 |
CT_MODEL_CH0 |
1 | u8 | r | user_config | Preset del modello CT applicato sul ch0 (specchio di verifica) |
0x52 |
CT_MODEL_CH1 |
1 | u8 | r | user_config | Preset del modello CT applicato sul ch1 |
0x53 |
CT_MODEL_CH2 |
1 | u8 | r | user_config | Preset del modello CT applicato sul ch2 |
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readCTModelCh(channel, out) |
legga il modello CT effettivamente applicato su un canale |
| ESP-IDF | rbamp_read_ct_model_ch() |
legga il modello CT effettivamente applicato su un canale |
| Python | dev.read_ct_model_ch(ch) |
legga il modello CT effettivamente applicato su un canale |
| ESPHome | log di avvio ct_model[0]: matches |
righe di log che confermano che la classe del sensore e il modello sono stati applicati |
4.8 Identità (0x54..0x6F)
| Ind. | Nome | Dimensione | Tipo | Accesso | Persistenza | Note |
|---|---|---|---|---|---|---|
0x54 |
PRODUCT_ID |
1 | u8 | r | rom | Famiglia: 0x01 = sensore rbAmp. Il master legge questo valore prima di qualsiasi registro specifico della famiglia |
0x55 |
HW_VARIANT |
1 | u8 | r | rom | Vedi §3.1 |
0x56 |
FW_TIER |
1 | u8 | r | rom | bit 0-1: 0=BASIC, 1=STANDARD (2 = non implementato); bit 2=bidirezionale; bit 3=calibrato con LUT |
0x57 |
CAPABILITY |
2 | u16 LE | r | rom | Vedi §3.2 |
0x59 |
GC_TICK |
2 | u16 LE | r | ram | Tick del master dall'ultimo frame GC accettato; 0xFFFF = mai ricevuto |
0x5C |
UID |
12 | byte | r | rom | UID del chip a 96 bit. Una sola lettura a raffica. |
0x68 |
LABEL |
8 | byte | rw | user_config | Etichetta di posizione dell'utente (ASCII, riempita con zeri). Vuoto = non impostata. Scriva byte per byte (vedi §5.1) |
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readProductId() / RbAmp::readUid(uid) |
legga l'ID famiglia; legga l'UID a 96 bit |
| ESP-IDF | rbamp_read_product_id() / rbamp_read_uid() |
legga l'ID famiglia; legga l'UID a 96 bit |
| Python | dev.read_product_id() / dev.read_uid() |
legga l'ID famiglia; legga l'UID a 96 bit |
| ESPHome | get_uid_hex() / get_variant_str() |
l'UID in esadecimale; la variante come testo |
4.9 Finestra del digest (0x70..0x85)
DIGEST è una finestra di polling compatta, servita da una sola lettura a raffica. La sua composizione è selezionata da DIGEST_CONFIG (0x29); una scrittura che imposta un bit non supportato viene rifiutata con ERR_PARAM:
DIGEST_CONFIG bit |
Contenuto | Formato |
|---|---|---|
| bit 0 | I_RMS[N] |
u16 per canale, 0.01 A |
| bit 1 | U_RMS |
u16, 0.1 V (solo varianti con HW di tensione) |
| bit 2 | P_REAL[N] |
i16 per canale, 1 W (solo has_power) |
| bit 3 | PF[N] |
u8 per canale, da 0 a 100 (solo has_power) |
| Ind. | Nome | Dimensione | Tipo | Accesso | Persistenza | Note |
|---|---|---|---|---|---|---|
0x70 |
DIGEST |
22 | byte | r | ram | Struttura: [STATUS_MIRROR u8][SEQ u8] + campi abilitati tramite maschera. Il payload massimo (maschera completa UI3) è 19 B + 2 B di intestazione = 21 B usati; 1 B di coda inutilizzato (legge 0x00). SEQ si incrementa a ogni commit RT, con avvolgimento 255→0. Atomico tramite read-freeze (vedi §5.4). |
La struttura è dinamica per DIGEST_CONFIG — ogni bit attivo aggiunge i propri campi in ordine fisso: I_RMS[N] → U_RMS → P[N] → PF[N]. I bit disattivati non lasciano spazio di riempimento — i campi scorrono in avanti. Il master deve interpretare con la stessa maschera scritta in DIGEST_CONFIG. Una lettura in burst di 22 byte è sicura (la coda è 0x00 ogni volta che il payload totale è < 22 byte). Il byte di coda singolo è sempre 0x00 (riservato).
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | — | finestra del digest non esposta |
| ESP-IDF | rbamp_set_digest_fields() / rbamp_read_digest() |
scelga i campi del digest; li legga in una sola transazione (BASIC) |
| Python | — | finestra del digest non esposta |
| ESPHome | — | finestra del digest non esposta |
4.10 Blocco real-time V03 (0x86..0xBD)
Tutti float32 LE (IEEE 754 a precisione singola, ordine dei byte little-endian standard). Il layout byte per byte è congelato dalla v1.2. Ogni registro è di accesso r, persistenza ram, gruppo v03_rt. Atomico tramite read-freeze (vedi §5.4): una lettura a raffica di 56 byte (0x86..0xBD) è garantita contigua (nessuno snapshot spezzato).
| Ind. | Nome | Dimensione | Tipo | Accesso | Persistenza | Unità | Note |
|---|---|---|---|---|---|---|---|
0x86 |
V03_U_RMS |
4 | float32 LE | r | ram | V | 0.0 sulle varianti I |
0x8A |
V03_U_PEAK |
4 | float32 LE | r | ram | V | |
0x8E |
V03_I0_RMS |
4 | float32 LE | r | ram | A | |
0x92 |
V03_I1_RMS |
4 | float32 LE | r | ram | A | 0.0 se la variante non ha ch1 |
0x96 |
V03_I2_RMS |
4 | float32 LE | r | ram | A | 0.0 se la variante non ha ch2 |
| ⛔ | STOP — il blocco RMS piatto per canale termina al canale 2. | La riga successiva (0x9A) è V03_I0_PEAK, NON V03_I3_RMS. NON estrapoli lo schema del passo 4 oltre il canale 2 — otterrà valori plausibili ma silenziosamente errati (picco, non RMS; ch0, non ch3). I canali 3+ (UI5/UI7) sono accessibili solo tramite la finestra di accesso ai canali — vedi §4.14. |
|||||
0x9A |
V03_I0_PEAK |
4 | float32 LE | r | ram | A | |
0x9E |
V03_I1_PEAK |
4 | float32 LE | r | ram | A | |
0xA2 |
V03_I2_PEAK |
4 | float32 LE | r | ram | A | |
0xA6 |
V03_P0_REAL |
4 | float32 LE | r | ram | W | 0.0 sulle varianti I (nessun calcolo di potenza) |
0xAA |
V03_P1_REAL |
4 | float32 LE | r | ram | W | |
0xAE |
V03_P2_REAL |
4 | float32 LE | r | ram | W | |
0xB2 |
V03_PF0 |
4 | float32 LE | r | ram | – | intervallo da −1 a +1 |
0xB6 |
V03_PF1 |
4 | float32 LE | r | ram | – | |
0xBA |
V03_PF2 |
4 | float32 LE | r | ram | – |
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readAll(snapshot) / RbAmp::channels() |
legga l'intero blocco real-time; numero di canali di corrente |
| ESP-IDF | rbamp_read_all() / rbamp_channels() |
legga l'intero blocco real-time; numero di canali di corrente |
| Python | dev.read_all() / dev.channels |
legga l'intero blocco real-time; numero di canali di corrente |
| ESPHome | voltage / power |
Sensori YAML per i valori in tempo reale |
4.11 Blocco del periodo V03 (0xBE..0xCF)
Uno snapshot del periodo preso con CMD_LATCH_PERIOD. Struttura irregolare (eredità storica della v1.2, congelata alla v1.3): avg_p per ch1/ch2 si trova qui, mentre avg_p per ch0 sta nel §4.12 all'indirizzo 0xDC (la primitiva di energia legacy non è stata spostata, per non rompere l'API di chi già integra). Logicamente questi tre valori appartengono allo stesso gruppo.
| Ind. | Nome | Dimensione | Tipo | Accesso | Persistenza | Unità | Note |
|---|---|---|---|---|---|---|---|
0xBE |
V03_PERIOD_COMMIT_CNT |
4 | u32 LE | r | ram | – | Commit RT nel periodo chiuso. Un commit = 0.1 s dalla v1.2 (0.2 s prima) — count × la lunghezza del commit è la misura propria del modulo della lunghezza della finestra (vedi §7.4) |
0xC2 |
V03_PERIOD_AVG_P_CH1 |
4 | float32 LE | r | ram | W | Media dello snapshot P ch1 (UI2, UI3) |
0xC6 |
V03_PERIOD_AVG_P_CH2 |
4 | float32 LE | r | ram | W | Media dello snapshot P ch2 (UI3) |
0xCA |
V03_PERIOD_MS |
4 | u32 LE | r | ram | ms | Durata del periodo corrente |
0xCE |
V03_STATUS |
1 | u8 | r | ram | – | bit 0 = valido (esito del commit RT). NON si azzera alla lettura. Il master fa polling su STATUS (0x00) per attendere la prontezza. L'alias DATA_VALID è talvolta usato per questo registro nei capitoli introduttivi — stesso indirizzo, stessa semantica. |
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodSnapshot() |
legga la potenza media del periodo; esegua e legga uno snapshot completo del periodo |
| ESP-IDF | rbamp_read_period_avg_power() / rbamp_read_period_snapshot() |
legga la potenza media del periodo; esegua e legga uno snapshot completo del periodo |
| Python | dev.read_period_avg_power(ch) / dev.read_period_snapshot() |
legga la potenza media del periodo; esegua e legga uno snapshot completo del periodo |
| ESPHome | update_interval: / latch_interval: |
Opzioni YAML per la cadenza del periodo e dello snapshot |
4.12 V03 Q + periodo ch0 (0xD0..0xE3, build di produzione)
| Ind. | Nome | Dimensione | Tipo | Accesso | Persistenza | Unità | Note |
|---|---|---|---|---|---|---|---|
0xD0 |
V03_Q0_REAC |
4 | float32 LE | r | ram | VAr | Potenza reattiva ch0 = √(S² − P²), S = U_rms × I_rms — senza segno (≥ 0), include la potenza di distorsione; 0 sulle varianti solo-I; rumorosa vicino a PF ≈ 1. Precisione non specificata |
0xD4 |
V03_Q1_REAC |
4 | float32 LE | r | ram | VAr | |
0xD8 |
V03_Q2_REAC |
4 | float32 LE | r | ram | VAr | |
0xDC |
V03_PERIOD_AVG_P |
4 | float32 LE | r | ram | W | Primitiva di energia PRODUZIONE: snapshot della media P ch0, ≥ 0 (pinza unidirezionale BASIC). Raggruppata logicamente con V03_PERIOD_AVG_P_CH1/CH2 (§4.11); il layout storico è mantenuto per compatibilità |
0xE0 |
V03_PERIOD_MAX_P |
4 | float32 LE | r | ram | W | Picco massimo P ch0 in questo periodo |
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodMaxPower() |
legga la potenza media e massima del periodo |
| ESP-IDF | rbamp_read_period_avg_power() / rbamp_read_period_max_power() |
legga la potenza media e massima del periodo |
| Python | dev.read_period_avg_power(ch) / dev.read_period_max_power() |
legga la potenza media e massima del periodo |
| ESPHome | reactive_power / update_interval: |
sensore di potenza reattiva; ogni aggiornamento chiude il periodo e legge le medie |
4.13 dt diagnostico lato chip (0xEC)
| Ind. | Nome | Dimensione | Tipo | Accesso | Persistenza | Unità | Note |
|---|---|---|---|---|---|---|---|
0xEC |
V03_PERIOD_LATCH_MS |
4 | u32 LE | r | ram | ms | dt lato chip tra i due snapshot più recenti. Timer diagnostico del modulo — può risultare basso sotto carico; per l'energia usi il clock del master. Vedi §7.4 |
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readPeriodLatchMs() |
legga la lunghezza del periodo lato modulo (solo diagnostica) |
| ESP-IDF | rbamp_read_period_latch_ms() |
legga la lunghezza del periodo lato modulo (solo diagnostica) |
| Python | dev.read_period_latch_ms() |
legga la lunghezza del periodo lato modulo (solo diagnostica) |
| ESPHome | — | non esposto |
4.14 Finestra di accesso ai canali (0x32 + 0x3C..0x3F)
Si applica a UI5 (5 canali) e UI7 (7 canali) moduli. Su UI1/UI2/UI3 e I1/I2/I3 è disponibile anche — un percorso unificato se lo preferisce ai registri piatti del §4.10.
I canali 3..6 non hanno registri piatti per canale (c'era spazio per 8 byte nello spazio di indirizzi a 8 bit, e una struttura piatta ne avrebbe richiesti ~88). Al loro posto è esposta una finestra di selezione e lettura:
| Ind. | Nome | Dimensione | Tipo | Accesso | Persistenza | Note |
|---|---|---|---|---|---|---|
0x32 |
REG_CHANNEL_SELECT |
1 | u8 | rw | ram | Questo è un indirizzo di registro, NON l'opcode di comando CMD_SAVE_USER_CONFIG — collidono numericamente. Citi sempre 0x32 dichiarando se si intende lo spazio dei registri o dei comandi. Codificato come (field << 4) \| channel. Il nibble channel va da 0..15 (riservato a un massimo di 16 canali); il massimo fisico per SKU è channels() (7 su UI7). Un selettore il cui indice di canale è >= channels() viene accettato senza ERR_PARAM; la finestra dati allora legge 0 e le scritture vi vengono ignorate. field secondo la tabella seguente. Scrivendo il selettore lo snapshot del valore richiesto viene copiato in REG_CHANNEL_DATA. |
0x3C..0x3F |
REG_CHANNEL_DATA |
4 | float32 LE | r | ram | Buffer dati per la selezione. float32 LE per tutti i campi pubblici. |
Codici dei campi (nibble alto in 0x32):
| Codice | Campo | Tipo | Accesso | Significato |
|---|---|---|---|---|
0 |
CHFIELD_I_RMS |
float32 LE | r | Corrente RMS live per il canale selezionato (unità A) |
1 |
CHFIELD_I_PEAK |
float32 LE | r | Corrente di picco live (unità A) |
2 |
CHFIELD_P_REAL |
float32 LE | r | Potenza reale live (unità W) |
3 |
CHFIELD_PF |
float32 LE | r | Fattore di potenza live (da −1 a +1) |
4..12 |
(reserved) | – | – | Non documentato per il codice utente; non dipenda da valori o codici. |
13 |
CHFIELD_PERIOD_AVG_P |
float32 LE | r | Potenza reale media di periodo (W). Per i canali 3 e successivi questo è l'UNICO campo di periodo/energia — i registri piatti V03_PERIOD_AVG_P* (§4.11/§4.12) coprono solo ch0..ch2. |
14 |
(reserved) | – | – | Riservato a firmware futuri; non ci faccia affidamento. |
15 |
CHFIELD_CT_MODEL |
u8 in 0x3C (i byte 0x3D..0x3F sono letti come riempimento a zero) |
rw | Firmware ≥ 1.4.18. Codice del modello CT per canale per il canale selezionato (0..N-1). La lettura restituisce il modello applicato sul canale. La scrittura è solo in RAM e si applica subito: la scala del canale passa alla preimpostazione del modello selezionato nella stessa transazione; non serve un comando di commit separato né CMD_SET_CT_MODEL_CH*. Le scritture avvengono byte per byte secondo la regola del protocollo (§5.1). Una coppia sconosciuta (SENSOR_CLASS, code) restituisce ERR_PARAM (0xFE) e il canale mantiene il modello precedente — nessuno stato parziale. I canali della linea superiore (ch3+) NON ereditano più il modello globale — ogni canale va configurato esplicitamente tramite il campo 15. Persistenza: CMD_SAVE_USER_CONFIG (opcode 0x32 su REG_COMMAND, senza subordine) salva i modelli di tutti i canali nella pagina flash della configurazione utente con un solo comando. Una scrittura senza successivo CMD_SAVE_USER_CONFIG torna indietro al riavvio. L'insieme delle coppie (class, code) accettate è definito dalla tabella dei modelli della sua versione del firmware; il modulo conferma in modo autorevole un codice — lo scriva, lo rilegga e controlli REG_ERROR. Sui moduli con firmware v1.4.0 la scrittura di questo campo restituisce ERR_PARAM; usi i comandi per canale e la preparazione del registro piatto REG_CT_MODEL. |
Le quattro trappole — legga questo prima di scrivere codice
- ⛔ L'RMS piatto per canale si ferma al canale 2. Le righe
V03_I0_RMS(0x8E) →V03_I1_RMS(0x92) →V03_I2_RMS(0x96) hanno passo 4, e0x9Aprosegue il passo — ma0x9AèV03_I0_PEAK, nonV03_I3_RMS. Estrapolare lo schema restituisce in silenzio il picco del ch0 invece dell'RMS del ch3. Il firmware non può rilevare l'errore; il valore sembra plausibile. I canali 3 e successivi sono disponibili solo nella finestra di accesso ai canali. - Riselezioni prima di ogni lettura.
REG_CHANNEL_DATAè uno snapshot preso nel momento della scrittura del selettore, non una vista in tempo reale. Interrogare0x3C..0x3Fin un ciclo senza riscrivere0x32restituisce un valore congelato per sempre. Ogni lettura aggiornata richiede una nuova scrittura su0x32. 0x32indirizzo di registro ≠0x32opcode di comando.CMD_SAVE_USER_CONFIGusa l'opcode0x32scritto inREG_COMMAND(0x01) — uno spazio di indirizzi diverso daREG_CHANNEL_SELECT(che si trova all'indirizzo di registro0x32). Non citi mai0x32senza dire di quale spazio si tratti.- Per i canali 3 e successivi il periodo/energia proviene solo dal campo
13(CHFIELD_PERIOD_AVG_P). I registriV03_PERIOD_AVG_P*(0xC2/0xC6/0xDC) coprono solo ch0/ch1/ch2. Non esiste unV03_PERIOD_AVG_P_CH3piatto — legga il campo 13 tramite la finestra.
Esempio a livello di filo — legga la corrente RMS per il canale 3
# select field=0 (I_RMS), channel=3 → (0 << 4) | 3 = 0x03
write_u8(REG_CHANNEL_SELECT=0x32, 0x03)
# read 4 bytes at REG_CHANNEL_DATA — float32 LE
bytes = read(0x3C, 4)
i3_rms = unpack_float32_le(bytes) # amperes
Per la corrente di picco del canale 4: selettore = (1 << 4) | 4 = 0x14, poi legga 0x3C..0x3F. Per la potenza media di periodo del canale 5: selettore = (13 << 4) | 5 = 0xD5, poi legga 0x3C..0x3F.
Esempio a livello di filo — legga la corrente RMS su TUTTI i canali di un modulo UI7
Combina entrambi i percorsi in un unico ciclo: blocco RT piatto per i canali 0..2, finestra di accesso ai canali per i canali 3..6.
# --- Discover physical channel count -----------------------------
N = read_u8(TOPOLOGY=0x24) # 5 on UI5, 7 on UI7
# --- ch 0..2 via flat block (single 12-byte burst) ---------------
bytes = read(V03_I0_RMS=0x8E, 12)
i0 = unpack_float32_le(bytes[0:4])
i1 = unpack_float32_le(bytes[4:8])
i2 = unpack_float32_le(bytes[8:12])
# --- ch 3..N-1 via channel access window (re-select per read) ----
i_rms = [i0, i1, i2]
for ch in range(3, N):
write_u8(REG_CHANNEL_SELECT=0x32, (0 << 4) | ch) # field 0 = I_RMS
i_rms.append(unpack_float32_le(read(REG_CHANNEL_DATA=0x3C, 4)))
# i_rms is now length-N: RMS current for every physical channel of the module.
Lo stesso schema si estende a I_PEAK (campo 1), P_REAL (campo 2), PF (campo 3) e allo snapshot PERIOD_AVG_P (campo 13) — blocco piatto per ch0..ch2, finestra per ch3+. Il campo 13 è l'UNICA fonte di periodo/energia per ch3+ — il blocco piatto non ha V03_PERIOD_AVG_P_CH3..6.
Per la configurazione del modello CT di ogni canale (0..N-1), usi il campo finestra 15 (CHFIELD_CT_MODEL): scriva (15 << 4) | ch in 0x32, poi scriva il codice del modello come un byte in 0x3C. Salvi i modelli di tutti i canali con un solo CMD_SAVE_USER_CONFIG (opcode 0x32 su REG_COMMAND (0x01) — senza gating).
Raccomandazione per nuove integrazioni
La finestra copre i canali 0..6 — può usarla come percorso unificato per tutti i canali invece di alternare tra registri piatti (ch0..ch2) e finestra (ch3..ch6). Per flotte che mescolano SKU junior (UI1/UI2/UI3) e senior (UI5/UI7) questo elimina una divisione del codice. La latenza è una piccola scrittura in più per lettura (rispetto a una lettura in burst diretta del blocco piatto).
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readCurrent(ch) / RbAmp::channels() |
legga un canale per indice; numero di canali |
| ESP-IDF | rbamp_read_channel() / rbamp_read_all_channels() |
legga un canale per indice, inclusi i canali 3 e superiori; legga ogni canale |
| Python | dev.current[ch] / dev.channels |
indice sui canali validi; numero di canali |
| ESPHome | current_N: |
slot sensore per canale, fino a sette canali di corrente |
5 · Protocollo sul filo
5.1 Asimmetria LETTURA / SCRITTURA
Comportamento canonico previsto:
| Direzione | Incremento automatico | Schema |
|---|---|---|
| LETTURA (lettura in burst di N byte) | ✅ SÌ | read(addr, N) restituisce N byte consecutivi a partire da addr. |
| SCRITTURA (registri multi-byte) | ❌ NO | Un registro multi-byte si scrive byte per byte — una transazione separata a singolo byte per ogni indirizzo. Una scrittura a raffica perde i byte da 1 a N-1 e accetta solo il primo. |
Registri scrivibili multi-byte interessati (scrittura byte per byte)
LABEL(0x68-0x6F, 8 byte)THRESH_I_HI(0x2C, 2 byte u16 LE)THRESH_P_HI(0x2E, 2 byte u16 LE)
Ordine dei byte per la scrittura multi-byte: il byte all'indirizzo più basso è il byte basso (LE). Per esempio, per scrivere THRESH_I_HI = 0x1234 (4660 in decimale):
# CORRECT: low byte first (LE)
write(addr=0x2C, value=0x34) # LO byte
write(addr=0x2D, value=0x12) # HI byte
Esempio ERRATO / CORRETTO (pseudocodice)
# WRONG — only 'M' (first byte) is accepted, the rest are dropped
write(addr=0x50, reg=0x68, data=b"MyMeter1") # 8-byte burst
# CORRECT — byte-at-a-time loop
label = b"MyMeter1"
for i, byte in enumerate(label):
write(addr=0x50, reg=0x68 + i, data=byte)
Eccezione — frame di broadcast GC
Il frame di broadcast GC (indirizzo general-call 0x00 + payload di 5 byte) è un percorso di protocollo sul filo separato, non una scrittura di registro. L'asimmetria lettura/scrittura del §5.1 non si applica al GC. Vedi §6.3.
5.2 Comportamento dei registri non mappati
Qualsiasi lettura da un indirizzo non mappato restituisce 0x00. Il firmware non risponde mai con NACK alle letture dei registri. È una scelta di progetto (correzione del blocco).
Implicazione per il rilevamento: il rilevamento di un dispositivo mancante deve passare per l'ACK del frame di indirizzo I²C, non per sonde sui registri.
5.3 Modello degli errori
Canonico v1.3:
REG_ERROR (0x02)è l'esito dell'ultima scrittura, NON persistente. A ogni scrittura su registro il firmware impostareg_error = ERR_OK; ogni scrittura successiva non correlata azzera l'errore precedente.EVENT_FLAGS (0x2A) bit 3è il segnale durevole (sticky W1C), attivato su qualsiasi scrittura o comando rifiutato.
Codici di errore
| Codice | Nome | Gravità |
|---|---|---|
0x00 |
OK | – |
0xF9 |
CLONE |
riservato — non sollevato |
0xFA |
LUT_BAD |
errore |
0xFB |
FLASH_PARAMS_BAD |
errore (vedi §6.5 flash appena caricato) |
0xFC |
NOT_READY |
errore |
0xFD |
SENSOR_OVERFLOW |
errore |
0xFE |
PARAM |
errore (scrittura rifiutata — argomento non valido / opcode sconosciuto / valore enum fuori intervallo; imposta EVENT.bit3. Immagini molto precoci, 1.2–1.4.3, ignoravano in silenzio gli opcode sconosciuti) |
0xFF |
UNHANDLED |
errore |
Struttura di EVENT_FLAGS (0x2A) (W1C persistente)
| bit | Nome | Note |
|---|---|---|
| 0 | PERIOD_READY |
snapshot del periodo disponibile |
| 1 | THRESH_I |
I_rms ha superato THRESH_I_HI |
| 2 | THRESH_P |
La somma P ha superato THRESH_P_HI |
| 3 | ERROR |
REG_ERROR != 0 (segnale di errore durevole) |
| 4 | CONFIG_CHANGED |
classe/modello/indirizzo/etichetta modificati |
| 5 | RESET_OCCURRED |
modulo riavviato (impostato all'avvio fino a W1C). Il master deve reinizializzare la configurazione in RAM. |
Schemi di errore canonici
Modello 1 — cattura singola dopo l'operazione (esito di quella sola operazione):
write target_reg(...)
err = read_u8(0x02) # IMMEDIATELY after the operation, before the next write
Schema 2 — monitoraggio durevole (canonico per un master in funzione a lungo):
event_flags = read_u8(0x2A)
if event_flags & (1 << 3): # ERROR bit
last_err = read_u8(0x02)
# handle
write_u8(0x2A, 1 << 3) # W1C clear bit 3
# or CMD_CLEAR_ERROR
⚠ attenzione asincrona sul bit 3
Un rifiuto di scrittura imposta EVENT_FLAGS.bit3 in modo asincrono, entro una finestra di misura (~100 ms dalla v1.2; 200 ms sulle immagini precedenti alla v1.2) dall'operazione, non immediatamente. Non interroghi il bit 3 subito dopo una scrittura — attenda ≥ 200 ms (copre tutte le immagini), oppure usi il Modello 1 (cattura immediata di REG_ERROR esito di una specifica operazione), riservando l'interrogazione del bit 3 al monitoraggio prolungato.
Sentinella anti-clone
DEV_ERR_CLONE (0xF9) è riservato — non viene mai sollevato. Il codice è mantenuto per la compatibilità futura.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readLastError() / RbAmp::hasError(out) |
legga il codice di errore dell'ultima scrittura; legga il flag di errore durevole |
| ESP-IDF | rbamp_read_last_error() / rbamp_has_error() |
legga il codice di errore dell'ultima scrittura; legga il flag di errore durevole |
| Python | dev.read_last_error() / dev.has_error() |
legga il codice di errore dell'ultima scrittura; legga il flag di errore durevole |
| ESPHome | get_last_error_str() / get_event_flags() |
il codice di errore come testo; i flag di evento |
5.4 Atomicità / semantica read-freeze
5.4.1 Read-freeze presente (atomico — NON spezzato)
Questi blocchi sono protetti dal read-freeze lato firmware. Una lettura in burst è atomica rispetto al commit RT:
- Blocco V03 RMS / P / PF (0x86..0xBD) — il blocco float completo.
- Blocco digest (0x70..0x85).
Le letture a raffica di questi intervalli sono sicure — non c'è campione spezzato tra due commit consecutivi.
5.4.2 Nessun read-freeze — consigliato read-twice-agree
Questi registri sono aggiornati in modo asincrono senza freeze durante la lettura. Le letture di singolo byte sono tollerate, ma il valore può cambiare tra una transazione e l'altra:
GC_TICK (0x59)— contatore dei tick GC.I2C_ADDRESS (0x30)— specchio di preparazione in RAM.CT_MODEL_CH0/1/2 (0x51..0x53)— specchi di verifica.
Schema per letture affidabili:
val1 = read_u8(addr)
val2 = read_u8(addr)
if val1 == val2:
return val1 # stable
else:
retry # value changed between reads
5.4.3 Semantica della pinza NF
I_RMS = 0x00000000 significa "segnale sotto la soglia di rumore" (il firmware calcola rms_corr² = max(0, raw² − nf²)), NON "nessun dato" / "errore". È una misura valida per scenari a carico nullo o molto basso.
Il codice del master non deve interpretare I_RMS = 0.0 come errore o dato mancante.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readAll(snapshot) |
legga l'intero blocco RT in tempo reale con una sola chiamata |
| ESP-IDF | rbamp_read_all() |
legga l'intero blocco RT in tempo reale con una sola chiamata |
| Python | dev.read_all() |
legga l'intero blocco RT in tempo reale con una sola chiamata |
| ESPHome | lettura in burst del blocco istantaneo | il componente legge il blocco istantaneo in una sola raffica per ogni aggiornamento |
6 · Sequenze di protocollo
6.0 Cronologia dell'avvio a freddo
Dopo POR (power-on reset) o reset hardware il modulo attraversa le seguenti fasi:
| Tempo dal POR | Stato |
|---|---|
| 0 ms | POR — tutti i registri in stato di reset, SCL/SDA in tri-state |
| ~10 ms | Reattivo sul bus (il modulo riceve ACK al proprio indirizzo) |
| ~50 ms | Primo commit RT (il blocco RT da 0x86 in poi contiene dati validi; STATUS.bit0 = 1) |
| ~60-80 ms | Primo V03_STATUS.bit0 valido (la pipeline RT ha completato un intero periodo di rete) |
| ~100 ms | Il primo CMD_LATCH_PERIOD può restituire V03_PERIOD_VALID = 1 (lo snapshot richiede ≥ 1 periodo di rete di accumulo; ~200 ms sulle immagini prima della v1.2) |
| ~250 ms | Tutte le misure stabili (tipico) |
Avvio a freddo completo fino alla prima misura valida ≈ 250 ms (tipico). Dopo un CMD_RESET soft la cronologia è identica (viene eseguita l'intera macchina a stati del reset).
Sequenza di inizializzazione del master:
1. wait ~50 ms after VCC stable
2. probe slave address (read PRODUCT_ID = 0x54); retry up to 300 ms on NACK
3. read identity (HW_VARIANT 0x55, CAPABILITY 0x57/0x58); validate
4. check REG_ERROR (0x02):
- 0x00 — normal boot
- 0xFB — fresh flash, provisioning required (§6.5)
- other — see §6.7 error-state recovery
5. configure (SENSOR_CLASS, CT_MODEL, FLEET_CONFIG, etc.)
6. poll STATUS (0x00) until bit0 = 1 (READY) — usually immediate after step 5
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::begin() / RbAmp::waitReady(timeout_ms) |
interroghi il modulo, poi attenda il flag di pronto |
| ESP-IDF | rbamp_begin() / rbamp_wait_ready() |
interroghi il modulo, poi attenda il flag di pronto |
| Python | dev.begin() / dev.wait_ready(timeout_ms=1000) |
interroghi il modulo, poi attenda il flag di pronto |
| ESPHome | rbamp: address: |
indirizzo del modulo impostato nello YAML; il componente sonda il modulo in fase di setup |
6.1 Modifica dell'indirizzo — commit a due fasi (compatibile con la produzione)
Protocollo sul filo (canonico v1.3):
1. write candidate_addr (1 byte) → REG_I2C_ADDRESS (0x30) # RAM staging, not persisted
2. write 0xA5 → REG_ADDR_COMMIT_MAGIC (0x31) # arm commit
3. issue CMD_COMMIT_ADDR (opcode 0x30 in REG_COMMAND) # persists into flash
4. wait ~700 ms (flash write completion; see §6.6 settle)
5. issue CMD_RESET (opcode 0x01) # module resets
6. wait ~300 ms boot-to-responsive
7. verify: bus-probe the new address (ACK = success)
: CMD_COMMIT_ADDR NON riavvia automaticamente il modulo — è richiesto un CMD_RESET esplicito al passo 5. Se il master salta il reset esplicito, il nuovo indirizzo resta memorizzato in flash, ma quello vecchio resta attivo fino al successivo reset esterno (ciclo di alimentazione, pin di reset hardware, IWDG).
Guarantees:
- La modifica dell'indirizzo funziona in modalità produzione (non subordinata alla fabbrica).
REG_I2C_ADDRESS (0x30)all'avvio legge l'indirizzo attivo (canonico v1.3). Fino al riavvio dopo la predisposizione ripete il candidato.- L'indirizzo è escluso dallo spazio di
CMD_SAVE_GAINS/CMD_SAVE_USER_CONFIG— viene reso persistente solo tramiteCMD_COMMIT_ADDR.
Tempistica della finestra di avvio per la verifica:
- Minimo 300 ms dall'accensione alla risposta.
- Finestra di retry sul nuovo indirizzo: ~1 s in totale (se un NACK persiste dopo 1–2 retry, potrebbe servire un ulteriore ritardo di avvio).
- Appena il nuovo indirizzo riceve ACK, può opzionalmente verificare leggendo
0x30(che ora riflette il nuovo indirizzo attivo) per conferma.
Modalità di guasto:
ADDR_COMMIT_MAGICnon armato →CMD_COMMIT_ADDR→REG_ERROR = ERR_PARAM (0xFE).- Candidato fuori intervallo (< 0x08 o > 0x77) →
ERR_PARAM. - Timeout di 5 s senza commit → il magic si azzera; il passo
prepareva ripetuto.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::prepareAddressChange(new_addr) / RbAmp::commitAddressChange() |
imposti e armi il nuovo indirizzo, poi lo confermi |
| ESP-IDF | rbamp_prepare_address_change() / rbamp_commit_address_change() |
imposti e armi il nuovo indirizzo, poi lo confermi |
| Python | dev.prepare_address_change(new_addr) / dev.commit_address_change() |
imposti e armi il nuovo indirizzo, poi lo confermi |
| ESPHome | new_address: |
modifica di indirizzo una tantum all'avvio; rimuova l'opzione in seguito |
6.2 Binding del modello CT — sola preparazione + CMD per canale
Sulle immagini precedenti al fw 1.4.20 (CAPABILITY bit 12 a zero) la scala applicata per modello torna al valore di fabbrica dopo un riavvio del modulo — riprepari e ricommetta CT_MODEL per canale dopo ogni riavvio rilevato, altrimenti l'energia risulterà errata.
Schema canonico v1.3 a sola predisposizione: scrivere REG_CT_MODEL (0x05) non applica più automaticamente il preset a ch0. L'associazione avviene solo tramite CMD_SET_CT_MODEL_CHn.
Protocollo canonico per canale sul filo (indipendente dall'ordine nella v1.3):
1. write REG_SENSOR_CLASS (0x25) = sct013 # if not already set
2. write REG_CT_MODEL (0x05) = model_code # stages, applies nothing
3. issue CMD_SET_CT_MODEL_CHn (opcode 0x28/0x29/0x2A for ch0/1/2)
# VALIDATES (class, model) + binds to channel n
4. wait 5 ms settle
5. (optional) issue CMD_SAVE_USER_CONFIG (opcode 0x32) for persistence
Indipendente dall'ordine: dalla v1.3 i canali possono essere configurati in qualsiasi ordine — ch0 per primo, per ultimo, come preferisce. Il workaround "associ ch0 per ultimo" della v1.2 non è più necessario.
Verifica di rilettura: dopo il binding, legga CT_MODEL_CH0/1/2 (0x51..0x53) — riflettono lo stato applicato per ciascun canale.
Modalità di guasto (validazione di (classe, modello) avviene al passo di associazione CMD_SET_CT_MODEL_CHn, non alla scrittura di sola predisposizione su 0x05):
SENSOR_CLASS = 0(NON IMPOSTATO) quando si inviaCMD_SET_CT_MODEL_CHn→REG_ERROR = ERR_PARAM.CT_MODELfuori dall'intervallo 1..7 (SCT-013-005/-010/-030/-050/-100/-020/-060) inCMD_SET→ERR_PARAM.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::setSensorClass(cls) / RbAmp::setCTModel(channel, code) |
imposti la classe del sensore e il modello CT per canale |
| ESP-IDF | rbamp_set_sensor_class() / rbamp_set_ct_model_ch() |
imposti la classe del sensore e il modello CT per canale |
| Python | dev.set_sensor_class(cls) / dev.set_ct_model_ch(channel, code) |
imposti la classe del sensore e il modello CT per canale |
| ESPHome | sensor_class: / ct_model: |
Opzioni YAML per la classe del sensore e il modello CT |
6.3 Snapshot GC in broadcast — sincronizzazione della flotta su attivazione
Attivazione per modulo tramite REG_FLEET_CONFIG.bit0 (GC_ENABLE). Predefinito OFF. La modifica ha effetto dopo il reset (reset software CMD_RESET o reset hardware).
6.3.1 Sequenza di attivazione (una volta per modulo)
1. write REG_FLEET_CONFIG (0x27) = 0x01 # bit0 = GC_ENABLE
2. issue CMD_SAVE_USER_CONFIG (opcode 0x32, ungated)
3. issue CMD_RESET (opcode 0x01)
4. wait ~300 ms boot
5. verify: read REG_FLEET_CONFIG → bit 0 should be 1
6.3.2 Formato del frame GC
I²C general-call address 0x00 | A5 27 (5-byte payload)
A5— magic del frame.27— opcodeCMD_LATCH_PERIOD.—0x00= all-call; altrimenti deve corrispondere aREG_GROUP_ID (0x28)del dispositivo.— contatore di tick a 16 bit lato master (per la numerazione delle finestre su tutta la flotta e il rilevamento dei frame persi per modulo tramiteGC_TICK (0x59)).
Solo snapshot: i frame GC non trasportano opcode distruttivi (SAVE_*, COMMIT_ADDR, FACTORY_RESET, ecc.) per progetto.
6.3.3 Rilevamento della modalità di guasto — a 2 livelli
Livello 1 — NACK sull'indirizzo General Call (immediato, a livello di bus):
- Se GC è disattivato su tutta la flotta → il master riceve un errore hard (NACK sull'indirizzo
0x00, o l'equivalente lato driver). - Si tratta di un errore hard, NON di un'omissione silenziosa — il master può rilevarlo e reagire.
- Scatto: NACK su GC = "GC non è abilitato su alcun dispositivo della flotta."
Livello 2 — witness per modulo (dopo l'assestamento):
- Se non arriva alcun NACK (almeno un modulo è in ascolto), il master legge
REG_V03_PERIOD_VALID (0x07)da ogni slave atteso. 1= lo snapshot è riuscito su quel modulo.0= GC è disattivato su quel modulo specifico, oppure il periodo corrente è vuoto.
Ripiego su snapshot per dispositivo se il witness riporta 0:
foreach module where witness == 0:
write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
foreach module: read period snapshot with skip_latch=true
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmpFleet::checkSync() |
invii il frame di snapshot General Call; verifichi ogni modulo |
| ESP-IDF | rbamp_fleet_gclatch() / rbamp_fleet_check_sync() |
invii il frame di snapshot General Call; verifichi ogni modulo |
| Python | fleet.gc_latch(group, tick, settle_ms) / fleet.check_sync(expected_tick) |
invii il frame di snapshot General Call; verifichi ogni modulo |
| ESPHome | fleet_gc_enable: / log di verifica sincronizzazione |
snapshot General Call opzionale; riga di log che conferma la sincronizzazione dei moduli |
6.4 Sincronizzazione del periodo — due strategie
Strategia 1 — snapshot sequenziale + assestamento condiviso (qualsiasi firmware)
for module in modules:
write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
for module in modules:
read_period_snapshot(module) # skip_latch=true
Sfasamento tra moduli: ~1 ms per modulo a 50 kHz. Su 16 moduli, rispetto a un periodo di 60 secondi, sono 0.027 %. Trascurabile per la contabilità tariffaria.
Attesa di assestamento dopo CMD_LATCH_PERIOD:
- Minimo 50 ms prima di leggere
V03_PERIOD_VALID (0x07)o lo snapshot di periodo — questo copre la latenza di snapshot nel caso peggiore (1 periodo di rete @ 50 Hz = 20 ms + commit RT + assestamento della periferica I²C). - Facoltativamente il master può fare polling su
STATUS.bit0 (READY)invece di una pausa fissa:READY=1significa che il blocco RT è in uno stato coerente, quindi lo snapshot del periodo può essere letto a raffica in sicurezza. - Su un modulo nuovo di fabbrica (< ~100 ms dall'avvio dalla v1.2; < 200 ms prima) uno snapshot può restituire
V03_PERIOD_VALID = 0perché si è accumulato meno di 1 periodo di rete — vedi la cronologia dell'avvio a freddo §6.0.
Strategia 2 — snapshot broadcast General-Call (richiede l'abilitazione)
Sfasamento = 0 (atomico a livello di bus). Vedi §6.3.
Quando usare cosa:
- < 8 moduli: Strategia 1 (più semplice, nessun enable richiesto).
- ≥ 8 moduli o sincronizzazione stretta: Strategia 2.
- Un metodo per modulo: il
CMD_LATCH_PERIODindirizzato e lo snapshot GC in broadcast azzerano lo stesso accumulatore unico — mescolarli su un modulo interrompe in anticipo il periodo in corso. Il ripiego per modulo (§6.3.3) è sicuro perché scatta solo su un modulo che il broadcast non ha raggiunto.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readPeriodSnapshot(..., skip_latch=true) / RbAmpFleet::gcLatch() |
lettura sequenziale dopo uno snapshot condiviso; frame di snapshot General Call |
| ESP-IDF | rbamp_read_period_snapshot(..., skip_latch=true) / rbamp_fleet_gclatch() |
lettura sequenziale dopo uno snapshot condiviso; frame di snapshot General Call |
| Python | snapshot sequenziale, skip_latch=True / fleet.gc_latch() |
lettura sequenziale dopo uno snapshot condiviso; frame di snapshot General Call |
| ESPHome | latch_interval: / fleet_gc_enable: |
cadenza di snapshot separata; snapshot General Call su attivazione |
6.5 Provisioning — flash da zero + SAVE
Comportamento di un modulo appena flashato:
- Al primo avvio dopo il flash del firmware:
REG_ERROR = 0xFB (FLASH_PARAMS_BAD)+EVENT_FLAGS.bit3impostato. - La pagina dei parametri non è inizializzata → vengono caricati i valori di fabbrica.
È NORMALE su un modulo vergine e non è fatale. Non interrompa la configurazione al primo 0xFB dell'avvio.
Recovery:
1. configure SENSOR_CLASS + CT_MODEL (per §6.2)
2. (optional) configure FLEET_CONFIG + GROUP_ID + LABEL
3. issue CMD_SAVE_USER_CONFIG (opcode 0x32, ungated)
4. wait ~700 ms (flash write)
5. verify: REG_ERROR = 0x00, EVENT_FLAGS.bit3 cleared
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmpFleet::provision() / RbAmp::saveUserConfig() |
sposti un modulo vergine al suo indirizzo; salvi la configurazione utente |
| ESP-IDF | rbamp_provision() / rbamp_save_user_config() |
sposti un modulo vergine al suo indirizzo; salvi la configurazione utente |
| Python | configurazione della flotta / dev.save_user_config() |
predisponga un modulo vergine, poi lo aggiunga alla flotta; salvi la configurazione utente |
| ESPHome | Flusso di configurazione / new_address: |
YAML passo-passo per un modulo vergine; cambio indirizzo una tantum |
6.7 Recupero dallo stato di errore — albero decisionale
Se all'avvio o durante l'esecuzione STATUS.bit1 (ERROR) = 1 oppure il segnale durevole EVENT_FLAGS.bit3 (ERROR) è impostato, il master legge REG_ERROR (0x02) e decide in base al codice:
read REG_ERROR (0x02):
0x00 → no error (false signal — clear stale EVENT bit3 via W1C)
action: write 1<<3 → EVENT_FLAGS (W1C clear)
0xF9 → CLONE (reserved)
action: not raised. If ever observed, treat as
vendor-reserved and contact the supplier.
0xFA → LUT_BAD (calibration LUT corrupted)
action: device unusable for measurement. Factory recovery required.
0xFB → FLASH_PARAMS_BAD (params page uninitialized — virgin module)
action: NORMAL for a freshly flashed module. Provision per §6.5
(configure SENSOR_CLASS/CT_MODEL/...; issue CMD_SAVE_USER_CONFIG).
Cleared after a successful SAVE.
0xFC → NOT_READY (transient; module still booting)
action: wait 50 ms, retry. If persistent > 300 ms — power cycle.
0xFD → SENSOR_OVERFLOW (transient; signal saturated)
action: physical overload detected. The chosen CT clamp has
insufficient range for the measured current, or a real overload.
Issue CMD_CLEAR_ERROR (0x31) after the cause is removed.
0xFE → PARAM (last operation rejected — invalid argument / unknown opcode;
EVENT bit3 set. Very early images, 1.2–1.4.3, ignored unknown
opcodes silently)
action: master-side bug — review the last write. Issue CMD_CLEAR_ERROR
after fixing the master logic.
0xFF → UNHANDLED (firmware-side anomaly)
action: open an issue with the vendor; CMD_CLEAR_ERROR attempts to clear.
If persistent after CMD_RESET — the device is suspect.
Procedura generale di recupero per errori transitori (0xFC/0xFD/0xFE):
1. capture context (what was the last write? master state?)
2. issue CMD_CLEAR_ERROR (opcode 0x31)
3. wait 5 ms
4. re-read STATUS / REG_ERROR — verify cleared
Per errori persistenti — invii CMD_RESET e segua la cronologia dell'avvio a freddo (§6.0). Se l'errore persiste dopo il reset e non è 0xFB (flash appena caricato) — contatti l'assistenza del fornitore.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readLastError() / RbAmp::clearError() |
legga il codice di errore; lo azzeri |
| ESP-IDF | rbamp_read_last_error() / rbamp_clear_error() |
legga il codice di errore; lo azzeri |
| Python | dev.read_last_error() / dev.clear_error() |
legga il codice di errore; lo azzeri |
| ESPHome | write_clear_error() / write_reset() |
cancelli l'errore; reset software del modulo |
6.6 Riferimento dei comandi
Opcode principali (da scrivere in REG_COMMAND (0x01))
| Opcode | Nome | Assestamento | Subordinato | Note |
|---|---|---|---|---|
0x01 |
RESET |
~300 ms | – | Reset software (HAL_NVIC_SystemReset) |
0x27 |
LATCH_PERIOD |
50 ms | – | Copia i contatori RT nello snapshot del periodo |
0x28 |
SET_CT_MODEL_CH0 |
5 ms | – | Associ REG_CT_MODEL preparato al canale 0 |
0x29 |
SET_CT_MODEL_CH1 |
5 ms | – | Associ REG_CT_MODEL preparato al canale 1 |
0x2A |
SET_CT_MODEL_CH2 |
5 ms | – | Associ REG_CT_MODEL preparato al canale 2 |
0x30 |
COMMIT_ADDR |
700 ms | – | Persista I2C_ADDRESS (vedi §6.1) |
0x31 |
CLEAR_ERROR |
0 | – | Azzera REG_ERROR (solo classi transitorie; CLONE (0xF9) è riservato, non viene sollevato) |
0x32 |
SAVE_USER_CONFIG |
700 ms | – | Persista il gruppo user_config (compatibile con la produzione) |
Gli opcode fuori dall'intervallo pubblico (uso di fabbrica) non sono documentati in questo riferimento. Un master consumer non li invia in funzionamento normale; un opcode non supportato → REG_ERROR = ERR_PARAM (0xFE).
7 · Semantica
7.0 Durata della flash e comportamento al reset
Promemoria: prima del firmware 1.4.20 anche un reset riporta la scala del modello CT applicata al valore di fabbrica (CAPABILITY bit 12 a zero) — vedi §6.2.
Durata della flash: ~10 000 cicli per pagina (tipico, specifica del fornitore). Ogni CMD_SAVE_USER_CONFIG o CMD_COMMIT_ADDR è un ciclo di cancellazione e scrittura sulla pagina dei parametri.
⚠ Non ripeta SAVE/COMMIT in un ciclo di esecuzione. A 1 SAVE/s un modulo si brucia in circa 3 ore. La configurazione si fa una volta in fase di installazione; non servono aggiornamenti delle impostazioni durante l'esecuzione (un master del consumatore raramente le modifica).
Conservazione: tipicamente oltre 10 anni a temperatura di esercizio normale.
Confronto del comportamento al reset:
| Tipo di reset | Conservato | Cancellato |
|---|---|---|
CMD_RESET (0x01) |
flash (configurazione, indirizzo, etichetta, guadagni, NF) | RAM (UPTIME, ZC_OFFSET, EVENT_FLAGS — tranne il bit RESET_OCCURRED 5 impostato all'avvio; THRESH_*; DIGEST_CONFIG) |
| Pin di spegnimento e riaccensione / reset hard | flash | uguale a CMD_RESET più l'eventuale RAM esterna trattenuta lato host |
CMD_FACTORY_RESET (0xAA) (solo modalità di fabbrica) |
niente | tutto — l'intero blocco dei parametri, compresa la calibrazione di fabbrica dei canali |
⚠ CMD_FACTORY_RESET non è un « ripristino dei valori predefiniti » a livello utente. Riscrive l'intero blocco dei parametri, compresa la calibrazione di fabbrica dei canali, e il modulo lo accetta solo in modalità di fabbrica — è un'operazione di produzione, non un intervento di assistenza. Un modulo BASIC non ha un comando di reset per l'utente. Per riportare un modulo a uno stato noto, usi CMD_RESET (0x01) (reset software: non viene toccato nulla in flash) e riconfiguri le impostazioni a livello utente con CMD_SAVE_USER_CONFIG (0x32).
Configurazione dei bit di RESET_OCCURRED (canonica):
- Dopo un reset, all'avvio:
EVENT_FLAGS.bit5 = 1. - Il master vede il bit 5 → sa che il modulo si è riavviato → deve reinizializzare i campi solo-RAM (DIGEST_CONFIG, THRESH_*, EVENT_MASK).
- Il master cancella il bit 5 con W1C:
write 1<<5 → EVENT_FLAGS.
7.1 Modello di persistenza
| Comando | Produzione | Persiste |
|---|---|---|
CMD_SAVE_USER_CONFIG (0x32) |
✅ OK | i2c_address (tramite due fasi), ct_model, sensor_class, fleet_config, group_id, label |
CMD_COMMIT_ADDR (0x30) |
✅ OK (con magic armato) | i2c_address |
CMD_RESET (0x01) |
✅ OK | — (reset software) |
CMD_LATCH_PERIOD (0x27) |
✅ OK | — (esegue lo snapshot del periodo) |
CMD_CLEAR_ERROR (0x31) |
✅ OK | — (cancella REG_ERROR) |
CMD_SAVE_GAINS (0x26) |
❌ BLOCCATO in produzione (rifiutato: REG_ERROR = 0xFE; il riavvio lo annulla) |
calibrazione di fabbrica |
CMD_FACTORY_RESET (0xAA) |
❌ BLOCCATO in produzione | — |
7.2 Read-back ≠ persistenza
⚠ La protezione di produzione accetta la scrittura in RAM (una lettura successiva restituisce il valore scritto), ma il salvataggio in flash può essere rifiutato. Dopo il riavvio il valore torna allo stato precedente la scrittura.
L'unico modo valido per confermare la persistenza è CMD_RESET + attesa dell'avvio + rilettura:
1. write target_reg(...)
2. issue CMD_RESET (0x01)
3. wait ~300 ms boot
4. re-read target_reg
5. assert read == written # only now is persistence confirmed
L'indirizzo è un'eccezione (canonico v1.3): REG_I2C_ADDRESS (0x30) all'avvio legge l'indirizzo attivo. Dopo la predisposizione ripete il candidato; dopo il riavvio mostra il valore effettivamente salvato.
7.3 Avvertenza sul riferimento di tensione unico
Il modulo usa un canale U per calcolare P su tutti i canali I. Se una pinza CT è agganciata a un filo di un'altra fase (quadro di distribuzione polifase), le letture di P per quel canale saranno errate (sfasamento arbitrario tra U e I). I_RMS resta corretto.
La misura multi-fase (L1/L2/L3 simultaneamente) è una SKU separata con una propria specifica.
7.4 Integrazione dell'energia del master — canone del tempo di parete
⚠ V03_PERIOD_LATCH_MS (0xEC) è un timer diagnostico del modulo; può risultare basso sotto carico — per l'energia usi il clock del master.
Integrazione canonica dell'energia lato master:
# CORRECT — master wall-clock
t_now = master_clock()
dt_s = (t_now - t_prev_latch) / time_unit
energy_wh[ch] += avg_p[ch] * dt_s / 3600
t_prev_latch = t_now
# WRONG — the module diagnostic timer may read short under load
dt_chip_s = read_u32(0xEC) / 1000.0
energy_wh[ch] += avg_p[ch] * dt_chip_s / 3600 # systematically under-reported
La misura lato modulo della finestra chiusa è V03_PERIOD_COMMIT_CNT (0xBE) moltiplicato per la durata del commit — conta i commit RT interi e non è influenzato dalla carenza di timer che fa leggere valori bassi a V03_PERIOD_LATCH_MS. Un commit = 0.1 s dalla v1.2; le immagini precedenti usavano 0.2 s. Per capire quale vale senza una tabella delle versioni: il rapporto V03_PERIOD_LATCH_MS / V03_PERIOD_COMMIT_CNT risulta vicino a 100 o vicino a 200. Lo usi per i controlli incrociati; il cronometro di parete del master resta l'autorità per la contabilità tariffaria.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::energyWh(ch) |
totale Wh corrente di un canale |
| ESP-IDF | rbamp_energy_wh() |
totale Wh corrente di un canale |
| Python | dev.energy.wh(ch) |
totale Wh corrente di un canale |
| ESPHome | energy |
Contatore Wh per canale |
7.5 Conservazione del periodo in caso di snapshot fallito
Il firmware CONSERVA l'accumulatore del periodo su uno snapshot vuoto. Quando g_period_count == 0 (uno snapshot senza periodo leggibile):
REG_V03_PERIOD_VALID = 0(segnale non aggiornato).period_start_msviene conservato → il successivo snapshot riuscito copre l'intero intervallo previsto dal master.
Implicazione: il master non perde dati con uno snapshot non aggiornato. Schema per l'integrazione del master:
issue snapshot
if PERIOD_VALID == 1:
integrate(avg_p, master_dt)
reset_master_clock
# else: skip integration (FW will automatically recover on the next success)
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readPeriodSnapshot() / RbAmp::isPeriodValid() |
eseguire uno snapshot del periodo e integrare solo se valido; verificare il bit di pronto |
| ESP-IDF | rbamp_read_period_snapshot() / rbamp_is_period_valid() |
eseguire uno snapshot del periodo e integrare solo se valido; verificare il bit di pronto |
| Python | dev.read_period_snapshot() / RbAmpStaleError |
eseguire uno snapshot del periodo; segnalato quando lo snapshot non è pronto, il successivo copre l'intervallo completo |
| ESPHome | Snapshot del periodo non valido | registrato quando il flag di validità è 0; il primo snapshot dopo l'avvio viene scartato |
7.6 Tolleranza alla deriva del clock
Riferimento: la base dei tempi interna del modulo può risultare più lenta fino al 30 % sotto carico — questo è normale, è una proprietà della base dei tempi del modulo, per progetto. Misurato in hardware sotto carico di produzione.
Accettazione: il chip è OK con deriva ≤ 30 %.
⚠ La soglia legacy del 3 % è ERRATA. Quella soglia rifiuterebbe in massa chip sani.
7.7 EMI / resilienza ai transitori di commutazione
Le letture durante la commutazione attiva dei relè (EMI da 5 A) falliscono circa il 67 % delle volte (misurato su hardware). Le letture a regime sono affidabili. Il bus si riprende da solo, non si blocca mai e nessun modulo viene perso.
Schema del master — retry a livello applicativo (obbligatorio quando si commutano carichi induttivi):
for attempt in range(5):
result = read_register(...)
if result is OK:
return result
sleep(20 ms)
raise IOError("read failed after retries")
Il solo bus_reset lato master non basta quando un disturbo EMI si sovrappone alla finestra di ripetizione del driver.
7.8 Riepilogo dei limiti noti
Elenco consolidato delle caratteristiche note che il master deve considerare:
| Argomento | Comportamento | Vedi |
|---|---|---|
| Deriva del timer lato chip | Può leggere valori bassi sotto carico, fino al 30 % (intervallo di accettazione) | §7.4, §7.6 |
| Commutazione di relè (EMI) | ~67 % di tasso di fallimento in lettura durante la commutazione; il bus si riprende da solo | §7.7 |
EVENT.bit3 latenza asincrona |
fino a una finestra (~100 ms; 200 ms prima della v1.2) dal rifiuto della scrittura all'asserzione del bit 3 | §5.3 |
V03_PERIOD_LATCH_MS (0xEC) |
Timer diagnostico del modulo; può risultare basso sotto carico — il master usa il proprio tempo di parete | §4.13, §7.4 |
Semantica di REG_ERROR (0x02) |
Esito dell'ultima scrittura (non persistente); bit 3 dell'EVENT = segnale durevole | §5.3 |
I_RMS = 0.0 |
Sotto la soglia di rumore (misura valida), NON « nessun dato » | §5.4.3 |
U_RMS/U_PEAK/P sulle varianti I |
Letto come 0.0 (valido solo se il bit 8 di CAPABILITY = 1) |
§4.10, §7.3 |
| Scrittura multi-byte | Nessun incremento automatico; è richiesto un ciclo byte per byte | §5.1 |
| Verifica del cambio di indirizzo | Tramite scansione del bus sul nuovo indirizzo; 0x30 è veritiero anche dopo il riavvio |
§6.1 |
| Avvio con flash vergine | REG_ERROR = 0xFB è normale; SAVE lo azzera |
§6.5 |
| GC predefinito | OFF (attivazione per modulo); NACK su GC = "non abilitato" | §6.3 |
| Durata della flash | ~10 000 cicli per pagina; non ripeta SAVE in un ciclo | §7.0 |
8 · Esempi di tracce sul filo
8.1 Rilevamento — legga PRODUCT_ID + HW_VARIANT + CAPABILITY
# I²C operations on default slave addr 0x50
S 0xA0 W 0x54 Sr 0xA1 R [PRODUCT_ID] P # read 0x54
S 0xA0 W 0x55 Sr 0xA1 R [HW_VARIANT] P # read 0x55
S 0xA0 W 0x57 Sr 0xA1 R [CAP_lo][CAP_hi] P # burst-read 0x57..0x58 (auto-increment)
Dove S=start, Sr=start ripetuto, P=stop, W=bit di scrittura, R=bit di lettura, 0xA0=indirizzo slave 0x50 << 1.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readVariant() / RbAmp::readCapability(out) |
legga la variante hardware; legga la mappa delle funzioni |
| ESP-IDF | rbamp_read_variant() / rbamp_read_capability() |
legga la variante hardware; legga la mappa delle funzioni |
| Python | dev.read_variant() / dev.read_capability() |
legga la variante hardware; legga la mappa delle funzioni |
| ESPHome | get_variant_str() / get_capability_hex() |
la variante come testo; la mappa delle funzioni in esadecimale |
8.2 Lettura in burst del blocco RT (variante UI, tutti i canali)
# Read all of V03 RMS + P + PF (0x86..0xBD) — 56 bytes, atomic via read-freeze
S 0xA0 W 0x86 Sr 0xA1 R [56 bytes] P
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readAll(snapshot) |
legga l'intero blocco RT in tempo reale con una sola chiamata |
| ESP-IDF | rbamp_read_all() |
legga l'intero blocco RT in tempo reale con una sola chiamata |
| Python | dev.read_all() |
legga l'intero blocco RT in tempo reale con una sola chiamata |
| ESPHome | lettura in burst del blocco istantaneo | il componente legge il blocco istantaneo in una sola raffica per ogni aggiornamento |
8.3 Scrittura multi-byte — LABEL byte per byte
# WRONG: burst-write — only 'M' is accepted
S 0xA0 W 0x68 'M' 'y' 'M' 'e' 't' 'e' 'r' '1' P
# CORRECT: byte-at-a-time loop
S 0xA0 W 0x68 'M' P
S 0xA0 W 0x69 'y' P
S 0xA0 W 0x6A 'M' P
S 0xA0 W 0x6B 'e' P
S 0xA0 W 0x6C 't' P
S 0xA0 W 0x6D 'e' P
S 0xA0 W 0x6E 'r' P
S 0xA0 W 0x6F '1' P
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::writeLabel(label) / RbAmp::readLabel(out) |
scriva l'etichetta da 8 byte (solo BASIC); la rilegga |
| ESP-IDF | rbamp_write_label() / rbamp_read_label() |
scriva l'etichetta di 8 caratteri; la rilegga |
| Python | dev.set_label(label) / dev.read_label() |
scriva l'etichetta da 8 byte; la rilegga |
| ESPHome | — | opzione label non documentata |
Snapshot broadcast GC 8.4 + ripiego witness
# Send GC frame: A5 27
S 0x00 W 0xA5 0x27 0x00 0x2A 0x00 P
# Wait 50 ms settle
# Witness check for every expected module
foreach module in [0x50, 0x51, 0x52]:
S (module<<1)|W 0x07 Sr (module<<1)|R [VALID] P
if VALID != 1:
# Fall back to per-device snapshot
S (module<<1)|W 0x01 0x27 P # CMD_LATCH_PERIOD
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmpFleet::checkSync() |
invii il frame di snapshot General Call; verifichi ogni modulo |
| ESP-IDF | rbamp_fleet_gclatch() / rbamp_fleet_check_sync() |
invii il frame di snapshot General Call; verifichi ogni modulo |
| Python | fleet.gc_latch(group, tick, settle_ms) / fleet.check_sync(expected_tick) |
invii il frame di snapshot General Call; verifichi ogni modulo |
| ESPHome | fleet_gc_enable: / log di verifica sincronizzazione |
snapshot General Call opzionale; riga di log che conferma la sincronizzazione dei moduli |
8.5 Cambio indirizzo in 5 passi
# 1. Stage candidate addr (0x51) → REG_I2C_ADDRESS
S 0xA0 W 0x30 0x51 P
# 2. Arm magic → ADDR_COMMIT_MAGIC
S 0xA0 W 0x31 0xA5 P
# 3. Issue CMD_COMMIT_ADDR (opcode 0x30) → REG_COMMAND
S 0xA0 W 0x01 0x30 P
# 4. Wait 700 ms flash write
# 5. Issue CMD_RESET (opcode 0x01) → REG_COMMAND
S 0xA0 W 0x01 0x01 P
# Wait ~300 ms boot
# Verify: probe the new addr
S 0xA2 W 0x55 Sr 0xA3 R [HW_VARIANT] P # 0xA2 = 0x51 << 1
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::prepareAddressChange(new_addr) / RbAmp::commitAddressChange() |
imposti e armi il nuovo indirizzo, poi lo confermi |
| ESP-IDF | rbamp_prepare_address_change() / rbamp_commit_address_change() |
imposti e armi il nuovo indirizzo, poi lo confermi |
| Python | dev.prepare_address_change(new_addr) / dev.commit_address_change() |
imposti e armi il nuovo indirizzo, poi lo confermi |
| ESPHome | new_address: |
modifica di indirizzo una tantum all'avvio; rimuova l'opzione in seguito |
8.6 Provisioning dopo il flash da zero
# 1. Check fresh-flash state
S 0xA0 W 0x02 Sr 0xA1 R [0xFB] P # ERR_FLASH_PARAMS_BAD — normal
# 2. Configure sensor_class
S 0xA0 W 0x25 0x01 P # SCT_013
# 3. Stage CT model + bind ch0
S 0xA0 W 0x05 0x03 P # SCT-013-030
S 0xA0 W 0x01 0x28 P # CMD_SET_CT_MODEL_CH0
# Wait 5 ms
# 4. Save user_config
S 0xA0 W 0x01 0x32 P # CMD_SAVE_USER_CONFIG
# Wait 700 ms
# 5. Verify: REG_ERROR should be 0x00 (read IMMEDIATELY before the next write)
S 0xA0 W 0x02 Sr 0xA1 R [0x00] P
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::configureChannels(cls, models, n) / RbAmp::saveUserConfig() |
imposti la classe e i modelli di tutti i canali; salvi la configurazione utente |
| ESP-IDF | rbamp_configure_channels() / rbamp_save_user_config() |
imposti la classe e i modelli di tutti i canali; salvi la configurazione utente |
| Python | dev.configure_channels(cls, models) / dev.save_user_config() |
imposti la classe e i modelli di tutti i canali; salvi la configurazione utente |
| ESPHome | sensor_class: / ct_model: |
Opzioni YAML per la classe del sensore e il modello CT |
8.7 DIGEST andata e ritorno — configurare + leggere
# 1. Configure digest mask: I_RMS + U_RMS + P_REAL (bits 0+1+2 = 0x07)
S 0xA0 W 0x29 0x07 P
# 2. Wait one RT-commit cycle (~100 ms from v1.2; waiting 200 ms covers all images; or poll STATUS.bit0)
# 3. Burst-read the digest window (22 bytes)
S 0xA0 W 0x70 Sr 0xA1 R [22 bytes] P
# Parse the layout per DIGEST_CONFIG = 0x07 on UI1 (N_I = 1):
# byte[0] = STATUS_MIRROR
# byte[1] = SEQ
# byte[2..3] = I_RMS[0] u16 (0.01 A units)
# byte[4..5] = U_RMS u16 (0.1 V units)
# byte[6..7] = P[0] i16 (1 W units)
# byte[8..21] = unused (0x00)
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | — | finestra del digest non esposta |
| ESP-IDF | rbamp_set_digest_fields() / rbamp_read_digest() |
scelga i campi del digest; li legga in una sola transazione (BASIC) |
| Python | — | finestra del digest non esposta |
| ESPHome | — | finestra del digest non esposta |
8.8 Flusso degli eventi di soglia — scrittura della soglia → attivazione → azzeramento W1C
# 1. Write current threshold = 30 A (0x0BB8 in 0.01 A units → 2 bytes LE)
S 0xA0 W 0x2C 0xB8 P # LO byte
S 0xA0 W 0x2D 0x0B P # HI byte
# 2. Unmask THRESH_I event (bit 1) → DRDY solid-LOW on trip
S 0xA0 W 0x2B 0x02 P # EVENT_MASK = bit 1 only
# 3. (runtime) The master polls EVENT_FLAGS
S 0xA0 W 0x2A Sr 0xA1 R [event_flags] P
# event_flags == 0x02 → threshold tripped
# 4. (optional) Read context — REG_ERROR, RT block, etc.
# 5. Clear EVENT_FLAGS.bit1 via W1C
S 0xA0 W 0x2A 0x02 P
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::setEventThresholds(i_amps, p_watts) / RbAmp::readEventFlags(out) |
imposti le soglie di corrente e potenza; legga e azzeri i flag di evento |
| ESP-IDF | rbamp_set_event_thresholds() / rbamp_read_event_flags() |
imposti le soglie di corrente e potenza; legga e azzeri i flag di evento |
| Python | dev.read_event_flags() |
legga e cancelli i flag degli eventi (nessun setter di soglia sul dispositivo) |
| ESPHome | Allarmi di soglia in YAML / get_event_flags() |
automazioni a soglia sui valori del sensore; i flag degli eventi |
8.9 Raffica diagnostica di cattura grezza (CAPTURE_*)
CMD_CAPTURE_RAW (0x38) e i registri CAPTURE_* sono una funzione diagnostica — non servono in funzionamento normale; li usi solo se il fornitore chiede di catturare campioni grezzi.
# 1. Arm raw-capture
S 0xA0 W 0x01 0x38 P # CMD_CAPTURE_RAW (opcode 0x38)
# Wait ~80 ms (3 DMA-TC cycles)
# 2. Check ready
S 0xA0 W 0x18 Sr 0xA1 R [status & 0x01] P # bit 0 = ready
# 3. Select page 0 (16 raw I0 samples → CAPTURE_WINDOW)
S 0xA0 W 0x19 0x00 P
# 4. Burst-read CAPTURE_WINDOW (32 bytes = 16×u16 LE samples)
S 0xA0 W 0x1A Sr 0xA1 R [32 bytes] P
# Repeat steps 3-4 for pages 1..15 (256 samples total ≈ 1.3 mains periods)
8.10 Rilettura dello specchio di verifica del modello CT (controllo di coerenza dopo il binding)
# After the §6.2 sequence — verify the applied state per channel via 0x51..0x53 (burst):
S 0xA0 W 0x51 Sr 0xA1 R [model_ch0][model_ch1][model_ch2] P
# Expected on UI2 mixed-CT (e.g. ch0=SCT-013-005, ch1=SCT-013-030):
# byte[0] = 0x01 # SCT-013-005 applied on ch0
# byte[1] = 0x03 # SCT-013-030 applied on ch1
# byte[2] = 0x00 # unused (UI2 N_I=2)
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readCTModelCh(channel, out) |
legga il modello CT effettivamente applicato su un canale |
| ESP-IDF | rbamp_read_ct_model_ch() |
legga il modello CT effettivamente applicato su un canale |
| Python | dev.read_ct_model_ch(ch) |
legga il modello CT effettivamente applicato su un canale |
| ESPHome | log di avvio ct_model[0]: matches |
righe di log che confermano che la classe del sensore e il modello sono stati applicati |
9 · Accettazione / tolleranza
| Parametro | Soglia | Fonte |
|---|---|---|
| Deriva del clock del chip rispetto al tempo di parete del master | ≤ 30 % | validato al banco |
| Tasso di insuccesso delle letture durante la commutazione dei relè EMI | fino a ~67 % durante la commutazione | validato al banco |
| Tasso di NACK sul bus (Linux/ESP I²C a 100 kHz senza tentativi) | fino a ~20 % | caratteristica lato host |
| Tasso di NACK sul bus @ 50 kHz + 3× retry | < 0.8 % | validato al banco |
Valore di REG_ERROR all'avvio con flash vergine |
0xFB (FLASH_PARAMS_BAD) |
NORMALE su un modulo vergine |
| Avvio a freddo fino alla prima misura valida | ~250 ms | tipico |
10 · Registro delle modifiche
1.3.0 (2026-06-15) — Prima versione pubblica.
Firmware di riferimento: protocol_version = 1.3, schema_version = 2. Contratto della pagina 0 congelato.
Principali modifiche della v1.3 rispetto alle versioni interne precedenti
- CT_MODEL solo preparazione:
REG_CT_MODEL (0x05)non si applica più automaticamente a ch0 alla scrittura. L'associazione avviene solo tramiteCMD_SET_CT_MODEL_CHn(indipendente dall'ordine). - Commit a due fasi dell'indirizzo (compatibile con la produzione):
I2C_ADDRESSè persistito tramiteADDR_COMMIT_MAGIC+CMD_COMMIT_ADDR.REG_I2C_ADDRESSlegge l'indirizzo attivo all'avvio. - REG_ERROR = esito dell'ultima scrittura (non persistente).
EVENT_FLAGS.bit3è il segnale durevole (W1C persistente; viene asserito entro una finestra, ~100 ms, dopo il rifiuto della scrittura). - Opcode sconosciuti / valori enum fuori intervallo → rifiutati:
REG_ERROR = ERR_PARAM (0xFE)+EVENT.bit3. Immagini molto precoci (1.2–1.4.3) ignoravano in silenzio gli opcode sconosciuti. - Configurazione alla prima scrittura in flash:
ERR_FLASH_PARAMS_BAD (0xFB)su un modulo vergine → cancellato tramiteCMD_SAVE_USER_CONFIG. - Snapshot in broadcast GC — attivazione per modulo tramite
FLEET_CONFIG.bit0(predefinito OFF; ha effetto dopo il reset). NACK con funzione disattivata = errore grave, non silenzioso. - Asimmetria lettura/scrittura per progetto: la LETTURA incrementa automaticamente l'indirizzo ✅; la SCRITTURA richiede un byte alla volta ❌ (confermato via HW).
- Registro CAPABILITY (0x57/0x58 u16 LE): mappa di bit delle funzioni — rilevi le funzioni bit per bit (§3.2), mai confrontando l'intero valore; bit 12 = SCT_RATING_SELF (fw 1.4.20+).
- Atomicità: il blocco RMS V03 + Digest hanno un read-freeze (lettura a raffica atomica); gli specchi GC_TICK / I2C_ADDRESS / CT_MODEL_CHn si leggono due volte e devono coincidere.
- Semantica NF-clamp:
I_RMS = 0.0significa "sotto la soglia di rumore", ed è una misura valida. - AC_FREQ derivato dal passaggio per lo zero su tutte le varianti (incluse le solo-I).
- L'integrazione dell'energia del master deve usare il proprio orologio di parete, non
V03_PERIOD_LATCH_MS (0xEC)(timer diagnostico del modulo — può leggere valori bassi sotto carico).