Commissioning
#############
.. _software-commissioning:
This manual references to the revision ``0.1.2`` of the control software.
Linux: Prepare your system
==========================
Quickstart
----------
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 ``usbmuxctl`` package from
`pypi `__.
* Clone the git repository:
.. code-block:: bash
$ git clone https://github.com/linux-automation/usbmuxctl.git
$ cd usbmuxctl
* Create and activate a virtualenv for usbmuxctl:
.. code-block:: bash
$ python3 -m venv venv
$ source venv/bin/activate
* Install usbmuxctl into the virtualenv:
.. code-block:: bash
$ python3 setup.py install
* To test the installation you can run ``usbmuxctl -h``
to get an overview of the possible ``usbmuxctl`` actions:
.. code-block:: none
$ usbmuxctl -h
usage: usbmuxctl [-h] [--serial SERIAL] [--path PATH] [--json | --raw] {list,status,update,connect,id,dfu} ...
USB-Mux control
positional arguments:
{list,status,update,connect,id,dfu}
Supply one of the following commands to interact with the USB-Mux
list Lists all connected USB-Mux
status Get the status of a USB-Mux
update Update software on the USB-Mux
connect Make connections between the ports of the USB-Mux
id Set the state of the ID-Pin to the DUT
dfu Send the USB-Mux into the USB-Bootloader mode.
optional arguments:
-h, --help show this help message and exit
--serial SERIAL Serial number of the USB-Mux
--path PATH path to the USB-Mux
--json Format output as json. Useful for scripting.
--raw Format output as raw info. Useful for command line scripting.
Have a look at the following chapter to learn how to use the ``usbmuxctl``
command and run it without root privileges by using an ``udev`` rule.
Using as root
-------------
You can use ``usbmuxctl`` as root, if it suits you.
The ``usbmuxctl`` can be called as root (e.g. by using ``sudo``) without
sourcing the ``virtualenv``.
To do so call ``usbmuxctl`` inside the ``bin/`` directory of the
``virtualenv`` you created in the previous step:
.. code-block:: bash
$ sudo /path/to/virtualenv/bin/usbmuxctl -h
.. _non-root-use:
Using as non-root user
----------------------
The udev rule ``contrib/udev/99-usbmux.rules`` in the usbmuxctl
git repository allows any user in the ``plugdev`` group to access
USB-Mux devices connected to a system.
On Debian-based Linux distributions users are, by default, members
of this group. Users of different distributions may need to adapt
the udev rules to their needs.
* Install the udev-rules by copying them into your local
``rules.d``-directory and reload the udev rules:
.. code-block:: bash
$ sudo cp contrib/udev/99-usbmux.rules /etc/udev/rules.d/
$ sudo udevadm control --reload-rules
Hardware Preparations
---------------------
If you have prepared your host system to control the USB-Mux,
connect it using an USB-A to USB-B Cable.
* The host will detect the USB-Mux as an USB-Hub with an USB-Mux device connected to its first port:
.. code-block:: bash
$ dmesg -w
[15911.530954] usb 5-1.3.4.2: new high-speed USB device number 26 using xhci_hcd
[15911.639790] usb 5-1.3.4.2: New USB device found, idVendor=0424, idProduct=2514, bcdDevice= b.b3
[15911.639797] usb 5-1.3.4.2: New USB device strings: Mfr=0, Product=0, SerialNumber=0
[15911.684106] hub 5-1.3.4.2:1.0: USB hub found
[15911.684410] hub 5-1.3.4.2:1.0: 3 ports detected
[15912.042944] usb 5-1.3.4.2.1: new full-speed USB device number 27 using xhci_hcd
[15912.183929] usb 5-1.3.4.2.1: New USB device found, idVendor=33f7, idProduct=0001, bcdDevice= 0.10
[15912.183935] usb 5-1.3.4.2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[15912.183937] usb 5-1.3.4.2.1: Product: USB-Mux
[15912.183938] usb 5-1.3.4.2.1: Manufacturer: Linux Automation GmbH
[15912.183939] usb 5-1.3.4.2.1: SerialNumber: 0022
.. note::
After powering up the USB-Mux the data- and power-supply-lines on
the :term:`DUT` and Device ports are disconnected from the other ports.
Windows: Prepare your system
============================
Make sure you have installed the requirements as listed under :ref:`system requirements`.
The preferred installation method on Windows is the installation into a ``venv``.
Assuming that you are using the *Power Shell* do the following to create a ``venv``:
.. code-block:: none
PS > python -m venv venv
PS >.\venv\Scripts\Activate.ps1
Install usbmuxctl into the virtualenv:
.. code-block:: none
(venv) PS > pip install usbmuxctl
You can now run ``usbmuxctl.exe -h`` to get a list of available sub-commands.
.. note::
For the rest of this document the binary is called ``usbmuxctl``.
Remember to use ``usbmuxctl.exe`` instead.
.. note::
You can call the ``usbmuxctl.exe`` inside ``venv\Scripts\`` without activating the ``venv`` first.
Accessing multiple USB-Muxes on a system
========================================
.. _reliable-names:
In cases where multiple USB-Muxes should be controlled by a
single host computer it becomes necessary to distinguish between
the connected Muxes.
The ``usbmuxctl`` software can distinguish between USB-Muxes
based on their unique serial number or their path in the tree
of connected USB-devices.
Both the serial number and USB-Path of an USB-Mux may be discovered
using ``usbmuxctl list``:
.. code-block:: bash
$ usbmuxctl list
Serial | USB-Path | Host-DUT Lock? | Connections
----------- | ------------------ | -------------- | -----------
22 | 1-3.1 | unlocked | None
To get the current connection status of the USB-Mux with serial
number 22 ``usbmuxctl status`` can then be supplied the ``--serial``
parameter:
.. code-block:: bash
$ usbmuxctl --serial 22 status
+-----------------------+
| USB-Mux |
+--| |
| | SN: 22 |
| | Path: 1-3.1 |
| +-----------------------+
VCC: 4.95V +---------+ |
Host |>--------------| 1 |--+ ID: High
| | VCC: 0.00V
| 2 |----x ------------|> DUT
| |
| 3 |----x ------------|> Device
+---------+ VCC: 0.00V
The ASCII-art representation of the USB-Mux status indicates that
the :term:`DUT` and Device ports are connected neither to the
internal 3-port USB-Hub nor to each other.
The Host port is also the only port where the nominal 5V USB
supply voltage is measured.
.. note::
On Windows the ``USB-Path`` attribute is always empty.
USB-Muxes can only be selected using their serial number.