Commissioning
This chapter describes how to use the LXA IOBus 4DO-3DI-3AI with control via the CAN interface.
Prepare your host system
Note
This manual refers to v0.2 of the lxa-iobus control software.
Software Installation
This quickstart guide clones the upstream git repository to install the
control software.
This is the recommended way to setup the control software since some
files from the contrib-directory are needed later during setup.
Alternatively it is possible to install the lxa-iobus package from
pypi.
Clone the git repository:
$ git clone https://github.com/linux-automation/lxa-iobus.git
$ cd lxa-iobus
Create and activate a virtualenv for lxa-iobus:
$ python3 -m venv venv
$ source venv/bin/activate
Install lxa-iobus-server into the virtualenv:
$ python3 -m pip install -e.[full]
You can now run the
lxa-iobus-servercommand with the--helpargument to test the installation:
$ lxa-iobus-server --help
usage: lxa-iobus-server [-h] [--port PORT] [--host HOST] [--shell]
[--firmware-directory FIRMWARE_DIRECTORY]
[--lss-address-cache-file LSS_ADDRESS_CACHE_FILE]
[-l {DEBUG,INFO,WARN,ERROR,FATAL}]
interface
...
Have a look at the section Hardware Preparations.
to learn how to setup a basic CAN-/IObus-network to connect your
LXA IOBus 4DO-3DI-3AI to the lxa-iobus-server.
CAN Setup
On startup the lxa-iobus-server expects a CAN network interface
that is pre-configured to work with IOBus devices.
For some CAN interfaces it is sufficient to place a configuration
file at /etc/systemd/network/80_can0.network containing the
following information:
[Match]
Name=can0
[CAN]
BitRate=100000
FDMode=False
RestartSec=10s
After rebooting the system the can0 interface should now
be configured to operate at a bitrate of 100kBits/s:
$ ip --details link show can0
8: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc pfifo_fast state UP mode DEFAULT group default qlen 10
link/can promiscuity 0 minmtu 0 maxmtu 0
can state ERROR-ACTIVE restart-ms 0
bitrate 100000 sample-point 0.875
tq 625 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1
gs_usb: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..1024 brp-inc 1
clock 48000000 numtxqueues 1 numrxqueues 1 gso_max_size 65536 gso_max_segs 65535
Warning
If you see a much smaller value than 625 for the tq
parameter you may be susceptible to an issue where your CAN bus is
very intolerant to bitrate offsets.
See Bitrate-Intolerant CAN Bus for more
information.
Hardware Preparations
Bus and Power Setup
The LXA IOBus 4DO-3DI-3AI connector labeled “CAN” is used to connect the LXA IOBus 4DO-3DI-3AI to the CAN bus and the power supply.
The following figure shows a minimum CAN-Bus Setup that can be used to operate a single LXA IOBus 4DO-3DI-3AI:
Power Supply ╭───────────────────────╮
╭───────╮ │ LXA IOBus 4DO-3DI-3AI │
│ 12V │ ├───────────────────────┤
│ 500mA ┝╾──╮ │ ╭╼┿╾ Out 0
│ PSU │ │ │ ╰╼┿╾ Out 0
╰───────╯ │ │ ╭╼┿╾ Out 1
│ │ ╰╼┿╾ Out 1
│ │ ╭╼┿╾ Out 2
│ │ ╰╼┿╾ Out 2
│ │ ╭╼┿╾ Out 3
│ │ ╰╼┿╾ Out 3
│ ╭───╮ │ │
│ │120│ │ ┝╾ ADC in 0
│ │Ohm│ │╭─────────╮ ┝╾ ADC in 1
╭───────╮ │ ╰─┰─╯ ││ │ ┝╾ ADC in 2
│ CAN │ │ │ ││ IOBus │ │
│Adapter┝╾──┶━━━━━━━━━━━━┷━━━━┿┥ Control │ ┝╾ In 0
│ │ CAN & 12V ││ │ ┝╾ In 1
╰───────╯ over D-Sub9 │╰─────────╯ ┝╾ In 2
Test Server ╰───────────────────────╯
CAN structure for a single LXA IOBus 4DO-3DI-3AI on a short bus.
The 120Ω termination resistor is connected between CAN_H and CAN_L
and (for short buses) may be placed anywhere on the bus.
In this example the LXA IOBus 4DO-3DI-3AI is the only device on the CAN bus. The Test-Server is the host running the control application and is connected to the CAN bus.
Power for the LXA IOBus 4DO-3DI-3AI is provided by a 12V DC power supply. The power supply is connected to the power pins on the CAN bus.
A single 120Ω termination resistor, connecting the two CAN signal lines, is sufficient when the bus length is kept very short.
The following chapters give more information on how to build this minimum setup.
Pinout
The following figure shows the pinout of the D-Sub 9 connector on the LXA IOBus 4DO-3DI-3AI:
Pinout of the D-Sub 9 Pin connector looking from the outside onto the connector. (Public Domain, from: Wikimedia)
The connector uses the standard pinout for CAN on D-Sub 9 connectors, that is defined in the CANopen standard CiA-303-1 and is used throughout the automotive industry. The following table shows the pins connected inside the LXA IOBus 4DO-3DI-3AI.
Pin Number |
Name |
Internal Function |
|---|---|---|
1 |
‐ |
Not connected |
2 |
CAN_L |
CAN bus (negative) |
3 |
CAN_GND |
Connected to system GND |
4 |
‐ |
Not connected |
5 |
CAN_SHIELD |
Connected to C102, an 18pF capacitor to GND |
6 |
POWER_GND |
Connected to system GND |
7 |
CAN_H |
CAN bus (positive) |
8 |
‐ |
Not connected |
9 |
+12V |
Power Supply |
Pins marked as not connected are internally floating and can be used for other purposes on the bus.
Warning
Make sure the voltage on the power input stays within the safe 9V to 13V working range of the LXA IOBus 4DO-3DI-3AI. Higher voltages may damage the LXA IOBus 4DO-3DI-3AI. Lower voltages may lead to misbehavior.
Warning
Make sure the voltage on CAN_H and CAN_L never exceeds ±13V. Higher voltages may damage the LXA IOBus 4DO-3DI-3AI.
Note
The CAN transceiver will not work if the common mode voltage on the CAN_H and CAN_L lines exceeds ±5V relative to system GND.
Note
The LXA IOBus 4DO-3DI-3AI uses a fixed bitrate of 100 kBits/s for communication. Other bus nodes should allow for at least ±2% bitrate error. See Bitrate-Intolerant CAN Bus for an example of how this may cause issues with some CAN-interfaces and how to fix these issues.
Termination resistor and bus topology
Important
Especially in installations with multiple meters of cabling, a clear topology and termination are required for highly reliability.
A CAN bus should be designed as a single line with short stubs connecting the devices to the bus.
The CAN bus needs to be terminated properly. This is usually done using 120Ω resistors between CAN_H and CAN_L at both ends of the line, close to the last devices on the bus.
Experience has shown that very short buses (eg. shorter than 0.5m) can be realized with a single termination resistor on the bus and without a strict line topology.
Cabling
For longer distances an unshielded twisted-pair (UTP) cable with 120Ω differential impedance should be used for the CAN bus. For GND and power supply use wires with a sufficient cross section to keep the power supply and CAN bus common mode voltage in the ranges given above.
For short buses flat ribbon cables present a cheap and easy-to-install alternative to UTP cabling. Plugs and sockets are available from many manufacturers, for example L17DEFRA09P and L17DEFRA09S from Amphenol.
Connecting the DUT
Digital Outputs
The digital outputs are implemented using solid state relays, this makes them great replacements for situations where the functionality of a push-button or a jumper should be automated.
This design should also allows the automation of buttons that are part of a multiplexed keyboard matrix or multiple buttons connected to a single ADC input using a resistor ladder. The solid state relays and output circuitry do however add additional capacitive and resistive components, when compared to a simple push-button. We can thus not guarantee correct operation when switching modulated or analog signals.
Usage of the digital outputs is best explained using examples for the three most common usage scenarios:
How to use a LXA IOBus 4DO-3DI-3AI to drive a …
… jumper input
A jumper input consists of two pins on a 2.54mm pin header that are either electrically shorted using a jumper bridge or left open. Use two female-to-female 2.54mm pin header jumper cables and connect one to each pin of an output channel:
╭───────────────────────╮
│ LXA IOBus 4DO-3DI-3AI │ ╭────────────╮
├───────────────────────┤ Out 0 │ │
│ ╭╼┿╾────────╼┥ Device │
│ ╰╼┿╾────────╼┥ under test │
│ │ Out 0 │ │
┆ ┆ ╰────────────╯
… floating input
The LXA IOBus 4DO-3DI-3AI does not apply a voltage to its output pins, as it is designed as a replacement for jumpers and buttons. To apply defined voltages to an input pin of a DUT you may use external resistors acting as pull-ups or pull-downs:
╭───────────────────────╮ 3.3V╭─────────╮
│ LXA IOBus 4DO-3DI-3AI │ ╭─┨1kΩ┠────╼┥ │
├───────────────────────┤ Out 0 │ │ Device │
│ ╭╼┿╾──────────┴──────────╼┥ under │
│ ╰╼┿╾─────────────────────╼┥ test │
│ │ Out 0 GND│ │
┆ ┆ ╰─────────╯
Digital Inputs
The digital inputs are implemented using solid state relays, this makes them suitable for a variety of input voltages and also provides electrical isolation.
The solid state relays do however require some current to operate.
The examples below show two example uses for the inputs.
How to use a LXA IOBus 4DO-3DI-3AI to monitor a …
… DUT output pin
Output pins that operate at logic levels between 1.8V and 10V and can source a couple of milli-amperes can be connected directly to the 4DO-3DI-3AI:
╭───────────────────────╮
│ LXA IOBus 4DO-3DI-3AI │
├───────────────────────┤
┆ ┆
│ │ In 0 DUT Out ╭─────────╮
│ ┝╾─────────────────╼┥ │
│ │ In 1 │ │
│ ┝╾ │ Device │
│ │ In 2 │ under │
│ ┝╾ │ test │
│ │ In GND DUT GND │ │
│ ┝╾─────────────────╼┥ │
╰───────────────────────╯ ╰─────────╯
… DUT LED
Monitoring the status of an LED will usually require soldering
connections directly to the DUTs PCB.
LEDs are usually driven using a current-limiting resistor R.
You will need to identify this resistor and solder connections
to the PCB bypassing the resistor:
╭───────────────────────╮
│ LXA IOBus 4DO-3DI-3AI │
├───────────────────────┤
┆ ┆
│ │ In 0 DUT Out ╭──────────────╮
│ ┝╾─────────────────╼┿──┬─┄ │
│ │ In 1 │ ┷ │
│ ┝╾ │ R Device │
│ │ In 2 │ ┯ under │
│ ┝╾ │ ┷ test │
│ │ │ LED │
│ │ In GND DUT GND │ ┯ │
│ ┝╾─────────────────╼┿──┴─┄ │
╰───────────────────────╯ ╰──────────────╯
Analog Inputs
The analog inputs are implemented directly in the microcontroller and not isolated from the IOBus system GND. The ADC inputs are useful for use cases like measuring voltage supply lines of a DUT to make sure that the device did in fact power down.
╭───────────────────────╮
│ LXA IOBus 4DO-3DI-3AI │
├───────────────────────┤
┆ ┆
│ │ ADC In 0 12V ╭─────────╮
│ ┝╾─────────────────╼┥ │
│ │ ADC In 1 │ │
│ ┝╾ │ Device │
│ │ ADC In 2 │ under │
│ ┝╾ │ test │
│ │ │ │
┆ ┆ GND DUT GND │ │
│ ┝╾─────────────────╼┥ │
╰───────────────────────╯ ╰─────────╯