smiocan

Configurazione dei moduli smartIO tramite CAN

In generale, i moduli smartIO vengono programmati e configurati tramite l'interfaccia USB integrata. La programmazione avviene in produzione con strumenti appositi, la configurazione tramite optiCONTROL o un programma terminale.

Per la famiglia di dispositivi smartIO basata su un controller ESP, queste funzioni sono ora disponibili anche sul campo tramite il bus CAN. A tale scopo serve il programma di utilità

smiocan <options>

disponibile dalla riga di comando in Yocto. Il programma richiede un'interfaccia socket-CAN ed è quindi disponibile su richiesta anche per altre distribuzioni Linux.

È possibile e consentito stabilire una sola connessione amministrativa alla volta con il dispositivo! L'instaurazione della connessione è protetta da una procedura seed-key e dalla password-key del dispositivo, in modo che almeno i componenti software coinvolti possano essere validati.

Ogni intervento amministrativo tramite SCPI (seriale-USB o CAN) o un caricamento del firmware può influenzare l'elaborazione dei dati nello smartIO interpellato. Non è possibile garantire che, per la durata della comunicazione, la velocità dati impostata o la cadenza di uscita dei messaggi CAN vengano rispettate esattamente!

Opzioni della riga di comando

Tramite le opzioni passate al programma dalla riga di comando è possibile richiamare impostazioni e funzioni obbligatorie e facoltative.

Short	Long	Parametro	Descrizione	Esempio
-h	--help		Visualizza le opzioni della riga di comando	-h
-p	--port	`<str>`	Obbligatorio: nome della porta CAN per stabilire la connessione ad es. `can0`, `can1`, `can2`, ...	-p can1
-B	--baud	`<uint>[k]`	Impostazione del baud rate; la lettera k può essere usata per la scala $\cdot 1000$	-B 500k
-G	--gpio	`<uint>`	Imposta il GPIO per attivare l'hardware CAN auto: automatico in base al tipo di dispositivo e alla porta `0x<c><p><l>`: con codifica per chip IO `<c>`, pin IO `<p>` e logica `<l>`, ad es. 0x251 - chip 2, pin 5, logic 1	-G auto
-U	--utc	`<uint>`	CAN id per il broadcast dell'ora UTC (def.: 0x10) disattivato: 0x0	-U 0x10
-T	--txid	`<uint>`	Canale ISO-TP+ verso lo smartIO (def.: 0x11)	-T 0x11
-R	--rxid	`<uint>`	Canale ISO-TP+ dallo smartIO (def.: 0x12)	-R 0x12
-d	--dump	`<uint>`	Scrive i messaggi CAN nel library-log, maschera di bit combinata con OR di 0x0001: inviati 0x0010: ricevuti, interpretati 0x0020: ricevuti, sconosciuti 0x0100: ISO-TP 0x0200: ISO-TP, estensione 0x0400: broadcast dell'ora UTC	-d 0xF00
-E	--liblog	`<str>`	Scrive i messaggi della libreria in questo file (invece di cout/cerr)	-E smiocan.log
-e	--liblevel	`<str>`	Soglia di uscita per i messaggi, 0..7 ovvero DEBUG, DUMP, SCPI, SYSTEM, INFO, WARNING, ERROR, FATAL	-e DUMP
-D	--devlog	`<str>`	Registro delle uscite del dispositivo e dei comandi SCPI	-D device.log
-Q	--query		Interroga e visualizza tutti i sistemi smartIO ESP sul bus CAN selezionato
-k	--pwkey	`<uint>`	Password-key per stabilire (automaticamente) la connessione ai dispositivi elencati	-k 123456
-H	--hello	`<serno> <pwkey>`	Apre la connessione al dispositivo con numero di serie e password-key¹ Indicazione multipla possibile	-H 24006200025 123456
-c	--command	`<str>`	Aggiunge un comando all'elenco dei comandi Indicazione multipla possibile	-c "*idn?"
-s	--script	`<str>`	Invia i comandi dal file di script	-s batch.txt
-x	--xfwimage	`<str>`	Sequenza estesa per l'aggiornamento automatizzato del firmware del dispositivo	-x newFW.bin
-i	--interactive		Avvia la modalità interattiva per la configurazione del dispositivo

