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:
$ git clone https://github.com/linux-automation/usbmuxctl.git
$ cd usbmuxctl
Create and activate a virtualenv for usbmuxctl:
$ python3 -m venv venv
$ source venv/bin/activate
Install usbmuxctl into the virtualenv:
$ python3 setup.py install
To test the installation you can run
usbmuxctl -hto get an overview of the possibleusbmuxctlactions:
$ 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:
$ sudo /path/to/virtualenv/bin/usbmuxctl -h
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:
$ 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:
$ 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 DUT and Device ports are disconnected from the other ports.
Windows: Prepare your system
Make sure you have installed the requirements as listed under 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:
PS > python -m venv venv
PS >.\venv\Scripts\Activate.ps1
Install usbmuxctl into the virtualenv:
(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
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:
$ 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:
$ 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 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.