USB Host Human Interface Device Class Driver (r_usb_hhid)

Functions
fsp_err_t	R_USB_HHID_TypeGet (usb_ctrl_t *const p_api_ctrl, uint8_t *p_type, uint8_t device_address)
	Get HID protocol.(USB Mouse/USB Keyboard/Other Type.) More...
fsp_err_t	R_USB_HHID_MaxPacketSizeGet (usb_ctrl_t *const p_api_ctrl, uint16_t *p_size, uint8_t direction, uint8_t device_address)
	Obtains max packet size for the connected HID device. The max packet size is set to the area. Set the direction (USB_HID_IN/USB_HID_OUT). More...

Detailed Description

This module provides a USB Host Human Interface Device Class Driver (HHID). It implements the USB HHID Interface.

Overview

The r_usb_hhid module combines with the r_usb_basic module to provide a USB Host Human Interface Device Class (HHID) driver. The HHID driver conforms to the USB Human Interface Device class specifications and implements communication with a HID device.

Features

The r_usb_hhid module has the following key features:

• Data communication with a connected HID device (USB mouse, keyboard etc.)
• Issuing of HID class requests to a connected HID device
• Supports Interrupt OUT transfer

Configuration

Build Time Configurations for r_usb_hhid

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

Configuration	Options	Default	Description
Interrupt In Pipe	USB PIPE6 USB PIPE7 USB PIPE8 USB PIPE9	USB PIPE6	Select the pipe number to use for input interrupt events.
Interrupt Out Pipe	USB PIPE6 USB PIPE7 USB PIPE8 USB PIPE9	USB PIPE9	Select the pipe number to use for output interrupt events.

Configurations for Connectivity > USB HHID driver (r_usb_hhid)

This module can be added to the Stacks tab via New Stack > Connectivity > USB HHID driver (r_usb_hhid). Non-secure callable guard functions can be generated for this module by right clicking the module in the RA Configuration tool and checking the "Non-secure Callable" box.

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

Clock Configuration

Refer to the USB (r_usb_basic) module.

Pin Configuration

Refer to the USB (r_usb_basic) module.

Usage Notes

Note

This driver is not guaranteed to provide USB HID operation in all scenarios. The developer must verify correct operation when connected to the targeted USB peripherals.

Class Requests

The class requests supported by this driver are shown below:

Request	Code	Description
USB_GET_REPORT	0x01	Receives a report from the HID device.
USB_SET_REPORT	0x09	Sends a report to the HID device.
USB_GET_IDLE	0x02	Receives a duration (time) from the HID device.
USB_SET_IDLE	0x0A	Sends a duration (time) to the HID device.
USB_GET_PROTOCOL	0x03	Reads a protocol from the HID device.
USB_SET_PROTOCOL	0x0B	Sends a protocol to the HID device.
USB_GET_REPORT_DESCRIPTOR	0x06	Requests a report descriptor.
USB_GET_HID_DESCRIPTOR	0x06	Requests a HID descriptor.

Data Format

The boot protocol data format of data received from the keyboard or mouse through interrupt-IN transfers is shown below:

offset	Keyboard (8 Bytes)	Mouse (3 Bytes)
0 (Top Byte)	Modifier keys	b0 : Button 1 b1 : Button 2 b2 : Button 3 b3-b7 : Reserved
+1	Reserved	X displacement
+2	Keycode 1	Y displacement
+3	Keycode 2	-
+4	Keycode 3	-
+5	Keycode 4	-
+6	Keycode 5	-
+7	Keycode 6	-

Limitations

• The HID driver does not analyze the report descriptor. This driver determines the report format from the interface protocol.
• This driver does not support DMA transfers.
• This driver does not support High-speed.
• The transfer rates of Full-speed and Low-speed are the same when the max packet sizes of Full-speed and Low-speed are the same.

Examples

USB HHID Example

The main functions of the application are as follows:

1. Performs enumeration and initialization of HID devices.
2. Transfers data to and from a connected HID device (mouse or keyboard). Data received from the device is read and discarded.
3. When an RTOS is used, the USB driver calls the callback (usb_apl_callback) in order to pass events to the main loop through a queue.