Per l'esecuzione delle sequenze di comandi vale il seguente ordine:

Tutti i comandi definiti con -c
Tutti i comandi del file di script / batch indicato con -s
La sequenza di comandi per l'aggiornamento del firmware -x
Passaggio alla modalità interattiva -i

Comandi di esecuzione

In modalità interattiva e negli script è possibile usare commenti dopo // nelle singole righe.

Tutti i comandi dell'opzione -c, del file di script -s o della modalità interattiva vengono inviati allo smartIO come comando SCPI, a meno che non appartengano all'insieme di comandi riservati elencato di seguito:

Comando	Parametro	Descrizione
help		Mostra i comandi di esecuzione disponibili con relativa descrizione
quit		Chiude la connessione e termina l'applicazione
query		Esegue l'interrogazione dei dispositivi, come '-Q'
open	`[<serno> [<pwkey>]]`	Apre uno specifico smartIO, come '-H', i parametri omessi vengono completati con il valore usato in precedenza.
select	`(help/[:<term>:])`	Interrogazioni di selezione sulla risposta del dispositivo a `idn?`, help* può essere eseguito solo se esiste una connessione a un dispositivo.
close	`[<serno>]`	Chiude la connessione corrente o una connessione specifica
next		Stabilisce la connessione al dispositivo successivo elencato ('-Q', '-H').
reset	`[<serno>]`	Esegue un RESET su tutti i dispositivi smartIO o su un dispositivo specifico.
upload	`<path> [<mode>]`	Carica una nuova immagine firmware sul dispositivo e per mode = flash: solo flash active: flash e attivazione auto: flash, attivazione e reset (def.)
sleep	`<uint>`	Ritarda l'ulteriore esecuzione del tempo definito in millisecondi, ad es. per un riavvio del dispositivo avviato
filter	`[:<code>:]`	Elenco di filtri per le uscite di debug

Telegramma dell'ora UTC

Durante l'accesso amministrativo al dispositivo è opportuno impostare correttamente l'ora del dispositivo. Ciò avviene automaticamente tramite il telegramma dell'ora UTC, che smiocan distribuisce periodicamente a tutti gli smartIO dopo l'avvio, dapprima 10 volte al secondo, poi una volta al minuto. Impostando l'ID del telegramma a 0 la funzione viene disattivata.

Modalità interattiva

In modalità interattiva è possibile inviare direttamente allo smartIO comandi SCPI per interrogare e impostare le funzioni del dispositivo. Ciò corrisponde, ad eccezione della funzione di modifica e della cronologia non disponibili nella riga di comando, all'interfaccia terminale tramite la connessione USB.

A tale scopo i comandi vengono inviati allo smartIO come blocco tramite l'interfaccia ISO-TP+ al termine dell'inserimento della riga. La risposta viene raccolta nel dispositivo e rinviata in blocco a smiocan. Per questo motivo comandi SCPI speciali, come ad es. *REPeat, che generano un'uscita continua nel terminale, non sono ammessi tramite questa interfaccia.

Il prompt della riga di comando contiene l'interfaccia CAN utilizzata e lo stato della connessione (se non connesso) oppure il numero di serie e la versione del firmware del dispositivo selezionato.

Un esempio¹ di interrogazione e impostazione interattiva del tipo di misura e del campo di misura di un modulo smartIO 8x24:

