Comissioning

Prepare your host system

Note

This manual refers to control software version 0.1.8.

Quickstart

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 usbsdmux package from pypi.

  • Clone the git repository:

$ git clone https://github.com/pengutronix/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 setup.py install

  • Now you can run 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 usbsdmux as root, if it suits you.

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

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

Using as normal user / Reliable names

Control Device

The example udev-rule in contib/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 a Micro 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

After powering up the USB-SD-Mux the micro SD card is disconnected from both the DUT and the Host.