# USB Host Camera on Fruit Jam
## Overview
https://www.youtube.com/shorts/mAecQBOQ2H8
[CircuitPython has recently gained support](https://github.com/adafruit/circuitpython/pull/11450) for isochronous communication over USB host on RP2040 and RP2350. This unlocks a few new types of USB devices that can work on the Adafruit Fruit Jam. USB cameras are the group that I have added support for.
This guide demonstrates two projects that use standard USB webcams:
1. Saving photos to the CPSAVES drive or SD card with several filters that can be applied.
2. Converting photos to black and white with Floyd Stenberg dithering and print them over BLE to a thermal printer
## Parts
Featured
### Adafruit Fruit Jam - Mini RP2350 Computer
[Adafruit Fruit Jam - Mini RP2350 Computer](https://www.adafruit.com/product/6200)
We were catching up on a recent [hackaday hackchat with eben upton](https://hackaday.io/event/202122-raspberry-pi-hack-chat-with-eben-upton) and learned some fun facts: such as the DVI hack for the RP2040 was inspired by
Out of Stock
[Buy Now](https://www.adafruit.com/product/6200)
[Related Guides to the Product](https://learn.adafruit.com/products/6200/guides)
### USB Camera
Any standard USB webcam that supports MJPEG at sizes of 320x240 or less. Tested successfully on Logitech models [C270](https://www.logitech.com/en-us/shop/p/c270-hd-webcam) and [C920](https://www.logitech.com/en-us/shop/p/c920s-pro-hd-webcam).
Featured
### USB Type A to Type C Cable - approx 1 meter / 3 ft long
[USB Type A to Type C Cable - approx 1 meter / 3 ft long](https://www.adafruit.com/product/4474)
As technology changes and adapts, so does Adafruit. This **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop.
USB C is the latest industry-standard connector for...
In Stock
[Buy Now](https://www.adafruit.com/product/4474)
[Related Guides to the Product](https://learn.adafruit.com/products/4474/guides)
Featured
### HDMI Cable - 1 meter
[HDMI Cable - 1 meter](https://www.adafruit.com/product/608)
Connect two HDMI devices together with this basic HDMI cable. It has nice molded grips for easy installation, and is 1 meter long (about 3 feet). This is a HDMI 1.3 cable.
We're now stocking a very fancy Official Raspberry Pi cable with overmolding and a Pi logo. Please note...
In Stock
[Buy Now](https://www.adafruit.com/product/608)
[Related Guides to the Product](https://learn.adafruit.com/products/608/guides)
### Cat BLE Thermal Printer
This small feline-styled BLE thermal printer is [available on Amazon](https://www.amazon.com/Printer-Portable-Bluetooth-Wireless-Compatible/dp/B0CHZ74442/)
# USB Host Camera on Fruit Jam
## Install CircuitPython
[CircuitPython](https://github.com/adafruit/circuitpython) is a derivative of [MicroPython](https://micropython.org) designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the **CIRCUITPY** drive to iterate.
## CircuitPython Quickstart
Follow this step-by-step to quickly get CircuitPython running on your board.
Warning: Support for USB host cameras was added in CircuitPython 11.0.0.alpha-1. As of 9/24/26 it is the latest development release of CircuitPython. Scroll down to the development release section of the downloads page!
[Download the latest version of CircuitPython for this board via circuitpython.org](https://circuitpython.org/board/adafruit_fruit_jam/)
**Click the link above to download the latest CircuitPython UF2 file.**
Save it wherever is convenient for you.
To enter the bootloader, hold down the **BOOT/**** BOOTSEL button**(highlighted in red above), and while continuing to hold it (don't let go!), press and release the**reset button**(highlighted in red or blue above). **Continue to hold the BOOT/BOOTSEL button until the RP2350 drive appears!**
If the drive does not appear, release all the buttons, and then repeat the process above.
You can also start with your board unplugged from USB, press and hold the BOOTSEL button (highlighted in red above), continue to hold it while plugging it into USB, and wait for the drive to appear before releasing the button.
A lot of people end up using charge-only USB cables and it is very frustrating! **Make sure you have a USB cable you know is good for data sync.**
You will see a new disk drive appear called **RP2350**.
Drag the **adafruit-circuitpython-_boardname_-_language_-_version_.uf2** file to **RP2350.**
The **RP2350** drive will disappear and a new disk drive called **CIRCUITPY** will appear.
That's it, you're done! :)
## Safe Mode
You want to edit your **code.py** or modify the files on your **CIRCUITPY** drive, but find that you can't. Perhaps your board has gotten into a state where **CIRCUITPY** is read-only. You may have turned off the **CIRCUITPY** drive altogether. Whatever the reason, safe mode can help.
Safe mode in CircuitPython does not run any user code on startup, and disables auto-reload. This means a few things. First, safe mode _bypasses any code in_ **boot.py** (where you can set **CIRCUITPY** read-only or turn it off completely). Second, _it does not run the code in_ **code.py**. And finally, _it does not automatically soft-reload when data is written to the_ **CIRCUITPY** _drive_.
Therefore, whatever you may have done to put your board in a non-interactive state, safe mode gives you the opportunity to correct it without losing all of the data on the **CIRCUITPY** drive.
### Entering Safe Mode
To enter safe mode when using CircuitPython, plug in your board or hit reset (highlighted in red above). Immediately after the board starts up or resets, it waits 1000ms. On some boards, the onboard status LED (highlighted in green above) will blink yellow during that time. If you press reset during that 1000ms, the board will start up in safe mode. It can be difficult to react to the yellow LED, so you may want to think of it simply as a slow double click of the reset button. (Remember, a fast double click of reset enters the bootloader.)
### In Safe Mode
If you successfully enter safe mode on CircuitPython, the LED will intermittently blink yellow three times.
If you connect to the serial console, you'll find the following message.
```terminal
Auto-reload is off.
Running in safe mode! Not running saved code.
CircuitPython is in safe mode because you pressed the reset button during boot. Press again to exit safe mode.
Press any key to enter the REPL. Use CTRL-D to reload.
```
You can now edit the contents of the **CIRCUITPY** drive. Remember, _your code will not run until you press the reset button, or unplug and plug in your board, to get out of safe mode._
## Flash Resetting UF2
If your board ever gets into a really _weird_ state and CIRCUITPY doesn't show up as a disk drive after installing CircuitPython, try loading this 'nuke' UF2 to RP2350. which will do a 'deep clean' on your Flash Memory. **You will lose all the files on the board** , but at least you'll be able to revive it! After loading this UF2, follow the steps above to re-install CircuitPython.
[Download flash erasing "nuke" UF2 for RP2350](https://cdn-learn.adafruit.com/assets/assets/000/132/526/original/rp2350_flash_nuke.uf2)
# USB Host Camera on Fruit Jam
## USB Host Camera Basics
Support for USB host cameras is provided by the [Adafruit CircuitPython USB Host Camera](https://github.com/adafruit/Adafruit_CircuitPython_USB_Host_Camera) library. This page covers the basic setup and usage of the library to view and capture photos from a USB camera. See the following guide pages for complete projects that are ready to run.
## Isochronous Buffer Size
USB devices with isochronous communication need a [ring buffer](https://en.wikipedia.org/wiki/Circular_buffer) to store incoming packets while CircuitPython is doing other things. The `CIRCUITPY_USB_HOST_ISO_BUFFER_SIZE` configuration in **settings.toml** is the way to declare the size allocated for that buffer. A size of `16384` has been found to work nicely for a USB web camera sending 320x240 pixel frames.
Here is an example **settings.toml** file with the buffer configured.
```auto
CIRCUITPY_USB_HOST_ISO_BUFFER_SIZE = 16384
```
## Detect the Camera
The `UVCCamera()` initializer will automatically search for a supported camera connected to a USB host port on the Fruit Jam. It is good practice to make your project code retry until a camera is found in case you happen to power up the board without the camera connected. This loop from the simpletest script demonstrates how to check for the camera every 2 seconds until it one is found.
```python
import time
import adafruit_usb_host_camera
camera = None
while camera is None:
try:
# Finds the camera among the attached devices (a keyboard, a mouse...)
camera = adafruit_usb_host_camera.UVCCamera()
except ValueError:
print("Plug a USB camera into the USB host port")
time.sleep(2)
```
## Configure Mode
Most USB cameras support multiple different modes, each with different capture formats and sizes. The list of supported modes is communicated by the camera inside of its USB descriptor. To make things easy, the `UVCCamera` class has the `find_mode(width, height)` function. Pass in the width and height that you want to capture photos at, and the function will return a `Mode` object corresponding to the closest match that the camera supports.
On the Fruit Jam, 320x240 works best, if you want a live preview from the camera displayed over DVI. 640x480 works as well, but saving a photo takes longer, and the display cannot show the preview at high frames per second (FPS).
```python
print("Camera modes:", camera.modes)
mode = camera.find_mode(320, 240)
print("Using", mode)
```
## Start the Camera
To start the camera so it will begin sending back image data, use the `start_camera()` function. It accepts a `Mode` object representing the capture mode that you want to use.
```python
camera.start(mode)
```
## Save a Photo
To capture a photo and save it as a jpeg file, use the `save_jpeg()` function and pass a path for where to save the photo. The path must be mounted as writable to CircuitPython. The easiest options are inside of the **/saves/** directory, or on an SD card.
```python
camera.save_jpeg("/saves/photo.jpg")
```
## Live Preview via DVI
To show a live preview from the camera on a display connected to the Fruit Jam's DVI output, the `camera.bitmap` property and `update_bitmap()` function are used. The `picogame` module is the fastest way to render the preview. You can use it instead of `displayio` for maximizing the preview FPS.
First initialize the display configured for 320x240, you can skip this the display is already set to 320x240 with 16 bit color depth from your **settings.toml** file. In that case just use `framebuffer = supervisor.runtime.display.framebuffer`.
Next set up the camera in the same way shown above. Then get the bitmap object from the camera and set up the Picogame `Sprite` and `layers`.
Inside the main loop, update the preview by calling `update_bitmap()` and `picogame.render()`
```python
# --------- Display Setup ---------
WIDTH, HEIGHT = 320, 240
# Manual display init
displayio.release_displays()
framebuffer = picodvi.Framebuffer(
WIDTH,
HEIGHT,
clk_dp=board.CKP,
clk_dn=board.CKN,
red_dp=board.D0P,
red_dn=board.D0N,
green_dp=board.D1P,
green_dn=board.D1N,
blue_dp=board.D2P,
blue_dn=board.D2N,
color_depth=16,
)
# Or automatic display init
# Inside settings.toml:
# CIRCUITPY_DISPLAY_WIDTH=320
# CIRCUITPY_DISPLAY_COLOR_DEPTH=16
# Here in code.py:
# framebuffer = supervisor.runtime.display.framebuffer
# Either way, wrap the framebuffer with picogame
render_buffer = picogame.Framebuffer(framebuffer, WIDTH, HEIGHT, native_rgb565=True)
# --------- Camera Setup ---------
# ... same as shown above ...
# --------- Picogame Sprite and Layers setup ---------
# The first access captures a frame and creates the bitmap.
bitmap = None
while bitmap is None:
try:
bitmap = camera.bitmap
except RuntimeError:
pass # no complete frame in time; keep trying
# update_bitmap() decodes each frame into this same bitmap, and picogame draws
# that memory (no copy) straight into the DVI framebuffer.
sprite = picogame.Sprite(picogame.Bitmap(bitmap, bitmap.width, bitmap.height), x=0, y=0)
layers = [sprite]
# --------- Main Loop ---------
while True:
try:
camera.update_bitmap()
except RuntimeError:
continue # no complete frame in time; keep trying
picogame.render(render_buffer, layers, None, 0, 0, WIDTH, HEIGHT)
```
# USB Host Camera on Fruit Jam
## Camera with Effects
This section covers an effects camera project. Live preview from the USB camera is shown on the display connected to the Fruit Jam's DVI output. Several different effects are available which modify colors and other aspects of the images. A number of the effects are 2x2 color grids, inspired by Andy Worhol's artwork.
Info: If you point the camera at the display showing the live preview it functions as a basic [video feedback](https://learn.adafruit.com/video-feedback-with-raspberry-pi) rig.
## Effects Gallery
This gallery shows several of the available photo effects from the project.
# USB Host Camera on Fruit Jam
## Code
## Getting the Program Files
To use the application, you need to obtain **code.py** with the program, and the other project files to place on the Fruit Jam **CIRCUITPY** drive.
Thankfully, this can be done in one go. In the example below, click the **Download Project Bundle** button below to download the necessary libraries, the **code.py** file, and other project files in a zip file.
Connect your board to your computer via a known good data+power USB cable. The board should show up in your File Explorer/Finder (depending on your operating system) as a flash drive named **CIRCUITPY**.
Extract the contents of the zip file, copy the **lib** directory files to **CIRCUITPY/lib**. Copy the **code.py** file to your **CIRCUITPY** drive. The program should self start.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Fruit_Jam/Fruit_Jam_USB_Host_Camera/camera_effects/code.py
## Drive Structure
After copying the files, your drive should look like the listing below. It can contain other files as well, but must contain these at a minimum.
# USB Host Camera on Fruit Jam
## Use
You can use the built-in buttons on the Fruit Jam or a USB keyboard to control the camera app.
## Choose Effect
### On-board Buttons
Cycle through the available effects with the onboard **button 1** and **button 2** on the Fruit Jam.
### USB Keyboard
The **left arrow** and **right arrow** keys on a USB keyboard can be used to go through the effects forward and backwards.
The **up arrow** key will pause the current effect switching to a clean pass-through of the video signal.
The **down arrow** key will resume the current effect after it has been paused. Switching back from the clean pass-through to the current effect.
The **number keys 0-9** will jump to different effects in the list. There are just over 20 effects total, each number on the keyboard acts as a hotkey to every other effect in the list. That means around half of the effects can be reached with a single button press, and the other half can be reached in two button presses, the correct hotkey then a left or right arrow press.
## Take Photo
### On-board Buttons
**Button 3** on the Fruit Jam will save a photo of the current frame.
### USB Keyboard
The **space** , or **enter** buttons will save the current photo.
Both methods will save the photo to an SD card if one is mounted, or the CPSAVES drive if not. Plain photos are saved as **.jpg** files, the version with effects applied is saved as a **.bmp** file.
# USB Host Camera on Fruit Jam
## Camera with BLE Thermal Printer
This section of the guide covers a photo printer project that uses cute feline thermal printer that communicates over BLE.
Info: The CircuitPython code only supports the "Cat" printer models GD02, and MXW01. Other models may not work without changes to the printer library code.
### Cat BLE Thermal Printer
This small feline-styled BLE thermal printer is [available on Amazon](https://www.amazon.com/Printer-Portable-Bluetooth-Wireless-Compatible/dp/B0CHZ74442/)
Thanks to [bitbank2](https://github.com/bitbank2/Thermal_Printer) who originally published the Arduino code for interfacing with these printers. And to Jeff for initially porting it to CircuitPython and writing the original cat printer guide for the CLUE.
### BLE Thermal "Cat" Printer with CircuitPython
[BLE Thermal "Cat" Printer with CircuitPython](https://learn.adafruit.com/ble-thermal-cat-printer-with-circuitpython)
# USB Host Camera on Fruit Jam
## Code
## Getting the Program's Files
To use the application, you need to obtain **code.py** with the program, and the other project files to place on the Fruit Jam **CIRCUITPY** drive.
Thankfully, this can be done in one go. In the example below, click the **Download Project Bundle** button below to download the necessary libraries, the **code.py** file, and other project files in a zip file.
Connect your board to your computer via a known good data+power USB cable. The board should show up in your File Explorer/Finder (depending on your operating system) as a flash drive named **CIRCUITPY**.
Extract the contents of the zip file, copy the **lib** directory files to **CIRCUITPY/lib**. Copy the **code.py** file, as well as **thermalprinter.py** and **fruitjam\_ble/** to your **CIRCUITPY** drive. The program should self start.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Fruit_Jam/Fruit_Jam_USB_Host_Camera/camera_printer/code.py
## Drive Structure
After copying the files, your drive should look like the listing below. It can contain other files as well, but must contain these at a minimum.
# USB Host Camera on Fruit Jam
## Use
You can use the built-in buttons on the Fruit Jam or a USB keyboard to control the printer app.
## Change Brightness
**Button 3** on the Fruit Jam or the **number 3 key** on a USB keyboard will cycle through the different available brightness levels: normal, light, lighter, and dark. This will lighten or darken the photo before applying the Floyd Stenberg dither which will influence the density of regions with white and black pixels in the resulting printed photo.
## Full Color Preview
To see a full color preview on the display, press **button 2** on the Fruit Jam or the **number 2 key** on a USB keyboard.
## Print Photo
Printing the photo is a two step process, first freeze the current frame and confirm it looks how you want. If it looks good, then send it to the printer. Use **button 3** on the Fruit Jam or the **number 3 key** on a USB keyboard. First press to capture the current frame and freeze it on the display, then press again to send it to the thermal printer.
If the captured frame isn't right, press **button 2** on the Fruit Jam or the **number 2 key** on a USB keyboard to re-take the photo instead of sending it to the printer.
## Guide Products
### Adafruit Fruit Jam - Mini RP2350 Computer
[Adafruit Fruit Jam - Mini RP2350 Computer](https://www.adafruit.com/product/6200)
We were catching up on a recent [hackaday hackchat with eben upton](https://hackaday.io/event/202122-raspberry-pi-hack-chat-with-eben-upton) and learned some fun facts: such as the DVI hack for the RP2040 was inspired by
Out of Stock
[Buy Now](https://www.adafruit.com/product/6200)
[Related Guides to the Product](https://learn.adafruit.com/products/6200/guides)
### USB Type A to Type C Cable - approx 1 meter / 3 ft long
[USB Type A to Type C Cable - approx 1 meter / 3 ft long](https://www.adafruit.com/product/4474)
As technology changes and adapts, so does Adafruit. This **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop.
USB C is the latest industry-standard connector for...
In Stock
[Buy Now](https://www.adafruit.com/product/4474)
[Related Guides to the Product](https://learn.adafruit.com/products/4474/guides)
### HDMI Cable - 1 meter
[HDMI Cable - 1 meter](https://www.adafruit.com/product/608)
Connect two HDMI devices together with this basic HDMI cable. It has nice molded grips for easy installation, and is 1 meter long (about 3 feet). This is a HDMI 1.3 cable.
We're now stocking a very fancy Official Raspberry Pi cable with overmolding and a Pi logo. Please note...
In Stock
[Buy Now](https://www.adafruit.com/product/608)
[Related Guides to the Product](https://learn.adafruit.com/products/608/guides)
## Related Guides
- [Adafruit Fruit Jam](https://learn.adafruit.com/adafruit-fruit-jam.md)
- [Using a Raspberry Pi as a Router](https://learn.adafruit.com/using-a-raspberry-pi-as-a-router.md)
- [MagTag Dishwasher Status](https://learn.adafruit.com/magtag-dishwasher-status.md)
- [Spell Jam App on Fruit Jam](https://learn.adafruit.com/spell-jam-app-on-fruit-jam.md)
- [No-Code WipperSnapper Action Counter](https://learn.adafruit.com/no-code-wippersnapper-action-counter.md)
- [MEMENTO Wireless Remote with TouchOSC](https://learn.adafruit.com/memento-wireless-remote.md)
- [Monster Matrix with WLED](https://learn.adafruit.com/monster-matrix-with-wled.md)
- [MCUME Emulators on Fruit Jam](https://learn.adafruit.com/mcume-emulators-on-fruit-jam.md)
- [Ahsoka Lightsaber Prop-Maker RP2040 retrofit](https://learn.adafruit.com/lightsaber-retrofit.md)
- [Track a Turtle with WipperSnapper](https://learn.adafruit.com/track-a-turtle-with-wippersnapper.md)
- [No-Code IoT Pool Monitor](https://learn.adafruit.com/iot-pool.md)
- [ESPHole Ad Blocker](https://learn.adafruit.com/esphole-ad-blocker.md)
- [Create a Memory Game on Fruit Jam Metro RP2350](https://learn.adafruit.com/create-a-memory-game-on-metro-rp2350.md)
- [How to Make Games in MakeCode Arcade](https://learn.adafruit.com/how-to-make-games-on-makecode-arcade.md)
- [itsaSNAP Daily Weather Forecast Board](https://learn.adafruit.com/itsasnap-daily-weather-forecast-board.md)
- [Google Graveyard with Adafruit MagTag](https://learn.adafruit.com/google-graveyard-with-adafruit-magtag.md)