smiocan

Konfiguration von smartIO Modulen über CAN

Im allgemeinen werden smartIO Module über die eingebaute USB Schnittstelle programmiert und konfiguriert. Die Programmierung erfolgt mit geeigneten Werkzeugen in der Produktion, die Konfiguration mittels optiCONTROL oder einem Terminalprogramm.

Für die auf einem ESP Controller basierende smartIO Gerätefamilie sind diese Funktionen nun auch im Prozessfeld über den CAN-Bus verfügbar. Dazu dient das Hilfsprogramm

smiocan <options>

das über die Kommandozeile im Yocto verfügbar ist. Das Programm erwartet eine socket-CAN Schnittstelle und ist somit auch für andere Linux-Distributionen auf Anfrage verfügbar.

Es kann und darf zeitgleich immer nur eine administrative Verbindung zum Gerät aufgebaut werden! Der Verbindungsaufbau ist über ein Seed-Key-Verfahren und den Geräte Password-Key geschützt, sodass zumindest die beteiligten Software-Komponenten validiert werden können.

Jeder administrative Eingriff über SCPI (Seriell-USB oder CAN) oder ein Firmware-Upload kann die Datenverarbeitung im angesprochenen smartIO beeinflussen. Es kann nicht garantiert werden, dass für die Dauer der Kommunikation die eingestellte Datenrate oder Ausgabetakte für CAN Botschaften exakt eingehalten werden!

Optionen auf der Kommandozeile

Über Optionen, die dem Programm in der Kommandozeile übergeben werden, sind verpflichtende, aber auch optionale Einstellungen und Funktionen aufrufbar.

Short	Long	Parameter	Beschreibung	Beispiel
-h	--help		Ausgabe der Kommandozeilen-Optionen	-h
-p	--port	`<str>`	Verpflichtend: CAN-Port-Name zum Aufbau der Verbindung z.B. `can0`, `can1`, `can2`, ...	-p can1
-B	--baud	`<uint>[k]`	Einstellung der Baudrate, der Buchstabe k kann für die Skalierung $\cdot 1000$ verwendet werden	-b 500k
-G	--gpio	`<uint>`	Setzte GPIO, um CAN Hardware einzuschalten auto: automatisch mit Bezug auf Gerätetyp und Port `0x<c><p><l>`: mit Kodierung für IO-Chip `<c>`, IO-Pin `<p>` und Logik `<l>`, z.B. 0x251 - chip 2, pin 5, logic 1	-G auto
-U	--utc	`<uint>`	CAN id für UTC Zeit-Broad-Cast (def.: 0x10) disabled: 0x0	-U 0x10
-T	--txid	`<uint>`	ISIO-TP+ Kanal zum smartIO (def.: 0x11)	-T 0x11
-R	--rxid	`<uint>`	ISO-TP+ Kanal vom smartIO (def.: 0x12)	-R 0x12
-d	--dump	`<uint>`	Dump CAN Botschaften ins library-log, ver-ODER-te Bitmaske von 0x0001: gesendet 0x0010: empfangen, interpretiert 0x0020: empfangen, unbekannt 0x0100: ISO-TP 0x0200: ISO-TP, Erweiterung 0x0400: UTC Zeit-Broad-Cast	-d 0xF00
-E	--liblog	`<str>`	Ausgabe der Bibliotheksmeldungen in diese Datei (statt cout/cerr)	-E smiocan.log
-e	--liblevel	`<str>`	Ausgabeschwelle für Meldungen, 0..7 bzw. DEBUG, DUMP, SCPI, SYSTEM, INFO, WARNING, ERROR, FATAL	-e DUMP
-D	--devlog	`<str>`	Protokoll der Geräteausgaben und SCPI-Befehle	-D device.log
-Q	--query		Abfrage und Ausgabe aller smartIO ESP Systeme am gewählten CAN-Bus
-k	--pwkey	`<uint>`	Passwort-Key zum (automatischen) Aufbau der Verbindung zu den aufgeführten Geräten	-k 123456
-H	--hello	`<serno> <pwkey>`	Öffne Verbindung zum Gerät mit Seriennummer und Passwort-Key¹ Mehrfachangabe möglich	-H 24006200025 123456
-c	--command	`<str>`	Fügt einen Befehl zur Befehlsliste hinzu Mehrfachangabe möglich	-c "*idn?"
-s	--script	`<str>`	Sendet die Befehle aus der Script-Datei	-s batch.txt
-x	--xfwimage	`<str>`	Erweiterte Sequenz zum automatisierten Update der Geräte-Firmware	-x newFW.bin
-i	--interactive		Startet den interaktiven Modus zur Konfiguration des Gerätes

