search

davidcoomer506 / miserver

1 stars 0 forks source link

Info_Miserver_Flow #3

Open davidcoomer506 opened 2 years ago

davidcoomer506 commented 2 years ago

[[PageOutline]]

= USB On-The-Go (OTG) = Certain devices have USB Device Controllers or Dual-Role controllers that can be used in either host mode or device mode.

This page aims to document how to use and configure USB OTG gadget devices on Linux for boards you wish to connect to a USB Host port and behave like a 'device'.

See also [wiki:USB_OTG USB_OTG]

This wiki page is created for use on [https://www.gateworks.com/products/ Gateworks Rugged and Industrial Single Board Computers] Made in the USA.

Note: Newport SBC's do not support OTG/Device/Gadget modes.
[=#host] == USB Host Mode == A Host mode cable allows connecting to a USB device. No special configuration is necessary for this.

[=#device] == USB Device Mode == 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 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 [#configfs 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 (​[http://en.wikipedia.org/wiki/Media_Transfer_Protocol Media Transfer Protocol]) device.

Note that the Vendor ID (VID) and Device ID (DID) that is presented to the USB host is configurable (see [https://www.kernel.org/doc/Documentation/usb/gadget_configfs.txt ​here] for details)

[=#g_ether] === g_ether Gadget === The g_ether gadget driver behaves as a USB-to-Ethernet dongle. Once loaded the device-mode system will add a 'usb' 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:

Linux Host Notes:

Windows Host Notes:

Reference:

[=#g_mass_storage] === g_mass_storage - USB Mass Storage Device === 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: {{{#!bash dd bs=1M count=64 if=/dev/zero of=/backing_file }}}

To use this as a backing store: {{{#!bash modprobe g_mass_storage file=/backing_file }}}

References:

[=#g_serial] === g_serial - Serial Device Gadget === 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:

Linux USB Host notes:

Windows USB Host notes:

Reference:

[=#g_cdc] === g_cdc - Composite Ethernet + Serial Gadget === The g_cdc gadget supports two functions in one configuration:

Example:

Linux USB Host notes:

Windows USB Host notes:

[=#g_multi] === g_multi - Composite Ethernet + Serial + Mass Storage Gadget === The g_multi gadget supports multiple functions in one configuration:

Example:

Linux USB Host notes:

Windows USB Host notes:

References:

[=#g_hid] === g_hid - Human Interface Device (HID) Gadget === The HID gadget driver provides generic emulation of USB Human Interface Devices (HID), for example keyboards, mice, touchscreens, etc

Example:

References:

[=#g_webcam] === g_webcam - Composite USB Audio and Video Class Gadget === The g_webcam gadget driver provides a Composite USB Audio and Video Class device.

Example:

Linux USB Host notes:

Windows USB Host notes:

[=#g_ncm] === g_ncm - USB CDC NCM subclass Ethernet Gadget === 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:

Linux USB Host notes:

Windows USB Host notes:

[=#configfs] === !ConfigFs === 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:

References:

[=#openwrt] == OpenWrt OTG == 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: {{{#!bash lsmod | grep g_* }}}

[=#dual-role] == OTG Mode selection USB OTG host controllers are 'dual-role' controllers in that they can behave as a {{{USB host}}} or a {{{USB peripheral}}}. The decision on which mode to be in is typically controlled by the state of the OTG ID pin (OTG_ID) which is grounded on OTG to host cables, and left floating on OTG to device cables.

In some cases you may have a board without an OTG_ID signal where you still want to use USB OTG in device mode.

Dual-role controllers can be forced into 'host' mode or 'peripheral' mode via the device-tree 'dr_mode' property. For example to force an IMX6 OTG controller to peripheral mode add 'dr_mode = "peripheral";' to the dt such as: {{{ &usbotg {         vbus-supply = <&reg_5p0v>;         pinctrl-names = "default";         pinctrl-0 = <&pinctrl_usbotg>;         disable-over-current;         dr_mode = "peripheral";         status = "okay"; }; }}}

This can be done in the bootloader, here's an example for GW54xx:

{{{#!bash setenv fixfdt 'fdt addr ${fdt_addr}; fdt resize; fdt set /soc/aips-bus@2100000/usb@2184000 dr_mode host' # host mode setenv fixfdt 'fdt addr ${fdt_addr}; fdt resize; fdt set /soc/aips-bus@2100000/usb@2184000 dr_mode gadget' # gadget mode saveenv #once you have made your selection }}}

Additionally some host controllers such as the Chips and Media controller used on the IMX6 have hooks that allow them to be configured at runtime in Linux Userspace. For example on IMX6 boards: {{{#!bash cat /sys/kernel/debug/ci_hdrc.0/role # see current role; default dictated by dr_mode dt property or state of OTG_ID pin if not set echo gadget > /sys/kernel/debug/ci_hdrc.0/role # specify device mode echo host > /sys/kernel/debug/ci_hdrc.0/role # specify host mode }}}

[=#device-mode] == Using a Non-OTG port in device mode In some cases you can use a USB Type-A socket in device mode in a non-standard way. This can be used for example on boards that route a USB OTG controller to a Type-A socket which does not have an OTG_ID signal. In this case you need to isolate VBUS to ensure both the host and the device are not both driving it at the same time. This opportunity exists on certain Ventana boards (where the 'usbotg' host controller is enabled in the device-tree yet the signals route to a USB Type-A socket connector instead of an OTG controller).

In this case you can do the following:

  1. use a non-standard Type-A plug to Type-A plug cable and isolate the VBUS (red wire) to ensure host and device are not both driving VBUS
  2. configure the OTG controller for device-mode (see [#dual-role above])
  3. Load a gadget driver (see [#device above])
davidcoomer506 commented 1 year ago

All I ever wanted to do was to play with my gadgets and learn what I can learn to be team member have a domain website and server maybe one day.