EMAC OE USB Gadget Connections

TODO: {{#todo:Polish and review (11.11.13-19:30->MD-)|Michael Welling|oe 4,oe 5,mw,md,InProgress}}

Systems that have a USB device port can be connected to a PC or other system through a USB host port. A USB cable will need to be connected between the USB device port on the board and a USB host port on the other system. This page covers the process of establishing a connection using the gadget Ethernet driver and several of the available USB gadget function drivers. More information regarding the USB Gadget drivers for Linux can be found at the Linux USB Project.

USB Gadget Ethernet

The USB Gadget Ethernet driver allows a device to enumerate and communicate as an Ethernet device over the USB link. On the host system, this requires the usbnet driver for a Linux system or the RNDIS driver for Windows hosts.

Device-side Configuration

To establish a connection, first create an entry in the /etc/network/interfaces file on the device system for the usb0 interface. An example of this configuration is shown below. Note that in almost all circumstances you will need to use a different subnetwork for the USB Ethernet link than what is used for the LAN connection on either the host or device system in order to prevent conflicts.

allow-hotplug usb0
iface usb0 inet static
    address 192.168.0.2
    netmask 255.255.255.0
    gateway 192.168.0.1

Host-side Configuration

Each section needs to be self-standing. For this section to be self-standing, the first sentence needs to not start with the word, "also." A bit of background information should be given to explain why this configuration is needed, even if it seems obvious. The little bit of extra information makes it come across as less dry to read and assumes less of the reader.

Also, add a configuration for the device connection on the host. The configuration will vary depending on the host operating system and flavor. The IP address of the host should be set to the value used for the gateway setting on the device (192.168.0.1 using the example above). An example configuration for a system that uses the /etc/network/interfaces networking configuration is shown below.

allow-hotplug usb0
iface usb0 inet static
    address 192.168.0.1
    netmask 255.255.255.0
    gateway 192.168.0.1

Initializing the Connection

Once the configuration is finished and the host and device systems are connected via a USB cable, load the gadget Ethernet driver on the device with the following command.

root@emac-oe:~# modprobe g_ether

After loading the driver, ifconfig should show an entry for the usb0 interface. Depending on the configuration, you may need to run ifup usb0 to configure the device.

The host system will most likely automatically detect and load the appropriate drivers. If this does not occur, verify that the usbnet driver is installed and loaded on a Linux distribution. See the Microsoft RNDIS driver documentation for more information on configuring this driver for Windows hosts. There should be example output from running ifconfig with the usb0 interface shown. This will give them an idea of what to look for. Remember, many/most of the people using this will be new to the ifconfig command.

Testing the Network Connection

Use the ping command to test that the connection sends and receives packets correctly. Once this has been verified, you should be able to use any network service to transfer data between the two systems.

USB Gadget Serial

The USB Gadget Serial driver can be used to emulate a serial port over a USB cable. This can be a useful method for getting serial access to the target machine from a system that does not have a serial port or when there is no spare serial port on the target system to utilize for access. Note that there is limited support for using the USB gadget serial device as a console for accessing the bootloader on most systems, so a hardware serial console is generally required for development.

Device-side Configuration

Serial device connections between the target board and host utilize the g_serial driver. This allows for data transfer using the standard serial programming API and existing serial terminal applications. Several parameters may be passed to the g_serial module, as seen in the modinfo listing below:

root@emac-oe:~# modinfo g_serial
filename:       /lib/modules/2.6.28/kernel/drivers/usb/gadget/g_serial.ko
license:        GPL
author:         David Brownell
author:         Al Borchers
description:    Gadget Serial v2.4
license:        GPL
author:         Felipe Balbi
depends:        at91_udc
vermagic:       2.6.28 preempt mod_unload ARMv5
parm:           idVendor:USB Vendor ID (ushort)
parm:           idProduct:USB Product ID (ushort)
parm:           bcdDevice:USB Device version (BCD) (ushort)
parm:           iManufacturer:USB Manufacturer string (charp)
parm:           iProduct:USB Product string (charp)
parm:           iSerialNumber:SerialNumber string (charp)
parm:           use_acm:Use CDC ACM, default=yes (bool)
parm:           use_obex:Use CDC OBEX, default=no (bool)
parm:           n_ports:number of ports to create, default=1 (uint)

In most cases, the default settings will be acceptable and the driver may be loaded using the following command:

root@emac-oe:~# modprobe g_serial

After loading the module, connect a USB cable between the device port and the host machine. Once connected, dmesg should indicate that the connection was detected and associated with g_serial.

Host-side Configuration

The host can be running a variety of environments including Linux, Windows, or any other system with a driver implementing the CDC ACM class. This section covers the basic configuration of a Linux host; see the Documentation/usb/gadget_serial.txt file in the Linux kernel source for your target board for detailed information on how to configure both Linux and Windows hosts.

If you can find a link to point them directly to a copy of the gadget_serial.txt file on the net that won't change, it should be put in the above paragraph.

On a Linux PC, the lsusb command or contents of the /proc/bus/usb/devices file should indicate that the device is connected and show the vendor and product ID used by the device. On some Linux distributions, a window may be displayed notifying you that it has detected a USB serial connection. If this occurs, you can skip forward to the Testing the Connection section. Otherwise, you will need to register and attach the device.

Registering and Attaching to the Device

To enable serial communication over the USB cable, the cdc_acm or usbserial drivers can be registered and associated to the device.

A note should be made here that on some distributions, such as Ubuntu, no configuration is needed on the host side. Therefore, they should test first to see if it came up automatically, and only follow these extra steps if they have to.

CDC ACM

If the Linux host system is configured to use the ACM driver and the g_serial driver on the device is loaded in ACM mode (the default), the host system should automatically load the cdc_acm driver, connect to the device, and create the required device node (/dev/ttyACM0 unless other ACM devices are registered on the system). The partial dmesg output below illustrates this connection being detected and created:

developer@emac-ldc:~# dmesg | tail
usb 2-1.3: New USB device found, idVendor=0525, idProduct=a4a7
usb 2-1.3: New USB device strings: Mfr=1, Product=2, SerialNumber=0
usb 2-1.3: Product: Gadget Serial v2.4
usb 2-1.3: Manufacturer: Linux 2.6.28 with at91_udc
usb 2-1.3: configuration #2 chosen from 1 choice
cdc_acm 2-1.3:2.0: This device cannot do calls on its own. It is not a modem.
cdc_acm 2-1.3:2.0: ttyACM0: USB ACM device

Generic USB Serial

In order to use the generic USB serial driver, the target device should be configured to use the generic serial configuration rather than ACM mode. This can be done by passing use_acm=0 as an option when the g_serial driver is loaded.

You must explicitly specify the device that the usbserial driver will be associated with using a pair of ID numbers. In this example, the vendor ID for the device is 0x0525 and the product ID is 0xA4A6. These IDs may vary depending on the device. Use the contents of /proc/bus/usb/devices to verify the correct ID values and pass these to the usbserial driver as shown in the example below:

developer@emac-ldc:~# sudo modprobe usbserial vendor=0x0525 product=0xA4A6

The kernel messages should indicate that the driver has been associated correctly and that the USB serial device node has been created (usually this will be /dev/ttyUSB0). See the listing below for example dmesg output.

developer@emac-ldc:~# sudo dmesg | tail
usb 4-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 4-2: Product: Gadget Serial
usb 4-2: Manufacturer: Linux 2.6.25 with at91_udc
usb 4-2: SerialNumber: 0
usbcore: registered new interface driver usbserial
drivers/usb/serial/usb-serial.c: USB Serial support registered for generic
usbserial_generic 4-2:1.0: generic converter detected
usb 4-2: generic converter now attached to ttyUSB0
usbcore: registered new interface driver usbserial_generic
drivers/usb/serial/usb-serial.c: USB Serial Driver core

Testing the Connection

To test the USB serial interface, use a standard terminal application such as minicom. The microcom application on the EMAC OE system can be used for the target board interface. The device on the Linux PC will be named /dev/ttyACM0 if using the CDC ACM interface, or /dev/ttyUSB0 if using the generic USB serial driver (assuming that this is the only USB serial device connected); the device node on the target system will be /dev/ttyGS0.

root@emac-oe:~# microcom -s 115200 /dev/ttyGS0
.... 
developer@emac-ldc:~$ minicom -s

Login Terminal

It is possible to add a login terminal on the USB gadget serial device. Although the getty can be started manually, typically this would be done through an entry in the /etc/inittab file. Follow the steps below to configure the system to start a login console on the USB serial gadget connection automatically on boot.

1. First, configure the system to load the g_serial module automatically on system boot. This can be done using the following command assuming that the root filesystem has been mounted read/write:
   root@emac-oe:~# echo "g_serial" >> /etc/modules
2. Edit /etc/inittab to add an entry for the required getty on the /dev/ttyGS0 device. The following line is an example of this configuration:
   S1:5:respawn:/sbin/getty 115200 ttyGS0
3. Reboot the board and verify that you can log in to the system through the USB device interface.

Other USB Gadget Connections

Several other USB gadget drivers are available, including MIDI, printer, and file storage. See the Linux USB Project and the kernel source for your target device for more information.