How to configure a USB remote server with an STM32 MPU board

This message will disappear after all relevant tasks have been resolved.

Semantic MediaWiki

There are 1 incomplete or pending task to finish installation of Semantic MediaWiki. An administrator or user with sufficient rights can complete it. This should be done before adding new data to avoid inconsistencies.

1. Article purpose[edit source]

The purpose of this article is to explain how to configure a USB remote server with an STM32MP157x-DKx board used as an example, managed by Linux^® on the Arm^® Cortex^®-A7 processor.

The goal is to transform an STM32MP157x-DKx board into a USB remote server, and then manage a USB device from a PC while the USB device is connected to a remote server on the network.

USB remote server

USBIP kernel modules are used to configure an STM32MP157x-DKx board as a USB remote server.

This article provides step-by-step instructions to:

explain how to transform a Linux^® board into a USB remote server with USBIP kernel modules and server
configure Linux^® software to enable the USBIP server (aka USB remote server)
configure a PC client to connect to the USBIP server.
further manage power for the USB device on the server using the uhubctl tool

Information

This configuration can be replicated with other STM32 MPU boards provided the USBIP kernel modules are activated on their Linux^® kernel.

2. Configure an STM32 MPU board with USBIP[edit source]

2.1. Overview[edit source]

As explained on the USB/IP Project webpage, the USB/IP Project aims to develop a general USB device sharing system over IP network. To share USB devices between computers with their full functionality, USB/IP encapsulates "USB I/O messages" into TCP/IP payloads and transmits them between computers. ^[1]

2.2. Step by step on server[edit source]

The installation of a USBIP server is made on boards with embedded Linux^®.
The following chapter shows how to configure manually the USBIP service on board and how to enable it on an STM32 MPU board on which all the configurations, files, and services are present.

2.2.1. Manual setup[edit source]

Before using the usbip command, it is necessary to load the kernel modules associated to USBIP:

  modprobe usbip-core
  modprobe usbip-host

Start the USBIP server:

  usbipd -D

To make available a USB device connected to a board with embedded Linux^®, it is necessary to bind the device.

List the available USB devices:

  usbip list -l
- busid 2-1.1 (03f0:e207)
  HP, Inc : unknown product (03f0:e207)

Bind this specific device to be visible by the PC client (here device 2-1.1):

  usbip bind -b 2-1.1

(To automate the binding of new USB devices, see the next section Automated setup.)

2.2.2. Automated setup (available by default on STM32 MPU boards)[edit source]

All the configurations, files, services are present on STM32 MPU boards by default.

Automate server startup via systemd:

Create on board a service dedicated to start the USBIP server.
Content of /lib/systemd/system/usbip.service:

[Unit]
Description=USB-IP Bindind
After=network.target
Wants=network.target
 
[Service]
Type=forking
ExecStartPre=-/sbin/modprobe usbip-core
ExecStartPre=-/sbin/modprobe usbip-host
ExecStart=/usr/sbin/usbipd -D
ExecStop=/usr/sbin/stm32mp-usbip-bind-unbind.sh unload

[Install]
WantedBy=multi-user.target

Start systemd USBIP service:

  systemctl daemon-reload 
  systemctl start usbip

Automate the binding of new USB devices:

The binding of new USB devices can be made by a script, which binds or unbinds the usb devices depending if they are plugged or unplugged.
This script must be called by an udev rules for the case of device plug/unplug.

Content of script: /usr/sbin/stm32mp-usbip-bind-unbind.sh:

#!/bin/sh -
#echo "Parameter number $#" >> /tmp/usbip.log
action=$1
devpath=$2
#echo "Parameter: $1" >> /tmp/usbip.log
#echo "Parameter: $2" >> /tmp/usbip.log

case $1 in
unload)
    modprobe -r usbip-core
    modprobe -r usbip-host
    kill -9 `pgrep usbipd`
    exit 0
    ;;
esac

subpath=$(echo $2 | sed "s|.*/\([^/]*\)|\1|")
#echo "subpath  >$subpath<" >> /tmp/usbip.log
if $(echo $subpath | grep -q ":");
then
    #echo "No valid path" >> /tmp/usbip.log
    exit 0
fi

# if usbip-core are not loaded, do nothing
if [ -z "$(cat /proc/modules | grep usbip_core)"  ]; then
   #echo "no module usbip_core loaded" >> /tmp/usbip.log
   exit 0
fi

case $1 in
add)
    #echo ">>> bind $subpath" >> /tmp/usbip.log
    usbip bind -b $subpath
    ;;
remove)
    #echo "<<< unbind $subpath" >> /tmp/usbip.log
    usbip unbind -b $subpath
    ;;
esac

Content of udev rules: /etc/udev/rules.d/99-usb-usbip.rules:

ACTION=="remove", SUBSYSTEM=="usb", RUN+="/usr/sbin/stm32mp-usbip-bind-unbind.sh remove %p"

ACTION=="add", SUBSYSTEM=="usb", DRIVER=="usb", RUN+="/usr/sbin/stm32mp-usbip-bind-unbind.sh add %p"

2.3. Step by step on PC client[edit source]

2.3.1. On Windows^®[edit source]

