USB Device UVC
usb_device_uvc is a USB UVC device driver for ESP32-S2/ESP32-S3/ESP32-P4, which supports streaming JPEG frames to the USB Host. User can wrapper the Camera or any devices as a UVC standard device through the callback functions.
Features:
Support video stream through the UVC Stream interface
Support both
IsochronousandBulkmodeSupport multiple resolutions and frame rates
Add component to your project
Please use the component manager command add-dependency to add the usb_device_uvc to your project’s dependency, during the CMake step the component will be downloaded automatically
idf.py add-dependency "espressif/usb_device_uvc=*"
User Reference
The component provides only one API to configure the UVC device. As the driver based on the TinyUSB stack, the deinit API is not provided.
#include "usb_device_uvc.h"
static esp_err_t camera_start_cb(uvc_format_t format, int width, int height, int rate, void *cb_ctx)
{
// user can initialize the camera here
// camera should be initialized with the given format, width, height and frame rate
return ESP_OK;
}
static void camera_stop_cb(void *cb_ctx)
{
//user code
return;
}
static uvc_fb_t* camera_fb_get_cb(void *cb_ctx)
{
// user code to return a image frame buffer
// camera should prepare next frame, and return the frame buffer
return uvc_fb;
}
static void camera_fb_return_cb(uvc_fb_t *fb, void *cb_ctx)
{
// the frame buffer is returned after it is copied to the transfer buffer
// user code to recycle the frame buffer
return;
}
//the buffer is used to store the data to be sent to the host
const size_t buff_size = 30 * 1024;
uint8_t *uvc_buffer = (uint8_t *)heap_caps_malloc(buff_size, MALLOC_CAP_DEFAULT);
assert(uvc_buffer != NULL);
uvc_device_config_t config = {
.uvc_buffer = uvc_buffer,
.uvc_buffer_size = 40 * 1024,
.start_cb = camera_start_cb,
.fb_get_cb = camera_fb_get_cb,
.fb_return_cb = camera_fb_return_cb,
.stop_cb = camera_stop_cb,
.cb_ctx = NULL,
};
ESP_ERROR_CHECK(uvc_device_config(0, &config));
ESP_ERROR_CHECK(uvc_device_init());
Examples
API Reference
Header File
Functions
-
esp_err_t uvc_device_config(int index, uvc_device_config_t *config)
Configure the UVC device by uvc device number.
- Parameters
index – UVC device index number [0,1]
config – Configuration for the UVC device
- Returns
ESP_OK on success ESP_ERR_INVALID_ARG if the configuration is invalid ESP_FAIL if the UVC device could not be initialized
-
esp_err_t uvc_device_init(void)
Initialize the UVC device, after this function is called, the UVC device will be visible to the host and the host can open the UVC device with the specific format and resolution.
- Returns
ESP_OK on success ESP_FAIL if the UVC device could not be initialized
-
esp_err_t uvc_device_deinit(void)
Deinitialize the UVC device.
- Returns
ESP_OK on success ESP_ERR_INVALID_STATE if the UVC device is not initialized, or event group is NULL
Structures
-
struct uvc_fb_t
Frame buffer structure.
Public Members
-
uint8_t *buf
Pointer to the frame data
-
size_t len
Length of the buffer in bytes
-
size_t width
Width of the image frame in pixels
-
size_t height
Height of the image frame in pixels
-
uvc_format_t format
Format of the frame data
-
struct timeval timestamp
Timestamp since boot of the frame
-
uint8_t *buf
-
struct uvc_device_config_t
Configuration for the UVC device.
Public Members
-
uint8_t *uvc_buffer
UVC transfer buffer
-
uint32_t uvc_buffer_size
UVC transfer buffer size, should bigger than one frame size
-
uvc_input_start_cb_t start_cb
callback function of host open the UVC device with the specific format and resolution
-
uvc_input_fb_get_cb_t fb_get_cb
callback function of host request a new frame buffer
-
uvc_input_fb_return_cb_t fb_return_cb
callback function of the frame buffer is no longer used
-
uvc_input_stop_cb_t stop_cb
callback function of host close the UVC device
-
void *cb_ctx
callback context, for user specific usage
-
uint8_t *uvc_buffer
Type Definitions
-
typedef esp_err_t (*uvc_input_start_cb_t)(uvc_format_t format, int width, int height, int rate, void *cb_ctx)
type of callback function when host open the UVC device
-
typedef uvc_fb_t *(*uvc_input_fb_get_cb_t)(void *cb_ctx)
type of callback function when host request a new frame buffer
-
typedef void (*uvc_input_fb_return_cb_t)(uvc_fb_t *fb, void *cb_ctx)
type of callback function when the frame buffer is no longer used
-
typedef void (*uvc_input_stop_cb_t)(void *cb_ctx)
type of callback function when host close the UVC device