Difference between revisions of "EMAC OE USB Gadget Connections"

From wiki.emacinc.com
Jump to: navigation, search
(Registering and Attaching to the Device)
 
(36 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{todo|Polish and review (11.11.13-19:30->MD-)|Michael Welling|project=oe 4,oe 5,mw,md,InProgress}}
+
{{todo|SEOKWREV (11.11.13-19:30->MD-);(11.26.13-13:24->MW+);(11.26.13-19:00->MD+);(12.06.13-15:46->MW+);(12.09.13-20:10->MD+);(12.10.13-19:30->KY+);(03.06.14-14:50->BS-);(04.10.14-15:00->BS+)|Michael Welling|project=oe 4,oe 5,mw,md,bs,SEOKWREV}}
  
Many of EMAC's ARM based products provide the capability of using them as a USB device. Systems that have a USB device port can be connected to another computer via a USB cable. Once connected, the USB connection can be used for communication or USB device emulation. This can be especially useful in situations when Ethernet or serial connection is not readily available. For instance, field updates can be performed on a device without interrupting possibly critical Ethernet or serial communications.
+
{{#seo:
 +
|title=EMAC OE USB Gadget Connections
 +
|titlemode=append
 +
|keywords=USB Connections,Device Configuration,Host Configuration,CDC ACM
 +
|description=This page covers the process of establishing a connection using the Gadget Ethernet and Serial drivers.
 +
}}
 +