Für die Ausführung von Befehlssequenzen gilt folgende Reihenfolge:

Alle mit -c definierten Befehle
Alle Befehle aus der angegebenen Script / Batch-Datei -s
Die Befehlssequenz für das Firmware Update -x
Wechsel in den interaktiven Mode -i

Ablauf-Befehle

Im interaktiven Modus und im Script können Kommentare nach // in den einzelnen Zeilen verwendet werden.

Alle Befehle der Option -c, der Script-Datei -s oder im interaktiven Modus werden als SCPI-Befehl an das smartIO gesendet, sofern sie nicht zu dem im Folgenden aufgeführten reservierten Befehlssatz gehören:

Befehl	Parameter	Beschreibung
help		Zeigt die verfügbaren Ablauf-Befehle mit Beschreibung an
quit		Verbindung schließen und Anwendung beenden
query		Geräteabfrage ausführen, wie '-Q'
open	`[<serno> [<pwkey>]]`	Öffne ein bestimmtes smartIO, wie '-H', weggelassene Parameter werden durch den zuvor verwendeten Wert ergänzt.
select	`(help/[:<term>:])`	Auswahl-Abfragen auf die Geräte-Antwort `idn?`, help* kann nur ausgeführt werden, wenn die Verbindung zu einem Gerät besteht.
close	`[<serno>]`	Schließe die aktuelle oder eine bestimmte Verbindung
next		Baut die Verbindung zum nächsten gelisteten Gerät ('-Q', '-H') auf.
reset	`[<serno>]`	Führe einen RESET auf alle smartIO Geräte oder ein bestimmtes Gerät aus.
upload	`<path> [<mode>]`	Lade ein neues Firmware-Image auf das Gerät und für mode = flash: nur flashen active: flashen und aktivieren auto: flashen, aktivieren und reset (Def.)
sleep	`<uint>`	Verzögere die weitere Ausführung um die definierte Zeit in Milli-Sekunden, z.B. für einen ausgelösten Geräte-Neustart
filter	`[:<code>:]`	Filter-Liste für Debug-Ausgaben

UTC Zeit-Telegramm

Während des administrativen Zugriffs auf das Gerät ist es sinnvoll, die Gerätezeit korrekt einzustellen. Dies geschieht automatisch über das UTC-Zeittelegramm, das von smiocan nach dem Start an alle smartIO periodisch verteilt wird, zunächst 10 mal im Sekundentakt, danach einmal in der Minute. Durch Setzen der Telegramm-ID auf 0 wird die Funktion abgeschaltet.

Interaktiver Modus

Im interaktiven Modus können direkt an das smartIO SCPI-Befehle zur Abfrage und zum Einstellen der Gerätefunktionen gesendet werden. Dies entspricht - bis auf die nicht verfügbare Editierfunktion und Historie in der Kommandozeile - der Terminal-Schnittstelle über die USB Verbindung.

Dazu werden die Befehle mit Abschluss der Zeileneingabe als Block über die ISO-TP+ Schnittstelle an das smartIO geschickt. Die Antwort wird dort gesammelt und im Block zurück an smiocan geschickt. Aus diesem Grund sind spezielle SCPI-Befehle, wie z.B. *REPeat, die eine fortlaufende Ausgabe im Terminal erzeugen, über diese Schnittstelle nicht zulässig.

