Commissioning ############# .. _software-commissioning: This chapter describes how to use the Ethernet-Mux with control via the CAN interface. If you want to control the Ethernet-Mux with the internal input refer to :ref:`Control via GPIO`. 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 following chapter to learn how to setup a basic CAN-/IObus-network to connect your Ethernet-Mux 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 Preparations ===================== Bus and Power Setup ------------------- The Ethernet-Mux connector labeled "CAN" is used to connect the Ethernet-Mux 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 Ethernet-Mux: .. code-block:: text Ethernet-Mux +----------------------------------+ | | | +-----+ | OUT A | | +-----+ (RJ45) | | | | IN +-----+ | | (RJ45) | +-----+ | Power Supply 12V DC | | +-------------------+ | | | | | +-----+ | | | OUT B | | | +---+ | CAN (RJ45) | | | 12 V DC Output | +---+ | + Power +-----+ | +---+ | | Input | | | | | (D-SUB 9) | | | | | +-----+ | +-------------------+ | +------------| |---------------+ | | | | +-----+ Test Server | ^ +-------------------+ | | | | | CAN-Bus: | | | | CAN_H, CAN_L | | +---+ | GND and +12V | +---+ | CAN Interface | |<--+---------------------+-------->| | | +---+ +---+ | | CAN-Bus Termination | | 120 Ohm between CAN_H and CAN_L +-------------------+ (can be placed anywhere on the bus) CAN structure for a single Ethernet-Mux on a short bus. In this example the Ethernet-Mux 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 Ethernet-Mux 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 Ethernet-Mux: .. 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 Ethernet-Mux. .. 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 C101, 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 Ethernet-Mux. Higher voltages may damage the Ethernet-Mux. 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 Ethernet-Mux. .. 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 Ethernet-Mux 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 Ethernet cables -------------------------- Ethernet is connected using the RJ45 sockets of the device. The Ethernet-Mux is designed as a transparent switch between the RJ45 sockets. That means that all pins are connected 1:1, for example: Pin 1 of the input is, depending on the selected setting, connected to either Pin 1 of Socket A or Socket B. When using non-crossover cables on both sides of the Ethernet-Mux all pins are connected 1:1. The Ethernet-Mux uses Ethernet magnetics to implement an insulation between the switch and the external connections. Therefore the pinout must follow standard TIA-568A/B cable usage: .. list-table:: Ethernet on TIA-568A/B pinout: :header-rows: 1 * - Pin - 10/100BASE-T function - 1000BASE-T function * - 1 - TX+ - DA+ * - 2 - TX- - DA- * - 3 - RX+ - DB+ * - 4 - *not connected* - DC+ * - 5 - *not connected* - DC- * - 6 - RX- - DB- * - 7 - *not connected* - DD+ * - 8 - *not connected* - DD-