USB Guest configuration

Also called USB OTG.
This Linux functionality is a bit obscure to most people yet very commonplace in consumer embedded linux devices. It allows to connect your device as if it was a USB peripheral of various types (serial port, usb storage, ethernet port, CD drive, audio device, keyboard/mouse and more).

To make an example, most modern 3G/4G dongles use this functionality to show themselves as: ethernet port (to provide the network connection), some serial ports (for comntrolling them), a CD drive (that holds an installer for some program to use them on Windows/MacOS) and usb storage (if they have a microSDcard port). Yes, there is a Linux system inside them, among other things.

Also most Android phones can do this, to show themselves as mass storage (usually not anymore in newer phones), to show themselves as MTP devices (most modern smartphones do this) so you can transfer files over, and as ethernet ports (when you enable usb tethering).

This feature requires hardware support and its own drivers, and some kind of system configuration before being used.

The USB port you use with this feature must be native, not generated by independent controllers (connected over PCIe usually), nor by a USB hub (that has a well-defined upstream port and downstream ports).

Most of the info in this article was taken from Gatework's wiki

The device needs to have a 'Gadget driver' loaded which implements the personality of the device(s) type you want. Note that most devices won't have so much drivers to choose from in LEDE because none packaged them (as most functions are very niche).

There are several Linux gadget drivers in today's linux kernel. These can be found under the Device Drivers → USB support → USB Gadget Support menu in the Linux kernel menuconfig (NOT in LEDE's menuconfig):

• g_zero (CONFIG_USB_ZERO)
• g_audio (CONFIG_USB_AUDIO)
• g_ether (CONFIG_USB_ETH) - implement a 'Communication Device Class' (CDC) Ethernet device to create a 'USB to Ethernet' network connection.
• g_ncm (CONFIG_USB_G_NCM) - implement USB CDC NCM subclass standard. NCM is an advanced protocol for Ethernet encapsulation and allows grouping of several ethernet frames into one USB transfer.
• g_mass_storage (CONFIG_USB_MASS_STORAGE) - acts as a USB Mass Storage disk driver. Its storage repository can use a regular file or a block device specified as a module parameter or sysfs option.
• g_serial (CONFIG_USB_G_SERIAL) - behave as a ACM Serial device to create a 'USB to Serial' connection which can be used to interoperate with MS-Windows hosts or with the Linux-USB 'cdc-acm' driver.
• g_midi (CONFIG_USB_MIDI_GADGET) - acts as a USB Audio device with one MIDI input and one MIDI output.
• g_printer (CONFIG_USB_G_PRINTER) - channels data between the USB host and a user-space program driving the print engine.
• g_cdc (CONFIG_USB_CDC_COMPOSITE) - provides two functions in one configuration: a CDC Ethernet (ECM) link, and a CDC ACM (serial port) link
• g_acm_ms (CONFIG_USB_G_ACM_MS) - provides two functions in one configuration: a USB Mass Storage device and a CDC ACM (serial port) link
• g_multi (CONFIG_USB_G_MULTI) - A multi-function composite gadget that can provide Ethernet (RNDIS and/or CDC), mass storage, and ACM serial link interfaces
• g_hid (CONFIG_USB_G_HID) - A Human Interface Device (HID) gadget that provides a generic interface for things such as keyboards, mice, touchscreens
• g_webcam - A Webcam Device

Additionally The Linux Configfs (CONFIG_CONFIGFS_FS) support allows complete dynamic configuration of gadget devices from userspace in which case you can create a single configuration or multi-configuration composite device with one or more of the functions available from drivers/usb/gadget/udc/functions. See below for more details on how to use this.

Note that only one gadget driver (device personality) can be loaded at a time but there are some 'composite' gadget drivers that behave as 'composite devices' meaning they have multiple endpoints per USB device. Note that the Vendor ID (VID) and Device ID (DID) that is presented to the USB host is configurable (see ​this linux kernel documentation for details)

LEDE packages only a few of the above drivers, you will find them in **Kernel modules -> USB Support** category.

