USB audio class module

This information applies to the nRF52840 SoC only.

This module allows to create and handle USB audio class instances. For detailed information on the USB audio class, refer to these specification documents:

• Universal Serial Bus Device Class Definition for Audio Devices

• Universal Serial Bus Device Class Definition for Audio Data Formats

• Universal Serial Bus Device Class Definition for Terminal Types

Defining audio class descriptors

A typical audio class has one control interface and one streaming interface. Before you can declare a class instance, you must first properly define the audio class descriptors. These must be defined as a raw uint8_t array.

Example 1: Layout of headphone descriptors in a raw array:

 AUDIO_CONTROL_INTERFACE
 AUDIO_CONTROL_HEADER
 INPUT_TERMINAL
 FEATURE_UNIT
 OUTPUT_TERMINAL
AUDIO_STREAMING_INTERFACE_ALTERNATE0
AUDIO_STREAMING_INTERFACE_ALTERNATE1
 AS_FORMAT_III
 EP_GENERAL
 ISO_EP_OUT

Example 2: Layout of microphone descriptors in a raw array:

AUDIO_CONTROL_INTERFACE
AUDIO_CONTROL_HEADER
 INPUT_TERMINAL
 FEATURE_UNIT
 OUTPUT_TERMINAL
AUDIO_STREAMING_INTERFACE_ALTERNATE0
AUDIO_STREAMING_INTERFACE_ALTERNATE1
 AS_FORMAT_III
 EP_GENERAL
 ISO_EP_IN 

The difference between headphones and microphone descriptors is in the direction of the isochronous endpoint descriptor. Microphone has the IN direction defined (from the USB device to the host). For headphones, the isochronous endpoint direction is set to OUT (from the host to the USB device). Both of these classes have two audio streaming descriptors:

• Streaming interface, alternate setting 0, is selected by the host when no isochronous transfers are required.
• Streaming interface, alternate setting 1, has the following three descriptors defined:
  • Audio streaming format descriptor (I, II, or III)
  • Audio streaming endpoint descriptor
  • Standard endpoint descriptor

Example: Raw uint8_t descriptors for an audio class (Headphones: 2 channels, Fs = 48KHz, Format 16bit PCM):

static const uint8_t m_hp_audio_class_descriptors[] = {
 /* Audio control interface descriptor: 0
 + descriptors defined by AUDIO_CONTROL_DSC_LIST */
 APP_USBD_AUDIO_CONTROL_DSC(0, HP_AUDIO_CONTROL_DSC_LIST(), (1))

 /* Audio streaming interface descriptor: 1, setting: 0 */
 APP_USBD_AUDIO_STREAMING_DSC(1, 0, 0)

 /* Audio streaming interface descriptor: 1, setting: 1 */
 APP_USBD_AUDIO_STREAMING_DSC(1, 1, 1)

 /* Audio class-specific interface descriptor */
 APP_USBD_AUDIO_AS_IFACE_DSC(1, 0, APP_USBD_AUDIO_AS_IFACE_FORMAT_PCM)

 /* Audio class-specific format I descriptor */
 APP_USBD_AUDIO_AS_FORMAT_III_DSC(2, 2, 16, 1, APP_USBD_U24_TO_RAW_DSC(48000))

 /* Audio class-specific endpoint general descriptor */
 APP_USBD_AUDIO_EP_GENERAL_DSC(0x00, 0, 0)

 /* Standard ISO endpoint descriptor */
 APP_USBD_AUDIO_ISO_EP_OUT_DSC(192)
};

Defining audio classes

When all descriptors are correctly defined, you can define the audio class:

#define HP_INTERFACES_CONFIG() APP_USBD_AUDIO_CONFIG_OUT(0, 1)

APP_USBD_AUDIO_GLOBAL_DEF(m_app_audio_headphone,
 HP_INTERFACES_CONFIG(),
 hp_audio_user_ev_handler,
 m_hp_audio_class_descriptors
);

You can pass an event handler function to the class instance definition. The following is an example of a correct audio class user event handler prototype:

void audio_user_ev_handler(app_usbd_class_inst_t const * p_inst,
 app_usbd_audio_user_event_t event);

Registering an audio class to the USBD library

After the function is defined, you must register the new class to the USBD library:

ret = app_usbd_init();
ASSERT(ret == NRF_SUCCESS);

app_usbd_class_inst_t const * class_inst_hp = app_usbd_audio_class_inst_get(&m_app_audio_headphone);
ret = app_usbd_controller_class_append(class_inst_hp);
ASSERT(ret == NRF_SUCCESS);

app_usbd_enable();
app_usbd_start();

Events defined by app_usbd_audio_user_event_t are passed to the user event handler. Requests defined for the audio class trigger the APP_USBD_AUDIO_USER_EVT_CLASS_REQ event. Access to the class request data is obtained by the app_usbd_audio_class_request_get function. Isochronous transfers trigger two types of events:

• APP_USBD_AUDIO_USER_EVT_RX_DONE for OUT endpoints.
• APP_USBD_AUDIO_USER_EVT_TX_DONE for IN endpoints.

The library client must set up buffers for isochronous transfers:

• app_usbd_audio_class_tx_buf_set, when an IN endpoint is defined in the audio descriptors.
• app_usbd_audio_class_rx_buf_set, when an OUT endpoint is defined in the audio descriptors.

Size of these transfer buffers must be the same as the endpoint size defined in raw descriptors. Example: After registering the headphones example presented above, the following buffer is set up:

static int16_t m_rx_buffer[2 * 48];

...

app_usbd_audio_class_rx_buf_set(p_inst, m_rx_buffer, sizeof(m_rx_buffer));

Isochronous transfer buffer can be safely switched (or modified) only on the APP_USBD_AUDIO_USER_EVT_RX_DONE or APP_USBD_AUDIO_USER_EVT_RX_DONE events. Every isochronous transfer is synchronized with the Start of Frame event (SOF) and it is fired automatically when the transfer buffer is configured.