Many of EMAC's ARM based products provide the capability of using them as USB devices via a USB cable. The USB connection can be used for communication or USB device emulation. This can be especially useful in situations when Ethernet or serial connection is not readily available. For instance, field updates can be performed on a device without interrupting possibly critical Ethernet or serial communications.
  
 
The Linux USB Gadget API was developed to make it easier to provide such USB device services. This page covers the process of establishing a connection using the Gadget Ethernet and Serial drivers. More information regarding the USB Gadget drivers for Linux can be found at the [http://linux-usb.org/gadget Linux USB Project].
 
The Linux USB Gadget API was developed to make it easier to provide such USB device services. This page covers the process of establishing a connection using the Gadget Ethernet and Serial drivers. More information regarding the USB Gadget drivers for Linux can be found at the [http://linux-usb.org/gadget Linux USB Project].
Line 17: Line 23:
  
 
=== Host-side Configuration ===
 
=== 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. '''
+
After the device is configured for a Gadget Ethernet connection it is necessary to configure the host to allow the connection. 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 <code>/etc/network/interfaces</code> networking configuration is shown below.
 
 
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 <code>/etc/network/interfaces</code> networking configuration is shown below.
 
 
  allow-hotplug usb0
 
  allow-hotplug usb0
 
  iface usb0 inet static
 
  iface usb0 inet static
Line 25: Line 29:
 
     netmask 255.255.255.0
 
     netmask 255.255.255.0
 
     gateway 192.168.0.1
 
     gateway 192.168.0.1
 +
 +
When configured properly the host will present an interface similar to other network interfaces.
  
 
=== Initializing the Connection ===
 
=== 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.
+
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
 
  root@emac-oe:~# modprobe g_ether
 
After loading the driver, <code>ifconfig</code> should show an entry for the usb0 interface. Depending on the configuration, you may need to run <code>ifup usb0</code> to configure the device.
 
After loading the driver, <code>ifconfig</code> should show an entry for the usb0 interface. Depending on the configuration, you may need to run <code>ifup usb0</code> 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 [http://msdn.microsoft.com/en-us/library/windows/hardware/gg463293.aspx Microsoft RNDIS driver documentation] for more information on configuring this driver for Windows hosts.
+
To determine if the device is registered properly you can use <code>ifconfig</code> as shown below.
'''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.'''
+
root@emac-oe:~# ifconfig usb0
 +
usb0      Link encap:Ethernet  HWaddr F2:D5:0C:DC:B4:FB
 +
          inet addr:192.168.0.2  Bcast:192.168.10.255  Mask:255.255.255.0
 +
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
 +
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0         
 +
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
 +
          collisions:0 txqueuelen:1000
 +
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)
 +
 
 +
The host system will most likely automatically detect and load the appropriate drivers. If this does not occur, verify that the <code>usbnet</code> driver is installed and loaded on a Linux distribution. See the [http://msdn.microsoft.com/en-us/library/windows/hardware/gg463293.aspx Microsoft RNDIS driver documentation] for more information on configuring this driver for Windows hosts.
  
 
=== Testing the Network Connection ===
 
=== Testing the Network Connection ===
 
Use the <code>ping</code> 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.
 
Use the <code>ping</code> 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.
 +
 +
Here is an example output from pinging the target from a host system via the USB Ethernet connection:
 +
developer@ldc:~$ ping 192.168.0.2
 +
PING 192.168.0.2 (192.168.0.2) 56(84) bytes of data.
 +
64 bytes from 192.168.0.2: icmp_req=1 ttl=64 time=0.458 ms
 +
64 bytes from 192.168.0.2: icmp_req=2 ttl=64 time=0.464 ms
 +
64 bytes from 192.168.0.2: icmp_req=3 ttl=64 time=0.460 ms
 +
64 bytes from 192.168.0.2: icmp_req=4 ttl=64 time=0.535 ms
 +
64 bytes from 192.168.0.2: icmp_req=5 ttl=64 time=0.376 ms
 +
^C
 +
--- 192.168.0.2 ping statistics ---
 +
5 packets transmitted, 5 received, 0% packet loss, time 3997ms
 +
rtt min/avg/max/mdev = 0.376/0.458/0.535/0.055 ms
  
 
== USB Gadget Serial ==
 
== USB Gadget Serial ==
Line 75: Line 103:
 
To enable serial communication over the USB cable, the <code>cdc_acm</code> or <code>usbserial</code> drivers can be registered and associated to the device.  
 
To enable serial communication over the USB cable, the <code>cdc_acm</code> or <code>usbserial</code> drivers can be registered and associated to the device.  
  
{{Fmbox | type = | text = 'Some distributions, such as Ubuntu, require no configuration on the host side.  Test to see if it came up automatically, and only follow these extra steps if required.'}}
+
{{mbox | type=caution | text = Some distributions, such as Ubuntu, require no configuration on the host side.  Test to see if it came up automatically, and only follow these extra steps if required.}}
  
 
===== CDC ACM =====
 
===== CDC ACM =====
Line 117: Line 145:
  
 
# First, configure the system to load the <code>g_serial</code> module automatically on system boot. This can be done using the following command assuming that the root filesystem has been mounted read/write:<br><code>root@emac-oe:~# echo "g_serial" >> /etc/modules</code>
 
# First, configure the system to load the <code>g_serial</code> module automatically on system boot. This can be done using the following command assuming that the root filesystem has been mounted read/write:<br><code>root@emac-oe:~# echo "g_serial" >> /etc/modules</code>
# Edit <code>/etc/inittab</code> to add an entry for the required <code>getty</code> on the <code>/dev/ttyGS0</code> device. The following line is an example of this configuration:<br><code>S1:5:respawn:/sbin/getty 115200 ttyGS0</code>
+
# Edit <code>/etc/inittab</code> to add an entry for the required <code>getty</code> on the <code>/dev/ttyGS0</code> device. The following line is an example of this configuration:<br><code>S1:2345:respawn:/sbin/getty 115200 ttyGS0</code>
 
# Reboot the board and verify that you can log in to the system through the USB device interface.
 
# Reboot the board and verify that you can log in to the system through the USB device interface.
 +
 +
{{mbox | type=caution | text = For a detailed explanation regarding the syntax for the line which starts the <code>getty</code>, please see [http://www.tldp.org/LDP/sag/html/config-init.html this page].  This page can be useful for configuring custom applications to run on a serial port, as well. }}
 +
 +
Below is an example /etc/inittab with the entry for ttyGS0:
 +
<syntaxhighlight lang="bash">
 +
# /etc/inittab: init(8) configuration.
 +
# $Id: inittab,v 1.91 2002/01/25 13:35:21 miquels Exp $
 +
 +
# The default runlevel.
 +
id:5:initdefault:
 +
 +
# Boot-time system configuration/initialization script.
 +
# This is run first except when booting in emergency (-b) mode.
 +
si::sysinit:/etc/init.d/rcS
 +
 +
# What to do in single-user mode.
 +
~~:S:wait:/sbin/sulogin
 +
 +
# /etc/init.d executes the S and K scripts upon change
 +
# of runlevel.
 +
#
 +
# Runlevel 0 is halt.
 +
# Runlevel 1 is single-user.
 +
# Runlevels 2-5 are multi-user.
 +
# Runlevel 6 is reboot.
 +
l0:0:wait:/etc/init.d/rc 0
 +
l1:1:wait:/etc/init.d/rc 1
 +
l2:2:wait:/etc/init.d/rc 2
 +
l3:3:wait:/etc/init.d/rc 3
 +
l4:4:wait:/etc/init.d/rc 4
 +
l5:5:wait:/etc/init.d/rc 5
 +
l6:6:wait:/etc/init.d/rc 6
 +
# Normally not reached, but fallthrough in case of emergency.
 +
z6:6:respawn:/sbin/sulogin
 +
S:2345:respawn:/sbin/getty 115200 ttyS3
 +
S1:2345:respawn:/sbin/getty 115200 ttyGS0
 +
</syntaxhighlight>
  
 
== Other USB Gadget Connections ==
 
== Other USB Gadget Connections ==
 
Several other USB gadget drivers are available, including MIDI, printer, and file storage. See the [http://linux-usb.org/gadget Linux USB Project] and the kernel source for your target device for more information.
 
Several other USB gadget drivers are available, including MIDI, printer, and file storage. See the [http://linux-usb.org/gadget Linux USB Project] and the kernel source for your target device for more information.
  
[[Category:Linux]]
+
<!--[[Category:Linux]]
[[Category:OpenEmbedded]]
+
[[Category:OpenEmbedded]]-->

Latest revision as of 15:07, 10 April 2014

TODO: {{#todo:SEOKWREV (11.11.13-19:30->MD-);(11.26.13-13:24->MW+);(11.26.13-19:00->MD+);(12.06.13-15:46->MW+);(12.09.13-20:10->MD+);(12.10.13-19:30->KY+);(03.06.14-14:50->BS-);(04.10.14-15:00->BS+)|Michael Welling|oe 4,oe 5,mw,md,bs,SEOKWREV}}

Many of EMAC's ARM based products provide the capability of using them as USB devices via a USB cable. The USB connection can be used for communication or USB device emulation. This can be especially useful in situations when Ethernet or serial connection is not readily available. For instance, field updates can be performed on a device without interrupting possibly critical Ethernet or serial communications.

The Linux USB Gadget API was developed to make it easier to provide such USB device services. This page covers the process of establishing a connection using the Gadget Ethernet and Serial 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

After the device is configured for a Gadget Ethernet connection it is necessary to configure the host to allow the connection. 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

When configured properly the host will present an interface similar to other network interfaces.

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.

To determine if the device is registered properly you can use ifconfig as shown below.

root@emac-oe:~# ifconfig usb0 
usb0      Link encap:Ethernet  HWaddr F2:D5:0C:DC:B4:FB
          inet addr:192.168.0.2  Bcast:192.168.10.255  Mask:255.255.255.0
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0           
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)

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.

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.

Here is an example output from pinging the target from a host system via the USB Ethernet connection:

developer@ldc:~$ ping 192.168.0.2
PING 192.168.0.2 (192.168.0.2) 56(84) bytes of data.
64 bytes from 192.168.0.2: icmp_req=1 ttl=64 time=0.458 ms
64 bytes from 192.168.0.2: icmp_req=2 ttl=64 time=0.464 ms
64 bytes from 192.168.0.2: icmp_req=3 ttl=64 time=0.460 ms
64 bytes from 192.168.0.2: icmp_req=4 ttl=64 time=0.535 ms
64 bytes from 192.168.0.2: icmp_req=5 ttl=64 time=0.376 ms
^C
--- 192.168.0.2 ping statistics ---
5 packets transmitted, 5 received, 0% packet loss, time 3997ms
rtt min/avg/max/mdev = 0.376/0.458/0.535/0.055 ms

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.

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.

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:2345:respawn:/sbin/getty 115200 ttyGS0
  3. Reboot the board and verify that you can log in to the system through the USB device interface.

Below is an example /etc/inittab with the entry for ttyGS0:

# /etc/inittab: init(8) configuration.
# $Id: inittab,v 1.91 2002/01/25 13:35:21 miquels Exp $

# The default runlevel.
id:5:initdefault:

# Boot-time system configuration/initialization script.
# This is run first except when booting in emergency (-b) mode.
si::sysinit:/etc/init.d/rcS

# What to do in single-user mode.
~~:S:wait:/sbin/sulogin

# /etc/init.d executes the S and K scripts upon change
# of runlevel.
#
# Runlevel 0 is halt.
# Runlevel 1 is single-user.
# Runlevels 2-5 are multi-user.
# Runlevel 6 is reboot.
l0:0:wait:/etc/init.d/rc 0
l1:1:wait:/etc/init.d/rc 1
l2:2:wait:/etc/init.d/rc 2
l3:3:wait:/etc/init.d/rc 3
l4:4:wait:/etc/init.d/rc 4
l5:5:wait:/etc/init.d/rc 5
l6:6:wait:/etc/init.d/rc 6
# Normally not reached, but fallthrough in case of emergency.
z6:6:respawn:/sbin/sulogin
S:2345:respawn:/sbin/getty 115200 ttyS3
S1:2345:respawn:/sbin/getty 115200 ttyGS0

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.