Experimental: USBD driver

This information applies to the nRF52840 SoC only.

The USB device (USBD) driver includes two layers: the hardware access layer (HAL) and the driver layer (DRV).

The hardware access layer provides basic APIs for accessing the registers of the USBD peripheral. For details, see the API documentation for the USBD HAL.

The driver provides APIs on a higher level than the HAL. For details, see the API documentation for the USB Device raw IP HAL and driver.

Key features of this driver include:

• Support for a single instance only.
• Architecture that is completely event driven. Most of the library processing is handled in interrupts.
• 16 bulk endpoints: eight IN and eight OUT.
  • Any endpoint size up to 64 B.
• Two isochronous endpoints: one IN and one OUT.
  • Any endpoint size up to 1024 B or up to 512 B when both endpoints are in use.
• Setup packet decoding.
• Setup data packets, bulk, and isochronous transfers use a consistent and similar interface.
• Transfers from the flash memory, realized in software transparently.
• Set and forget functionality for long transfers (not for isochronous endpoints).

The driver can have four different states:

• Uninitialized: the driver cannot be used.
• Initialized:
  • The event handler is configured.
  • HFCLK is requested.
  • All endpoints size configured to maximum.
  • The peripheral is still disabled.
• Enabled:
  • The peripheral itself is enabled.
  • Peripheral 48 MHz clock is active.
  • Interrupts stay disabled.
  • USB pins pull-up is disabled.
• Started:
  • Fully functional library.
  • Interrupts are enabled.
  • USB pins pull-up is enabled.

See the following function documentation for more details about the USBD driver states:

• nrf_drv_usbd_init
• nrf_drv_usbd_enable
• nrf_drv_usbd_disable
• nrf_drv_usbd_start

Using the USBD driver

Example code that provides USB HID functionality using only the USBD driver can be found here: USB Device Example. Compared to the other USB examples available in this SDK, this example does not use the USBD high level library.

The driver's functionality can be divided into three types of functions:

• Functions that modify the internal state of the whole library:
  • nrf_drv_usbd_init and nrf_drv_usbd_uninit
  • nrf_drv_usbd_enable and nrf_drv_usbd_disable
  • nrf_drv_usbd_start and nrf_drv_usbd_stop
  • Internal status functions: nrf_drv_usbd_is_initialized, nrf_drv_usbd_is_enabled, and nrf_drv_usbd_is_started
• Functions related to the endpoints:
  • Data transfer:
    • nrf_drv_usbd_ep_transfer
    • nrf_drv_usbd_ep_handled_transfer
    • usbd_drv_ep_abort
    • nrf_drv_usbd_transfer_out_drop
  • State and status:
    • nrf_drv_usbd_ep_max_packet_size_set, and nrf_drv_usbd_ep_max_packet_size_get
    • nrf_drv_usbd_ep_enable, nrf_drv_usbd_ep_disable, and nrf_drv_usbd_ep_enable_check
    • nrf_drv_usbd_ep_status_get
    • nrf_drv_usbd_epout_size_get
    • nrf_drv_usbd_ep_is_busy
    • nrf_drv_usbd_ep_stall, nrf_drv_usbd_ep_stall_clear, and nrf_drv_usbd_ep_stall_check
• Functions related to the setup messages:
  • nrf_drv_usbd_setup_get
  • nrf_drv_usbd_setup_data_clear
  • nrf_drv_usbd_setup_clear
  • nrf_drv_usbd_setup_stall
  • nrf_drv_usbd_last_setup_dir_get

To start the USBD driver, you must initialize it first:

ret_code_t ret;

ret = nrf_drv_usbd_init(usbd_event_handler);
APP_ERROR_CHECK(ret);

The event handler provided to the nrf_drv_usbd_init function will process all events that come from the driver:

static void usbd_event_handler(nrf_drv_usbd_evt_t const * const p_event)
{
 switch(p_event->type)
 {
 case NRF_DRV_USBD_EVT_SOF:
 {
 ...
 break;
 }
 case NRF_DRV_USBD_EVT_RESET:
 {
 ...
 break;
 }
 case NRF_DRV_USBD_EVT_SUSPEND:
 {
 ...
 break;
 }
 case NRF_DRV_USBD_EVT_RESUME:
 {
 ...
 break;
 }
 case NRF_DRV_USBD_EVT_SETUP:
 {
 ...
 break;
 }
 case NRF_DRV_USBD_EVT_EPTRANSFER:
 {
 ...
 break;
 }
 default:
 break;
 }
}

In most cases, enabling and starting of the USBD driver will be processed in response to USB power events (see nrf_drv_power_usbevt_init). Using the POWER driver driver, USB can be initialized in the following way:

static void power_usb_event_handler(nrf_drv_power_usb_evt_t event)
{
 switch(event)
 {
 case NRF_DRV_POWER_USB_EVT_DETECTED:
 if(!nrf_drv_usbd_is_enabled())
 {
 nrf_drv_usbd_enable();
 }
 break;
 case NRF_DRV_POWER_USB_EVT_REMOVED:
 if(nrf_drv_usbd_is_started())
 {
 nrf_drv_usbd_stop();
 }
 if(nrf_drv_usbd_is_enabled())
 {
 nrf_drv_usbd_disable();
 }
 break;
 case NRF_DRV_POWER_USB_EVT_READY:
 if(!nrf_drv_usbd_is_started())
 {
 nrf_drv_usbd_start(true);
 }
 break;
 default:
 ASSERT(false);
 }
}

The USB driver is fully functional as soon as the nrf_drv_usbd_start function is processed.

You can now start transferring any data over endpoints. For example, the following code presents sending data in response to the SETUP command on EP0:

ret_code_t ret;
nrf_drv_usbd_transfer_t transfer =
{
 .p_data = {.tx = p_data},
 .size = size
};
ret = nrf_drv_usbd_ep_transfer(NRF_DRV_USBD_EPIN0, &transfer);

When the transmission is finished, the NRF_DRV_USBD_EVT_EPTRANSFER event is generated. See nrf_drv_usbd_evt_t and nrf_drv_usbd_ep_status_t for more details.