A USBIP client exists for Windows^®. It is available via GitHub usbip-win.

2.3.1.1. Installation[edit source]

Follow the instructions specified on README.md.

2.3.1.2. Usage[edit source]

User action:

List the USB devices available on the specific server:

 usbip.exe list -l -r <usbip server ip>

Attach a USB device available on the specific server (here 2-1):

 usbip.exe list -r <usbip server ip> -b 2-1

List USB devices attached on the host PC:

 usbip.exe port

Detach a specific attached USB device from the host PC:

List attached device on the host PC and detach it (here 00):
 usbip detach -p 00

2.3.2. On Linux^®[edit source]

2.3.2.1. Installation[edit source]

On Ubuntu^®, it is necessary to install some pre-requisite package:

 sudo apt-get install sysfsutils linux-tools-generic

For having a translation of USB device name and ID, install a specific hardware data base:

  wget http://www.linux-usb.org/usb.ids
  sudo mkdir -p /usr/share/hwdata/
  sudo cp usb.ids /usr/share/hwdata/

2.3.2.2. Usage[edit source]

Before using the usbip command, load the kernel modules associated to USBIP:

 sudo modprobe usbip-core
 modprobe vhci-hcd

List USB remote devices available on the specific server:

 sudo usbip list -r <server IP>

Attach a USB remote device available on the specific server:

 sudo usbip attach -r <server IP> -b <USB ID>

Detach a specific attached USB device from the host PC:

List the attached USB devices:

 sudo usbip port

Detach the specific USB device attached as 00:

 sudo usbip detach -p 00

3. Configure the STM32 MPU board to add USB power management with uhubctl[edit source]

3.1. Overview[edit source]

uhubctl is the utility to control per-port USB power on smart USB hubs. A smart hub is defined as a hub that implements per-port power switching^[2].

3.2. Usage[edit source]

 uhubctl 
Current status for hub 2-1 [0424:2514]
 Port 1: 0507 power highspeed suspend enable connect [03f0:e207 Hewlett Packard HP Webcam HD 2300]
 Port 2: 0100 power
 Port 3: 0100 power
 Port 4: 0100 power
Current status for hub 2 [1d6b:0002 Linux 5.9.0-rc4 ehci_hcd EHCI Host Controller 5800d000.usbh-ehci]
 Port 1: 0503 power highspeed enable connect [0424:2514]
 Port 2: 0100 power
Current status for hub 1 [1d6b:0002 Linux 5.9.0-rc4 dwc2_hsotg DWC OTG Controller 49000000.usb-otg]
 Port 1: 0000 off

On hub 2-1 Port 1, a USB webcam is plugged:

 cat /sys/class/video4linux/video1/name 
HP Webcam HD 2300: HP Webcam HD

To power off the USB webcam connected on this port:

 uhubctl -a off -p 1 -l 2-1
Current status for hub 2-1 [0424:2514]
 Port 1: 0507 power highspeed suspend enable connect [03f0:e207 Hewlett Packard HP Webcam HD 2300]
Sent power off request
New status for hub 2-1 [0424:2514]
 Port 1: 0000 off
 uhubctl 
Current status for hub 2-1 [0424:2514]
 Port 1: 0503 power highspeed enable connect [03f0:e207]
 Port 2: 0100 power
 Port 3: 0100 power
 Port 4: 0100 power
Current status for hub 2 [1d6b:0002 Linux 5.9.0-rc4 ehci_hcd EHCI Host Controller 5800d000.usbh-ehci]
 Port 1: 0503 power highspeed enable connect [0424:2514]
 Port 2: 0100 power
Current status for hub 1 [1d6b:0002 Linux 5.9.0-rc4 dwc2_hsotg DWC OTG Controller 49000000.usb-otg]
 Port 1: 0000 off

To power on the USB webcam connected on this port:

 uhubctl -a on -p 1 -l 2-1
Current status for hub 2-1 [0424:2514]
 Port 1: 0507 power highspeed suspend enable connect [03f0:e207 Hewlett Packard HP Webcam HD 2300]
Sent power on request
New status for hub 2-1 [0424:2514]
 Port 1: 0503 power highspeed enable connect [03f0:e207 Hewlett Packard HP Webcam HD 2300]
 uhubctl
Current status for hub 2-1 [0424:2514]
 Port 1: 0507 power highspeed suspend enable connect [03f0:e207 Hewlett Packard HP Webcam HD 2300]
 Port 2: 0100 power
 Port 3: 0100 power
 Port 4: 0100 power
Current status for hub 2 [1d6b:0002 Linux 5.9.0-rc4 ehci_hcd EHCI Host Controller 5800d000.usbh-ehci]
 Port 1: 0503 power highspeed enable connect [0424:2514]
 Port 2: 0100 power
Current status for hub 1 [1d6b:0002 Linux 5.9.0-rc4 dwc2_hsotg DWC OTG Controller 49000000.usb-otg]
 Port 1: 0000 off

4. References[edit source]

↑ USB/IP Project web page [1]
↑ uhubctl web page [2]

[USB.2FIP_Project-1] USB/IP Project web page [1]

[uhubctl_github-2] uhubctl web page [2]

[1]

[2]