USBAudioConfig.h

Go to the documentation of this file.

#pragma once
#include <stdint.h>
 
#include <cstring>
 
#include "AudioTools/CoreAudio/AudioTypes.h"
 
namespace audio_tools {
 
// ── Platform-specific default USB endpoint numbers ──────────────────────────
// Some MCUs' USB peripherals restrict isochronous transfers to one hardwired
// endpoint number instead of allowing the stack to allocate any free one.
//
// nRF52833/nRF52840 caveats:
//  - The USBD peripheral has exactly one isochronous endpoint pair, hardwired
//    to endpoint number 8 (tinyusb dcd_nrf5x.c: EP_ISO_NUM == 8). Opening an
//    isochronous endpoint at any other number hits
//    TU_ASSERT(epnum == EP_ISO_NUM) and the device stops responding -- this
//    is why ep_in/ep_out/ep_fb are pinned here instead of using
//    TinyUSBDevice.allocEndpoint() like on RP2040/SAMD/STM32.
//  - ep_in and ep_fb both resolve to 0x88 (the same physical IN endpoint),
//    which is safe because they're mutually exclusive: enableFeedbackEp()
//    already requires enable_ep_in == false (see USBAudio2DescriptorBuilder),
//    matching the hardware's single ISO IN + single ISO OUT pair exactly.
//  - ep_int (the AC status/change interrupt endpoint) is NOT restricted --
//    endpoints 1-7 (control/bulk/interrupt) are freely assignable on this
//    chip -- so it keeps the generic -1 default below and is still allocated
//    dynamically even on nRF52.
//  - Because the fixed 0x88/0x08 numbers bypass allocEndpoint() entirely,
//    TinyUSBDevice's internal endpoint counters don't know endpoint 8 is
//    taken. Audio + a single CDC Serial (the common composite case) is safe
//    since CDC only needs a handful of low-numbered endpoints, but stacking
//    many other USB classes alongside Audio could in theory let one of them
//    also land on endpoint 8 and collide -- an edge case, not a concern for
//    a simple Audio+CDC composite device.
#if defined(NRF52840_XXAA) || defined(NRF52833_XXAA)
#ifndef USB_AUDIO_EP_IN
#define USB_AUDIO_EP_IN 0x88
#endif
#ifndef USB_AUDIO_EP_OUT
#define USB_AUDIO_EP_OUT 0x08
#endif
#ifndef USB_AUDIO_EP_FB
#define USB_AUDIO_EP_FB 0x88
#endif
#endif
 
// USBAudioDeviceESP32 (arduino-esp32) has no dynamic endpoint allocation of
// its own -- whatever address is in the config is baked straight into the
// descriptor -- so it needs real, working defaults.
#if defined(ESP32)
#ifndef USB_AUDIO_EP_IN
#define USB_AUDIO_EP_IN 0x83
#endif
#ifndef USB_AUDIO_EP_OUT
#define USB_AUDIO_EP_OUT 0x03
#endif
#ifndef USB_AUDIO_EP_FB
#define USB_AUDIO_EP_FB 0x84
#endif
#ifndef USB_AUDIO_EP_INT
#define USB_AUDIO_EP_INT 0x85
#endif
#endif
 
// Everywhere else (generic TinyUSB: RP2040, SAMD, STM32) -1 tells
// USBAudioDeviceTinyUSB::getInterfaceDescriptor() to allocate the endpoint
// dynamically via TinyUSBDevice.allocEndpoint() instead of using a fixed
// number. Define any of these yourself (e.g. via a build flag) to support
// additional boards/cores, or to pin a fixed address, without touching the
// struct or driver.
#ifndef USB_AUDIO_EP_IN
#define USB_AUDIO_EP_IN -1
#endif
#ifndef USB_AUDIO_EP_OUT
#define USB_AUDIO_EP_OUT -1
#endif
#ifndef USB_AUDIO_EP_FB
#define USB_AUDIO_EP_FB -1
#endif
#ifndef USB_AUDIO_EP_INT
#define USB_AUDIO_EP_INT -1
#endif
 
struct USBAudioConfig : public AudioInfo {
 
  // ── Direction ─────────────────────────────────────────────────────────────
  bool enable_ep_in = true;   
  bool enable_ep_out = true;  
 
  // ── USB endpoint addresses ────────────────────────────────────────────────
  int16_t ep_in = USB_AUDIO_EP_IN;    
  int16_t ep_out = USB_AUDIO_EP_OUT;  
  int16_t ep_fb = USB_AUDIO_EP_FB;    
  int16_t ep_int = USB_AUDIO_EP_INT;  
 
  // ── Interface numbering ───────────────────────────────────────────────────
  uint8_t itf_num_ac = 0;
 
  // ── Buffering ─────────────────────────────────────────────────────────────
  uint8_t fifo_packets = 32;
 
  // ── Device identity ───────────────────────────────────────────────────────
  uint16_t vid = 0xCafe;
  uint16_t pid = 0x4002;
  const char* manufacturer = "Audio Tools";
  const char* product = "USB Audio";
  const char* serial = "000001";
  bool self_powered = true;
  uint8_t max_power_ma = 100;
 
  // ── Advanced ──────────────────────────────────────────────────────────────
  bool enable_feedback_ep = true;
 
  bool enable_multi_sample_rate = false;
 
  bool enable_interrupt_ep = false;
 
  bool enable_ep_in_flow_control = true;
 
  bool use_linear_buffer_rx = true;
  bool use_linear_buffer_tx = true;
  
#if defined(FREERTOS_H) || defined(INC_FREERTOS_H)
  // ── FreeRTOS USB task (RP2040 + FreeRTOS only) ───────────────────────────
  bool enable_usb_task = true;
  int usb_task_stack_size = 1024;
  int usb_task_priority = configMAX_PRIORITIES - 1;
  int usb_task_write_wait_ms = 5;
 
#endif
  // ── Volume Handling ────────────────────────────────────────────────────────
  bool volume_active = false;
 
  // ── ESP32-specific ────────────────────────────────────────────────────────
  bool begin_usb = false;
 
  // ── Zephyr-specific ───────────────────────────────────────────────────────
  uint8_t terminal_id = 1;
 
  bool operator==(const USBAudioConfig& other) {
    return sample_rate == other.sample_rate && channels == other.channels &&
           bits_per_sample == other.bits_per_sample &&
 
           enable_ep_in == other.enable_ep_in &&
           enable_ep_out == other.enable_ep_out &&
 
           ep_in == other.ep_in && ep_out == other.ep_out &&
           ep_fb == other.ep_fb &&
 
           itf_num_ac == other.itf_num_ac &&
           fifo_packets == other.fifo_packets &&
 
           vid == other.vid && pid == other.pid &&
 
           std::strcmp(manufacturer ? manufacturer : "",
                       other.manufacturer ? other.manufacturer : "") == 0 &&
 
           std::strcmp(product ? product : "",
                       other.product ? other.product : "") == 0 &&
 
           std::strcmp(serial ? serial : "",
                       other.serial ? other.serial : "") == 0 &&
 
           self_powered == other.self_powered &&
           max_power_ma == other.max_power_ma &&
 
           enable_feedback_ep == other.enable_feedback_ep &&
           enable_ep_in_flow_control == other.enable_ep_in_flow_control &&
           use_linear_buffer_rx == other.use_linear_buffer_rx &&
           use_linear_buffer_tx == other.use_linear_buffer_tx &&
 
           begin_usb == other.begin_usb && terminal_id == other.terminal_id;
  }
 
  bool operator!=(const USBAudioConfig& other) { return !(*this == other); }
};
 
}  // namespace audio_tools