Example Operating Environment

Application Processing (for RTOS)

The main loop performs processing to receive data from the HID device as part of the main routine. An overview of the processing performed by the loop is shown below.

1. When a USB-related event has completed, the USB driver calls the callback function (usb_apl_callback). In the callback function (usb_apl_callback), the application task (APL) is notified of the USB completion event using the real-time OS functionality.
2. In APL, information regarding the USB completion event was notified from the callback function is retrieved using the real-time OS functionality.
3. If the USB completion event (the event member of the usb_ctrl_t structure) retrieved in step 2 above is USB_STATUS_CONFIGURED, APL sends the class request (SET_PROTOCOL) to the HID device.
4. If the USB completion event (the event member of the usb_ctrl_t structure) retrieved in step 2 above is USB_STATUS_REQUEST_COMPLETE, APL performs a data reception request to receive data transmitted from the HID device by calling the R_USB_Read function.
5. The above processing is repeated.

Main Loop (Normal mode)

Application Processing (for Non-OS)

The main loop performs processing to receive data from the HID device as part of the main routine. An overview of the processing of the main loop is presented below.

1. When the R_USB_GetEvent function is called after an HID device attaches to the USB host and enumeration completes, USB_STATUS_CONFIGURED is set as the return value. When the APL confirms USB_STATUS_CONFIGURED, it calls the R_USB_Write function to request transmission of data to the HID device.
2. When the R_USB_GetEvent function is called after sending of class request SET_PROTOCOL to the HID device has completed, USB_STATUS_REQUEST_COMPLETE is set as the return value. When the APL confirms USB_STATUS_REQUEST_COMPLETE, it calls the R_USB_Read function to make a data receive request for data sent by the HID device.
3. When the R_USB_GetEvent function is called after reception of data from the HID device has completed, USB_STATUS_READ_COMPLETE is set as the return value. When the APL confirms USB_STATUS_READ_COMPLETE, it calls the R_USB_Read function to make a data receive request for data sent by the HID device.
4. The processing in step 3, above, is repeated.

Main Loop (Normal mode)

/******************************************************************************
 * Macro definitions
 ******************************************************************************/
#define SET_PROTOCOL               (USB_HID_SET_PROTOCOL | USB_HOST_TO_DEV | USB_CLASS | USB_INTERFACE)
#define BOOT_PROTOCOL              (0)
#define USB_FS_DEVICE_ADDRESS_1    (1)

/******************************************************************************
 * Private global variables and functions
 ******************************************************************************/
static const usb_hhid_api_t g_hhid_on_usb =
{
    .typeGet          = R_USB_HHID_TypeGet,
    .maxPacketSizeGet = R_USB_HHID_MaxPacketSizeGet,
};

/******************************************************************************
 * Function Name   : r_usb_hhid_example
 * Description     : Host HID application main process
 * Arguments       : none
 * Return value    : none
 ******************************************************************************/
