smiocan

Configuration of smartIO modules via CAN

In general, smartIO modules are programmed and configured via the built-in USB interface. Programming is carried out using suitable tools in production, configuration using optiCONTROL or a terminal program.

For the smartIO device family based on an ESP controller, these functions are now also available in the process field via the CAN bus. The auxiliary program

smiocan <options>

which is available via the command line in Yocto. The program expects a socket-CAN interface and is therefore also available for other Linux distributions on request.

Only one administrative connection to the device can and may be established at a time The connection is protected by a seed key procedure and the device password key, so that at least the software components involved can be validated.

Any administrative intervention via SCPI (serial USB or CAN) or a firmware upload can influence the data processing in the smartIO addressed. It cannot be guaranteed that the set data rate or output clocks for CAN messages will be maintained exactly for the duration of the communication!

Options on the command line

Mandatory and optional settings and functions can be called up via options that are passed to the program in the command line.

Short	Long	Parameter	Description	Example
-h	--help		Output of the command line options	-h
-p	--port	<str>	commit: CAN port name for establishing the connection e.g. can0, can1, can2, ...	-p can1
-B	--baud	<uint>[k]	Setting the baud rate, the letter k can be used for scaling $\cdot 1000$	-b 500k
-G	--gpio	<uint>	Set GPIO to switch on CAN hardware auto: automatically with reference to device type and port 0x<c><p><l>: with coding for IO chip <c>, IO pin <p> and logic <l>, e.g. 0x251 - chip 2, pin 5, logic 1	-G auto
-U	--utc	<uint>	CAN id for UTC time broadcast cast (def.: 0x10) disabled: 0x0	-U 0x10
-T	--txid	<uint>	ISIO-TP+ channel to smartIO (def.: 0x11)	-T 0x11
-R	--rxid	<uint>	ISO-TP+ channel from smartIO (def.: 0x12)	-R 0x12
-d	--dump	<uint>	Dump CAN messages into the library log, ORed bitmask of 0x0001: sent 0x0010: received, interpreted 0x0020: received, unknown 0x0100: ISO-TP 0x0200: ISO-TP, extension 0x0400: UTC time broadcast cast	-d 0xF00
-E	--liblog	<str>	Output of the library messages to this file (instead of cout/cerr)	-E smiocan.log
-e	--liblevel	<str>	Output threshold for messages, 0..7 resp. DEBUG, DUMP, SCPI, SYSTEM, INFO, WARNING, ERROR, FATAL	-e DUMP
-D	--devlog	<str>	Log of device outputs and SCPI commands	-D device.log
-Q	--query		Query and output of all smartIO ESP systems on the selected CAN bus
-k	--pwkey	<uint>	Password key for (automatically) establishing the connection to the listed devices	-k 123456
-H	--hello	<serno> <pwkey>	Open connection to device with serial number and password key1 Multiple entries possible	-H 24006200025 123456
-c	--command	<str>	Adds a command to the command list Multiple entries possible	-c "*idn?"
-s	--script	<str>	Sends the commands from the script file	-s batch.txt
-x	--xfwimage	<str>	Extended sequence for automated update of the device firmware	-x newFW.bin
-i	--interactive		Starts the interactive mode for configuring the device

The following sequence applies to the execution of command sequences:

