usb_video – Allows streaming bitmaps to a host computer via USB

This makes your CircuitPython device identify to the host computer as a video camera. This mode is also known as “USB UVC”.

This mode requires 1 IN endpoint. Generally, microcontrollers have a limit on the number of endpoints. If you exceed the number of endpoints, CircuitPython will automatically enter Safe Mode. Even in this case, you may be able to enable USB video by also disabling other USB functions, such as usb_hid or usb_midi.

To enable this mode, you must configure the framebuffer size in boot.py and then create a display in code.py.

# boot.py
import usb_video
usb_video.enable_framebuffer(128, 96)

# code.py
import usb_video
import framebufferio
import displayio

displayio.release_displays()
display = framebufferio.FramebufferDisplay(usb_video.USBFramebuffer())

# ... use the display object with displayio Group and TileGrid objects

This interface is experimental and may change without notice even in stable versions of CircuitPython.

Available on these boards
  • 0xCB Helios
  • 42. Keebs Frood
  • Adafruit Feather RP2040
  • Adafruit Feather RP2040 CAN
  • Adafruit Feather RP2040 DVI
  • Adafruit Feather RP2040 Prop-Maker
  • Adafruit Feather RP2040 RFM
  • Adafruit Feather RP2040 Scorpio
  • Adafruit Feather RP2040 ThinkInk
  • Adafruit Feather RP2040 USB Host
  • Adafruit Floppsy RP2040
  • Adafruit ItsyBitsy RP2040
  • Adafruit KB2040
  • Adafruit Macropad RP2040
  • Adafruit Metro RP2040
  • Adafruit QT Py RP2040
  • Adafruit QT2040 Trinkey
  • Arduino Nano RP2040 Connect
  • BBQ20KBD
  • BLOK
  • COSMO-Pico
  • Challenger NB RP2040 WiFi
  • Challenger RP2040 LTE
  • Challenger RP2040 LoRa
  • Challenger RP2040 SD/RTC
  • Challenger RP2040 SubGHz
  • Challenger RP2040 WiFi
  • Challenger RP2040 WiFi/BLE
  • Cytron EDU PICO W
  • Cytron Maker Nano RP2040
  • Cytron Maker Pi RP2040
  • Cytron Maker Uno RP2040
  • Datanoise PicoADK
  • E-Fidget
  • ELECFREAKS PICO:ED
  • Electrolama minik
  • EncoderPad RP2040
  • Fig Pi
  • HEIA-FR Picomo V2
  • Hack Club Sprig
  • LILYGO T-DISPLAY
  • Maple Computing Elite-Pi
  • Melopero Shake RP2040
  • Oak Dev Tech BREAD2040
  • Oak Dev Tech Cast-Away RP2040
  • Pajenicko PicoPad
  • Pimoroni Badger 2040
  • Pimoroni Badger 2040 W
  • Pimoroni Inky Frame 5.7
  • Pimoroni Inky Frame 7.3
  • Pimoroni Interstate 75
  • Pimoroni Keybow 2040
  • Pimoroni Motor 2040
  • Pimoroni PGA2040
  • Pimoroni Pico DV Base W
  • Pimoroni Pico LiPo (16MB)
  • Pimoroni Pico LiPo (4MB)
  • Pimoroni Pico dv Base
  • Pimoroni PicoSystem
  • Pimoroni Plasma 2040
  • Pimoroni Plasma 2040W
  • Pimoroni Servo 2040
  • Pimoroni Tiny 2040 (2MB)
  • Pimoroni Tiny 2040 (8MB)
  • PyKey 18 Numpad
  • PyKey 44 Ergo
  • PyKey 60
  • PyKey 87 TKL
  • RF.Guru RP2040
  • RP2.65-F
  • RP2040 Stamp
  • Raspberry Breadstick
  • Raspberry Pi Pico
  • Raspberry Pi Pico W
  • Seeeduino XIAO RP2040
  • Silicognition LLC RP2040-Shim
  • SparkFun MicroMod RP2040 Processor
  • SparkFun Pro Micro RP2040
  • SparkFun Thing Plus - RP2040
  • VCC-GND Studio YD RP2040
  • W5100S-EVB-Pico
  • W5500-EVB-Pico
  • Waveshare RP2040-GEEK
  • Waveshare RP2040-LCD-0.96
  • Waveshare RP2040-LCD-1.28
  • Waveshare RP2040-Plus (16MB)
  • Waveshare RP2040-Plus (4MB)
  • Waveshare RP2040-TOUCH-LCD-1.28
  • Waveshare RP2040-Tiny
  • Waveshare RP2040-Zero
  • WeAct Studio Pico
  • WeAct Studio Pico 16MB
  • WisdPi Ardu2040M
  • WisdPi Tiny RP2040
  • nullbits Bit-C PRO
  • splitkb.com Liatris
  • takayoshiotake Octave RP2040
  • uGame22

usb_video.enable_framebuffer(width: int, height: int) → None

Enable a USB video framebuffer, setting the given width & height

This function may only be used from boot.py.

Width is rounded up to a multiple of 2.

After boot.py completes, the framebuffer will be allocated. Total storage of 4×``width``×``height`` bytes is required, reducing the amount available for Python objects. If the allocation fails, a MemoryError is raised. This message can be seen in boot_out.txt.

class usb_video.USBFramebuffer

Displays to a USB connected computer using the UVC protocol

The data in the framebuffer is in RGB565_SWAPPED format.

This object is most often used with framebufferio.FramebufferDisplay. However, it also supports the WritableBuffer protocol and can be accessed as an array of H (unsigned 16-bit values).

Returns the singleton framebuffer object, if USB video is enabled

width: int

The width of the display, in pixels

height: int

The height of the display, in pixels

refresh() → None

Transmits the color data in the buffer to the pixels so that they are shown.