Changes between Initial Version and Version 1 of USB_OTG


Ignore:
Timestamp:
10/21/2017 10:28:45 PM (11 months ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • USB_OTG

    v1 v1  
     1[[PageOutline]]
     2
     3= USB On-The-Go (OTG) =
     4USB On-The-Go, often abbreviated USB OTG or just OTG, is a specification that allows USB devices to act as either a host or a device.  In host mode, you can connect a USB device (ie a flash stick/drive, phone, music player, keyboard, etc).  In device mode, you can connect to a host (ie PC) and behave as a specific type of device.
     5
     6The typical 4-pin USB signalling (D+, D-, VUSB, GND) is augmented with a 5th pin called 'ID' which floats to indicate device mode, and is grounded to indicate host mode.  A dual-role controller will sense the state of the ID pin and select its mode taking care to provide VUSB when it is in host mode.
     7
     8There are a variety of USB OTG connectors in both mini and micro form (micro is more popular today where-as mini USB connectors prevailed before 2010).
     9
     10Many of the '''Gateworks Ventana product family single board computers''' all have a USB OTG micro-B connector allowing two types of cable connections:
     11 * a micro-A Adapter allows connection to standard-A USB cables, coming from peripherals (ie phone, flash stick etc)
     12 * a micro-B Adapter is more common and allows connection to standard-B USB cables, going to host controllers such as a PC
     13
     14Product information can be found at [http://www.gateworks.com]
     15
     16== Host Mode ==
     17
     18A Host mode cable allows connecting to a USB device.  No special configuration is necessary for this.
     19
     20[[Image(micro-USB host cable.jpg, 150px)]]
     21
     22
     23== Device Mode ==
     24
     25A Device mode cable allows connection to a USB host such as a PC. 
     26
     27[[Image(micro-USB device cable.jpg, 150px)]]
     28
     29When used in this mode, the device (the Ventana board) needs to have a 'Gadget driver' loaded which impelemnts the personality of the device type you want.  There are several Linux gadget drivers in today's linux kernel:
     30 * g_ether - behave as a 'Communication Device Class' (CDC) Ethernet device to create a 'USB to Ethernet' network connection.
     31 * g_file_storage - acts as a USB Mass Storage disk drive using either a regular file or a block device as its backing store specified as a module parameter or sysfs option
     32 * g_serial - behave as a ACM Serial device to create a 'USB to Serial' connection
     33 * g_cdc - provides two functions in one configuration:  a CDC Ethernet (ECM) link, and a CDC ACM (serial port) link
     34 * g_multi - A multifunction composite gadget that can provide Ethernet (RNDIS and/or CDC), mass storage, and ACM serial link interfaces
     35 * g_hid - A Human Interface Device (HID) gadget that provides a generic interface for things such as keyboards, mice, touchscreens
     36 * g_webcam - A Webcam Device
     37 * g_ncm - USB CDC NCM subclass for Ethernet encapsulation allowing grouping of several ethernet frames into one USB transfer with varying alignment possibilities
     38
     39Note 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 ([http://en.wikipedia.org/wiki/Media_Transfer_Protocol Media Transfer Protocol]) device.
     40
     41Note that the Vendor ID (VID) and Device ID (DID) that is presented to the USB host is configuable (see [https://www.kernel.org/doc/Documentation/usb/gadget_configfs.txt here] for details)
     42
     43Reference:
     44 * https://www.kernel.org/doc/Documentation/usb/gadget_configfs.txt
     45
     46
     47=== g_ether Gadget ===
     48
     49The 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.
     50
     51This module can be built with additional support:
     52 * EEM: CDC Ethernet Emulation Model (EEM) is a newer standard that has a a simpler interface that can be used by more USB host hardware.
     53 * RNDIS: RNDIS support is an additional option (more CPU intensive) that may be more compatible with Windows drivers.
     54
     55Example:
     56 * on target device (Gateworks board with OTG controller):
     57{{{
     58modprobe g_ether
     59}}}
     60  * usb0 network interface appears on target (treat like any other network interface)
     61 * on host device (ie PC) a device with VID:PID 0525:a4a2 will appear conforming to the [http://en.wikipedia.org/wiki/USB_communications_device_class CDC Ethernet] standard
     62  * usb0 appears on Linux host (using the cdc_ether driver)
     63 * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
     64 * module parameters can specify the device and host ethernet address and whether or not to use CDC EEM mode
     65
     66Linux Host Notes:
     67 * cdc_ether driver supports this and will create a 'usb<n>' device on the USB host
     68
     69Windows Host Notes:
     70 * the g_ether driver is typically built with RNDIS support enabled which will make it compatible with drivers in Windows7 and above which will appear in the device manager as a 'USB Ethernet/RNDIS Gadget' and can be configured just as any other network interface.
     71
     72Reference:
     73 * http://en.wikipedia.org/wiki/USB_communications_device_class
     74 * http://en.wikipedia.org/wiki/Ethernet_over_USB
     75
     76
     77=== g_file_storage - USB Mass Storage Device ===
     78
     79The 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.
     80
     81Example (using the first physical disk (/dev/sda) as a backing store):
     82 * on target device  (Gateworks board with OTG controller):
     83  * load module specifying block device (ie /dev/sda the first physical disk device)
     84{{{
     85modprobe g_file_storage file=/dev/sda
     86}}}
     87 * 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.
     88 * module parameters can specify the serialnumber, number of luns to support as well as some other low-level features (see 'modinfo g_file_storage' for details)
     89
     90Using a file as a backing store:
     91 * Create backing storage file (done once, before you load the gadget module)
     92{{{
     93dd bs=1M count=64 if=/dev/zero of=/tmp/backing_file # create empty file
     94}}}
     95  * you can choose to partition it (ie 'printf ",,83,,\n" | sfdisk /tmp/backing_file' for a single linux partition) or partition/format it from the host after connection
     96  * make sure you choose a partition/filesystem scheme that is compatible with the USB Host PC you are going to use (ie, Windows doesn't know how to deal with ext2/ext3/ext4 partitions, so you may want to use VFAT or NTFS)
     97  * specify the path to the backing store via the file parameter (ie 'modprobe g_mass_storage file=/tmp/backing_file')
     98
     99Reference:
     100 * http://www.linux-usb.org/gadget/file_storage.html
     101
     102=== g_serial - Serial Device Gadget ===
     103
     104The 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.
     105
     106Example:
     107 * on target device  (Gateworks board with OTG controller):
     108  * load module
     109{{{
     110modprobe g_serial
     111}}}
     112 * on host device (ie PC) a USB CDC ACM device (VID:PID 0525:a4a7 by default) will appear and behave as a serial device
     113 * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
     114 * module parameters can specify whether or not to use CDC ACM, CDC OBEX, and the number of ports to create
     115
     116Linux USB Host notes:
     117 * the cdc_acm driver will enumerate this device as '/dev/ttyACM<n>'
     118
     119Windows USB Host notes:
     120 * see https://www.kernel.org/doc/Documentation/usb/gadget_serial.txt
     121
     122
     123Reference:
     124 * https://www.kernel.org/doc/Documentation/usb/gadget_serial.txt
     125
     126
     127=== g_cdc - Composite Ethernet + Serial Gadget ===
     128
     129The g_cdc gadget supports two functions in one configuration:
     130 * a CDC Ethernet (ECM) link (USB-to-Ethernet connection)
     131 * a CDC ACM (serial port) link (USB-to-Serial connection)
     132
     133Example:
     134 * on target device  (Gateworks board with OTG controller):
     135  * load module
     136{{{
     137modprobe g_cdc
     138}}}
     139 * on host device (ie PC) a USB CDC ACM device (VID:PID 0525:a4aa) will appear
     140
     141Linux USB Host notes:
     142 * the cdc_acm driver will enumerate this device as '/dev/ttyACM<n>'
     143 * the cdc_ether driver will enumerate this device as a 'usb<n>' network device
     144
     145Windows USB Host notes:
     146 * A CDC Composite Gadget device will appear in Device Manager
     147 * TODO: Is there a driver available that can use this in Windows?  See g_multi below
     148
     149
     150=== g_multi - Composite Ethernet + Serial + Mass Storage Gadget ===
     151
     152The g_multi gadget supports multiple functions in one configuration:
     153 * a CDC Ethernet (ECM) link
     154 * a CDC ACM (serial port) link
     155 * a USB Mass Storage device
     156
     157Example:
     158 * on target device  (Gateworks board with OTG controller):
     159  * load module
     160{{{
     161modprobe g_cdc
     162}}}
     163 * on host device (ie PC) a USB CDC ACM device (VID:PID 1d6b:0104 by default) will appear
     164 * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
     165 * module parameters can specify the ethernet device and host address and queue length multiplier at high speed
     166
     167Linux USB Host notes:
     168 * the cdc_acm driver will enumerate this device as '/dev/ttyACM<n>'
     169 * the cdc_ether driver will enumerate this device as a 'usb<n>' network device
     170 * the usb-storage driver will provide the USB Mass Storage feature
     171
     172Windows USB Host notes:
     173 * A Multifunction Composite Gadget device will appear in Device Manager
     174 * see [https://www.kernel.org/doc/Documentation/usb/gadget_multi.txt here] for details on Windows configuration
     175
     176References:
     177 * https://www.kernel.org/doc/Documentation/usb/gadget_multi.txt
     178
     179=== g_hid - Human Interface Device (HID) Gadget ===
     180
     181The HID gadget driver provides generic emulation of USB Human Interface Devices (HID), for example keyboards, mice, touchscreens, etc
     182
     183Example:
     184 * on target device  (Gateworks board with OTG controller):
     185  * load module
     186{{{
     187modprobe g_hid
     188}}}
     189 * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
     190
     191
     192References:
     193 * https://www.kernel.org/doc/Documentation/usb/gadget_hid.txt
     194
     195
     196=== g_webcam - Composite USB Audio and Video Class Gadget ===
     197
     198The g_webcam gadget driver provides a Composite USB Audio and Video Class device.
     199
     200Example:
     201 * on target device (Gateworks board with OTG controller):
     202  * load module
     203{{{
     204modprobe g_webcam
     205}}}
     206 * on host device (ie PC) a 'Linux Foundation Webcam Gadget' device (VID:PID 1d6b:0102 by default) will appear
     207 * 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
     208 * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
     209
     210Linux USB Host notes:
     211 * the uvcvideo driver will enumerate the device and create a /dev/video<n> video capture device
     212
     213Windows USB Host notes:
     214 * A USB Composite device will appear in Device Manager
     215 * A UVC Camera device will appear under Imaging devices in the device manager and be available to capture video
     216
     217
     218=== g_ncm - USB CDC NCM subclass Ethernet Gadget ===
     219
     220The 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.
     221
     222Example:
     223 * on target device (Gateworks board with OTG controller):
     224  * load module
     225{{{
     226modprobe g_ncm
     227}}}
     228 * on host device (ie PC) a 'Linux-USB Ethernet Gadget' device (VID:PID 0525:a4a1 by default) will appear
     229 * on target device (Gateworks board) a usb<n> network device will be created
     230 * module parameters can specify the VID, PID, device version, manufacturer string, product string, serialnumber
     231 * module parameters can specify the device and host ethernet addresses and the queue length multiplier used at high speeds
     232
     233Linux USB Host notes:
     234 * the cdc_ncm driver will enumerate the device and create a /dev/video<n> video capture device
     235
     236Windows USB Host notes:
     237 * A NCM Gadget device will appear in Device Manager
     238 * see [http://www.thesycon.de/eng/usb_cdcncm.shtml here] for details about a Windows CDC NCM driver
     239
     240= OpenWrt OTG =
     241Use the make kernel_menuconfig to add gadget modules.
     242
     243They are located in Device Drivers > USB support > USB Gadget Support