SILICON LABS Usb Device Cdc Acm Class User Guide

SILICON LABS Usb Device Cdc Acm Class

 

 

Specifications

• USB Device CDC ACM Class
• USB Device CDC Base Class Overview

Product Information
This product is a USB device that supports the Communications Device Class (CDC) class and the associated CDC subclass, specifically the Abstract Control Model (ACM) subclass for serial emulation.

CDC Device Composition
A CDC device consists of at least one Communication Class Interface (CCI) and zero or more Data Class Interfaces (DCIs) to provide communication capabilities. In a CDC composite device,multiple functions can be implemented with different sets of CCI and DCI(s).

Endpoints Usage
The CDC device typically uses the following combination ofendpoints:

• A pair of control IN and OUT endpoints for default communication.
• An optional bulk or interrupt IN endpoint.
• A pair of bulk or isochronous IN and OUT endpoints (isochronous endpoints are not currently supported by Silicon Labs USB device
  stack).

CDC Endpoint Usage Table

Endpoint	Direction	Interface Usage
Control IN	Device-to-CCI	Standard requests for enumeration, class-specific requests, device management, and optionally call management.
Control OUT	Host-to-CCI	Standard requests for enumeration, class-specific requests, device management, and optionally call management.
Interrupt or bulk IN	Device-to-CCI	Events notification, such as ring detect, serial line status, network status.
Bulk or isochronous IN	Device-to-DCI	Raw or formatted data communication.
Bulk or isochronous OUT	Host-to-DCI	Raw or formatted data communication.

Product Usage Instructions

Setup and Connection

• Connect the USB device to your computer using an appropriate USB cable.

Data Communication

• Use the provided software to establish communication with the USB device.

Functionality Testing

Send/receive data through the designated endpoints to test the functionality of the CDC device.

USB Device CDC ACM Class
This section describes the Communications Device Class (CDC) class and the associated CDC subclass supported by Silicon Labs’ USB Device stack. Silicon Labs USB-Device currently supports the Abstract Control Model (ACM) subclass, which is commonly used for serial emulation. CDC includes various telecommunication and networking devices. Telecommunication devices encompass analog modems, analog and digital telephones, ISDN terminal adapters, etc. For example, networking devices contain ADSL and cable modems, Ethernet adapters, and hubs. CDC defines a framework to encapsulate existing communication services standards, such as V.250 (for modems over telephone network) and Ethernet (for local area network devices), using a USB link. A communication device is in charge of device management, call management when needed, and data transmission. CDC defines seven major groups of devices. Each group belongs to a model of communication, which may include several subclasses. Each group of devices has its own specification document besides the CDC base class. The seven groups are:

• Public Switched Telephone Network (PSTN), devices including voiceband modems, telephones, and serial emulation devices. Integrated Services Digital Network (ISDN) devices, including terminal adaptors and telephones.
• Ethernet Control Model (ECM) devices, including devices supporting the IEEE 802 family (ex.: cable and ADSL modems, WiFi adapters).
• Asynchronous Transfer Mode (ATM) devices, including ADSL modems and other devices connected to ATM networks (workstations, routers, LAN switches).
• Wireless Mobile Communications (WMC) devices, including multi-function communications handset devices used to manage voice and data communications.
• Ethernet Emulation Model (EEM) devices which exchange Ethernet-framed data.
• Network Control Model (NCM) devices, including high-speed network devices (High Speed Packet Access modems, Line Terminal Equipment)
• The CDC and the associated subclass implementation complies with the following specifications:
• Universal Serial Bus, Class Definitions for Communications Devices, Revision 1.2, November 3 2010. Universal Serial Bus, Communications, Subclass for PSTN Devices, Revision 1.2, February 9 2007.

USB Device CDC Base Class Overview
A CDC device is composed of the following interfaces to implement communication capability:

