Comissioning ############ .. _software-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: .. code-block:: bash $ git clone https://github.com/pengutronix/usbsdmux.git $ cd usbsdmux * Create and activate a virtualenv for usbsdmux: .. code-block:: bash $ python3 -m venv venv $ source venv/bin/activate * Install usbsdmux into the virtualenv: .. code-block:: bash $ python3 setup.py install * Now you can run ``usbsdmux`` command by giving the appropriate ``/dev/sg*`` device, e.g.: .. code-block:: bash $ 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: .. code-block:: bash $ sudo /path/to/virtualenv/bin/usbsdmux /dev/sg0 dut .. _non-root-use: .. _reliable-names: Using as normal user / Reliable names ------------------------------------- .. rubric:: 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: .. code-block:: bash $ 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. .. rubric:: 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] 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: .. code-block:: bash 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/``. .. code-block:: bash cfi@klee:~$ ls /dev/usb-sd-mux/ id-000000000382 * Additionally udev will create a symlink in ``/dev/disk/by-id/``: .. code-block:: bash 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 :term:`DUT` and the Host.