espressif/usb_device_uvc

readme

[![Component Registry](https://components.espressif.com/components/espressif/usb_device_uvc/badge.svg)](https://components.espressif.com/components/espressif/usb_device_uvc) ## USB Device UVC Component `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 2. 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=*" ``` ### Examples * [USB WebCamera: Make ESP32-S3-EYE as a USB Camera Device](https://github.com/espressif/esp-iot-solution/tree/master/examples/usb/device/usb_webcam)

changelog

# ChangeLog ## v1.0.0 2024-4-15 * Support trans two cam's picture * Support P4 * Add api `uvc_device_config` ## v0.1.0 2024-2-20 * Break the bidirectional dependency with tinyusb ## v0.0.2 2023-12-06 * Add documentation : https://docs.espressif.com/projects/esp-iot-solution/en/latest/usb/usb_device/usb_device_uvc.html ## v0.0.1 Init version * Support Isochronous and Bulk transfer * Support multiple frame resolutions

readme of usb_dual_uvc_device example

                                        
                                        ## USB UVC Device Example

This example demonstrates how to use the usb_device_uvc component to simulate two virtual cameras. Camera one transmits an AVI video stream, while camera two transmits JPEG images.

## Hardware

* Development board

  1. Any `ESP32-S2`, `ESP32-S3`, `ESP32-P3` board with USB Host port can be used.
  2. Please note that the `esp32-sx-devkitC` board can not output 5V through USB port, If the OTG conversion cable is used directly, the device cannot be powered.
  3. For `esp32s3-usb-otg` board, please enable the USB Host power domain to power the device
  4. The flash size should be at least 8MB.

* Connection

    ||USB_DP|USB_DM|
    |--|--|--|
    |ESP32-S2/S3|GPIO20|GPIO19|

## Build and Flash

Build the project and flash it to the board, then run the monitor tool to view the serial output:

* Run `. ./export.sh` to set IDF environment
* Run `idf.py set-target esp32s3` to set target chip
* Run `pip install "idf-component-manager~=1.1.4"` to upgrade your component manager if any error happends during last step
* Run `idf.py -p PORT flash monitor` to build, flash and monitor the project

(To exit the serial monitor, type `Ctrl-]`.)

See the Getting Started Guide for all the steps to configure and use the ESP-IDF to build projects.

>> Note: The example will fetch an AVI file online. Please make sure the first compilation is done with an internet connection.

## Example Output

```
I (770) avi player: AVI Player Version: 0.1.0
I (770) usb_cam1: Format List
I (770) usb_cam1:       Format(1) = MJPEG
I (772) usb_cam1: Frame List
I (775) usb_cam1:       Frame(1) = 480 * 270 @20fps
I (781) usb_cam2: Format List
I (784) usb_cam2:       Format(1) = MJPEG
I (788) usb_cam2: Frame List
I (792) usb_cam2:       Frame(1) = 1280 * 720 @15fps
I (798) usbd_uvc: UVC Device Start, Version: 0.2.0
I (803) main_task: Returned from app_main()
I (1136) usbd_uvc: Mount
I (3451) usb_cam1: Camera:1 Stop
I (3452) usb_cam2: Camera:2 Stop
I (3452) usbd_uvc: Suspend
I (6279) usbd_uvc: Resume
I (6690) usbd_uvc: bFrameIndex: 1
I (6690) usbd_uvc: dwFrameInterval: 666666
I (6690) usb_cam2: Camera:2 Start
I (6692) usb_cam2: Format: 0, width: 1280, height: 720, rate: 15
I (11180) usbd_uvc: bFrameIndex: 1
I (11180) usbd_uvc: dwFrameInterval: 666666
I (11180) usb_cam2: Camera:2 Start
I (11182) usb_cam2: Format: 0, width: 1280, height: 720, rate: 15
I (32942) usb_cam1: Camera:1 Stop
I (32943) usb_cam2: Camera:2 Stop

```

readme of usb_webcam example

                                        
                                        ## USB WebCam Example

This example demonstrates how to use ESP32-Sx USB function as the USB Web Camera (UVC device). 

* Support both UVC Isochronous and Bulk transfer mode
* Support MJPEG format only
* Support LCD animation in `esp32-s3-eye` board (**IDF v5.0 or later**)

![esp32_s3_eye_webcam](https://dl.espressif.com/AE/esp-dev-kits/webcam.gif)

### Try the example through the esp-launchpad

<a href="https://espressif.github.io/esp-launchpad/?flashConfigURL=https://raw.githubusercontent.com/espressif/esp-dev-kits/master/launch.toml">
    <img alt="Try it with ESP Launchpad" src="https://espressif.github.io/esp-launchpad/assets/try_with_launchpad.png" width="200" height="56">
</a>

This example has been built for `ESP32-S3-EYE`, you can use `esp-launchpad` to flash the binary to your board directly.

Please choose `ESP32-S3-EYE-USB_WebCam_v1_0`, then click flash to quickly start

## How to build the example

### Hardware Required

- Any ESP32-S2 or ESP32-S3 development board with both camera and USB interface, you can also use `idf.py menuconfig`,  select board through `USB WebCam config → Camera Pin Configuration → Select Camera Pinout`, this example use `ESP32-S3-EYE` by default
 
- USB Connection：
  - GPIO19 to D
  - GPIO20 to D+

- Camera Connection：
  - For boards not in the list, please choose `Custom Camera Pinout` to configure each Pin

### Camera Configuration

1. Please check [esp32-camera](https://github.com/espressif/esp32-camera) to find the supported cameras, for this example camera JPEG compression should be supported.
2. Using `idf.py menuconfig`, through `USB WebCam config` users can configure the frame resolution, frame rate and image quality.
3. Through ` USB WebCam config → UVC transfer mode`, users can change to `Bulk` mode to get twice the throughput than `Isochronous`.

|Transfer Mode|Max Throughput|Compatibility|
|--|--|--|
|Isochronous|~512KB/s|Windows/Linux/MacOS|
|Bulk|~1216KB/s|Windows/MacOS|

* `Bulk` mode may encounter compatibility issues on some Linux platform

### Build and Flash

1. Make sure `ESP-IDF` is setup successfully

2. Set up the `ESP-IDF` environment variables, please refer [Set up the environment variables](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#step-4-set-up-the-environment-variables), Linux can use:

    ```bash
    . $HOME/esp/esp-idf/export.sh
    ```

3. Set ESP-IDF build target to `esp32s2` or `esp32s3`

    ```bash
    idf.py set-target esp32s3
    ```

4. Build, Flash, output log

    ```bash
    idf.py build flash monitor
    ```

## Example Output

```
I (0) cpu_start: Starting scheduler on APP CPU.
I (533) spiram: Reserving pool of 32K of internal memory for DMA/internal allocations
I (534) usb_webcam: Selected Camera Board ESP-S3-EYE
I (534) usb_webcam: Format List
I (534) usb_webcam:     Format(1) = MJPEG
I (534) usb_webcam: Frame List
I (535) usb_webcam:     Frame(1) = 1280 * 720 @15fps, Quality = 14
I (535) usb_webcam:     Frame(2) = 640 * 480 @15fps, Quality = 14
I (535) usb_webcam:     Frame(3) = 480 * 320 @30fps, Quality = 10
I (869) usb_webcam: Mount
I (2099) usb_webcam: Suspend
I (9343) usb_webcam: bFrameIndex: 1
I (9343) usb_webcam: dwFrameInterval: 666666
I (9343) s3 ll_cam: DMA Channel=4
I (9344) cam_hal: cam init ok
I (9344) sccb: pin_sda 4 pin_scl 5
I (9344) sccb: sccb_i2c_port=1
I (9354) camera: Detected camera at address=0x30
I (9357) camera: Detected OV2640 camera
I (9357) camera: Camera PID=0x26 VER=0x42 MIDL=0x7f MIDH=0xa2
I (9434) cam_hal: buffer_size: 16384, half_buffer_size: 1024, node_buffer_size: 1024, node_cnt: 16, total_cnt: 180
I (9435) cam_hal: Allocating 184320 Byte frame buffer in PSRAM
I (9435) cam_hal: Allocating 184320 Byte frame buffer in PSRAM
I (9436) cam_hal: cam config ok
I (9436) ov2640: Set PLL: clk_2x: 0, clk_div: 0, pclk_auto: 0, pclk_div: 12
```

Examples:

usb_dual_uvc_device

more details

To create a project from this example, run:

idf.py create-project-from-example "espressif/usb_device_uvc^1.0.0:usb_dual_uvc_device"

or download archive (105 bytes)

usb_webcam

more details

To create a project from this example, run:

idf.py create-project-from-example "espressif/usb_device_uvc^1.0.0:usb_webcam"

or download archive (151 bytes)

espressif/usb_device_uvc

readme

changelog

readme of usb_dual_uvc_device example

readme of usb_webcam example

Links

Targets

License: Apache-2.0

Dependencies

Examples:

usb_dual_uvc_device

usb_webcam

Stats

Badge