• Communications Class Interface (CCI) is responsible for the device management and optionally the call management. The device management enables the general configuration and control of the device and the notification of events to the host. The call management enables calls establishment and termination. Call management might be multiplexed through a DCI. A CCI is mandatory for all CDC devices. It identifies the CDC function by specifying the communication model supported by the CDC device. The interface(s) following the CCI can be any defined USB class interface, such as Audio or a vendor-specific interface. The vendor-specific interface is represented specifically by a DCI. Data Class Interface (DCI) is responsible for data transmission. Data transmitted and/or received do not follow a specific format. Data could be raw data from a communication line, data following a proprietary format, etc. All the DCIs following the CCI can be seen as subordinate interfaces.
• A CDC device must have at least one CCI and zero or more DCIs. One CCI and any subordinate DCI together provide a feature to the host. This capability is also referred to as a function. In a CDC composite device, you could have several functions. Therefore, the device would be composed of several sets of CCI and DCI(s) as shown in Figure – CDC Composite Device.

A CDC device is likely to use the following combination of endpoints:

• A pair of control IN and OUT endpoints called the default endpoint.
• An optional bulk or interrupt IN endpoint.
• A pair of bulk or isochronous IN and OUT endpoints. Note that Silicon Labs USB device stack does not currently support isochronous endpoints.

The table below shows the usage of the different endpoints and by which interface of the CDC they are used.

Table – CDC Endpoint Usage

Endpoint	Direction	Interface	Usage
Control IN	Device-to- host	CCI	Standard requests for enumeration, class-specific requests, device management, and optionally call management.
Control OUT	Host-to- device	CCI	Standard requests for enumeration, class-specific requests, device management, and optionally call management.
Interrupt or bulk IN	Device-to- host	CCI	Events notification, such as ring detect, serial line status, network status.
Bulk or isochronous IN	Device-to- host	DCI	Raw or formatted data communication.
Bulk or isochronous OUT	Host-to- device	DCI	Raw or formatted data communication.

• Most communication devices use an interrupt endpoint to notify the host of events. Isochronous endpoints should not be used for data transmission when a proprietary protocol relies on data retransmission in case of USB protocol errors. Isochronous communication can inherently lose data since it has no retry mechanisms.
• The seven major models of communication encompass several subclasses. A subclass describes the way the device should use the CCI to handle the device management and call management. The table below shows all the possible subclasses and the communication model they belong to.

Table – CDC Subclasses

Subclass	Communication Model	Example of Devices Using This Subclass
Direct Line Control Model	PSTN	Modem devices directly controlled by the USB host
Abstract Control Model	PSTN	Serial emulation devices, modem devices controlled through a serial command set

Overview

Subclass	Communication Model	Example of Devices Using This Subclass
Telephone Control Model	PSTN	Voice telephony devices
Multi-Channel Control Model	ISDN	Basic rate terminal adaptors, primary rate terminal adaptors, telephones
CAPI Control Model	ISDN	Basic rate terminal adaptors, primary rate terminal adaptors, telephones
Ethernet Networking Control Model	ECM	DOC-SIS cable modems, ADSL modems that support PPPoE emulation, Wi-Fi adaptors (IEEE 802.11-family), IEEE 802.3 adaptors
ATM Networking Control Model	ATM	ADSL modems
Wireless Handset Control Model	WMC	Mobile terminal equipment connecting to wireless devices
Device Management	WMC	Mobile terminal equipment connecting to wireless devices
Mobile Direct Line Model	WMC	Mobile terminal equipment connecting to wireless devices
OBEX	WMC	Mobile terminal equipment connecting to wireless devices
Ethernet Emulation Model	EEM	Devices using Ethernet frames as the next layer of transport. Not intended for routing and Internet connectivity devices
Network Control Model	NCM	IEEE 802.3 adaptors carrying high-speed data bandwidth on network

USB Device CDC ACM Class Resource Needs from Core

Each time you add a CDC ACM class instance to a USB configuration via a call to the function sl_usbd_cdc_acm_add_to_configuration() , the following resources will be allocated from the core.

Resource	Quantity
Interfaces	2
Alternate interfaces	2
Endpoints	3
Interface groups	1

