rbAmp
IT
Negozio
Docs
Aggiornato il

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). ERROR legge 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.