Skip to content

ring buffer for isochronous USBIn for espressif - #11924

Open
FoamyGuy wants to merge 4 commits into
adafruit:mainfrom
FoamyGuy:espressif_usb_host_iso_buffer_2
Open

FoamyGuy wants to merge 4 commits into
adafruit:mainfrom
FoamyGuy:espressif_usb_host_iso_buffer_2

Conversation

@FoamyGuy

@FoamyGuy FoamyGuy commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Adds a ring buffer to hold data from isochronous USB while the VM is busy with other work. Tinyusb host task is used for this as was suggested in hathach/tinyusb#4579. This implementation requires no further changes in upstream tinyusb.

The usage of that task was modeled after existing implementation of the Max3421E.

The goal of this work is to get an example like this one that records audio from USB mic directly to an SD card working on Metro ESP32-P4

import time

import adafruit_usb_host_descriptors
import board
import digitalio
import sdioio
import storage
import usb_host
import usb_host_audio
from audiofilewriter import AudioFileWriter

RECORD_SECONDS = 60

# Mount the SD card and start the USB host port.
sd_card = sdioio.SDCard(
    clock=board.SD_CLK,
    command=board.SD_CMD,
    data=(board.SD_DATA0, board.SD_DATA1, board.SD_DATA2, board.SD_DATA3),
    frequency=40_000_000,
)
storage.mount(storage.VfsFat(sd_card), "/sd")
usb_power = digitalio.DigitalInOut(board.USB_HOST_POWER)
usb_power.switch_to_output(value=True)
usb_port = usb_host.Port(board.USB_HOST_DP, board.USB_HOST_DM)

# Find the microphone and start its stream at 48 kHz.
device = None
while device is None:
    device = adafruit_usb_host_descriptors.find_microphone()
    time.sleep(0.1)
formats = adafruit_usb_host_descriptors.find_microphone_formats(device)
mic_format = adafruit_usb_host_descriptors.choose_microphone_format(formats, sample_rate=48000)
rate = mic_format.nearest_rate(48000)
device.set_configuration()
# SET_INTERFACE starts the stream, then SET_CUR picks the sample rate.
device.ctrl_transfer(0x01, 11, mic_format.alternate, mic_format.interface, None)
if mic_format.rate_control:
    device.ctrl_transfer(0x22, 0x01, 0x0100, mic_format.endpoint, rate.to_bytes(3, "little"))
mic = usb_host_audio.USBIn(
    device,
    mic_format.endpoint,
    sample_rate=rate,
    channel_count=mic_format.channel_count,
    bit_depth=8 * mic_format.bytes_per_sample,
    samples_signed=mic_format.samples_signed,
    max_packet_size=mic_format.max_packet_size,
)
# Some microphones send silence for a second or two after they are powered.
time.sleep(2)

# The point: AudioFileWriter writing straight to a file on the card.
print("Recording", RECORD_SECONDS, "s to /sd/recording.wav")
dropouts = 0
mic.overflow  # reading it clears it
with open("/sd/recording.wav", "wb") as file:
    writer = AudioFileWriter(file)
    writer.play(mic)
    start = time.monotonic()
    while time.monotonic() - start < RECORD_SECONDS:
        # The rest of your program runs here while the recording goes on.
        if mic.overflow:  # audio from the microphone was lost
            dropouts += 1
        time.sleep(0.01)
    writer.stop()  # writes what's left and fills in the WAV header
print("Done:", dropouts, "dropouts")

There are still a few tweaks that will be needed in audiofilewriter on top of this PR to get things working fully.

@FoamyGuy

Copy link
Copy Markdown
Collaborator Author

The RTD page says that the build was cancelled manually:
image

I was able to make a local docs build successfully with make html. I'm not sure if there was a reason it was cancelled or if there is some issue with the build.

@dhalbert

Copy link
Copy Markdown
Collaborator

The RTD page says that the build was cancelled manually:

I have been seeing this recently too. It might be because a build in process was cancelled by pushing a new commit, and there is some recovery issue.

@dhalbert dhalbert left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The ring buffer impl here is a complex, single-use piece of code. We have ringbuf.h already, but it is not atomic and is byte-oriented. Its operations are meant to be called inside critical regions if that is necessary. I don't know if it could be substituted easily.

If not, would it be possible to factor out the ring code into some general purpose atomic ring buffer, so the mechanics are not in the USBIn code? Maybe ringbuf.h could be made better. I rewrote it a long time ago to be simpler because it was very hard to understand how much storage should be allocated. There were lots of off-by-one errors due to how it used to work in MicroPython.

@FoamyGuy

Copy link
Copy Markdown
Collaborator Author

This is updated to use the existing ringbuf now. I added ringbuf_discard_n() which gets used by USBIn to drop the oldest bytes in order to skip ahead if the ring has overflowed.

I changed ringbuf_put_n() and ringbuf_get_n() to copy with at most two memcpy() calls instead of one call per byte. New coverage test validates the bulk put/get implementations.

I tested the audiofilewriter example code from the original post successfully with the latest version

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants