View source for How to use USB CDC ACM and MS composite Linux gadget driver

= Introduction =

This document explains the Communications Device Class (CDC) Abstract Control Model (ACM) + 
Mass Storage (MS) composite Linux gadget driver and how to use it with a Linux host PC and 
a Windows host PC.

* [http://www.linux-usb.org/gadget Linux device (gadget) driver framework (last updated 2005)]
* [http://www.usb.org/developers/devclass_docs USB Communication Device (CDC) and Mass Storage (MS) Device Class Specifications]


= CDC ACM + MS driver =

The CDC ACM + MS driver is a USB composite gadget driver which implements the serial 
communication and mass storage functions.  This  allows the device to be registered 
on a host computer as a seral port (e.g. /dev/ttyACM0 or COM1:) and as a USB thumb
drive (e.g. /dev/sdf or E:). The composite driver allows for simultaneous
use of the serial and mass storage functions.

= Driver support =

The CDC ACM only driver that comes with the Linux kernel is supported on both Linux
and Windows.  For Windows it is necessary the use of the following INF file:

 http://www.kernel.org/doc/Documentation/usb/linux-cdc-acm.inf

Our experience shows the CDC ACM + MS composite USB driver is not well supported 
on Windows with this INF file.  We have tested with a propretary solutions from
[http://www.thesycon.de  Thesycon], with a demo version available at 

* [http://www.thesycon.de/eng/usb_cdcacm.shtml#demo Demo version of CDC ACM driver].

Linux host computers have full support for the CDC ACM + MS composite USB drivert
without the need of additional files.

= Using CDC ACM + MS device with Linux host =

== Linux host device file identification ==

The following description is based on the host computer running  Linux Ubuntu 10.04 LTS.

Once you attached the device, inspect the log to obtain the device file names used
on the host.

<pre>

dmesg | tail -n 20

Jan 31 14:19:34 mmadrigal kernel: [109059.420096] usb 1-3: new high speed USB device using ehci_hcd and address 16
Jan 31 14:19:34 mmadrigal kernel: [109059.553321] usb 1-3: configuration #1 chosen from 1 choice
Jan 31 14:19:34 mmadrigal kernel: [109059.562570] cdc_acm 1-3:1.0: ttyACM0: USB ACM device
Jan 31 14:19:34 mmadrigal kernel: [109059.567214] scsi8 : SCSI emulation for USB Mass Storage devices
Jan 31 14:19:35 mmadrigal kernel: [109060.604592] usb 1-3: USB disconnect, address 16
Jan 31 14:22:58 mmadrigal kernel: [109262.944049] usb 1-3: new high speed USB device using ehci_hcd and address 17
Jan 31 14:22:58 mmadrigal kernel: [109263.077362] usb 1-3: configuration #1 chosen from 1 choice
Jan 31 14:22:58 mmadrigal kernel: [109263.088675] cdc_acm 1-3:1.0: ttyACM0: USB ACM device
Jan 31 14:22:58 mmadrigal kernel: [109263.123308] scsi9 : SCSI emulation for USB Mass Storage devices
Jan 31 14:23:13 mmadrigal kernel: [109278.133699] scsi 9:0:0:0: Direct-Access     Linux    File-CD Gadget   0316 PQ: 0 ANSI: 2
Jan 31 14:23:13 mmadrigal kernel: [109278.142902] sd 9:0:0:0: Attached scsi generic sg6 type 0
Jan 31 14:23:13 mmadrigal kernel: [109278.150041] sd 9:0:0:0: [sdf] Attached SCSI removable disk
</pre>

The serial communication port has been registed as 'ttACM0', meaning it will show 
up as '/dev/ttyACM0'.  The mass storage device have been registered as 'sdf', 
meaning it will show up as '/dev/sdf'.

== How to test the serial driver in Linux ==

In order to test the serial function on Linux you should need to install picocom 

 sudo apt-get install picocom

and use the picocom terminal emulator to display data received over the USB serial 
connection:

 picocom /dev/ttyACM0

In order to send data from the target device we need to use the USB serial 
gadget driver device file '/dev/ttyGS0'.  We can echo command to send data from the
device to the Ubuntu host computer:

 echo foo > /dev/ttyGS0

After that you should see the text ''foo'' on picocom's output.

In a similar way, if we want to send data from the host computer to the device we should 
first send the data on the host by running

 echo hello > /dev/ttyACM0

and read it on the device

 cat /dev/ttyGS0


= Using CDC ACM + MS device with Windows 7 host =

When using the device on Windows, you need to use a INF file in order to load the 
appropriate driver.  There is an INI file avaiable (see above), but it didn't work
for use on Windows 7 with a CDC ACM + MS device.  Instead we used the proprietary
driver from  [http://www.thesycon.de  Thesycon].

[http://www.thesycon.de  Thesycon] provides a demo version of the driver
[[http://www.thesycon.de/eng/usb_cdcacm.shtml#demo]] that can be installed on Windows.
By default it creates a directory on ''C:\Thesycon\CdcAcm\V1.96.0_Demo\''.  There is
an INI file and a SYS driver in the idisk sub-directory you can use to exchange USB serial data
with the target device.

In order use the INF file provided it is necessary to add the VID (Vendor ID) and PID (Product ID) 
of the target device to the file; look for the following piece of code into the file:

<pre>
[_Devices.ntamd64]
; enter your VID (VVVV) and PID (PPPP) here
%S_DeviceDesc1%=Install,USB\VID_VVVV&PID_PPPP
</pre>

Replace the ''USB\VID_VVVV&PID_PPPP'' string with the corresponding VID and PID. In addition we 
need to specify the interface on which the serial function is located since it is a composite device.
For example, the following uses the Linux Foundation (VID = 0x1D6B) device  with a PID = 0x0104
(Multifunction Composite Gadget).  We assume the serial interface is located in the interface 1, 
so the piece of code shown above should be replaced by:

<pre>
[_Devices.ntamd64]
; enter your VID (VVVV) and PID (PPPP) here
%S_DeviceDesc1%=Install,USB\VID_1D6B&PID_0104&MI_01
</pre>

where MI_01 means the serial interface is on interface 1.

Once the edited INF file is read, just plug the device to the Windows host computer.  Windows
will try to locate a usable driver.  When it asks for the driver just point it to the folder where
the modified INF file resides and Windows will do the rest.


If Windows doesn't ask for it but still fails on the installation you can install the driver by:

# Go to ''Start -> Control panel -> Devices and printers"
# Right click on the composite device.
# Properties -> Hardware.
# Select the CDC ACM Data function.
# Properties
# Change configuration
# Update firmware
# Point it to the folder containing the INF file and then wait to the driver to be installed.

Once Windows announces the driver was installed correctly, the device is ready to use.

== Using the Windows 7 serial port ==

In order to use the serial function you can install [ http://logmett.com TeraTerm] on your 
Windows machine and launch the TeraTerm application.  On first dialog TeraTerm will ask 
for the connection properties as is shown on figure 1, be sure to select ''Serial'' and 
the port corresponding to your composite device.

[[File:teraterm.jpeg|500px|thumb|center| Figure 1. TeraTerm initial screen.]]

After selecting the appropriated port, TeraTerm will open the connection with the device.

To send data from the device to your host PC run the following command on the target device:

 echo foo > /dev/ttyACM0

You should be able to see the text ''foo'' in the TeraTerm window.

To send data from Windows to the device write any word on your TeraTerm's window and type in
the TeraTerm window the word ''INTRO'' and then run the following command on the device:

 cat /dev/ttyACM0

You should be able to see the string on your target device console.

== How to use the mass storage function in Windows 7 ==

Once the driver has been installed correctly we just need to mount the SD card on the device 
in order to get the mass storage device ready. In order to do that we just need to run the 
following commands on the target device:

* Mount the MMC partition

 echo /dev/mmcblk0p2 >  sys/devices/platform/musb_hdrc/gadget/lun0/file

* On the Windows PC open the external media device, now you have access to the MMC card on your device.

[[Category:VidmicDocumentation]]