USB HCDC (r_usb_hcdc)

Functions
fsp_err_t	R_USB_HCDC_ControlDataRead (usb_ctrl_t *const p_api_ctrl, uint8_t *p_buf, uint32_t size, uint8_t device_address)
	Read Control Data.(CDC Interrupt IN data) More...
fsp_err_t	R_USB_HCDC_SpecificDeviceRegister (usb_ctrl_t *const p_api_ctrl, uint16_t vendor_id, uint16_t product_id)
	Register the specified vendor class device in the device table. More...
fsp_err_t	R_USB_HCDC_DeviceInfoGet (usb_ctrl_t *const p_api_ctrl, usb_hcdc_device_info_t *p_info, uint8_t device_address)
	Get the VID, PID and subclass code of the connected device. More...

Detailed Description

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.
Bulk Input Transfer Pipe	USB PIPE1 USB PIPE2 USB PIPE3 USB PIPE4 USB PIPE5	USB PIPE4	Select the USB pipe to use for bulk input transfers.
Bulk Output Transfer Pipe	USB PIPE1 USB PIPE2 USB PIPE3 USB PIPE4 USB PIPE5	USB PIPE5	Select the USB pipe to use for bulk output transfers.
Interrupt In Pipe	USB PIPE6 USB PIPE7 USB PIPE8 USB PIPE9	USB PIPE6	Select the USB pipe to use for interrupts.

Configurations for Connectivity > USB HCDC (r_usb_hcdc)

This module can be added to the Stacks tab via New Stack > Connectivity > USB HCDC (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.
• This driver does not support simultaneous operation with the other device class.

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)

#if (BSP_CFG_RTOS == 2)

/******************************************************************************
 * Function Name   : usb_apl_callback
 * Description     : Callback function for Application program
 * Arguments       : usb_event_info_t *p_api_event    : Control structure for USB API.
 *               : usb_hdl_t        cur_task        : Task Handle
 *               : uint8_t          usb_state       : USB_ON(USB_STATUS_REQUEST) / USB_OFF
 * Return value    : none
 ******************************************************************************/
void usb_apl_callback (usb_event_info_t * p_api_event, usb_hdl_t cur_task, usb_onoff_t usb_state)
{
    (void) usb_state;
    (void) cur_task;

    xQueueSend(g_apl_mbx_hdl, (const void *) &p_api_event, (TickType_t) (0));
}                                      /* End of function usb_apl_callback() */

#endif /* (BSP_CFG_RTOS == 2) */

/******************************************************************************
 * Function Name   : usb_hcdc_example
 * Description     : Host CDC application main process
 * Arguments       : none
 * Return value    : none
 ******************************************************************************/
void usb_hcdc_example (void)
{
    usb_status_t     event;
    usb_event_info_t event_info;
#if (BSP_CFG_RTOS == 2)
    usb_event_info_t * p_mess;
#endif

    g_usb_on_usb.open(&g_basic0_ctrl, &g_basic0_cfg);


    while (1)
    {
#if (BSP_CFG_RTOS == 2)                /* FreeRTOS */
        xQueueReceive(g_apl_mbx_hdl, (void *) &p_mess, portMAX_DELAY);

        event_info = *p_mess;
        event      = event_info.event;
#else                                  /* (BSP_CFG_RTOS == 2) */
        /* Get USB event data */
        g_usb_on_usb.eventGet(&event_info, &event);
#endif  /* (BSP_CFG_RTOS == 2) */

        /* 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;
        }

    }
}                                      /* End of function usb_hcdc_example() */

/******************************************************************************
 * Function Name   : set_control_line_state
 * Description     : Send the class request (SetControLineState) to CDC device.
 * Arguments       : device_address : device address of CDC device.
 * Return value    : none
 ******************************************************************************/
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);
} /* End of function set_control_line_state() */

/******************************************************************************
 * Function Name   : set_line_coding
 * Description     : Send the class request (SetLineCoding) to CDC device.
 * Arguments       : device_address : device address of CDC device.
 * Return value    : none
 ******************************************************************************/
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);
} /* End of function set_line_coding() */

/******************************************************************************
 * Function Name   : get_line_coding
 * Description     : Send the class request (GetLineCoding) to CDC device.
 * Arguments       : device_address : device address of CDC device.
 * Return value    : none
 ******************************************************************************/
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);
} /* End of function get_line_coding() */

Function Documentation

R_USB_HCDC_ControlDataRead()

fsp_err_t R_USB_HCDC_ControlDataRead	(	usb_ctrl_t *const	p_api_ctrl,
		uint8_t *	p_buf,
		uint32_t	size,
		uint8_t	device_address
	)

Read Control Data.(CDC Interrupt IN data)

Return values

FSP_SUCCESS	Successfully completed (Data read request completed).
FSP_ERR_USB_FAILED	The function could not be completed successfully.
FSP_ERR_USB_BUSY	Data receive request already in process for USB device with same device address.
FSP_ERR_ASSERTION	Parameter is NULL error.
FSP_ERR_USB_PARAMETER	Parameter error.

Note

1. Do not call this API in the following function.

(1). Interrupt function.

(2). Callback function ( for RTOS ).

R_USB_HCDC_SpecificDeviceRegister()

fsp_err_t R_USB_HCDC_SpecificDeviceRegister	(	usb_ctrl_t *const	p_api_ctrl,
		uint16_t	vendor_id,
		uint16_t	product_id
	)

Register the specified vendor class device in the device table.

Return values

FSP_SUCCESS	Successfully completed.
FSP_ERR_USB_FAILED	The function could not be completed successfully.
FSP_ERR_ASSERTION	Parameter Null pointer error.
FSP_ERR_USB_PARAMETER	Parameter error.

Note

(1). Interrupt function.

(2). Callback function ( for RTOS ).

R_USB_HCDC_DeviceInfoGet()

fsp_err_t R_USB_HCDC_DeviceInfoGet	(	usb_ctrl_t *const	p_api_ctrl,
		usb_hcdc_device_info_t *	p_info,
		uint8_t	device_address
	)

Get the VID, PID and subclass code of the connected device.

Return values

FSP_SUCCESS	Successfully completed.
FSP_ERR_USB_FAILED	The function could not be completed successfully.
FSP_ERR_ASSERTION	Parameter Null pointer error.
FSP_ERR_USB_PARAMETER	Parameter error.

Note

(1). Interrupt function.

(2). Callback function ( for RTOS ).