Package: usbsdmux
PurposeThis software is used to control a special piece of hardware called usb-sd-mux from the command line or python.The usb-sd-mux is build around aMicrochip USB2642card reader. Thus most of this software deals with interfacing this device using Linux ioctls().This software is aimed to be used withLabgrid. But it can also be used stand-alone or in your own applications.High-Level Functionsusbsdmux provides the following functions:Multiplexing the SD-Card to either DUT, Host or disconnect withusbsdmuxWriting the Configuration-EEPROM of the USB2642 from the command line to customize the representation of the USB device:usbsdmux-configureLow-Level FunctionsUnder the hood this tool provides interfaces to access the following features of the Microchip USB2642:Accessing the auxiliary I2C bus with write and write-read transactions with up to 512 bytes of payload using a simple python interface.Writing an I2C Configuration-EEPROM on the configuration I2C.
This is done using an undocumented command that was reverse-engineered from Microchip’s freely available EOL-Tools.PackagesThis tool ispackagedin Debian 12
(akabookworm) and later.
The package ships theusbsdmuxtool and the correspondingudev-rules.
So you can simplyapt install usbsdmuxand skip all installation steps below.Packages also exist forsome other distributions.QuickstartCreate and activate a virtualenv for usbsdmux:$virtualenv-ppython3venv$sourcevenv/bin/activateInstall usbsdmux into the virtualenv:$pipinstallusbsdmuxNow you can runusbsdmux-hto get a list of possible
command invocations:$ usbsdmux -h
usage: usbsdmux [-h] [--config CONFIG] [--json]
                SG {get,dut,client,host,off,gpio,info} ...

positional arguments:
  SG                    /dev/sg* to use
  {get,dut,client,host,off,gpio,info}
                        Supply one of the following commands to interact with the device
    get                 Read the current state of the USB-SD-Mux
    dut                 Switch to the DUT
    client              Switch to the DUT
    host                Switch to the host
    off                 Disconnect from host and DUT
    gpio                Manipulate a GPIO (open drain output only)
    info                Show information about the SD card

options:
  -h, --help            show this help message and exit
  --config CONFIG       Set config file location
  --json                Format output as json. Useful for scripting.Using as rootIf you just want to try the USB-SD-Mux (or maybe if it is just ok for you) you
can just useusbsdmuxas root.If you have installed this tool inside a virtualenv you can just call the
shell-wrapper along with the appropriate/dev/sg*device path:sudo/path/to/virtualenv/bin/usbsdmux/dev/sg0dutsudo/path/to/virtualenv/bin/usbsdmux/dev/sg0hostUsing as normal user / Reliable namesThe example udev-rule incontrib/udev/99-usbsdmux.rulesserves two purposes:Allow users currently logged into the system and users in theplugdevgroup[1]to access connected USB-SD-Muxes.Create a reliable path in the filesystem to access specific
USB-SD-Muxes based on their pre-programmed unique serial number.
This is useful when multiple USB-SD-Muxes are connect to a system,
as the enumeration-order, and thus the/dev/sg*numbering,
may differ between reboots.
The serial number is printed on a label attached to the device.Users of a Debian based distribution[1]can install the udev rule
by cloning this repository and copying it to the appropriate location
and reloading the active udev rules:$gitclone"https://github.com/linux-automation/usbsdmux.git"$sudocpusbsdmux/contrib/udev/99-usbsdmux.rules/etc/udev/rules.d/$sudoudevadmcontrol--reload-rulesAfter reattaching the USB-SD-Mux you should get a list of connected USB-SD-Muxes,
based on their unique serial numbers, by listing the contents of
the/dev/usb-sd-mux/directory:$ls-l/dev/usb-sd-mux/total0lrwxrwxrwx1rootplugdev6Mar3111:21id-000000000042->../sg3lrwxrwxrwx1rootplugdev6Mar2700:33id-000000000078->../sg2lrwxrwxrwx1rootplugdev6Mar2409:51id-000000000378->../sg1[1](1,2)Theplugdevgroup is used in Debian and Debian based distributions
(like Ubuntu and Linux Mint) to grant access to pluggable gadgets.
Depending on your Linux distribution you may want to create/use another
group for this purpose and adapt theudevrule accordingly.TroubleshootingSome single board computers, especially Raspberry Pi model 4s, do not work with
new/fast micro SD cards, due to drive strength issues at high frequencies.
Use old and slow micro SD cards with these devices.
Another workaround is the replacement of resistorsR101andR102with 0Ω
parts. This modifications does however void the EMC compliance statement provided
by the Linux Automation GmbH.Some usecases, like hard to reach connectors or full-size SD cards, necessitate the
use of adapters or extension cables, leading to the same drive strength issues
and require the same workarounds as documented above.In order for the/dev/sg*device to appear thesgkernel module needs to be loaded
into the kernel. This is usually done automatically byudevonce the USB-SD-Mux is connected.
To manually load the kernel module runsudo modprobe sg.MQTT StatisticsThis tool can be configured to send certain statistics to a MQTT broker.
To enable this function create a config file at/etc/usbsdmux.configor use--configspecify a file location.See example config fileusbsdmux.config.ContributingThank you for thinking about contributing to this project!
Changes should be submitted via aGithub pull request.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 a known identity (sorry, no anonymous contributions).