• kmod-usb-gadget (main driver which should select your device's base usb gadget drivers, may have a different name as seen with Qualcomm-Atheros AR9331 below)
• kmod-usb-gadget-ehci-debug (Kernel support for USB EHCI debug port Gadget)
• kmod-usb-gadget-eth (Kernel support for USB Ethernet Gadget)
• kmod-usb-gadget-mass-storage (Kernel support for USB Gadget Mass Storage)
• kmod-usb-gadget-serial (Kernel support for USB Serial Gadget)

Note that all of these packages will attempt to autoload their respective kernel module so whichever one is alphabetically first will be loaded. You can see what is loaded by looking at the current modules: lsmod | grep g_*

I've tested this on a TP-Link MR3020 minirouter after I replicated the minor hardware modifications I've seen done on a TP-Link WR703N. Both devices use the same SoC, a Qualcomm-Atheros AR9331, and both had a very similar board.

-raspberry pi 4 (or similar) via dtoverlay=dwc2 in config.txt and kmod-usb-dwc2

Please add other known working devices here, and the steps to have the function enabled if they differ from mine.

To get this working on a Qualcomm-Atheros AR9331 device I had to install kmod-usb-chipidea instead of the kmod-usb-gadget (that was not available) and then I installed my gadget driver of choice, kmod-usb-gadget-eth.

That device has 4 MB of flash, so it was a bit more involved than just using opkg, but it's not relevant for enabling USB guest feature.

Here you can see module-specific configuration.

kmod-usb-gadget-eth

The g_ether gadget driver behaves as a USB-to-Ethernet dongle. Once loaded the device-mode system will add a 'usb<n>' network device which can be used the same as any other network device. On the USB host system, a similar network device will appear as long as a driver supporting the 'CDC Ethernet' standard is available.

This module in LEDE is built with the following options:
CONFIG_USB_ETH_RNDIS=y (RNDIS support is an additional and more CPU intensive option that makes this device more compatible with Windows drivers)
CONFIG_USB_ETH_EEM=n (CDC Ethernet Emulation Model (EEM) is a newer standard that has a a simpler interface that can be used by more USB host hardware)

Usage example:

• on target device (a device with an OTG controller) write modprobe g_ether (or nothing, as this module seems to be loaded automatically on boot) and then you will see a usb0 network interface. (you can treat it like any other network interface)
  • module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
  • module parameters can specify the device and host ethernet address and whether or not to use CDC EEM mode
  • To see module parameters write in the console modinfo g_ether (maybe on a PC linux system?)

• on host device (for example a PC or anything else)
  • Linux Host: cdc_ether driver will create a 'usbX' device (X= number) with VID:PID 0525:a4a2, which to most userspace programs will act like a normal ethernet port.
  • Windows Host: in Windows 7 and above in the device manager will appear a 'USB Ethernet/RNDIS Gadget' and can be configured as any other network interface.

The g_file_storage driver behaves as a USB Mass Storage device such as a USB hard-disk or USB flash drive. You can decide whether to use a 'file' as a backing store, or a block device (ie a flash partition, or a physical disk). The file/device is provided to the module via the 'file' module parameter.
The file or device in use by g_mass_storage will NOT be accessible to LEDE system, only to the host device. Also the driver exposes raw block devices (or partitions) so the LEDE system does not need any filesystem driver.
Make sure you choose a partition/filesystem scheme that is compatible with the USB Host system you are going to use (ie, Windows doesn't have native drivers for ext2/ext3/ext4 partitions, so you may want to use VFAT or NTFS, same applies to MacOS/OSX), although you can also use the host to format any partition/file/device you expose like this.

If using a backing storage 'file' you must create it beforehand with its desired size. For example to create a 64MB backing store:

dd bs=1M count=64 if=/dev/zero of=/backing_file

To use this as a backing store:

modprobe g_mass_storage file=/backing_file

You can also use a whole device or partition like this:

modprobe g_mass_storage file=/dev/sda

On host device (ie PC) a USB Mass Storage device (VID:PID 0525:a4a5 by default) will appear and behave as any other USB Mass Storage device (ie flash stick) would.
Module parameters can specify the serialnumber, number of LUNs to support as well as some other low-level features (see 'modinfo g_mass_storage' for details)

https://www.kernel.org/doc/Documentation/usb/mass-storage.txt
http://www.linux-usb.org/gadget/file_storage.html

The Serial Gadget supports CDC-ACM and CDC-OBEX which can inter-operate with the MS-Windows hosts or with Linux hosts using the 'cdc-acm' driver to create a 'USB-to-Serial' connection.

Example:

• on target device load module (should be autoloaded in LEDE)
  

modprobe g_serial

• on host device (ie PC) a USB CDC ACM device (VID:PID 0525:a4a7 by default) will appear and behave as a serial device. On Linux the cdc_acm driver will enumerate this device as '/dev/ttyACMx' (x= number), on Windows new COM ports will appear.

module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber, whether or not to use CDC ACM, CDC OBEX, and the number of ports to create.

https://www.kernel.org/doc/Documentation/usb/gadget_serial.txt

(available on limited devices)

The g_cdc gadget supports two functions in one configuration:

• a CDC Ethernet (ECM) link (USB-to-Ethernet connection)
• a CDC ACM (serial port) link (USB-to-Serial connection)

Example:

on target device load module modprobe g_cdc

on host device (ie PC) a USB CDC ACM device (VID:PID 0525:a4aa) will appear

Linux USB Host notes:
the cdc_acm driver will enumerate this device as '/dev/ttyACM<n>'
the cdc_ether driver will enumerate this device as a 'usb<n>' network device

Windows USB Host notes: A CDC Composite Gadget device will appear in Device Manager

(currently not available in LEDE)

The g_multi gadget supports multiple functions in one configuration:

• a CDC Ethernet (ECM) link
• a CDC ACM (serial port) link
• a USB Mass Storage device

Example:

on target device load module modprobe g_cdc

on host device (ie PC) a USB CDC ACM device (VID:PID 1d6b:0104 by default) will appear
module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
module parameters can specify the ethernet device and host address and queue length multiplier at high speed

Linux USB Host notes:

• the cdc_acm driver will enumerate this device as '/dev/ttyACM<n>'
• the cdc_ether driver will enumerate this device as a 'usb<n>' network device
• the usb-storage driver will provide the USB Mass Storage feature

Windows USB Host notes:

  A Multifunction Composite Gadget device will appear in Device Manager\\
  see ​the Further Reading for details on Windows configuration 

https://www.kernel.org/doc/Documentation/usb/gadget_multi.txt

(available on limited devices)

The HID gadget driver provides generic emulation of USB Human Interface Devices (HID), for example keyboards, mice, touchscreens, etc

Example:

on target device load module modprobe g_hid

module parameters can specify the VID, PID, device version, manufacturer string, product string, serial number

https://www.kernel.org/doc/Documentation/usb/gadget_hid.txt

(currently not available in LEDE)

The g_webcam gadget driver provides a Composite USB Audio and Video Class device.

Example:

on target device load module modprobe g_webcam

on host device (ie PC) a 'Linux Foundation Webcam Gadget' device (VID:PID 1d6b:0102 by default) will appear
on target device (Gateworks board) a /dev/video<n> device will be created and avialable as a Video4Linux output device supporting 320/240 YUYV video
module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber

Linux USB Host notes:
the uvcvideo driver will enumerate the device and create a /dev/videoX (X= number) video capture device

Windows USB Host notes:
A USB Composite device will appear in Device Manager
A UVC Camera device will appear under Imaging devices in the device manager and be available to capture video

(available on limited devices)

The g_ncm gadget driver provides a a USB CDC NCM subclass. NCM is an advanced protocol for Ethernet encapsulation, allowing grouping of several ethernet frames into one USB transfer with various alignment possibilities.

Example:

on target device load module modprobe g_ncm

on host device (ie PC) a 'Linux-USB Ethernet Gadget' device (VID:PID 0525:a4a1 by default) will appear
on target device (Gateworks board) a usb<n> network device will be created
module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
module parameters can specify the device and host ethernet addresses and the queue length multiplier used at high speeds

Linux USB Host notes:
the cdc_ncm driver will enumerate the device and create a /dev/video<n> video capture device

Windows USB Host notes:
A NCM Gadget device will appear in Device Manager

(I don't know what LEDE supports of this paragraph, it will likely require source code contributions to activate this functionality in LEDE builds)

The Linux Configfs (CONFIG_CONFIGFS_FS) support allows complete dynamic configuration of gadget devices from userspace in which case you can create a single configuration or multi-configuration composite device with one or more of the functions available from drivers/usb/gadget/udc/functions:

• usb_f_acm - CDC Serial (ACM - Abstract Control Model)
• usb_f_ecm - CDC Ethernet (ECM - Ethernet Networking Control Model)
• usb_f_eem - CDC Ethernet (EEM - Ethernet Emulation Model)
• usb_f_fs - Filesystem
• usb_f_hid - HID Interface
• usb_f_mass_storage - USB Mass Storage class
• usb_f_midi - MIDI
• usb_f_ncm - CDC Network (NCM - Network Control Model Ethernet)
• usb_f_obex - CDC OBEX (Object Exchange Model)
• usb_f_phonet - CDC Phonet
• usb_f_printer - Printer function
• usb_f_rndis - (Remote Network Driver Interface Specification - Microsoft Ethernet over USB)
• usb_f_serial - Generic serial function
• usb_f_subset - CDC Subset (Ethernet with no control mechanism - just raw data transfer)
• usb_f_uac1 - USB Audio class
• usb_f_uac2 - USB Audio class 2.0
• usb_f_uvc - USB Video class

Examples:

Create a CDC ACM Serial device:

# mount configfs
mount -t configfs none /sys/kernel/config
# load libcomposite module
modprobe libcomposite
# create a gadget
mkdir /sys/kernel/config/usb_gadget/g1
# cd to its configfs node
cd /sys/kernel/config/usb_gadget/g1
# configure it (vid/pid can be anything if USB Class is used for driver compat)
echo 0xabcd > idVendor
echo 0x1234 > idProduct
# configure its serial/mfg/product
mkdir strings/0x409
echo myserial > strings/0x409/serialnumber
echo mymfg > strings/0x409/manufacturer
echo myproduct > strings/0x409/product
# create a config
mkdir configs/c.1
# configure it with attributes if needed
echo 120 > configs/c.1/MaxPower
# ensure function is loaded
modprobe usb_f_acm
# create the function (name must match a usb_f_<name> module such as 'acm')
mkdir functions/acm.0
# associate function with config
ln -s functions/acm.0 configs/c.1
# enable gadget by binding it to a UDC from /sys/class/udc
echo 0000:01:00.0 > UDC
# to unbind it: echo "" UDC; sleep 1; rm -rf /sys/kernel/config/usb_gadget/g1

Create a CDC ECM Ethernet device:

# mount configfs
mount -t configfs none /sys/kernel/config
# load libcomposite module
modprobe libcomposite
# create a gadget
mkdir /sys/kernel/config/usb_gadget/g1
# cd to its configfs node
cd /sys/kernel/config/usb_gadget/g1
# configure it (vid/pid can be anything if USB Class is used for driver compat)
echo 0xabcd > idVendor
echo 0x1234 > idProduct
# configure its serial/mfg/product
mkdir strings/0x409
echo myserial > strings/0x409/serialnumber
echo mymfg > strings/0x409/manufacturer
echo myproduct > strings/0x409/product
# create a config
mkdir configs/c.1
# configure it with attributes if needed
echo 120 > configs/c.1/MaxPower
# ensure function is loaded
modprobe usb_f_ecm
# create the function (name must match a usb_f_<name> module such as 'ecm')
mkdir functions/ecm.0
# associate function with config
ln -s functions/ecm.0 configs/c.1
# enable gadget by binding it to a UDC from /sys/class/udc
echo 0000:01:00.0 > UDC
# to unbind it: echo "" UDC; sleep 1; rm -rf /sys/kernel/config/usb_gadget/g1

Create a USB Mass Storage device (with 2 LUN's 16MB each):

# mount configfs
mount -t configfs none /sys/kernel/config
# load libcomposite module
modprobe libcomposite
# create a gadget
mkdir /sys/kernel/config/usb_gadget/g1
# cd to its configfs node
cd /sys/kernel/config/usb_gadget/g1
# configure it (vid/pid can be anything if USB Class is used for driver compat)
echo 0xabcd > idVendor
echo 0x1234 > idProduct
# configure its serial/mfg/product
mkdir strings/0x409
echo myserial > strings/0x409/serialnumber
echo mymfg > strings/0x409/manufacturer
echo myproduct > strings/0x409/product
# create configs
mkdir configs/c.1
mkdir configs/c.2
mkdir configs/c.3
# configure them with attributes if needed
echo 120 > configs/c.1/MaxPower
echo 120 > configs/c.2/MaxPower
echo 120 > configs/c.2/MaxPower
# ensure function is loaded
modprobe usb_f_mass_storage
# create the function (name must match a usb_f_<name> module such as 'acm')
mkdir functions/mass_storage.0
# create backing store(s): in this example 2 LUN's 16MB each
dd bs=1M count=16 if=/dev/zero of=/tmp/lun0.img # 16MB
dd bs=1M count=16 if=/dev/zero of=/tmp/lun1.img # 16MB
# associate with partitions
mkdir functions/mass_storage.0/lun.0
echo /tmp/lun0.img > functions/mass_storage.0/lun.0/file
mkdir functions/mass_storage.0/lun.1
echo /tmp/lun1.img > functions/mass_storage.0/lun.1/file
# associate function with config
ln -s functions/mass_storage.0 configs/c.1
# enable gadget by binding it to a UDC from /sys/class/udc
echo 0000:01:00.0 > UDC
# to unbind it: echo "" UDC; sleep 1; rm -rf /sys/kernel/config/usb_gadget/g1

https://www.kernel.org/doc/Documentation/usb/gadget_configfs.txt
https://wiki.tizen.org/USB/Linux_USB_Layers/Configfs_Composite_Gadget/General_configuration