1. All commands defined with `-c
2. All commands from the specified script / batch file -s
3. The command sequence for the firmware update -x
4. Switch to interactive mode -i

Sequence commands

In interactive mode and in the script, comments can be used after // in the individual lines.

All commands of the '-c' option, the '-s' script file or in interactive mode are sent to the smartIO as SCPI commands, unless they belong to the reserved command set listed below:

Command	Parameter	Description
help		Displays the available run commands with description
quit		Close connection and exit application
query		Execute device query, like '-Q'
open	[<serno> [<pwkey>]]	Open a specific smartIO, such as '-H', omitted parameters are supplemented by the previously used value.
select	(help/[:<term>:])	Selection queries on the device response *idn?, help can only be executed if the connection to a device exists.
close	[<serno>]	Close the current or a specific connection
next		Establishes the connection to the next listed device ('-Q', '-H').
reset	[<serno>]	Execute a RESET on all smartIO devices or a specific device.
upload	<path> [<mode>]	Upload a new firmware image to the device and for mode = flash: flash only active: flash and activate auto: flash, activate and reset (def.)
sleep	<uint>	Delay further execution by the defined time in milli-seconds, e.g. for a triggered device restart
filter	[:<code>:]	Filter list for debug outputs

UTC time telegram

During administrative access to the device, it is advisable to set the device time correctly. This is done automatically via the UTC time telegram, which smiocan distributes periodically to all smartIOs after the start, initially 10 times every second, then once a minute. The function is switched off by setting the telegram ID to 0.

Interactive mode

In interactive mode, SCPI commands can be sent directly to the smartIO to query and set the device functions. With the exception of the editing function and history in the command line, which are not available, this corresponds to the terminal interface via the USB connection.

To do this, the commands are sent to the smartIO as a block via the ISO-TP+ interface when the line input is complete. The response is collected there and sent back to smiocan as a block. For this reason, special SCPI commands, such as *REPeat, which generate a continuous output in the terminal, are not permitted via this interface.

The command line prompt contains the CAN interface used as well as the connection status (if not connected) or the serial number and firmware version of the selected device.

An example¹ for the interactive query and setting of the measurement type and measurement range of a smartIO 8x24 module:

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

Device selection for administration "select"

As soon as several/all smartIOs are selected via the command line using -Q and -k or -H, the defined commands or the script file are applied to all devices one after the other. This makes it necessary to use a filter to restrict the devices to be administered again, e.g. via the serial number, firmware version or production date.

The select command first executes a *idn? query on the device. The response could look like this:

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

The individual data fields of the response are assigned as follows:

Key	Value	Type	Description
comp	optiMEAS	<str>	Manufacturer
fwd	Dec 5 2024 13:52:28	<datetime>	firmware date
fwv	1.35	<float>	firmware version
hwv	0	<float>	hardware version
model	8X24	<str>	model name
prod	202400301	<datetime>	production date
serno	24006200011	<uint>	serial number
type	smartIO	<str>	device family/type
var	1	<uint>	device variant

The select command now receives a list of individual arguments, which are separated from each other by spaces or tabs.

If the first argument is help, the assignment of the currently available device response is output as help together with the syntax described here.

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 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'

An argument can be a Boolean operator && (AND) or || (OR). The || operator connects the terms linked with && (disjunctive normal form).

Three consecutive arguments form terms for value comparisons that return a Boolean result (false/true). Such a term always has the following structure:

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

Several terms can be listed one after the other. The individual results are implicitly linked with && if no Boolean operator is specified.

The key <key> can be taken from the table (or help) listed above and is a placeholder for the corresponding value from the *idn? query.

For the data type <str>, only the comparison operators == (equal) and != (not equal) are to be used as operator <op>. For this purpose, <value> is regarded as a regular expression² (case-insensitive), which must be enclosed in quotation marks.

For all other data types, the usual operators <, <=, ==, !=, >= and > are permitted and <value> corresponds to the data type of the key.

Valid dates are: Oct 28 2024, 10/28/2024, 28.10.2024, 2024-10-28 and 20241028, which can optionally be supplemented by a time specification of the form 13:29:37, 132937, 13:29 or 1329 after a space. If this date or time specification itself contains a space, it must be enclosed in quotation marks.

As soon as the result of the comparisons and Boolean operators provides a clear result, the next command in the command sequence is executed if true or the execution of the command sequence is aborted if false and the connection to the device is closed. The connection to the next found (-Q) or listed (-H) smartIO is established in order to execute the same command sequence again. By sequencing several select commands, the selection for administration can be narrowed down further and further.

Examples of select statements:

// all devices with firmware version before 1.3
select fwv < 1.3

// all devices with 8 channels and production date before June 2024
select model == "8x.*" prod < 20240601

// all "smartIO" with hardware version 2 or higher or firmware 1.60 or higher
select type == "smartIO"
select hwv >= 2 || fwv >= 1.6

Update the device firmware "-x, --xfwimage"

In order to install new firmware on a smartIO device, a new firmware image is required, which is delivered in the form of a *.bin file and stored temporarily on the external SD card or temporary drive, for example, and a stable CAN connection to the device. The transfer of the firmware is monitored so that incomplete, faulty or non-validated software cannot be installed on the device. However, as the transfer can take several minutes, a stable connection is advisable.

During the transfer, the rest of the measuring operation and communication via the CAN bus can continue. All device settings and the factory calibration are retained after the update, unless settings become superfluous or are implemented in a different form due to changes in the functional scope of the new firmware.

It is recommended to log the communication with the individual devices for the firmware update in a log file, e.g. -D fwUpdate.log.

With the -x or --xfwimage option, the following command sequence is executed to install the firmware on the device and to log status information before and after the update process:

*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

---

Application examples

Firmware update for all devices

The example applies a new firmware image theNewFirmwareImage.bin to all devices on the CAN bus can1 and logs the result in the file fwUpdate.log.

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

Configuration for individual sensors

A commented file for configuring the channel and CAN bus settings is prepared for a smartIO 8x24. To ensure that this file is only applied to the system installed in the control cabinet, the serial number is checked at the beginning.

The comments contain information on the measuring ranges, linearization or even designations or serial numbers of the connected sensors.

Contents of the 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 linearization
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

Transfer the configuration file to the device:

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

Footnotes

1. The password key is available on request from optiMEAS and must be treated confidentially. The key can be changed at a later date. ↩ ↩²

2. A useful tool for building regular expressions can be found here. ↩