Skip to end of metadata
Go to start of metadata

CDC ACM Class Terminal Example

This example emulates a USB-to-Serial adapter that displays a simple menu on a serial terminal. The menu allows you to send single or multiple characters to the adapter. The data is then sent back by the adapter, thereby creating a loopback.

Location

The example implementation is located in /examples/usb/device/all/ex_usbd_cdc_acm_terminal.c.

To execute it, you will also need some files on the host side. The files can be downloaded from the Micrium web site.

To install the Windows driver for the device, use the .inf file from the Windows application files located in /micrium_usb_dev_host_app/OS/Windows/CDC/INF.

Running the Demo Application

In this section, we will assume Windows is the host operating system. Upon connection of your CDC ACM device, Windows will enumerate your device and load the native driver usbser.sys to handle the device communication. The first time you connect your device to the host, you must indicate to Windows which driver to load using an INF file (refer to the About INF Files section for more details about INF files). The INF file tells Windows to load the usbser.sys driver. Indicating the INF file to Windows has to be done only once. Windows will then automatically recognize the CDC ACM device and load the proper driver for any new connection. The process of indicating the INF file may vary according to the Windows operating system version:

  • Windows XP directly opens the Found New Hardware Wizard. Follow the different steps of the wizard until you reach the page where you can indicate the path of the INF file.
  • Windows Vista and later won’t open a “Found New Hardware Wizard”. They will only indicate that no driver was found for the vendor device. You have to manually open the wizard. When you open the Device Manager, your CDC ACM device should appear with a yellow icon. Right-click on your device and choose ‘Update Driver Software...’ to open the wizard. Follow the different steps of the wizard until you reach the page where you can indicate the path of the INF file.

The INF file is located in:

/micrium_usb_dev_host_app/OS/Windows/CDC/INF

Refer to the About INF Files section for more details about how to edit the INF file to match your Vendor ID (VID) and Product ID (PID). By default, the provided INF files define 0xFFFE for VID and 0x1234 for PID. Once the driver is loaded, Windows creates a virtual COM port as shown in Figure - Windows Device Manager and Created Virtual COM Port.

Windows Device Manager and Created Virtual COM Port
Figure - Windows Device Manager and Created Virtual COM Port

The usbser.sys driver is already digitally signed by Windows. Micrium provides only an INF file, usbser.inf, telling Windows that your device uses that driver. Under Windows 7, providing this INF file was sufficient to load the driver usbser.sys for managing the CDC device. Windows 7 would display a warning message saying that the publisher of the driver can’t be verified but it was possible to continue the driver loading. Since Windows 8.x, Microsoft has enforced by default the loading of digitally signed driver packages. This is called Driver Signature Enforcement. Windows 8.x won’t let you load the CDC driver if the driver package is not fully signed. The Micrium CDC driver package is composed of usbser.inf (unsigned) and usbser.sys (signed). Basically, Windows 8.x requires a digitally signed INF file.

For development purposes, it is possible to disable the Driver Signature Enforcement. You can follow the instructions described on this page and you will be able to load the CDC driver and communicate with your USB device.

For your USB product release, you will have to follow the official procedure from Microsoft to sign the driver package (INF file + usbser.sys). The procedure is called the Release-Signing and is described here.

Micrium cannot provide an already-signed CDC driver package that would avoid disabling the Driver Signature Enforcement feature because the INF file contains a Vendor and Product IDs specific to the USB device manufacturer. For your USB product, the INF file must contain an official Vendor ID assigned to your company by the USB Implementer Forum. Micrium does not possess an official USB vendor ID. It is the customer’s responsibility to go through the official signing process as you are the USB device manufacturer.

Note that this restriction does not exist anymore under Windows 10 and later as the INF file usbser.sys is now natively digitally signed by Microsoft.


Figure - Serial Demo presents the steps to follow to use the serial demo.

Serial Demo
Figure - Serial Demo

(1) Open a serial terminal (for instance, HyperTerminal). Open the COM port matching to your CDC ACM device with the serial settings (baud rate, stop bits, parity and data bits) you want. This operation will send a series of CDC ACM class-specific requests (GET_LINE_CODING, SET_LINE_CODING, SET_CONTROL_LINE_STATE) to your device. Note that Windows Vista and later don’t provide HyperTerminal anymore. You may use other free serial terminals such TeraTerm ( http://ttssh2.sourceforge.jp/), Hercules ( http://www.hw-group.com/products/hercules/index_en.html ), RealTerm ( http://realterm.sourceforge.net/ ), etc.

(2) In order to start the communication with the serial task on the device side, the Data Terminal Ready (DTR) signal must be set and sent to the device. The DTR signal prevents the serial task from sending characters if the terminal is not ready to receive data. Sending the DTR signal may vary depending on your serial terminal. For example, HyperTerminal sends a properly set DTR signal automatically upon opening of the COM port. Hercules terminal allows you to set and clear the DTR signal from the graphical user interface (GUI) with a checkbox. Other terminals do not permit to set/clear DTR or the DTR set/clear’s functionality is difficult to find and to use.

(3) Once the serial task receives the DTR signal, the task sends a menu to the serial terminal with two options as presented in Figure - CDC Serial Demo Menu in HyperTerminal.

(4) The menu option #1 is the Echo 1 demo. It allows you to send one unique character to the device. This character is received by the serial task and sent back to the host.

(5) The menu option #2 is the Echo N demo. It allows you to send several characters to the device. All the characters are received by the serial task and sent back to the host. The serial task can receive a maximum of 512 characters.

CDC Serial Demo Menu in HyperTerminal
Figure - CDC Serial Demo Menu in HyperTerminal

To support the two demos, the serial task implements a state machine as shown in Figure - Serial Demo State Machine. Basically, the state machine has two paths corresponding to the user choice in the serial terminal menu.

Serial Demo State Machine
Figure - Serial Demo State Machine

(1) Once the DTR signal has been received, the serial task is in the MENU state.

(2) If you choose the menu option #1, the serial task will echo back any single character sent by the serial terminal as long as “Ctrl+C” is not pressed.

(3) If you choose the menu option #2, the serial task will echo all the received characters sent by the serial terminal as long as “Ctrl+C” is not pressed.

Table - Serial Terminals and CDC Serial Demo shows four possible serial terminals which you may use to test the CDC ACM class.

TerminalDTR set/clearMenu option(s) usable
HyperTerminalYes (properly set DTR signal automatically sent upon COM port opening)1 and 2
HerculesYes (a checkbox in the GUI allows you to set/clear DTR)1 and 2
RealTermYes (Set/Clear DTR buttons in the GUI)1 and 2
TeraTermYes (DTR can be set using a macro. GUI does NOT allows you to set/clear DTR easily)1 and 2
Table - Serial Terminals and CDC Serial Demo

API

This example offers only one API named Ex_USBD_ACM_SerialInit(). This function is normally called from a USB device core example.