static void r_usb_hhid_example (void)
{
#if (BSP_CFG_RTOS == 2)
    usb_event_info_t * p_mess;
#endif                                 /* (BSP_CFG_RTOS == 2) */
    usb_status_t     event;
    usb_event_info_t event_info;
    uint16_t         offset = 0;

    g_usb_on_usb.open(&g_basic0_ctrl, &g_basic0_cfg);

    while (1)
    {
#if (BSP_CFG_RTOS == 2)
        USB_APL_RCV_MSG(USB_APL_MBX, (usb_msg_t **) &p_mess);
        event_info = *p_mess;
        event      = event_info.event;
#else                                        /* (BSP_CFG_RTOS == 2) */
        g_usb_on_usb.eventGet(&event_info, &event); /* Get event code */
#endif  /* (BSP_CFG_RTOS == 2) */

        switch (event)
        {
            case USB_STATUS_CONFIGURED:
            {
                g_hhid_on_usb.typeGet(&g_basic0_ctrl, &g_hid_type, USB_FS_DEVICE_ADDRESS_1);
                g_hhid_on_usb.maxPacketSizeGet(&g_basic0_ctrl, &g_mxps, USB_HID_IN, USB_FS_DEVICE_ADDRESS_1);

                /* Send the HID request (SetProtocol) to HID device */
                set_protocol(&g_basic0_ctrl, BOOT_PROTOCOL, USB_FS_DEVICE_ADDRESS_1);
                break;
            }

            case USB_STATUS_READ_COMPLETE:
            {
                offset = hid_memcpy(g_store_buf, g_buf, offset, g_mxps);
                g_usb_on_usb.read(&g_basic0_ctrl, g_buf, (uint32_t) g_mxps, USB_FS_DEVICE_ADDRESS_1);
                break;
            }

            case USB_STATUS_REQUEST_COMPLETE:
            {
                if (USB_HID_SET_PROTOCOL == (event_info.setup.request_type & USB_BREQUEST))
                {
                    g_usb_on_usb.read(&g_basic0_ctrl, g_buf, (uint32_t) g_mxps, USB_FS_DEVICE_ADDRESS_1);
                }

                break;
            }

            default:
            {
                break;
            }
        }
    }
}                                      /* End of function usb_main */

/******************************************************************************
 * Function Name   : set_protocol
 * Description     : Sending SetProtocol request to HID device
 * Arguments       : usb_ctrl_t   *p_ctrl : Pointer to usb_instance_ctrl_t structure.
 *                 : uint8_t      ptorocol: Protocol Type
 *                 : uint8_t      device_address: Device address that sends this request
 * Return value    : none
 ******************************************************************************/
static void set_protocol (usb_instance_ctrl_t * p_ctrl, uint8_t protocol, uint8_t device_address)
{
    usb_setup_t setup;

    setup.request_type   = SET_PROTOCOL;                                                  /* bRequestCode:SET_PROTOCOL, bmRequestType */
    setup.request_value  = protocol;                                                      /* wValue: Protocol Type */
    setup.request_index  = 0x0000;                                                        /* wIndex:Interface */
    setup.request_length = 0x0000;                                                        /* wLength:Zero */
    g_usb_on_usb.hostControlTransfer(p_ctrl, &setup, (uint8_t *) &g_setup_data, device_address); /* Request Control transfer */
} /* End of function set_protocol */

/******************************************************************************
 * Function Name   : hid_memcpy
 * Description     : Copy received hhid data to the application buffer
 * Arguments       : uint8_t      *p_dest   : Pointer to application buffer
 *                 : uint8_t      *p_src    : Pointer to received buffer
 *                 : uint16_t     offset    : Application buffer offset
 *                 : uint16_t     size      : Size of receiced hhid data
 * Return value    : uint16_t     offset + i: Offset
 ******************************************************************************/
static uint16_t hid_memcpy (uint8_t * p_dest, uint8_t * p_src, uint16_t offset, uint16_t size)
{
    uint16_t i;
    for (i = 0; i < size; i++)
    {
        if ((offset + i) == BUFSIZE)
        {
            offset = 0;
        }

        *(p_dest + offset + i) = *(p_src + i);
    }

    return (uint16_t) (offset + i);
}                                      /* End of function hid_memcpy */

Function Documentation

R_USB_HHID_TypeGet()

fsp_err_t R_USB_HHID_TypeGet	(	usb_ctrl_t *const	p_api_ctrl,
		uint8_t *	p_type,
		uint8_t	device_address
	)

Get HID protocol.(USB Mouse/USB Keyboard/Other Type.)

Return values

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

R_USB_HHID_MaxPacketSizeGet()

fsp_err_t R_USB_HHID_MaxPacketSizeGet	(	usb_ctrl_t *const	p_api_ctrl,
		uint16_t *	p_size,
		uint8_t	direction,
		uint8_t	device_address
	)

Obtains max packet size for the connected HID device. The max packet size is set to the area. Set the direction (USB_HID_IN/USB_HID_OUT).

Return values

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