This manual references to the revision 0.1.2 of the control software.

Linux: Prepare your system


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
$ cd usbmuxctl
  • Create and activate a virtualenv for usbmuxctl:

$ python3 -m venv venv
$ source venv/bin/activate
  • Install usbmuxctl into the virtualenv:

$ python3 install
  • To test the installation you can run usbmuxctl -h to get an overview of the possible usbmuxctl actions:

$ usbmuxctl -h
usage: usbmuxctl [-h] [--serial SERIAL] [--path PATH] [--json | --raw] {list,status,update,connect,id,dfu} ...

USB-Mux control

positional arguments:
            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- new high-speed USB device number 26 using xhci_hcd
[15911.639790] usb 5- New USB device found, idVendor=0424, idProduct=2514, bcdDevice= b.b3
[15911.639797] usb 5- New USB device strings: Mfr=0, Product=0, SerialNumber=0
[15911.684106] hub 5- USB hub found
[15911.684410] hub 5- 3 ports detected
[15912.042944] usb 5- new full-speed USB device number 27 using xhci_hcd
[15912.183929] usb 5- New USB device found, idVendor=33f7, idProduct=0001, bcdDevice= 0.10
[15912.183935] usb 5- New USB device strings: Mfr=1, Product=2, SerialNumber=3
[15912.183937] usb 5- Product: USB-Mux
[15912.183938] usb 5- Manufacturer: Linux Automation GmbH
[15912.183939] usb 5- SerialNumber: 0022


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.


For the rest of this document the binary is called usbmuxctl. Remember to use usbmuxctl.exe instead.


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.


On Windows the USB-Path attribute is always empty. USB-Muxes can only be selected using their serial number.