Note
that those numbers are per configuration. When setting up your SL_USBD_INTERFACE_QUANTITY, SL_USBD_ALT_INTERFACE_QUANTITY, SL_USBD_INTERFACE_GROUP_QUANTITY and SL_USBD_DESCRIPTOR_QUANTITY configuration values, don’t forget to take into account on how many configurations the class will be added. For the SL_USBD_OPEN_ENDPOINTS_QUANTITY configuration value, since endpoints are opened only when a configuration is set by the    host, you just need to take into account the number of needed endpoints for a class instance.

USB Device CDC ACM Subclass Overview

The CDC base class is composed of a Communications Class Interface (CCI) and Data Class Interface (DCI), which is discussed in detail in USB Device CDC Base Class Overview . This section discusses a CCI of type ACM. It consists of a default endpoint for the management element and an interrupt endpoint for the notification element. A pair of bulk endpoints is used to carry unspecified data over the DCI.
The ACM subclass is used by two types of communication devices:

• Devices supporting AT commands (for instance, voiceband modems). Serial emulation devices which are also called Virtual COM port devices.

There are several subclass-specific requests for the ACM subclass. They allow you to control and configure the device. The complete list and description of all ACM requests can be found in the specification <Universal Serial Bus, Communications,

Overview
Subclass for PSTN Devices, revision 1.2, February 9, 2007=, section 6.2.2. From this list, Silicon Labs9 ACM subclass supports the following:

Table – ACM Requests Supported by Silicon Labs

ACM Subclass
The ACM subclass has one compile-time configuration shown in the table below.

Table – USB Device CDC ACM Configuration Define

Configuration Name

• SL_USBD_CDC_ACM_SUBCLASS_I NSTANCE_QUANTITY

Description

• Configures the number of subclass instances you will allocate via a call to the function sl_usbd_cdc_acm_create_instance() .

Default  Value

• 2

USB Device CDC ACM Class Instance Configurations
This section defines the configurations related to the CDC ACM serial class instances.

• Class Instance Creation
  • line state interval
  • call mgmt capabilities
  • p_acm_callbacks

Class Instance Creation
To create a CDC ACM serial class instance, call the function configuration arguments, as described here.

line_state_interval
This is the interval (in milliseconds) that your CDC ACM serial class instance will report the line state notifications to the host. This value must be a power of two (1, 2, 4, 8, 16, etc).

call_mgmt_capabilities
Call Management Capabilities bitmap. Possible values of the bitmap are as follows:

Value (bit)	Description
SL_USBD_ACM_SERIAL_CALL_MGMT_DEV	Device handles call management itself.
SL_USBD_ACM_SERIAL_CALL_MGMT_DATA_CCI_DCI	Device can send/receive call management information over a Data Class interface.

p_acm_callbacks

Overview
p_acm_callbacks is a pointer to a structure of type sl_usbd_cdc_acm_callbacks_t . Its purpose is to give the CDC ACM Class a set of callback functions to be called when a CDC ACM event occurs. Not all callbacks are mandatory and a null pointer ( NULL ) can be passed in the callbacks structure variable when the callback is not needed. The table below describes each configuration field available in this configuration structure.

Table – sl_usbd_cdc_acm_callbacks_t Configuration Structure

See section Registering Event Notification Callbacks for the callback functions example.

USB Device CDC ACM Class Programming Guide

• This section explains how to use the CDC Abstract Control Model class.
• Initializing the USB Device CDC ACM Class
• Adding a USB Device CDC ACM Class Instance to Your Device
• Communicating Using the CDC ACM Class

Initializing the USB Device CDC ACM Class
To add CDC ACM class functionality to your device, you must first initialize the CDC base class and the ACM subclass by calling the functions sl_usbd_cdc_init() and sl_usbd_cdc_acm_init() . The example below shows how to call sl_usbd_cdc_init() and sl_usbd_cdc_acm_init() using default arguments. Example – Initialization of CDC ACM Class

Adding a USB Device CDC ACM Class Instance to Your Device
To add CDC ACM class functionality to your device, you must create an instance, then add it to your device’s configuration(s).

