ACM Subclass

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.

Micrium’s ACM subclass implementation complies with the following specification:

• Universal Serial Bus, Communications, Subclass for PSTN Devices, revision 1.2, February 9, 2007.

Overview

The general characteristics of the CDC base class in terms of Communications Class Interface (CCI) and Data Class Interface (DCI) were presented in the CDC Class Overview page. In this section, a CCI of type ACM is considered. It will consist 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.

Several subclass-specific requests exists 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, Subclass for PSTN Devices, revision 1.2, February 9, 2007”, section 6.2.2. From this list, Micrium’s ACM subclass supports:

Micrium’s ACM subclass uses the interrupt IN endpoint to notify the host about the current serial line state. The serial line state is a bitmap informing the host about:

• Data discarded because of overrun
• Parity error
• Framing error
• State of the ring signal detection
• State of break detection mechanism
• State of transmission carrier
• State of receiver carrier detection

Configuration

Subclass Instance Configuration

Before starting the communication phase, your application needs to initialize and configure the class to suit its needs.  Table - ACM Subclass Initialization API Summary summarizes the initialization functions provided by the ACM subclass. For more details about the functions’ parameters, refer to the CDC ACM Subclass Functions reference.

You need to call these functions in the order shown below to successfully initialize the ACM subclass:

1. Call USBD_ACM_SerialInit() 
   This function initializes all internal structures and variables that the ACM subclass needs. You should call this function only once even if you use multiple class instances.
2. Call USBD_ACM_SerialAdd() 
   This function allocates an ACM subclass instance. Internally, this function allocates a CDC class instance. It also allows you to specify the line state notification interval expressed in milliseconds and the Call Management capabilities.
3. Call USBD_ACM_SerialLineCodingReg() 
   This function allows you to register a callback used by the ACM subclass to notify the application about a change in the serial line coding settings (that is baud rate, number of stop bits, parity and number of data bits).
4. Call USBD_ACM_SerialLineCtrlReg() 
   This function allows you to register a callback used by the ACM subclass to notify the application about a change in the serial line state (that is RS-232 break signal, carrier control, i.e. RS-232 RTS signal, and a flag indicating that data equipment terminal is present or not, i.e. RS-232 DTR signal,).
5. Call USBD_ACM_SerialCfgAdd() 
   Finally, once the ACM subclass instance has been created, you must add it to a specific configuration.

Listing - CDC ACM Subclass Initialization Example illustrates the use of the previous functions for initializing the ACM subclass. Note that the error handling has been omitted for clarity.

CPU_BOOLEAN  App_USBD_CDC_Init (CPU_INT08U  dev_nbr,
                                CPU_INT08U  cfg_hs,
                                CPU_INT08U  cfg_fs)
{
    USBD_ERR    err;
    CPU_INT08U  subclass_nbr;


    USBD_CDC_Init(&err);                                                      (1)

    USBD_ACM_SerialInit(&err);                                                (2)
                                                                              (3)
    subclass_nbr = USBD_ACM_SerialAdd(64u,
                                     (USBD_ACM_SERIAL_CALL_MGMT_DATA_CCI_DCI | USBD_ACM_SERIAL_CALL_MGMT_DEV),
                                     &err);

    USBD_ACM_SerialLineCodingReg(        subclass_nbr,                        (4)
                                         App_USBD_CDC_SerialLineCoding,
                                 (void *)0,
                                        &err);

    USBD_ACM_SerialLineCtrlReg(        subclass_nbr,                          (5)
                                       App_USBD_CDC_SerialLineCtrl,
                               (void *)0,
                                      &err);

    if (cfg_hs != USBD_CFG_NBR_NONE) {
        USBD_ACM_SerialCfgAdd(subclass_nbr, dev_nbr, cfg_hs, &err);           (6)
    }

    if (cfg_fs != USBD_CFG_NBR_NONE) {
        USBD_ACM_SerialCfgAdd(subclass_nbr, dev_nbr, cfg_fs, &err);           (7)
    }
}

Listing - CDC ACM Subclass Initialization Example also illustrates an example of multiple configurations. The functions USBD_ACM_SerialAdd() and USBD_ACM_SerialCfgAdd() allow you to create multiple configurations and multiple instances architecture. Refer to the Class Instance Concept page for more details about multiple class instances.

Subclass Notification and Management

You have access to some functions provides in the ACM subclass which relate to the ACM requests and the serial line state previously presented in the Overview section.  shows these functions. Refer to the CDC ACM Subclass Functions reference for more details about the functions’ parameters.

Micrium’s ACM subclass always uses the interrupt endpoint to notify the host of the serial line state. You cannot disable the interrupt endpoint.

Subclass Instance Communication

Micrium’s ACM subclass offers the following functions to communicate with the host. For more details about the functions’ parameters, refer to the CDC ACM Subclass Functions reference.

USBD_ACM_SerialRx() and USBD_ACM_SerialTx() provide synchronous communication which means that the transfer is blocking. Upon calling the function, the application blocks until transfer completion with or without an error. A timeout can be specified to avoid waiting forever. Listing - Serial Read and Write Example presents a read and write example to receive data from the host using the bulk OUT endpoint and to send data to the host using the bulk IN endpoint.

CPU_INT08U  rx_buf[2];
CPU_INT08U  tx_buf[2];
USBD_ERR    err;


(void)USBD_ACM_SerialRx(subclass_nbr,                                         (1)
                       &rx_buf[0],                                            (2)
                        2u,
                        0u,                                                   (3)
                       &err);
if (err != USBD_ERR_NONE) {
    /* Handle the error. */
}

(void)USBD_ACM_SerialTx(subclass_nbr,                                         (1)
                       &tx_buf[0],                                            (4)
                        2u,
                        0u,                                                   (3)
                       &err);
if (err != USBD_ERR_NONE) {
    /* Handle the error. */
}