Package: usbmuxctl
PurposeThis 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 withLabgrid,
but can also be made to fit your workflow by using it standalone or in a custom application.Functional overviewusbmuxctlprovides the following sub-commands:usbmuxctl list- Get a list of available USB-Muxesusbmuxctl status- Get the current status of a particular USB-Muxusbmuxctl update- Perform firmware upgradesusbmuxctl disconnect- Tear down all USB connections to the DUT and Device portsusbmuxctl 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 runningusbmuxctl) to the DUT (acting as an USB device)--host-device- Connect the Host to the Device portusbmuxctl id- Set the status of the DUT’sidpin used for USB OTG negotiationPossible example use cases are:Testing the hot-plug reliability by toggling betweenusbmuxctl disconnectandusbmuxctl connect--dut-device.Testing USB-based firmware upgrades by sharing a flash drive usingusbmuxctl--host-deviceandusbmuxctl--dut-device.Testing USB OTG functionality usingusbmuxctl--dut-device(DUT in the USB host role)
andusbmuxctl--host-dut(DUT in the USB device role).Further documentation is available in thehandbook.QuickstartYou can install usbmuxctl either directly from git or from pypi.
If you just want to give the tool a spin you should use thepypi-method.Install from gitClone this repository and create a virtualenv for usbmuxctl:$gitclonehttps://github.com/linux-automation/usbmuxctl.git$cdusbmuxctl$python3-mvenvvenv$sourcevenv/bin/activateInstall usbmuxctl into the virtualenv:$pip3install.You can now continue to test your installation using the help command.Install from pypiCreate and activate a virtualenv for usbmuxctl:$python3-mvenvvenv$sourcevenv/bin/activateInstall usbmuxctl into the virtualenv:$pip3installusbmuxctlTest your installationYou can now runusbmuxctl-hto get a list of available sub-commands:$usbmuxctl-husage:usbmuxctl[-h][--serialSERIAL][--pathPATH][--json|--raw]{list,status,update,disconnect,connect,id,dfu}...USB-Muxcontrolpositionalarguments:{list,status,update,disconnect,connect,id,dfu}SupplyoneofthefollowingcommandstointeractwiththeUSB-MuxlistListsallconnectedUSB-MuxstatusGetthestatusofaUSB-MuxupdateUpdatesoftwareontheUSB-MuxdisconnectClearallconnectionsbetweentheportsoftheUSB-MuxconnectMakeconnectionsbetweentheportsoftheUSB-MuxidSetthestateoftheID-PintotheDUTdfuSendtheUSB-MuxintotheUSB-Bootloadermode.optionalarguments:-h,--helpshowthishelpmessageandexit--serialSERIALSerialnumberoftheUSB-Mux--pathPATHpathtotheUSB-Mux--jsonFormatoutputasjson.Usefulforscripting.--rawFormatoutputasrawinfo.Usefulforcommandlinescripting.Using as rootTo communicate with the USB-Muxesusbmuxctlneeds 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 runusbmuxctlas root by usingsudoand a path to theusbmuxctlfile 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[1]Thesudocommand discards most environment variables when executing commands,
making it incompatible with the usual virtual env workflow.Using as non-root userTo useusbmuxctlas non-root user you should use anudevrule 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 thecontrib/udevfolder 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 ofudevrules 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-rulesAfter reattaching the USB-Mux you should be able to able to use it without
requiringsudopermissions.[2]Theplugdevgroup may not be present in your Linux distribution of choice.
Please adapt the rule according to the groups provided by your distribution.Using on WindowsMost features of theusbmuxctlutility can also be used on Windows.Limitations on WindowsOn Windows the following limitations apply:Updating the firmware: this feature has not been tested successfully on Windows.
(In theory it should be possible to installdfu-utiland the drivers needed - but it has not yet been
documented.)Using the USB path to select an USB-Mux.
(On Linux this feature can be used to select which USB-Mux to use by the physical path on the USB.
On Windows the path is not exposed bylibusband thus this field is empty.)Installation of dependenciesInstallpython3.
Make sure to add the Python binaries to your path during installation.Afterwards install theWindows driver package:
Download and extract the archive. Then runInstallDriver.exe.Install from pypiWe suggest to use the PowerShell to use this tool.Create and activate a virtualenv for usbmuxctl:PS > python -m venv venv
PS >.\venv\Scripts\Activate.ps1Install usbmuxctl into the virtualenv:(venv) PS > pip install usbmuxctlYou can now runusbmuxctl.exe-hto get a list of available sub-commands.ContributingThank you for considering a contribution to this project!
Changes should be submitted via aGithub pull request.We use theblackcode formatter,
please runblackwhen contributing changes:$python3-mpipinstallblack$black*.pyusbmuxctl/Alldone!✨🍰✨8filesleftunchanged.This project uses theDeveloper’s Certificate of Origin 1.1with the sameprocessas used for the Linux kernel:Developer’s Certificate of Origin 1.1By making a contribution to this project, I certify that:The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; orThe contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; orThe contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.Then you just add a line (usinggit commit-s) saying:Signed-off-by: Random J Developer <random@developer.example.org>using your real name (sorry, no pseudonyms or anonymous contributions).