The USB (Universal Serial Bus) standard specifies two roles USB host and USB peripheral (also known as USB function, USB peripheral device or sometimes just USB device). The bus can only have one USB host connected all other devices need to be in USB peripheral mode. Most PCs support USB host mode exclusively. However, embedded systems often have multiple USB controller supporting host or peripheral roles or supporting both roles on a single controller (dual-role controller). The dual-role controllers often also support the OTG (On-The-Go) specification which defines a host negotiation protocol allowing two devices to negotiate for the role of the host.

On Colibri modules the client port (USBC) is usually connected to a dual-role capable controller. By default the port is in peripheral mode. If a USB Micro-B OTG cable is used (which connects the ID pin to ground) the circuit on the carrier board automatically enables driving +5V onto VBUS in order to provide power to USB devices as required by a host. On the other hand VBUS is also connected to the Colibri USBC_DET signal (usually via a diode) allowing driver software to monitor and subsequently change the role. On Apalis modules a full OTG port (USBO1) is provided which makes use of the OTG ID pin using the USBO1_ID signal to determine its role and additionally the VBUS pin using the USBO1_VBUS signal to determine the actual connection status thereof allowing suspending the USB complex if not connected.

On Linux USB peripheral mode is supported through the Gadget API. This API abstracts the USB peripheral controller hardware as well as offers hardware neutral routines which allow to implement USB functions (e.g. USB CDC ACM or RNDIS). Traditionally the USB function had to be chosen at Kernel compile time (e.g. g_ether). The Linux USB gadget drivers received increasingly more attention and have evolved over time, especially since Android appeared. The Android variant of the Linux kernel added functionality allowing easy switching between USB functions using sysfs. Later in Linux 3.10 a similar functionality also landed in the upstream kernel which now allows configuring USB gadgets through configfs (the USB Gadget ConfigFS). Depending on the Linux kernel version provided by our BSP a different level of USB peripheral functionality and API is available.

USB peripheral devices need a vendor and product identification. Toradex has its own vendor ID (0x1b67) and assigns a product ID for each Colibri and Apalis product which you as a customer can use too. The USB Product ID is the sum of an offset of 0x4000 and the hexadecimal representation of the product identifier, e.g. 0x4000 + 14 = 0x400e (the product identifier is the first 4 digits of the Toradex Product Number, e.g. 0014 for Colibri VF61 256MB IT).

Some platforms need device dependent and certified drivers (e.g. CDC ACM for Microsoft Windows) even for standard USB classes. While it is possible to use the driver delivered with Windows a custom inf file still needs to be provided. For better out-of-the-box experience the standard images typically use the default Linux USB product/vendor ID (e.g. 1d6b:0104 Linux Foundation Multifunction Composite Gadget).

The USB Gadget ConfigFS is a file system which allows to configure USB functions by using file system commands such as mkdir and creating/writing files. Typically the file system is mounted under /sys/kernel/config/. The official Linux kernel documentation has more information in Documentation/usb/gadget_configfs.txt on how to use the file system to enable USB functions. Matt Porter held a talk at ELC 2014 titled Kernel USB Gadget Configfs Interface cover the Gadget ConfigFS a bit more in depth.

The library libusbg allows to use the USB Gadget ConfigFS through a C API. This can be useful if embedded software needs to dynamically control USB functions provided by a device. The library also provides two utilities called gadget-import and gadget-export. This utilities allow to export a hand-crafted USB Gadget to a schema file and reimport it. The BSP provides a default schema specifying two configurations (USB functions), RNDIS and CDC ACM, under /etc/usbg/g1.schema. A systemd service called usbg.service uses gadget-import to import this schema on startup (see libusbg: add updated version of USB gadget library).

To alter the schema, one can either create a completely new gadget schema, alter the existing gadget and reexport it, or alter the schema directly (for simple changes).

This example shows how to create a completely new configuration., to create a Gadget configuration for the a single USB CDC (Communications Device Class) Ethernet (ECM).

Then, one or multiple configurations can be assigned. A Gadget supporting multiple configurations (USB functions) is also known as a composite gadget. Note that depending on the operating system used on the USB host device, it might be problematic to use such configurations (see also Documentation/usb/gadget_multi.txt)

Functions can be created by creating a directory like functions/.. The following table provides a (incomplete) list of available functions in the Linux kernel. Up to V2.5 Beta 1, only the Gadget drivers for RNDIS and CDC ACM (serial) functions have been built into the kernel. Newer BSP provide all Gadget functions in this list as kernel modules:

To enable this configuration write the name of the USB controller to the UDC file (see /sys/class/udc/ for available USB Device Controllers). You need to disable the old configuration first before enabling the new one:

USB Mass Storage allows exporting any block device from the target module to a PC and use it just in the same way as any regular USB memory stick.

Note: Whatever block device you export by using this method, it can not be in use on the target module side (e.g. by a file system driver). Otherwise the simultaneously accessing file system drivers would corrupt the file system on the block device!

The example below shows how a regular SD card inside one of the Apalis Evaluation board's slots can be shared:

The Vibrante kernel in our V1.x BSPs contained the g_ether driver which acts as an Ethernet over USB controller (CDC Ethernet) by default. The later L4T kernel in our V2.x BSPs comes with the Android RNDIS Ethernet gadget driver. Most nowadays operating system (including Linux, Windows 7) include respective host drivers (plug and play). Our latest BSPs now run a DHCP server on the module to automatically assign your PC an IP address upon USB device connection.