See OTG for more info.
A Host mode cable allows connecting to a USB device. No special configuration is necessary for this.
A Device mode cable allows connection to a USB host such as a PC.
When used in this mode, the device needs to have a 'Gadget driver' loaded which implements the personality of the device type you want.
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:
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. This will seem familiar if you think of how a modern smart-phone works. Take an Android phone for example: When plugged into a host PC via micro-USB OTG, it will behave as a storage device (MTP), however if you want to have it behave as a serial debug device you have to go into the developer menu and select this option. Note that modern smartphones no longer behave as 'USB Mass Storage' devices as this protocol does not allow the device OS to access the filesystem at the same time the host PC does - instead these devices act as an MTP (Media Transfer Protocol) device.
Note that the Vendor ID (VID) and Device ID (DID) that is presented to the USB host is configuable (see here for details)
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 can be built with additional support:
Example:
modprobe g_ether
Linux Host Notes:
Windows Host Notes:
Reference:
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.
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
References:
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.
This gadget driver was repaced with g_mass_storage in Linux 3.8
Example (using the first physical disk (/dev/sda) as a backing store):
modprobe g_file_storage file=/dev/sda
Using a file as a backing store:
dd bs=1M count=64 if=/dev/zero of=/tmp/backing_file # create empty file
Reference:
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:
modprobe g_serial
Linux USB Host notes:
Windows USB Host notes:
Reference:
The g_cdc gadget supports two functions in one configuration:
Example:
modprobe g_cdc
Linux USB Host notes:
Windows USB Host notes:
The g_multi gadget supports multiple functions in one configuration:
Example:
modprobe g_cdc
Linux USB Host notes:
Windows USB Host notes:
References:
The HID gadget driver provides generic emulation of USB Human Interface Devices (HID), for example keyboards, mice, touchscreens, etc
Example:
modprobe g_hid
References:
The g_webcam gadget driver provides a Composite USB Audio and Video Class device.
Example:
modprobe g_webcam
Linux USB Host notes:
Windows USB Host notes:
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:
modprobe g_ncm
Linux USB Host notes:
Windows USB Host notes:
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:
Note that not all of the above kernel modules may be available depending on your kernel configuration or BSP.
Examples:
# 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
# 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
# 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
References:
OpenWrt packages several of the above Linux kernel modules as packages:
You must have gadget support enabled:
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_*