USB Host Communications Device Class Driver (r_usb_hcdc)

This module provides a USB Host Communications Device Class (HCDC) driver. It implements the USB HCDC Interface.

Functions

Refer to USB (r_usb_basic) for the common API (r_usb_basic) to be called from the application.

Detailed Description

Overview

The r_usb_hcdc module, when used in combination with the r_usb_basic module, operates as a USB Host Communications Device Class (HCDC) driver. The HCDC conforms to the PSTN device subclass abstract control model of the USB Communications Device Class (CDC) specification and enables communication with a CDC peripheral device.

Features

The r_usb_hcdc module has the following key features:

• Checks for connected devices
• Implementation of communication line settings
• Acquisition of the communication line state
• Data transfer to and from a CDC peripheral device

Configuration

Build Time Configurations for r_usb_hcdc

The following build time configurations are defined in fsp_cfg/r_usb_hcdc_cfg.h:

Configuration	Options	Default	Description
Target Peripheral Device Class ID	CDC class supported device Vendor class device	CDC class supported device	Specify the device class ID of the CDC device to be connected.

Configurations for Connectivity > USB HCDC driver (r_usb_hcdc)

This module can be added to the Stacks tab via New Stack > Connectivity > USB HCDC driver (r_usb_hcdc).

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_hcdc0	Module name.

Note

Refer to the USB (r_usb_basic) module for hardware configuration options.

Clock Configuration

Refer to the USB (r_usb_basic) module.

Pin Configuration

Refer to the USB (r_usb_basic) module.

Usage Notes

Communications Device Class (CDC), PSTN and ACM

This software conforms to the Abstract Control Model (ACM) subclass of the Communications Device Class specification as defined in the "USB Communications Class Subclass Specification for PSTN Devices", Revision 1.2. The Abstract Control Model subclass is a technology that bridges the gap between USB devices and earlier modems (employing RS-232C connections) enabling use of application programs designed for older modems.

Basic Functions

The main functions of HCDC are the following:

• Verify connected devices
• Make communication line settings
• Acquire the communication line state
• Transfer data to and from the CDC peripheral device

Abstract Control Model Class Requests - Host to Device

This driver supports the following class requests:

Request	Code	Description
SendEncapsulatedCommand	0x00	Transmits an AT command as defined by the protocol used by the device (normally 0 for USB).
GetEncapsulatedResponse	0x01	Requests a response to a command transmitted by SendEncapsulatedCommand.
SetCommFeature	0x02	Enables or disables features such as device-specific 2-byte code and country setting.
GetCommFeature	0x03	Acquires the enabled/disabled state of features such as device-specific 2-byte code and country setting.
ClearCommFeature	0x04	Restores the default enabled/disabled settings of features such as device-specific 2-byte code and country setting.
SetLineCoding	0x20	Makes communication line settings (communication speed, data length, parity bit, and stop bit length).
GetLineCoding	0x21	Acquires the communication line setting state.
SetControlLineState	0x22	Makes communication line control signal (RTS, DTR) settings.
SendBreak	0x23	Transmits a break signal.

Note

For more information about Abstract Control Model requests, refer to Table 11 "Requests - Abstract Control Model" in the "USB Communications Class Subclass Specification for PSTN Devices", Revision 1.2.

The expected data format for each command is shown below followed by dependent structures.

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0x21	SEND_ENCAPSULATED_COMMAND (0x00)	0x0000	0x0000	Data length	usb_hcdc_encapsulated_t
0x21	GET_ENCAPSULATED_RESPONSE (0x01)	0x0000	0x0000	Data length	usb_hcdc_encapsulated_t
0x21	SET_COMM_FEATURE (0x02)	usb_hcdc_feature_selector_t	0x0000	Data length	usb_hcdc_commfeature_t
0x21	GET_COMM_FEATURE (0x03)	usb_hcdc_feature_selector_t	0x0000	Data length	usb_hcdc_commfeature_t
0x21	CLEAR_COMM_FEATURE (0x04)	usb_hcdc_feature_selector_t	0x0000	Data length	None
0x21	SET_LINE_CODING (0x20)	0x0000	0x0000	0x0000	usb_hcdc_linecoding_t
0xA1	GET_LINE_CODING (0x21)	0x0000	0x0000	0x0007	usb_hcdc_linecoding_t
0x21	SET_CONTROL_LINE_STATE (0x22)	usb_hcdc_controllinestate_t	0x0000	0x0000	None
0x21	SEND_BREAK (0x23)	usb_hcdc_breakduration_t	0x0000	0x0000	None

