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:

IOBus Server Webinterface - List of nodes

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:

IOBus Server Webinterface - Node controls

The IOBus Server node control interface

Toggling between Ethernet output port A and B is done by clicking the SW button in the interface.

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:

IOBus Server Webinterface - Active Locator

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 prefered 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:

Internal connector P101 pinout

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

Internal connector P102 pinout

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.