Hardware Abstraction Layer (HAL)
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):

Features

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);
USB Device object.
Definition: cyhal_hw_types.h:1579
@ USBDM
Port 14 Pin 1.
Definition: cyhal_psoc6_01_104_m_csp_ble_usb.h:137
@ USBDP
Port 14 Pin 0.
Definition: cyhal_psoc6_01_104_m_csp_ble_usb.h:135
cy_rslt_t cyhal_usb_dev_init(cyhal_usb_dev_t *obj, cyhal_gpio_t dp, cyhal_gpio_t dm, const cyhal_clock_t *clk)
Initialize the USB instance.
void cyhal_usb_dev_connect(cyhal_usb_dev_t *obj)
Make the USB device visible to the USB host.
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:426

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
usb_dev_event_handler);
}
void cyhal_usb_dev_register_event_callback(cyhal_usb_dev_t *obj, cyhal_usb_dev_event_t event, cyhal_usb_dev_event_callback_t callback)
The USB Device event complete callback handler registration.
cyhal_usb_dev_event_t
Service Callback Events.
Definition: cyhal_usb_dev.h:157
@ CYHAL_USB_DEV_EVENT_EP0_IN
Callback hooked to endpoint 0 IN packet interrupt.
Definition: cyhal_usb_dev.h:160
@ CYHAL_USB_DEV_EVENT_BUS_RESET
Callback hooked to bus reset interrupt.
Definition: cyhal_usb_dev.h:158
@ CYHAL_USB_DEV_EVENT_EP0_SETUP
Callback hooked to endpoint 0 SETUP packet interrupt.
Definition: cyhal_usb_dev.h:159
@ CYHAL_USB_DEV_EVENT_EP0_OUT
Callback hooked to endpoint 0 OUT packet interrupt.
Definition: cyhal_usb_dev.h:161

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
}
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);
}
void cyhal_usb_dev_process_irq(cyhal_usb_dev_t *obj)
Default USB Device interrupt handler.
void cyhal_usb_dev_irq_enable(cyhal_usb_dev_t *obj, bool enable)
Configure USB Device event enablement.
cy_rslt_t cyhal_usb_dev_register_irq_callback(cyhal_usb_dev_t *obj, cyhal_usb_dev_irq_callback_t callback)
Register a USB Device callback 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
// Enable added Endpoint
}
uint8_t cyhal_usb_dev_ep_t
USB endpoint address (consists from endpoint number and direction)
Definition: cyhal_usb_dev.h:168
void(* cyhal_usb_dev_endpoint_callback_t)(cyhal_usb_dev_ep_t endpoint)
Callback handler for the transfer completion event for data endpoints (not applicable for endpoint 0)
Definition: cyhal_usb_dev.h:178
void cyhal_usb_dev_set_configured(cyhal_usb_dev_t *obj)
Set this device to the configured state.
void cyhal_usb_dev_register_endpoint_callback(cyhal_usb_dev_t *obj, cyhal_usb_dev_ep_t endpoint, cyhal_usb_dev_endpoint_callback_t callback)
The USB Device endpoint complete callback handler registration.
cy_rslt_t cyhal_usb_dev_endpoint_add(cyhal_usb_dev_t *obj, bool alloc, bool enable, cyhal_usb_dev_ep_t endpoint, uint32_t max_packet, cyhal_usb_dev_ep_type_t type)
Configure an endpoint.

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.