USB Device UVC

[中文]

usb_device_uvc is a USB UVC device driver for ESP32-S2/ESP32-S3, 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:

  1. Support video stream through the UVC Stream interface

  2. Support both Isochronous and Bulk mode

  3. Support 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 = buff_size,
    .start_cb = camera_start_cb,
    .fb_get_cb = camera_fb_get_cb,
    .fb_return_cb = camera_fb_return_cb,
    .stop_cb = camera_stop_cb,
};

ESP_ERROR_CHECK(uvc_device_init(&config));

Examples

usb/device/usb_webcam

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.

参数

  • index – UVC device index number [0,1]

  • config – Configuration for the UVC device

返回

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.

返回

ESP_OK on success ESP_FAIL if the UVC device could not be initialized

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

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

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

Enumerations

enum uvc_format_t

UVC format.

Values:

enumerator UVC_FORMAT_JPEG

JPEG format

提供有关此文档的反馈