• Creating a CDC ACM Class Instance
• Adding the CDC ACM Class Instance to Your Device’s Configuration(s)
• Registering Event Notification Callbacks

Overview

Creating a CDC ACM Class Instance
Create a CDC ACM class instance by calling the function sl_usbd_cdc_acm_create_instance() . The example below shows how to create a CDC ACM class instance via sl_usbd_cdc_acm_create_instance() .

Example
Creating a CDC ACM Function via sl_usbd_cdc_acm_create_instance()

Adding the CDC ACM Class Instance to Your Device’s Configuration(s)
After you have created a CDC ACM class instance, you can add it to a configuration by calling the function sl_usbd_cdc_acm_add_to_configuration() . The example below shows how to call sl_usbd_cdc_acm_add_to_configuration() .

Example
Call to USBD ACM sl_usbd_cdc_acm_add_to_configuration()

1. Class number to add to the configuration returned by sl_usbd_cdc_acm_create_instance() .
2. Configuration number (here adding it to a Full-Speed configuration).

Registering Event Notification Callbacks
The CDC ACM Serial class can notify your application of any changes in line control or coding via notification callback functions. A callback functions structure can be passed as argument during the ACM instance creation. Note that those callbacks are optional.

Example
CDC ACM Callbacks Registration illustrates the use of the callback registration functions. Example – CDC ACM Callbacks Implementation shows an example of implementation of the callback functions.

Overview

Example – CDC ACM Callbacks Implementation

1. It is important to return false to this function if the line coding applying failed. Otherwise, return true.

Communicating Using the CDC ACM Class

• Serial Status
• Line Coding
• Line Control
• Line State
• Subclass Instance Communication

Serial Status

Line Coding
The USB host controls the line coding (baud rate, parity, etc) of the CDC ACM device. When necessary, the application is responsible for setting the line coding. There are two functions provided to retrieve and set the current line coding, as described in the table below.

Table – CDC ACM Line Coding Functions

Line Control
The USB host controls the line control (RTS and DTR pins, break signal, and so on) of the CDC ACM device. When necessary, your application is responsible for applying the line controls. A function is provided to retrieve and set the current line controls, as are described in the table below.

Table – CDC ACM Line Control Functions

Line State
The USB host retrieves the line state at a regular interval. Your application must update the line state each time it changes. When necessary, your application is responsible for setting the line state. Two functions are provided to retrieve and set the current line controls, as described in the table below.

Table – CDC ACM Line State Functions

Subclass Instance Communication
Silicon Labs’ ACM subclass offers the following functions to communicate with the host. For more details about the functions9 parameters, see the CDC ACM Subclass Functions reference.

Overview

Table – CDC ACM Communication API Summary
sl_usbd_cdc_acm_read() and sl_usbd_cdc_acm_write() provide synchronous communication, which means that the transfer is blocking. In other words, upon calling the function, the application blocks until the transfer is complete with or without an error. A timeout can be specified to avoid waiting forever. The example below shows a read and write example that receives data from the host using the bulk OUT endpoint and sends data to the host using the bulk IN endpoint.

Listing – Serial Read and Write Example

1. The class instance number created with sl_usbd_cdc_acm_create_instance() provides an internal reference to the ACM subclass to route the transfer to the proper bulk OUT or IN endpoint.
2. Your application must ensure that the buffer provided to the function is large enough to accommodate all the data. Otherwise, synchronization issues might happen.
3. To avoid an infinite blocking situation, specify a timeout expressed in milliseconds. A value of 809 makes the application task wait forever.
4. The application provides the initialized transmit buffer.

FAQs

Q: Can this product support isochronous endpoints?

A: No, the Silicon Labs USB device stack does not currently support isochronous endpoints.

Q: How many functions can be implemented in a CDC composite device?

A: A CDC composite device can have several functions by combining different sets of CCI and DCI(s).

Documents / Resources

SILICON LABS Usb Device Cdc Acm Class [pdf] User Guide Usb Device Cdc Acm Class, Usb Device Cdc Acm Class, Usb Device, Cdc Acm, Class

References

• User Manual