ACM Notifications from Device to Host

The following class notifications are supported:

Notification	Code	Description
RESPONSE_AVAILABLE	0x01	Response to GET_ENCAPSULATED_RESPONSE
SERIAL_STATE	0x20	Notification of serial line state

The data types returned are as follows:

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xA1	RESPONSE_AVAILABLE (0x01)	0x0000	0x0000	0x0000	None
0xA1	SERIAL_STATE (0x20)	0x0000	0x0000	0x0002	usb_hcdc_serialstate_t

Note

The host is notified with SERIAL_STATE whenever a change in the UART port state is detected.

Limitations

This driver is subject to the following limitations:

• Suspend is not supported when a data transfer is in progress. Confirm that data transfer has completed before executing suspend.
• Use of compound USB devices with CDC class support is not supported.
• This module must be incorporated into a project using r_usb_basic and does not provide any public APIs.
• This driver does not support Low-speed.

Examples

USB HCDC Loopback Example

The main functions of the HCDC loopback example are as follows:

1. Virtual UART control settings are configured by transmitting the class request SET_LINE_CODING to the CDC device.
2. Sends receive (Bulk In transfer) requests to a CDC peripheral device and receives data.
3. Loops received data back to the peripheral by means of Bulk Out transfers.

Data Transfer (Loopback)

The main loop performs loopback processing in which data received from a CDC peripheral device is transmitted unaltered back to the peripheral.

#define SET_LINE_CODING           (USB_CDC_SET_LINE_CODING | USB_HOST_TO_DEV | USB_CLASS | USB_INTERFACE)
#define GET_LINE_CODING           (USB_CDC_GET_LINE_CODING | USB_DEV_TO_HOST | USB_CLASS | USB_INTERFACE)
#define SET_CONTROL_LINE_STATE    (USB_CDC_SET_CONTROL_LINE_STATE | USB_HOST_TO_DEV | USB_CLASS | USB_INTERFACE)

#define COM_SPEED                 (9600U)
#define COM_DATA_BIT              (8U)
#define COM_STOP_BIT              (0)
#define COM_PARITY_BIT            (0)
#define LINE_CODING_LENGTH        (7)

