ESPHome components for USB camera

This repository contains external components for ESPHome that enable web camera connected via USB OTG port of ESP32 S2/S3 family of microcontrollers.

Supported video devices

Not every USB video device can work with ESP devices due to their limited capabilities. E.g. only USB1.1 full-speed mode and MJPEG format are supported along with limitations on max bandwidth and max packet size (as requested by the video device). Please refer to the documentation for details.

Power supply

ESP32-S3 DevKitC-1 or similar boards do not provide enough power for USB devices. It must be provided externally or via your own schematics.

Memory, PSRAM

usb_stream requires a lot of video buffers. Current setting is 256K just for transfer buffers. Thus, the ESP32-S2/S3 device has to have PSRAM connected and enabled, e.g.:

psram:
  mode: quad
  speed: 80MHz

ESP-IDF framework mode

The webcam component uses usb_stream component of esp-iot-solution library, which is based on ESP-IDF framework. The following yaml enables esp-idf mode for ESP32-S3 DevKitC-1 board along with correct flash mode:

esphome:
  platformio_options:
    board_build.flash_mode: dio  # default mode is wrong

esp32:
  board: esp32-s3-devkitc-1
  framework:
    type: esp-idf

Import external components

The following yaml can be used to import components into your ESPHome configuration:

external_components:
  - source: github://anton-malakhov/esphome_webcam

Enable webcam

usb_webcam:
  name: usb-webcam

Configuration

The following parameters change behavior of the component:

usb_webcam:
  drop_frame_size: 15000
  # same as esp32_camera parameters:
  idle_framerate: 0.1 fps
  on_stream_start: # trigger
  on_stream_stop:  # trigger

Full example YAML

esphome:
  name: esp-webcam
  platformio_options:
    board_build.flash_mode: dio

esp32:
  board: esp32-s3-devkitc-1
  framework:
    type: esp-idf

psram:
  mode: quad
  speed: 80MHz

external_components:
  - source: github://anton-malakhov/esphome_webcam

usb_webcam:
  name: usb-webcam