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-server command with the --help argument 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 susceptive 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 busses) 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:

Numbered DE9 female Diagram

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.

D-Sub 9 CAN Pinout

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 reliablility.

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 busses (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 busses 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   │            │
┆                       ┆          ╰────────────╯
… button input

To automate a push-button you need to identify the appropriate pins on the DUTs PCB and solder leads directly to the PCB. One way to identify the correct pins on the PCB is to unplug the DUT and use an ohm-meter to identify the pins of the switch that change resistance when the button is pressed.

… 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 optocouplers inside 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 milliamperes 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 │         │
│                       ┝╾─────────────────╼┥         │
╰───────────────────────╯                   ╰─────────╯