Commissioning
#############
.. _software-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:
.. code-block:: bash
$ git clone https://github.com/linux-automation/lxa-iobus.git
$ cd lxa-iobus
* Create and activate a virtualenv for lxa-iobus:
.. code-block:: bash
$ python3 -m venv venv
$ source venv/bin/activate
* Install lxa-iobus-server into the virtualenv:
.. code-block:: bash
$ python3 -m pip install -e.[full]
* You can now run the ``lxa-iobus-server`` command with the
``--help`` argument to test the installation:
.. code-block:: bash
$ 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 :ref:`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:
.. code-block:: ini
[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:
.. code-block:: bash
$ ip --details link show can0
8: can0: 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 :ref:`Bitrate-Intolerant CAN Bus` for more
information.
.. _hardware-commissioning:
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:
.. code-block:: text
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.
.. _hardware-pinout:
Pinout
.......
The following figure shows the pinout of the D-Sub 9 connector on the
LXA IOBus 4DO-3DI-3AI:
.. figure:: Numbered_DE9_female_Diagram.svg
:alt: 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.
.. list-table:: D-Sub 9 CAN Pinout
:header-rows: 1
* - 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 :ref:`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 :term:`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:
.. code-block:: text
╭───────────────────────╮
│ 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
:term:`DUT`\ s :term:`PCB` and solder leads directly to the :term:`PCB`.
One way to identify the correct pins on the :term:`PCB` is to unplug the
:term:`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 :term:`DUT` you may
use external resistors acting as pull-ups or pull-downs:
.. code-block:: text
╭───────────────────────╮ 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:
.. code-block:: text
╭───────────────────────╮
│ 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 :term:`DUT`\ s :term:`PCB`.
LEDs are usually driven using a current-limiting resistor ``R``.
You will need to identify this resistor and solder connections
to the :term:`PCB` bypassing the resistor:
.. code-block:: text
╭───────────────────────╮
│ 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 :term:`ADC` inputs are useful for use cases like measuring
voltage supply lines of a :term:`DUT` to make sure that the
device did in fact power down.
.. code-block:: text
╭───────────────────────╮
│ LXA IOBus 4DO-3DI-3AI │
├───────────────────────┤
┆ ┆
│ │ ADC In 0 12V ╭─────────╮
│ ┝╾─────────────────╼┥ │
│ │ ADC In 1 │ │
│ ┝╾ │ Device │
│ │ ADC In 2 │ under │
│ ┝╾ │ test │
│ │ │ │
┆ ┆ GND DUT GND │ │
│ ┝╾─────────────────╼┥ │
╰───────────────────────╯ ╰─────────╯