usb_uvc — ESP-IDF USB UVC demo apps (ESP32-S3)

This repo contains small ESP-IDF projects that turn an ESP32‑S3 into a USB UVC camera device (a “webcam”) using Espressif’s usb_device_uvc component.

• Upstream component: usb_device_uvc in esp-iot-solution
• Output format: MJPEG (JPEG frames over UVC)
• Input source: most demos generate frames from embedded assets or a software renderer; webcam/ streams from a real camera sensor via esp32-camera

Demos in this repo

• static_test_card/: stream a single embedded JPEG test card (simplest “hello UVC”).
• streaming_gif/: decode an embedded animated GIF at boot, JPEG‑encode each frame, then stream the animation.
• pong/: render a Pong game into an in‑RAM framebuffer, JPEG‑encode frames on demand, and stream to the host.
• webcam/: capture JPEG frames from a camera sensor (esp32-camera) and stream them as a UVC webcam.

Hardware

• ESP32‑S3 with native USB (USB‑OTG) wired to a USB connector on your dev board.
• Plug the board into your host via the USB (native) port used for UVC (not a separate UART bridge).

Build / flash (pick a demo directory)

Each demo is an independent ESP-IDF project. From the demo directory:

idf.py set-target esp32s3
idf.py menuconfig   # optional
idf.py build flash monitor

View the “camera” on the host

Open any webcam viewer and select the new camera device:

• macOS: Photo Booth / QuickTime Player (New Movie Recording → camera selector)
• Linux: Cheese or ffplay /dev/videoX
• Windows: Camera app

Common knobs / gotchas

• UVC stream settings: resolution, frame rate, and transport mode (bulk/isochronous) are configured via idf.py menuconfig (the exact menu path depends on the usb_device_uvc component version).
• Frame size limits: these demos commonly budget ~60 KiB per JPEG frame. If your JPEGs exceed that, streaming can fail or frames can be dropped.
• JPEG encoder buffer: some demos expose USB_UVC_JPEG_OUTBUF_SIZE (Kconfig) as an upper bound for encoded JPEG size.