USB Device¶

group group_hal_usb_dev

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);
}