USB Device

General Description

High level interface for interacting with the USB Device.

This block supports one control endpoint (EP0) and one or more data endpoints. See the device datasheet for the number of data endpoints supported.

Four transfer types are supported (see cyhal_usb_dev_ep_type_t):

• Bulk
• Interrupt
• Isochronous
• Control

Features

• Complies with USB specification 2.0
• Supports full-speed peripheral device operation with a signaling bit rate of 12 Mbps.
• Configurable D+ AND D- pins using cyhal_gpio_t
• Configurable Interrupt and Callback assignment on USB events like SOF, Bus Reset, EP0 Setup and EP0 transaction.
• Configurable USB device address.
• Configurable USB Endpoints (except for Endpoint 0)

Quick Start

cyhal_usb_dev_init can be used for initialization of USB by providing the USBDP and USBDM pins. See Snippet 1: USB Device Initialization for the initialization code snippet.

Code snippets

Snippet 1: USB Device Initialization

The following section initializes the USB Device and assigns the USBDM and USBDP pins using cyhal_usb_dev_init. The clock parameter clk is optional and need not be provided (NULL), to generate and use an available clock resource with a default frequency. The device can be made physically visible to the USB Host by using cyhal_usb_dev_connect

    cyhal_usb_dev_t usb_dev_obj;
    cy_rslt_t rslt;

    /* Initialize USB, assign the USBDP and USBDM pins and assign a new clock */
    rslt = cyhal_usb_dev_init(&usb_dev_obj, USBDP, USBDM, NULL);

    /* Application code to register callback functions, enable events, add endpoints, etc. */

    /* Make the USB device physically visible to USB host */
    cyhal_usb_dev_connect(&usb_dev_obj);

Snippet 2: Handling USB Event Completion

USB events (see cyhal_usb_dev_event_t) like Bus Reset, EP0 transaction, EP0 Setup can be mapped to an interrupt and assigned a callback function. The callback function needs to be first registered using cyhal_usb_dev_register_event_callback. Use different callback functions to handle events individually.

cyhal_usb_dev_t usb_dev_obj;

void usb_dev_event_handler()
{
    /* Handle USB Events here */
}

void snippet_cyhal_usb_dev_event()
{
    /* Initialize the USB as done in Snippet 1 */

    /* Register callback handler for USB events EP0_OUT, EP0_IN, Bus Reset, EP0_SETUP */
    cyhal_usb_dev_register_event_callback(&usb_dev_obj,
        (cyhal_usb_dev_event_t)(CYHAL_USB_DEV_EVENT_EP0_OUT | CYHAL_USB_DEV_EVENT_EP0_SETUP |
        CYHAL_USB_DEV_EVENT_EP0_IN | CYHAL_USB_DEV_EVENT_BUS_RESET),
        usb_dev_event_handler);
}

Snippet 3: Custom USB Interrupt Handler

The following section illustrates how to set up the IRQ interrupt handler for USB device. Inside the handler cyhal_usb_dev_process_irq has been used to process the interrupts.

cyhal_usb_dev_t usb_dev_obj;

/* Interrupt handler callback function */
void usb_irq_handler()
{
    /* Calling the default USB handler*/
    cyhal_usb_dev_process_irq(&usb_dev_obj);
}

void snippet_cyhal_usb_dev_irq()
{
    /* Initialize the USB Device */

    /* Configure USB Device event enablement */
    cyhal_usb_dev_irq_enable(&usb_dev_obj, true);

    /* Register the callback function to handle the events */
    cyhal_usb_dev_register_irq_callback(&usb_dev_obj, usb_irq_handler);
}

Snippet 4: Adding an Endpoint and Handling its Interrupts

The following section shows how to add endpoint to the USB device and configure the endpoint using cyhal_usb_dev_endpoint_add. The interrupts associated with the endpoints are handled by a callback function registered using cyhal_usb_dev_register_endpoint_callback. The endpoint can also be configured using ModusToolbox USB Configurator

cy_rslt_t rslt;
cyhal_usb_dev_t usb_dev_obj;

/* Declare USB Endpoint address that consists of endpoint number and direction */
/* EP1 address value = 0x81 where bits 6:0 represent the endpoint number(0x01) and 7th bit represent the (IN) direction (0x10). */
/* The decimal equivalent of which is 129. */
/* This value is obtained while configuring the endpoint using Modustoolbox USB Configurator */
const uint8_t EP1 = 129;

/* Declare the maximum packet size that can be sent or received */
const uint32_t max_packet_size = 8;

void endpoint_handler()
{
    /* Handle Endpoint related Interrupts here */
}

void snippet_cyhal_usb_dev_endpoint()
{
    /* Initialize the USB Device here */

    /* Adding Endpoint 1 as Interrupt endpoint, with direction IN */
    rslt = cyhal_usb_dev_endpoint_add(&usb_dev_obj, true, true, EP1, max_packet_size, CYHAL_USB_DEV_EP_TYPE_INT );

    /* Register callback handler for Endpoint 1 */
    cyhal_usb_dev_register_endpoint_callback(&usb_dev_obj,
    (cyhal_usb_dev_ep_t) EP1, (cyhal_usb_dev_endpoint_callback_t) endpoint_handler);

    /* Enable added Endpoint */
    cyhal_usb_dev_set_configured(&usb_dev_obj);
}

API Reference
	USB Device HAL Results
	USB Device specific return codes.
	Endpoint
	APIs relating to endpoint management.
	Common
	EP0
	APIs relating specifically to management of endpoint zero.