root@smartrail-8037:~# smiocan -p can1 -H 24006200011 123456 -i
can1[24006200011,1.35]: *idn?
optiMEAS, smartIO, 8X24, 1, 24006200011, 1.35, 0, Dec  5 2024 13:52:28, 202400301
can1[24006200011,1.35]: adc:cur? all
0: 0
1: 0
2: 0
3: 0
4: 0
5: 0
6: 0
7: 0
can1[24006200011,1.35]: adc:cur 4, 1; adc:cur 5,1
OK
OK
can1[24006200011,1.35]: adc:cur? all
0: 0
1: 0
2: 0
3: 0
4: 1
5: 1
6: 0
7: 0
can1[24006200011,1.35]: adc:gai? all
0: 1
1: 1
2: 1
3: 1
4: 1
5: 1
6: 1
7: 1
can1[24006200011,1.35]: adc:gai 1,8; adc:gai 3,4; adc:gai 6,8
OK
OK
OK
can1[24006200011,1.35]: adc:gai? all
0: 1
1: 8
2: 1
3: 4
4: 1
5: 1
6: 8
7: 1
can1[24006200011,1.35]: close
can1[csDisabled]: quit
root@smartrail-8037:~#

Selezione dei dispositivi per l'amministrazione "select"

Non appena, dalla riga di comando, vengono selezionati più dispositivi smartIO o tutti tramite -Q e -k oppure -H, i comandi definiti o il file di script vengono applicati uno dopo l'altro a tutti i dispositivi. Ne deriva la necessità di restringere nuovamente, tramite un filtro, i dispositivi da amministrare, ad es. in base al numero di serie, alla versione del firmware o alla data di produzione.

A tale scopo il comando select esegue dapprima un'interrogazione *idn? sul dispositivo. La risposta potrebbe avere il seguente aspetto:

optiMEAS, smartIO, 8X24, 1, 24006200011, 1.35, 0, Dec 5 2024 13:52:28, 202400301

I singoli campi dati della risposta vengono associati come segue:

Key	Value	Tipo	Descrizione
comp	`optiMEAS`	`<str>`	Produttore
fwd	`Dec 5 2024 13:52:28`	`<datetime>`	Data del firmware
fwv	`1.35`	`<float>`	Versione del firmware
hwv	`0`	`<float>`	Versione dell'hardware
model	`8X24`	`<str>`	Denominazione del modello
prod	`202400301`	`<datetime>`	Data di produzione
serno	`24006200011`	`<uint>`	Numero di serie
type	`smartIO`	`<str>`	Famiglia/tipo di dispositivo
var	`1`	`<uint>`	Variante del dispositivo

Il comando select riceve ora un elenco di singoli argomenti, da separare tra loro con spazio o tabulazione.

Se il primo argomento è help, viene emessa come aiuto l'associazione della risposta del dispositivo attualmente disponibile insieme alla sintassi qui descritta.

can1[24006200011,1.35]: select help
optiMEAS, smartIO, 8X24, 1, 24006200011, 1.35, 0, Dec  5 2024 13:52:28, 202400301
select [:<terms>:]
Process the <terms> list finding a positive decision to continue the script.
Therefore <terms> are implicitly connected with && (AND) unless an || (OR) is placed.
If the condition fails, the command sequence is terminated and execution is restarted
on the next device
The command first request the device idn-string and parses it for its components:
 e.g.:   'optiMEAS, smartIO, 8X24, 1, 24006200011, 1.35, 0, Dec  5 2024 13:52:28, 202400301'
 <key> = <value>                interpreted as...
 -----   ----------------       -----------------
 comp    'optiMEAS'             <string>
 fwd     'Dec  5 2024 13:52:28' <date[time]>
 fwv     '1.35'                 <float>
 hwv     '0'                    <float>
 model   '8X24'                 <string>
 prod    '202400301'            <date[time]>
 serno   '24006200011'          <unsigned int>
 type    'smartIO'              <string>
 var     '1'                    <unsigned int>
A term is either
  - of the format <key> <op> <value> (use always white space as sep!)
  - a single '||' to logically OR the implicit &&-sequences
  - a single '&&' which is ignored being the default link of the comparing terms anyhow.
