Skip to main content

Tool to control an USB-Mux from the command line

Project description



This is the control software for the Linux Automation GmbH USB-Mux. This repository contains a standalone command line application and a python module, both of which may be used to control USB-Muxes on Linux.

USB-Muxes contain an USB Hub, high speed analog switches, power switches and a microcontroller for control. USB-Muxes enable the automated testing of embedded USB devices by allowing the connection of a USB device to a DUT (device under test) without requiring physical access.

The USB-Mux hardware and software is usually used with Labgrid, but can also be made to fit your workflow by using it standalone or in a custom application.

Functional overview

usbmuxctl provides the following sub-commands:

  • usbmuxctl list - Get a list of available USB-Muxes

  • usbmuxctl status - Get the current status of a particular USB-Mux

  • usbmuxctl update - Perform firmware upgrades

  • usbmuxctl disconnect - Tear down all USB connections to the DUT and Device ports

  • usbmuxctl connect - Create a connection between USB ports. Possible connections are:

    • --dut-device - Connect the DUT (e.g. a single board computer) to the Device port (e.g. an USB flash drive)

    • --host-dut - Connect the Host (e.g. a PC running usbmuxctl) to the DUT (acting as an USB device)

    • --host-device - Connect the Host to the Device port

  • usbmuxctl id - Set the status of the DUT’s id pin used for USB OTG negotiation

Possible example use cases are:

  • Testing the hot-plug reliability by toggling between usbmuxctl disconnect and usbmuxctl connect --dut-device.

  • Testing USB-based firmware upgrades by sharing a flash drive using usbmuxctl --host-device and usbmuxctl --dut-device.

  • Testing USB OTG functionality using usbmuxctl --dut-device (DUT in the USB host role) and usbmuxctl --host-dut (DUT in the USB device role).


You can install usbmuxctl either directly from git or from pypi. If you just want to give the tool a spin you should use the pypi-method.

Install from git

Clone this repository and create a virtualenv for usbmuxctl:

$ git clone
$ cd usbmuxctl
$ python3 -m venv venv
$ source venv/bin/activate

Install usbmuxctl into the virtualenv:

$ pip3 install .

You can now continue to test your installation using the help command.

Install from pypi

Create and activate a virtualenv for usbmuxctl:

$ python3 -m venv venv
$ source venv/bin/activate

Install usbmuxctl into the virtualenv:

$ pip3 install usbmuxctl

Test your installation

You can now run usbmuxctl -h to get a list of available sub-commands:

$ usbmuxctl -h
usage: usbmuxctl [-h] [--serial SERIAL] [--path PATH] [--json | --raw] {list,status,update,
disconnect,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
    disconnect          Clear all connections between the ports of 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.

Using as root

To communicate with the USB-Muxes usbmuxctl needs permissions to access the USB-connected microcontroller. The section below describes the correct way to grant these permissions to your user.

To rule out issues with the configuration of these permissions for the initial test you can run usbmuxctl as root by using sudo and a path to the usbmuxctl file inside the previously set up virtualenv [1]:

$ sudo venv/bin/usbmuxctl list
Serial      | USB-Path           | Host-DUT Lock? | Connections
----------- | ------------------ | -------------- | -----------
22          | 1-3.1              | unlocked       | None

$ sudo venv/bin/usbmuxctl --serial 22 connect --host-device
                                     | USB-Mux               |
                                  +--|                       |
                                  |  | SN:   22              |
                                  |  | Path: 1-3.1           |
                                  |  +-----------------------+
       VCC: 4.95V    +---------+  |
Host |>--------------|       1 |--+         ID: High
                     |         |           VCC: 0.00V
                     |       2 |----x    ------------|> DUT
                     |         |
                     |       3 |---------------------|> Device
                     +---------+           VCC: 4.62V

Using as non-root user

To use usbmuxctl as non-root user you should use an udev rule to grant access to the USB-Mux device to your user. An example rule for Debian and Debian based distributions (like Ubuntu or Mint) [2] is included in the contrib/udev folder of this repository. The content of this rule file should be placed in a file in the /etc/udev/rules.d/ directory. An example installation, including the reloading of udev rules is shown below:

$ echo 'ATTRS{idVendor}=="33f7", ATTRS{idProduct}=="0001", TAG+="uaccess", GROUP="plugdev"' \
 | sudo tee /etc/udev/rules.d/99-usbmux.rules
$ sudo udevadm control --reload-rules

After reattaching the USB-Mux you should be able to able to use it without requiring sudo permissions.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

usbmuxctl-0.1.0.tar.gz (28.4 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page