Der Kommandozeilen-Prompt enthält die verwendete CAN-Schnittstelle sowie den Verbindungsstatus (falls nicht verbunden) oder die Seriennummer und Firmwareversion des gewählten Gerätes.

Ein Beispiel¹ für die interaktive Abfrage und Einstellung von Messart und Messbereich eines smartIO 8x24 Moduls:

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:~#

Geräteauswahl zur Administration "select"

Sobald über die Kommandozeile mittels -Q und -k oder -H mehrere/alle smartIO ausgewählt werden, werden die definierten Kommandos oder das Script-File nacheinander auf alle Geräte appliziert. Damit ensteht die Notwendigkeit, über ein Filter die zu administrierenden Geräte wieder einzuschränken, z.B. über die Seriennummer, den Firmware-Stand oder das Produktionsdatum.

Der Befehl select führt dazu zunächst eine *idn? Abfrage auf dem Gerät aus. Die Antwort könnte wie folgt aussehen:

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

Die einzelnen Datenfelder der Antwort werden wie folgt zugeordnet:

Key	Value	Typ	Beschreibung
comp	`optiMEAS`	`<str>`	Hersteller
fwd	`Dec 5 2024 13:52:28`	`<datetime>`	Firmware-Datum
fwv	`1.35`	`<float>`	Firmware-Version
hwv	`0`	`<float>`	Hardware-Version
model	`8X24`	`<str>`	Modellbezeichnung
prod	`202400301`	`<datetime>`	Produktionsdatum
serno	`24006200011`	`<uint>`	Seriennummer
type	`smartIO`	`<str>`	Gerätefamilie/-typ
var	`1`	`<uint>`	Gerätevariante

Der Befehl select bekommt nun eine Liste von einzelnen Argumenten, die durch Leerzeichen oder Tabulator voneinander zu trennen sind.

Falls das erste Argument help ist, wird die Zuordnung der aktuell verfügbaren Geräte-Antwort zusammen mit der hier beschriebenen Syntax als Hilfe ausgegeben.

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 beeing the default link of the comparing terms anyhow.
For strings           <op> is one of '==', '!=', value is a case insensitive regular expresion
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'

Ein Argument kann ein boolscher-Operator && (UND) oder || (ODER) sein. Dabei verbindet der ||-Operator die mit && verknüpften Terme (Disjunktive Normalform).

Drei aufeinanderfolgende Argumenten bilden Terme für Wertevergleiche, die ein boolsches Ergebnis (false/true) liefern. Ein solcher Term hat immer den folgenden Aufbau:

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

Mehrere Terme können nacheinander aufgeführt werden. Dabei werden die einzelnen Ergebnisse implizit mit && verknüpft, wenn kein boolscher Operator angegeben wird.

Der Schlüssel <key> ist der oben aufgeführten Tabelle (oder Hilfe) zu entnehmen und ist Platzhalter für den entsprechenden Wert aus der *idn? Abfrage.

Für den Datentyp <str> sind ausschließlich die Vergleichsoperatoren == (gleich) und != (ungleich) als Operator <op> zu verwenden. Dafür wird <value> als Regular-Expression² angesehen (case-insensitive), der in Anführungszeichen einzuschließen ist.

Für alle anderen Datentypen sind die üblichen Operatoren <, <=, ==, !=, >= und > zulässig und <value>entspricht dem Datentyp des Schlüssels.

Gültige Datumsangaben sind: Oct 28 2024, 10/28/2024, 28.10.2024, 2024-10-28 und 20241028, die nach einem Leerzeichen optional durch eine Zeitangabe der Form 13:29:37, 132937, 13:29 oder 1329 ergänzt werden können. Wenn diese Datums- oder Zeitangabe selbst ein Leerzeichen enthält, ist sie mit Anführungszeichen einzuschließen.

