Commissioning

Prepare your host system

Note

This manual refers to control software version 24.01.1.

Quickstart

This quickstart guide clones the upstream git repository to install the control software. This installation method provides easy access to files in the contrib-directory, which are needed later during setup. There are also other ways to install the control software, like the installation from Linux distribution package repositories or from pypi via pipx or a venv. See the usbsdmux tool README for more information on the currently preferred installation methods.

• Clone the git repository:

$ git clone https://github.com/linux-automation/usbsdmux.git
$ cd usbsdmux

• Create and activate a virtualenv for usbsdmux:

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

• Install usbsdmux into the virtualenv:

$ python3 -m pip install .

• Now you can run the usbsdmux command by giving the appropriate /dev/sg* device, e.g.:

$ sudo venv/bin/usbsdmux /dev/sg0 dut
$ sudo venv/bin/usbsdmux /dev/sg0 host

Have a look at the following chapter to learn how to use udev to run the usbsdmux command without root privileges and how to uniquely identify the /dev/sg* devices of multiple USB-SD-Muxes.

Using as root

You can use the usbsdmux command as root, if it suits you.

The usbsdmux script can be called as root (e.g. by using sudo) without sourcing the virtualenv. To do so call the usbsdmux script inside the bin/ directory of the virtualenv:

$ sudo /path/to/virtualenv/bin/usbsdmux /dev/sg0 dut

Using as normal user / Reliable names

Control Device

The example udev-rule in contrib/udev/99-usbsdmux.rules serves two purposes:

• Allow users currently logged into the system and users in the plugdev group [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 copying it to the appropriate location and reloading the active udev rules:

$ sudo cp contrib/udev/99-usbsdmux.rules /etc/udev/rules.d/
$ sudo udevadm control --reload-rules

For each newly-connected USB-SD-Mux a symlink to its /dev/sg* device will appear in /dev/usb-sd-mux/. These links contain the devices unique serial number and can be used as arguments to the usbsdmux command.

Mass Storage

The generic udev rules already generate a reliable symlink. The block device will appear as /dev/disk/by-id/usb-LinuxAut_sdmux_HS-SD_MMC_*-0:0.

[1] (1,2)

The plugdev group 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 the udev rule accordingly.

Hardware Preparations

If you have prepared your host system to control the USB-SD-Mux, connect your USB-SD-Mux to your host system with an appropriate USB-Cable.

• The host will detect the USB-SD-Mux as an off-the-shelf card reader:

cfi@klee:~$ dmesg -w

 [55748.877949] usb 1-4.4.3: new high-speed USB device number 62 using xhci_hcd
 [55748.978215] usb 1-4.4.3: New USB device found, idVendor=0424, idProduct=2640, bcdDevice= 8.a2
 [55748.978227] usb 1-4.4.3: New USB device strings: Mfr=0, Product=0, SerialNumber=0
 [55748.981779] hub 1-4.4.3:1.0: USB hub found
 [55748.985373] hub 1-4.4.3:1.0: 1 port detected
 [55749.273992] usb 1-4.4.3.1: new high-speed USB device number 63 using xhci_hcd
 [55749.435323] usb 1-4.4.3.1: New USB device found, idVendor=0424, idProduct=4041, bcdDevice= 2.09
 [55749.435332] usb 1-4.4.3.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
 [55749.435337] usb 1-4.4.3.1: Product: usb-sd-mux_rev4.0
 [55749.435342] usb 1-4.4.3.1: Manufacturer: Linux Automation GmbH
 [55749.435346] usb 1-4.4.3.1: SerialNumber: 000000000382
 [55749.438548] usb-storage 1-4.4.3.1:1.0: USB Mass Storage device detected
 [55749.441300] scsi host2: usb-storage 1-4.4.3.1:1.0
 [55750.459336] scsi 2:0:0:0: Direct-Access     LinuxAut sdmux HS-SD/MMC  2.09 PQ: 0 ANSI: 0
 [55750.460980] sd 2:0:0:0: Attached scsi generic sg0 type 0
 [55750.463741] sd 2:0:0:0: [sdb] Attached SCSI removable disk

• The provided udev-rules will create a symlink for every USB-SD-Mux in /dev/usb-sd-mux/.

cfi@klee:~$ ls /dev/usb-sd-mux/
id-000000000382

• Additionally udev will create a symlink in /dev/disk/by-id/:

cfi@klee:~$ ls /dev/disk/by-id/usb-PTX_sdmux*
/dev/disk/by-id/usb-LinuxAut_sdmux_HS-SD_MMC_000000000382-0:0

Note

On USB-SD-Mux Classic the micro SD card is not connected to the DUT or host after power up. To connect the card to the DUT or host you must use the usbsdmux tool.

On USB-SD-Mux FAST the micro SD is connected to the DUT after power up.