Comandi
Tutte le azioni del dispositivo passano dal registro COMMAND (0x0060, u8) — su Modbus, holding 0x8113 (solo scrittura). Una scrittura accoda l'opcode; l'esecuzione avviene nel ciclo principale del dispositivo (millisecondi per la maggior parte dei comandi; quelli che toccano la flash richiedono più tempo).
Completamento e semantica del risultato
-
Occupato:
CMD_STATE(0x006A) bit 0 = BUSY mentre un comando è in esecuzione. BUSY è il segnale di completamento — interrogarlo fino a 0 prima di leggere il risultato. Un nuovo comando scritto mentre BUSY è scartato (bit 1 OVERRUN impostato; il comando in esecuzione non viene sovrascritto; OVERRUN si azzera quando viene accettato il comando successivo). Su Modbus una scrittura COMMAND mentre è occupato → eccezione 06. -
Risultato:
ERROR(0x0002; readback Modbus holding 0x8114) contiene il risultato al termine (0x00 = OK).ERRORlegge 0xF0 (Modbus 0xFFFF) per l'intera esecuzione ed è scritto insieme al completamento; giudicare il completamento da BUSY, e leggere il risultato da ERROR dopo. -
Freschezza:
CMD_SEQ(0x0067) aumenta di uno per ogni comando concluso — interrogarlo per distinguere un risultato recente da uno vecchio. -
Schema: verificare BUSY = 0 → scrivere i parametri, poi COMMAND → interrogare BUSY → 0 (timeout: ≥1 s per comandi semplici e salvataggi, ≥0.5 s per la scrittura di una pagina di aggiornamento, ≥3 s per COMMIT di aggiornamento; su I²C tollerare un clock stretching di ≥10 ms e riprovare le letture NACK — non rinviare mai alla cieca un COMMAND) → leggere
ERROR. Procedura completa: Sequenze D2. -
Comandi che riavviano il modulo (0x02 RESET, 0x13 ACTIVATE, 0x16 ADDR_BY_UID sul modulo corrispondente): su Modbus la risposta può essere troncata o assente (e un ritardo TX configurato può sopprimerla); confermare interrogando di nuovo il dispositivo dopo il riavvio.
Codici di errore (ERROR 0x0002)
| Codice | Nome | Significato |
|---|---|---|
| 0x00 | OK | accettato / completato |
| 0xF0 | PENDING | comando ancora in esecuzione (con BUSY = 1) |
| 0xF6 | NVM_IO | una scrittura persistente non è riuscita (SAVE_CAL / SAVE_CONFIG / importazione della storia) |
| 0xF7 | NO_KEY | attestazione rifiutata — nessuna chiave del dispositivo fornita |
| 0xF8 | — | operazione rifiutata dalla politica di assistenza |
| 0xF9 | NVM_RATE_LIMIT | riscrittura persistente limitata nel tempo (almeno ~5 s tra i salvataggi) — riprovare più tardi |
| 0xFA | OP_RETRY | operazione già in corso · rifiutata nello stato attuale (ad es. archivio energia in FAULT, valore di adozione negativo) |
| 0xFB | KEY_GATE | comando protetto da chiave senza una chiave monouso valida (LT_KEY) |
| 0xFC | VALUE_CRC | CRC della pagina di aggiornamento errato (rinviare la pagina) · epoch dell'ora sotto 1 600 000 000 · UID non corrispondente (ADDR_BY_UID) · nessun record storico di questo tipo (HIST_READ) |
| 0xFD | PARAM | parametro / valore di configurazione non valido — nulla resa persistente |
| 0xFE | UNKNOWN_CMD | opcode non supportato |
Insieme dei comandi
Comandi di famiglia
| Op | Nome | Effetto |
|---|---|---|
| 0x01 | SAVE_CAL | persistere i registri di calibrazione (assistenza/fabbrica; protetto da UNLOCK su Modbus; limitato nel tempo → 0xF9) |
| 0x02 | RESET | reset a caldo (protetto da UNLOCK su Modbus; attendersi nessuna risposta o risposta troncata) |
| 0x03 | LATCH_PERIOD | al confine della finestra successiva, eseguire lo snapshot del banco selezionato da LATCH_BANK (0..7; ≥ 8 → 0xFD) e riavviarne l'accumulo — bit di capacità 8; altrimenti 0xFE |
| 0x04 | SAVE_CONFIG | salva la configurazione (lettura-modifica-scrittura; calibrazione invariata; non protetta da UNLOCK). Valori validati rispetto alla tabella dei valori legali; non valido → 0xFD, nulla salvato; limitato nel tempo → 0xF9; un salvataggio senza modifiche è un no-op OK (solleva comunque CONFIG_CHANGED) |
| 0x06 | SET_TIME | applicare l'epoch scritto in TIME_SET/RTC_EPOCH; epoch < 1 600 000 000 → 0xFC; il bit 4 di STATUS si imposta subito |
| 0x07 | ENERGY_RESET | codice operativo della famiglia, subordinato a UNLOCK. Non usato (0xFE / eccezione 03) — il reset del contatore è il LT_RESET protetto da chiave qui sotto |
| 0x0E | IDENTIFY | fa lampeggiare i LED per 10 s — per individuare il modulo nel quadro. Non condizionato |
| 0x0F | ATTEST | firmare la challenge di 32 B a 0x0B80 (mappa dei registri); ~55 ms; 0xF7 = nessuna chiave |
| 0x10 | OTA_BEGIN | aprire una sessione di aggiornamento (Aggiornamento firmware) |
| 0x11 | OTA_BLOCK_WR | programma una pagina da 256 B (limitata a una pagina / ~250 ms — BUSY fino al suo turno) |
| 0x12 | OTA_COMMIT | verificare + armare l'immagine in staging (senza reset); interrogare BUSY ≥ 3 s |
| 0x13 | OTA_ACTIVATE | reset nell'immagine armata (solo quando OTA_STATUS = 2; ~4 s per riapparire) |
| 0x14 | FW_ABORT | chiudere la sessione di aggiornamento / disarmare un'immagine armata |
| 0x15 | — | riservato (fabbrica/assistenza) |
| 0x16 | ADDR_BY_UID | il modulo il cui UID corrisponde a ADDR_UID riceve l'indirizzo (o gli indirizzi) in staging, li persiste insieme a eventuali altre modifiche CFG_ in sospeso e si riavvia; gli altri moduli rispondono 0xFC. Entrambi i campi del nuovo indirizzo a zero → 0xFD; indirizzo non valido → 0xFD; limite di frequenza di salvataggio → 0xF9. Funziona su broadcast Modbus. Non protetto |
Comandi protetti da chiave (contatori a vita e storia)
Questi comandi modificano lo stato rilevante per la misura, quindi ognuno richiede la chiave monouso corrispondente scritta in LT_KEY (0x0844 / Modbus holding 0x8142–43, parola alta per prima) immediatamente prima del comando. La chiave viene consumata da qualsiasi comando successivo; chiave errata o assente → ERROR 0xFB. È una protezione da azione deliberata che si aggiunge al trasporto (non è l'UNLOCK Modbus).
| Op | Nome | Chiave (u32) | Effetto |
|---|---|---|---|
| 0x08 | HIST_READ | — (non protetto da chiave) | recupera il record selezionato da HIST_PERIOD/HIST_BACK in HIST_REC; nessun record → 0xFC |
| 0x09 | HIST_FLUSH | — (non protetto da chiave) | scarica l'energia ora: sempre la copia di ritenzione; il record NVM solo se sono passati ≥ 10 s dalla sua ultima scrittura (implicato anche da RESET e dall'attivazione dell'aggiornamento) |
| 0x0A | LT_RESET | 0x4C545253 "LTRS" |
azzera l'energia a vita; generazione del contatore ++ (registrato). Guasto dell'archivio → 0xFA |
| 0x0B | LT_ADOPT | 0x4C544150 "LTAP" |
adotta i valori dei contatori in staging (sostituzione o migrazione della scheda); generazione ++ (registrata). Ordine di staging: import Wh · export Wh · import reattiva varh · export reattiva varh (4×i64); un valore negativo → 0xFA |
| 0x0C | HIST_WRITE | 0x48494D50 "HIMP" |
importare il record da 80 B di HIST_REC nell'anello orario (HIST_PERIOD deve essere 1, altrimenti 0xFC); timestamp non più recente → 0xFD; errore I/O NVM → 0xF6 |
| 0x0D | HIST_CLEAR | 0x48434C52 "HCLR" |
cancellazione graduale dell'anello orario; ripetere durante l'esecuzione → 0xFA (registrato) |
Azzeramenti a vita, adozioni e scritture della storia sono registrati nel log eventi con i valori prima/dopo — non possono avvenire in silenzio.
Riepilogo delle protezioni
| Meccanismo | Ambito | Come |
|---|---|---|
| UNLOCK Modbus | 0x01 · 0x02 · 0x07 · 0x10 · 0x12 · 0x13 · 0x14 · 0x15 | chiave 0xA5C3 → holding 0x8112; finestra di 10 s, un comando; può condividere un FC16 con il codice operativo (Modbus) |
| LT_KEY | 0x0A–0x0D, entrambi i trasporti | magic per comando, monouso |
| Lista bianca dei broadcast | Modbus unit 0 | solo impostazione dell'ora, snapshot, indirizzo tramite UID (Modbus) |
Non protetti su nessun trasporto: 0x04, 0x06, 0x08, 0x09, 0x0E, 0x0F, 0x11, 0x16. I²C non ha un passo UNLOCK: l'accesso fisico al bus I²C della scheda è il limite di fiducia dell'installazione; i comandi con chiave sono comunque protetti su entrambi i trasporti.