USBAudioConfig.h

Go to the documentation of this file.

#pragma once
#include <stdint.h>
 
#include <cstring>
#include <vector>
 
#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) previously pinned 0x83/0x03/0x84/0x85
// here under the assumption that CDC uses 0x81/0x82/0x02. That assumption is
// wrong: arduino-esp32's own USBCDC::load_cdc_descriptor() (USBCDC.cpp)
// hardcodes notification=0x85, OUT=0x03, IN=0x84 -- i.e. exactly the "safe"
// defaults this block used to define -- so a composite CDC + Audio device
// silently collided on three endpoints (confirmed independently: Adafruit's
// own TinyUSBDevice::allocEndpoint() carries a matching ESP32 workaround
// that explicitly steers around 0x03/0x84/0x85 for the same reason). Rather
// than guess another set of "safe" fixed numbers, ESP32 now falls through to
// the generic -1 ("allocate dynamically") default below: USBAudioDeviceESP32
// resolves it via arduino-esp32's own tinyusb_get_free_in_endpoint() /
// tinyusb_get_free_out_endpoint(), which already know about CDC's reserved
// endpoints. See https://github.com/pschatzmann/arduino-audio-tools/issues/2396.
 
// Arduino UNO R4 / Nano R4 (Renesas RA4M1, arduino:renesas_uno core) caveats:
//  - This core's USB.cpp builds one fixed composite descriptor (CDC + HID +
//    MSD) at runtime and has no dynamic endpoint allocator API (no
//    TinyUSBDevice.allocEndpoint(), no tinyusb_get_free_in_endpoint()), so
//    endpoint numbers must be fixed constants here, same as nRF52 above.
//  - Values must avoid the ones the core's own USB.cpp hardcodes for its
//    built-in interfaces: CDC uses 0x81 (notification), 0x02/0x82 (data);
//    HID uses 0x83; MSD uses 0x04/0x84 (see __USBGetCustomInterfaceDescriptor
//    in USB.h for the authoritative list). EP5-EP7 are free on every
//    variant since none of the built-ins use them.
//  - The RA4M1's RUSB2 USB peripheral (dcd_rusb2.c) only has 2 isochronous-
//    capable pipes, so at most 2 ISO endpoints can be open at once. This
//    matches USBAudioConfig's own constraint that feedback
//    (enable_feedback_ep) is only active in RX-only mode (no IN endpoint) --
//    TX-only, RX-only-with-feedback, and RXTX-without-feedback each need
//    exactly 2 or fewer ISO endpoints, so this hardware limit is never hit
//    through this library's own configuration surface.
#if defined(ARDUINO_ARCH_RENESAS)
#ifndef USB_AUDIO_EP_IN
#define USB_AUDIO_EP_IN 0x85
#endif
#ifndef USB_AUDIO_EP_OUT
#define USB_AUDIO_EP_OUT 0x05
#endif
#ifndef USB_AUDIO_EP_FB
#define USB_AUDIO_EP_FB 0x86
#endif
#ifndef USB_AUDIO_EP_INT
#define USB_AUDIO_EP_INT 0x87
#endif
#endif
 
// Everywhere else (generic TinyUSB: RP2040, SAMD, STM32, and now ESP32) -1
// tells the platform subclass to allocate the endpoint dynamically 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;
 
  std::vector<uint32_t> supported_sample_rates = {8000,  11025, 16000, 22050,
                                                   24000, 32000, 44100, 48000};
 
  bool enable_interrupt_ep = false;
 
  bool enable_ep_in_flow_control = 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 &&
 
           begin_usb == other.begin_usb && terminal_id == other.terminal_id;
  }
 
  bool operator!=(const USBAudioConfig& other) { return !(*this == other); }
};
 
inline uint32_t highestSupportedSampleRate(const USBAudioConfig& cfg) {
  return !cfg.enable_multi_sample_rate || cfg.supported_sample_rates.empty() ? (uint32_t)cfg.sample_rate
                                             : cfg.supported_sample_rates.back();
}
 
}  // namespace audio_tools