Sobald das Ergebnis der Vergleiche und boolschen Operatoren ein eindeutiges Ergebnis liefert, wird bei true der nächste Befehl der Kommandosequenz ausgeführt oder bei false die Ausführung der Kommandosequenz abgebrochen und die Verbindung zum Gerät geschlossen. Die Verbindung zum nächsten gefundenen (-Q) oder gelisteten (-H) smartIO wird aufgebaut, um die selbe Kommandosequenz erneut auszuführen. Durch die Reihung mehrerer select Befehle kann die Auswahl zur Administration immer weiter eingeschränkt werden.

Beispiele für select Anweisungen:

// 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 Harwareversion ab 2 oder Firmware ab 1.60
select type == "smartIO"
select hwv >= 2 || fwv >= 1.6

Update der Gerätefirmware "-x, --xfwimage"

Um neue Firmware auf ein smartIO Gerät aufzuspielen, ist zum einen das neue Firmware-Image erforderlich, das in Form eines *.bin-Files ausgeliefert und z.B. auf der externen SD-karte oder dem temporären Laufwerk zwischengespeichert wird, zum anderen eine stabile CAN Verbindung zum Gerät. Die Übertragung der Firmware wird überwacht, sodass unvollständige, fehlerhafte oder nicht validierte Software nicht auf dem Gerät installiert werden kann. Da jedoch die Übertragung einige Minuten in Anspruch nehmen kann, ist eine stabile Verbindung sinnvoll.

Während der Übertragung kann der übrige Messbetrieb und die Kommunikation über den CAN Bus weiterlaufen. Alle Geräteeinstellungen und die Werkskalibrierung bleiben nach dem Update erhalten, sofern nicht durch Änderungen im Funktionsumfang der neuen Firmware Einstellungen überflüssig oder in anderer Form implementiert werden.

Es wird empfohlen, die Kommunikation mit den einzelnen Geräten für den Firmware-Update in einer Log-Datei zu protokollieren, z.B. -D fwUpdate.log

Mit der Option -x oder --xfwimage wird folgende Kommandosequenz ausgeführt, um die Firmware auf das Gerät zu installieren und Statusinformation vor und nach dem Update-Vorgang zu protokollieren:

*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

Anwendungsbeispiele

Firmware-Update für alle Geräte

Das Beispiel bringt ein neues Firmware-Image theNewFirmwareImage.bin auf alle Geräte am CAN-Bus can1 und protokolliert das Ergebnis in der Datei fwUpdate.log

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

Konfiguration für individuelle Sensorik

Für ein smartIO 8x24 wird eine kommentierte Datei zur Konfiguration der Kanal und CAN-Bus Einstellungen vorbereitet. Um sicherzustellen, dass diese Datei ausschließlich auf dem im Schaltschrank montierten System appliziert wird, wird die Seriennummer am Anfang geprüft.

Die Kommentare enthalten Hinweise zu den Messbereichen, der Linearisierung oder auch Bezeichnungen oder Seriennummern der angeschlossenen Sensoren.

Inhalte der Datei 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.625, -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

Übertragen der Konfigurationsdatei an das Gerät:

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

Der Passwort-Key ist auf Anfrage bei optiMEAS erhältlich und vertraulich zu behandeln. Der Key kann nachträglich geändert werden. ↩ ↩²
Eine nützliches Werkzeug zum Aufbau von Regular-Expressions ist hier zu finden. ↩

Konfiguration von smartIO Modulen über CAN​

Optionen auf der Kommandozeile​

Ablauf-Befehle​

UTC Zeit-Telegramm​

Interaktiver Modus​

Geräteauswahl zur Administration "select"​

Update der Gerätefirmware "-x, --xfwimage"​

Anwendungsbeispiele​

Firmware-Update für alle Geräte​

Konfiguration für individuelle Sensorik​

Footnotes​