Operation ========= Software -------- .. note:: Make sure you have installed the control software as described in :ref:`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 :term:`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: .. code-block:: bash $ lxa-iobus-server can0 starting server on http://localhost:8080/ .. .. note:: The `lxa-iobus handbook `_. contains more information on how to configure the server software. And a guide on how to automatically start the server on system boot. .. TODO:: The handbook does not yet exist. When it does: point right to the chapter explaining the systemd.service-setup and uncomment this section. 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: .. figure:: product-operation-server-nodes.png :alt: 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: .. figure:: product-operation-server-ethmux.png :alt: 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. Setting the **SW** button to the *activated* state configures a connection of the IN connector of the Ethernet-Mux to the OUT A connector. Setting the **SW** button to the *deactivated* state configures a connection of the IN connector of the Ethernet-Mux to the OUT B connector. 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: .. figure:: product-operation-server-locator.png :alt: 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: .. code-block:: bash # 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: .. code-block:: yaml 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 preferred 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``. .. code-block:: bash # 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 :term:`LSS` Fastscan. .. _gpio-control: 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: .. list-table:: Internal connector ``P101`` pinout :header-rows: 1 * - 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 .. list-table:: Internal connector ``P102`` pinout :header-rows: 1 * - 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.