Operation¶
Software¶
Note
Make sure you have installed the control software as described in Software Commissioning.
This chapter should give you a general overview of the lxa-iobus-server
software and how it may be integrated into your workflows.
A more in-depth documentation is provided in the lxa-iobus-server
handbook.
The lxa-iobus-server provides a gateway between the CAN-based
IOBus communication protocol for use with lab devices and a
HTTP REST-based protocol for communication with test-automation software.
Running the Server¶
For basic operation the lxa-iobus-server can be started from
the commandline, supplying the name of a CAN interface as the
only parameter:
$ lxa-iobus-server can0
starting server on http://localhost:8080/
Web Interface Usage¶
Once started the server should start enumerating devices connected to the bus. Visit the IOBus Server webinterface at http://localhost:8080/ for a list of detected IOBus devices:
List of nodes in the IOBus Server webinterface¶
More options to control a particular node are available by clicking on a line in the list:
The IOBus Server node control interface¶
Toggling between Ethernet output port A and B is done by clicking the SW button in the interface.
Setting the SW button to the activated state configures a connection of the IN connector of the Ethernet-Mux to the OUT A connector. Setting the SW button to the deactivated state configures a connection of the IN connector of the Ethernet-Mux to the OUT B connector.
Toggling the Locator LED, that can be used to find a particular device in a lab, is done by clicking the Locator button in the interface. The Locator indicator can also be used in the opposite direction, as pushing the locator button on the Ethernet-Mux also toggles the state of the on-board LED and the one shown in the web interface:
List of nodes. Device “00005.00009” has an active Locator.¶
REST Interface Usage¶
The actions available through the web interface can alternatively be performed programmatically using the REST api provided by the server:
# Get a list of available nodes:
$ curl http://localhost:8080/nodes/
{"code": 0, "error_message": "", "result": ["Ethernet-Mux-00003.00020"]}
# Get a list of pins on a device:
$ curl http://localhost:8080/nodes/Ethernet-Mux-00003.00020/pins/
{"code": 0, "error_message": "", "result": ["SW", "SW_IN", "SW_EXT", "AIN0", "VIN"]}
# Get the current status of a pin:
$ curl http://localhost:8080/nodes/Ethernet-Mux-00003.00020/pins/SW/
{"code": 0, "error_message": "", "result": 0}
# Set the status of a pin:
$ curl -d "value=0" -X POST http://localhost:8080/nodes/Ethernet-Mux-00003.00020/pins/SW/
{"code": 0, "error_message": "", "result": null}
# Toggle the Locator LED:
$ curl -X POST http://localhost:8080/nodes/Ethernet-Mux-00003.00020/toggle-locator/
{"code": 0, "error_message": "", "result": null}
Tool Integration¶
The labgrid project has support for the Ethernet-Mux. The switch of the device shown above can be exposed as a labgrid resource using a piece of configuration like this:
LXAIOBusPIO:
host: localhost:8080
node: Ethernet-Mux-00002.00020
pin: SW
invert: False
See labgrid’s documentation for more details.
Direct IOBus Protocol Interaction¶
The lxa-iobus-server, as described above, is the preferred method of
communication with IOBus nodes.
An alternative means of communication is by directly sending bare
CAN packets on the bus.
This can, for example, be achieved using the cansend command,
that may be installed using sudo apt install can-utils on a
Debian based Linux distribution.
Warning
The IOBus protocol, as demonstrated below, is not a stable API.
Be prepared to adapt custom implementations to changes made
in the node firmwares and the lxa-iobus-server.
# Configure the CAN-Interface bitrate
$ sudo ip link set can0 type can bitrate 100000
# Set the interface to the "up" state
$ sudo ip link set can0 up
# Set all devices on the bus to the configuration mode
$ cansend can0 "7e5#0401000000000000"
# ^^------------- Mode 1 (Configuration)
# ^^--------------- Command 4 (Switch mode global)
# ^^^------------------ CAN Message ID 2021
# Configure a node id for the IOBus device
$ cansend can0 "7e5#1101000000000000"
# ^^------------- New node ID 1
# ^^--------------- Command 17 (Configure node ID)
# ^^^------------------ CAN Message ID 2021
# Set all devices on the bus to the operation mode
$ cansend can0 "7e5#0400000000000000"
# ^^------------- Mode 0 (Operation)
# ^^--------------- Command 4 (Switch mode global)
# ^^^------------------ CAN Message ID 2021
# Deactivate the IOBus watchdog
# (If the watchdog is active the node will reset it's node ID when
# it is not addressed (e.g. read a value) once every 30 seconds.)
$ cansend can0 "601#23062d0100000000"
# ^^^^^^^^- Value 0 (0: Deactivate, 1: Activate)
# ^^--------- Sub Index 1
# ^^^^----------- Index 0x2d06
# ^^--------------- Command/Length/Type³ 0x23
# ^^^------------------ CAN ID⁴ 0x601
# Switch the Ethernet-Mux to Output B
$ cansend can0 "601#230021020100ffff"
# ^^^^- Output mask¹ 0xffff
# ^^^^----- Output state² 0x0001
# ^^--------- Sub Index 2
# ^^^^----------- Index 0x2100
# ^^--------------- Command/Length/Type³ 0x23
# ^^^------------------ CAN ID⁴ 0x601
#
# ¹: 0xffff = 0b1111111111111111
# ^^^^^^^^^^^^^^^^----- Output 1-16 Are written
#
# ²: 0x0001 = 0b0000000000000001
# ^----- Output 1 High
# ^^^^^^^^^^^^^^^------ Output 2-16 Low (Ignored due to masking)
#
# ³: 0x23 = 0b00100011
# ^^--------------- Type 3
# ^^^----------------- Length 0 (4 - LENGTH_BYTES)
# ^^^-------------------- Command 1
#
# ⁴: 0x601 = 0x600 | 0x001
# = BASE_ADDR | NODE_ADDR
# Switch the Ethernet-Mux to Output A
$ cansend can0 "601#230021020000ffff"
# ^^^^- Output mask 0xffff
# ^^^^----- Output state⁵ 0x0000
# ^^--------- Sub Index 2
# ^^^^----------- Index 0x2100
# ^^--------------- Command/Length/Type 0x23
# ^^^------------------ CAN ID 0x601
#
# ⁵: 0x0000 = 0b0000000000000000
# ^----- Output 1 Low
# ^^^^^^^^^^^^^^^------ Output 2-16 Low (Ignored due to masking)
Warning
The commands above assume a single node on the bus, as the first two CAN packets would otherwise configure all nodes on the bus to share a single node id. A configuration of multiple nodes may be performed using LSS Fastscan.
Control via GPIO¶
To use the GPIO-based control interface you need to open the
Ethernet-Mux enclosure and identify connectors P101 and
P102 on the PCB. The pinout of these connectors is:
Pin Number |
Name |
Internal Function |
|---|---|---|
1 |
CAN |
Select CAN-based control |
2 |
‐ |
Connect to either Pin 1 or 3 for selection |
3 |
Manual |
Select GPIO-based control |
Pin Number |
Name |
Internal Function |
|---|---|---|
1 |
12V |
Power Supply |
2 |
GND |
Connected to system GND |
3 |
IN |
3.3V logic-level control input |
4 |
GND |
Connected to system GND |
The GPIO-based interface is enabled by disconnecting Pins 1 and 2
of the P102 connector and connecting Pins 3 and 2 instead.
The active output is now selected by pulling the IN in low
or leaving it floating/driving it high.
The IN pin contains an internal pull-up
and is designed to be tolerant to a wide range of input voltages.
Input voltages between -12V and 0V select upstream port A,
input voltages between 3V and 12V,
or a floating input,
select upstream port B.
Note
The supply voltage may either be applied between the 12V
and GND pins on connector P102 or to the corresponding
Pins on the D-Sub 9 connector.