void usb_basic_example (void)
{
    usb_status_t     event;
    usb_event_info_t event_info;

    g_usb_on_usb.open(&g_basic0_ctrl, &g_basic0_cfg);


    while (1)
    {
        /* Get USB event data */
        g_usb_on_usb.eventGet(&event_info, &event);

        /* Handle the received event (if any) */
        switch (event)
        {
            case USB_STATUS_CONFIGURED:

                /* Configure virtual UART settings */
                set_line_coding(&g_basic0_ctrl, event_info.device_address); /* CDC Class request "SetLineCoding" */
                break;

            case USB_STATUS_READ_COMPLETE:

                if (USB_CLASS_HCDC == event_info.type)
                {
                    if (event_info.data_size > 0)
                    {
                        /* Send the received data back to the connected peripheral */

                        g_usb_on_usb.write(&g_basic0_ctrl, g_snd_buf, event_info.data_size, USB_DEVICE_ADDRESS_1);

                    }
                    else
                    {

                        /* Send the data reception request when the zero-length packet is received. */
                        g_usb_on_usb.read(&g_basic0_ctrl, g_rcv_buf, CDC_DATA_LEN, USB_DEVICE_ADDRESS_1);

                    }
                }
                else                   /* USB_HCDCC */
                {
                    /* Control Class notification "SerialState" receive start */
                    g_usb_on_usb.read(&g_basic0_ctrl,
                                      (uint8_t *) &g_serial_state,
                                      USB_HCDC_SERIAL_STATE_MSG_LEN,
                                      USB_DEVICE_ADDRESS_1);
                }

                break;

            case USB_STATUS_WRITE_COMPLETE:

                /* Start receive operation */
                g_usb_on_usb.read(&g_basic0_ctrl, g_rcv_buf, CDC_DATA_LEN, USB_DEVICE_ADDRESS_1);
                break;

            case USB_STATUS_REQUEST_COMPLETE:

                if (USB_CDC_SET_LINE_CODING == (event_info.setup.request_type & USB_BREQUEST))
                {
                    /* Set virtual RTS/DTR signal state */
                    set_control_line_state(&g_basic0_ctrl, event_info.device_address); /* CDC Class request "SetControlLineState" */
                }
                /* Check Complete request "SetControlLineState" */
                else if (USB_CDC_SET_CONTROL_LINE_STATE == (event_info.setup.request_type & USB_BREQUEST))
                {
                    /* Read back virtual UART settings */
                    get_line_coding(&g_basic0_ctrl, event_info.device_address); /* CDC Class request "SetLineCoding" */
                }
                else if (USB_CDC_GET_LINE_CODING == (event_info.setup.request_type & USB_BREQUEST))
                {
                    /* Now that setup is complete, start loopback operation */
                    g_usb_on_usb.read(&g_basic0_ctrl, g_snd_buf, CDC_DATA_LEN, USB_DEVICE_ADDRESS_1);
                }
                else
                {
                    /* Unsupported request */
                }

                break;

            default:

                /* Other event */
                break;
        }

    }
}

void set_control_line_state (usb_instance_ctrl_t * p_ctrl, uint8_t device_address)
{
    usb_setup_t setup;

    setup.request_type   = SET_CONTROL_LINE_STATE; /* bRequestCode:SET_CONTROL_LINE_STATE, bmRequestType */
    setup.request_value  = 0x0000;                 /* wValue:Zero */
    setup.request_index  = 0x0000;                 /* wIndex:Interface */
    setup.request_length = 0x0000;                 /* wLength:Zero */

    g_usb_on_usb.hostControlTransfer(p_ctrl, &setup, (uint8_t *) &g_usb_dummy, device_address);
}

void set_line_coding (usb_instance_ctrl_t * p_ctrl, uint8_t device_address)
{
    usb_setup_t setup;

    g_com_parm.dwdte_rate   = (usb_hcdc_line_speed_t) COM_SPEED;
    g_com_parm.bchar_format = (usb_hcdc_stop_bit_t) COM_STOP_BIT;
    g_com_parm.bparity_type = (usb_hcdc_parity_bit_t) COM_PARITY_BIT;
    g_com_parm.bdata_bits   = (usb_hcdc_data_bit_t) COM_DATA_BIT;

    setup.request_type   = SET_LINE_CODING;    /* bRequestCode:SET_LINE_CODING, bmRequestType */
    setup.request_value  = 0x0000;             /* wValue:Zero */
    setup.request_index  = 0x0000;             /* wIndex:Interface */
    setup.request_length = LINE_CODING_LENGTH; /* Data:Line Coding Structure */

    /* Request Control transfer */
    g_usb_on_usb.hostControlTransfer(p_ctrl, &setup, (uint8_t *) &g_com_parm, device_address);
}

void get_line_coding (usb_instance_ctrl_t * p_ctrl, uint8_t device_address)
{
    usb_setup_t setup;

    setup.request_type   = GET_LINE_CODING;    /* bRequestCode:GET_LINE_CODING, bmRequestType */
    setup.request_value  = 0x0000;             /* wValue:Zero */
    setup.request_index  = 0x0000;             /* wIndex:Interface */
    setup.request_length = LINE_CODING_LENGTH; /* Data:Line Coding Structure */

    /* Request Control transfer */
    g_usb_on_usb.hostControlTransfer(p_ctrl, &setup, (uint8_t *) &g_com_parm, device_address);
}