For strings           <op> is one of '==', '!=', value is a case insensitive regular expression
For all numeric types <op> is one of '<' '<=' '==' '!=' '>=' '>', value is of same type as key
Valid <date> formats are any of: 'Oct 28 2024', '10/28/2024', '28.10.2024', '2024-10-28', '20241028'
Valid optional time extensions are: '<date> 13:29:37', '<date> 132937', '<date> 13:29', '<date> 1329'

Un argomento può essere un operatore booleano && (AND) oppure || (OR). L'operatore || collega i termini concatenati con && (forma normale disgiuntiva).

Tre argomenti consecutivi formano termini per confronti di valori, che restituiscono un risultato booleano (false/true). Un tale termine ha sempre la seguente struttura:

<term> := <key> <op> <value>

È possibile elencare più termini uno dopo l'altro. In tal caso i singoli risultati vengono collegati implicitamente con &&, se non è indicato alcun operatore booleano.

La chiave <key> è da ricavare dalla tabella sopra riportata (o dall'aiuto) ed è il segnaposto per il valore corrispondente dell'interrogazione *idn?.

Per il tipo di dati <str> come operatore <op> sono ammessi esclusivamente gli operatori di confronto == (uguale) e != (diverso). <value> viene interpretato come espressione regolare² (case-insensitive), da racchiudere tra virgolette.

Per tutti gli altri tipi di dati sono ammessi i consueti operatori <, <=, ==, !=, >= e > e <value> corrisponde al tipo di dati della chiave.

Le date valide sono: Oct 28 2024, 10/28/2024, 28.10.2024, 2024-10-28 e 20241028, che dopo uno spazio possono essere completate facoltativamente da un'indicazione oraria della forma 13:29:37, 132937, 13:29 o 1329. Se questa indicazione di data o ora contiene a sua volta uno spazio, va racchiusa tra virgolette.

Non appena il risultato dei confronti e degli operatori booleani fornisce un esito univoco, in caso di true viene eseguito il comando successivo della sequenza di comandi, in caso di false l'esecuzione della sequenza di comandi viene interrotta e la connessione al dispositivo viene chiusa. Viene quindi stabilita la connessione con lo smartIO successivo trovato (-Q) o elencato (-H), per eseguire di nuovo la stessa sequenza di comandi. Concatenando più comandi select è possibile restringere sempre di più la selezione per l'amministrazione.

Esempi di istruzioni select:

// alle Geräte mit Firmware-Version vor 1.3
select fwv < 1.3

// alle Geräte mit 8 Kanälen und Produktionsdatum vor Juni 2024
select model == "8x.*" prod < 20240601

// alle "smartIO" mit Hardwareversion ab 2 oder Firmware ab 1.60
select type == "smartIO"
select hwv >= 2 || fwv >= 1.6

Aggiornamento del firmware del dispositivo "-x, --xfwimage"

Per installare un nuovo firmware su un dispositivo smartIO sono necessari, da un lato, la nuova immagine firmware, fornita sotto forma di file *.bin e memorizzata ad es. sulla scheda SD esterna o sull'unità temporanea, dall'altro una connessione CAN stabile al dispositivo. La trasmissione del firmware viene monitorata, in modo che software incompleto, difettoso o non validato non possa essere installato sul dispositivo. Poiché tuttavia la trasmissione può richiedere alcuni minuti, è opportuna una connessione stabile.

Durante la trasmissione, il restante funzionamento di misura e la comunicazione tramite il bus CAN possono proseguire. Tutte le impostazioni del dispositivo e la calibrazione di fabbrica restano invariate dopo l'aggiornamento, a meno che, per modifiche dell'insieme di funzioni del nuovo firmware, alcune impostazioni diventino superflue o vengano implementate in altra forma.

Si raccomanda di registrare la comunicazione con i singoli dispositivi per l'aggiornamento del firmware in un file di log, ad es. -D fwUpdate.log

Con l'opzione -x o --xfwimage viene eseguita la seguente sequenza di comandi per installare il firmware sul dispositivo e registrare le informazioni di stato prima e dopo il processo di aggiornamento:

*idn?
update:info?
system:admin 1,<pwkey>
upload "<path>" active
update:info?
reset <serno>
sleep 1500
open
update:info?
close            // only non-interactive mode
next            // only non-interactive mode

Esempi applicativi

Aggiornamento del firmware per tutti i dispositivi

L'esempio installa una nuova immagine firmware theNewFirmwareImage.bin su tutti i dispositivi sul bus CAN can1 e registra il risultato nel file fwUpdate.log

smiocan -p can1 -Q -k 123456 -D fwUpdate.log -x theNewFirmwareImage.bin

Configurazione per sensori individuali

Per uno smartIO 8x24 viene preparato un file commentato per la configurazione delle impostazioni dei canali e del bus CAN. Per garantire che questo file venga applicato esclusivamente al sistema montato nel quadro elettrico, all'inizio viene verificato il numero di serie.

I commenti contengono indicazioni sui campi di misura, sulla linearizzazione o anche sulle denominazioni o sui numeri di serie dei sensori collegati.

Contenuto del file config_target24006200011.txt:

// no other device!
select serno == 24006200011

// Clear all channel settings
adc:cur all, 0        // Voltage mode
adc:gai all, 1        // Gain 1         -> +-160V
adc:pol all, 0        // no linearization
adc:uni all, -        // use default units 'V', 'mA'

// [0] channel 1: Voltage +-10V, no linearisation
adc:cur 0, 0; adc:gai 0, 16

// [1] channel 2: Volumetric Sensor, Voltage +-10V, 
// linearization from datasheet: V = 0.5 u^2 + 3.16 u - 0.889
adc:cur 1, 0; adc:gai 1, 16; adc:pol 1, 0.5, 3.16, 0.889; adc:uni 1, "m^3"

// [2] channel 3: Current, LEM connector, 400 A at 150 mA
// scale := 400 A/150 mA = 2.6667 A/mA, offset := 0
adc:cur 2, 1; adc:gai 2,  1; adc:pol 2, 2.6667, 0; adc:uni 2, "A"

// [3] channel 4: Current, LEM connector, 1500 A at 100 mA
// scale := 15.0 A/mA, offset := 0
adc:cur 3, 1; adc:gai 3,  2; adc:pol 3, 15.0, 0; adc:uni 3, "A"

// [4] channel 5: High Voltage, 0 .. 5V -> 10 .. 25 kV 
// scale := 5.0 kV/V, 
// offset at 0 V-input := 10.0 kV
adc:cur 4, 0; adc:gai 4, 32; adc:pol 4, 5.0, 10.0; adc:uni 4, "kV"

// [5] channel 6: Pressure Sensor, 4 .. 20mA -> 0 .. 25 hPa 
// scale := 25 hPa/16 mA = 1.5625 hPa/mA, 
// offset at 0 mA-input := -4 mA * scale = -6.25 hPa
adc:cur 5, 1; adc:gai 5, 8; adc:pol 5, 1.5625, -6.25; adc:uni 5, "hPa"

// Filter Settings:
adc:tau 0.05

// Default (factory) Setup for CAN Messages
can:fac 0x636C7246

// Query and Log settings:
adc:cur? all
adc:gai? all
adc:pol? all
adc:uni? all
adc:tau?
can:msg? all

Trasferimento del file di configurazione al dispositivo:

smiocan -p can1 -H 24006200011 123456 -D devConfig.log -s config_target24006200011.txt

La password-key è disponibile su richiesta presso optiMEAS e va trattata in modo riservato. La key può essere modificata in un secondo momento. ↩ ↩²
Un utile strumento per la costruzione di espressioni regolari si trova qui. ↩

Configurazione dei moduli smartIO tramite CAN​

Opzioni della riga di comando​

Comandi di esecuzione​

Telegramma dell'ora UTC​

Modalità interattiva​

Selezione dei dispositivi per l'amministrazione "select"​

Aggiornamento del firmware del dispositivo "-x, --xfwimage"​

Esempi applicativi​

Aggiornamento del firmware per tutti i dispositivi​

Configurazione per sensori individuali​

Footnotes​