Raspberry Pi USB Webcam Setup (Headless)

Turn your Raspberry Pi into a plug-and-play USB webcam using uvc-gadget.

Based on:

• Raspberry Pi USB Webcam Tutorial
• Raspberry Pi Forum Discussion

---

Requirements

• Raspberry Pi Zero 2 W, Pi 4, or Pi 5 with USB OTG support
• Raspberry Pi Camera Module
• MicroSD card (16 GB recommended)
• USB data cable connected to your host computer
• Wi-Fi network access
• Another computer to use the webcam

---

1. Flash Raspberry Pi OS

Install Raspberry Pi OS using Raspberry Pi Imager.

Select:

Raspberry Pi OS (Other)
→ Raspberry Pi OS (Legacy) Lite

The Legacy Lite image is recommended for compatibility with this setup.

This installation runs fully headless (without monitor, mouse, or keyboard).

---

2. Configure Raspberry Pi Imager Settings

Before flashing, open the OS Customisation menu and configure the following:

Setting	Value
Hostname	pi-webcam
Username	Your preferred username
Password	Your preferred password
Wi-Fi SSID	Your network name
Wi-Fi Password	Your network password
SSH	Enabled
Authentication	Password authentication

Enable:

• Wi-Fi
• SSH
• Password authentication

You will use these credentials later to connect over SSH.

---

3. Boot the Raspberry Pi

1. Insert the MicroSD card into the Pi
2. Power it on
3. Wait approximately 1–2 minutes for first boot

---

4. Connect via SSH

Connect from your computer:

ssh <username>@pi-webcam.local

Example:

ssh pi@pi-webcam.local

If .local does not work, locate the Pi IP address from your router or network scanner.

---

5. Update the System

Update packages and reboot:

sudo apt update
sudo apt full-upgrade -y
sudo reboot

Reconnect via SSH after reboot completes.

---

6. Configure USB OTG Mode

Move Boot Mount to /boot/firmware

sudo umount /boot
sudo sed -i "s:/boot:/boot/firmware:" /etc/fstab
sudo mkdir /boot/firmware
sudo mount /boot/firmware

Enable USB Gadget Overlay

Append the OTG overlay to config.txt:

echo "dtoverlay=dwc2,dr_mode=otg" | sudo tee -a /boot/firmware/config.txt

This enables USB gadget mode.

---

7. Install Required Dependencies

sudo apt install -y git meson libcamera-dev libjpeg-dev

---

8. Download and Build uvc-gadget

Clone the repository:

git clone https://gitlab.freedesktop.org/camera/uvc-gadget.git
cd uvc-gadget

Compile and install:

make uvc-gadget

cd build

sudo meson install
sudo ldconfig

---

9. Create the Webcam Startup Script

Create the startup script:

sudo nano ~/.rpi-uvc-gadget.sh

Paste the following:

#!/bin/bash

# Variables we need to make things easier later on.

CONFIGFS="/sys/kernel/config"
GADGET="$CONFIGFS/usb_gadget"
VID="0x0525"
PID="0xa4a2"
SERIAL="0123456789"
MANUF=$(hostname)
PRODUCT="UVC Gadget"
BOARD=$(strings /proc/device-tree/model)
UDC=`ls /sys/class/udc` # will identify the 'first' UDC

# Later on, this function is used to tell the usb subsystem that we want
# to support a particular format, framesize and frameintervals
create_frame() {
	# Example usage:
	# create_frame <function name> <width> <height> <format> <name> <intervals>

	FUNCTION=$1
	WIDTH=$2
	HEIGHT=$3
	FORMAT=$4
	NAME=$5

	wdir=functions/$FUNCTION/streaming/$FORMAT/$NAME/${HEIGHT}p

	mkdir -p $wdir
	echo $WIDTH > $wdir/wWidth
	echo $HEIGHT > $wdir/wHeight
	echo $(( $WIDTH * $HEIGHT * 2 )) > $wdir/dwMaxVideoFrameBufferSize

	cat <<EOF > $wdir/dwFrameInterval
$6
EOF
}

# This function sets up the UVC gadget function in configfs and binds us
# to the UVC gadget driver.
create_uvc() {
	CONFIG=$1
	FUNCTION=$2

	echo "Creating UVC gadget functionality : $FUNCTION"

	mkdir functions/$FUNCTION

	create_frame $FUNCTION 640 480 uncompressed u "333333
416667
500000
666666
1000000
1333333
2000000
"

	create_frame $FUNCTION 1280 720 uncompressed u "1000000
1333333
2000000
"

	create_frame $FUNCTION 1920 1080 uncompressed u "2000000"

	create_frame $FUNCTION 640 480 mjpeg m "333333
416667
500000
666666
1000000
1333333
2000000
"

	create_frame $FUNCTION 1280 720 mjpeg m "333333
416667
500000
666666
1000000
1333333
2000000
"

	create_frame $FUNCTION 1920 1080 mjpeg m "333333
416667
500000
666666
1000000
1333333
2000000
"

	mkdir functions/$FUNCTION/streaming/header/h

	cd functions/$FUNCTION/streaming/header/h
	ln -s ../../uncompressed/u
	ln -s ../../mjpeg/m

	cd ../../class/fs
	ln -s ../../header/h

	cd ../../class/hs
	ln -s ../../header/h

	cd ../../class/ss
	ln -s ../../header/h

	cd ../../../control

	mkdir header/h
	ln -s header/h class/fs
	ln -s header/h class/ss

	cd ../../../

	# Maximum USB 2.0 bandwidth
	echo 2048 > functions/$FUNCTION/streaming_maxpacket

	ln -s functions/$FUNCTION configs/c.1
}

# Load composite module
echo "Loading composite module"
modprobe libcomposite

# Configure USB gadget
if [ ! -d $GADGET/g1 ]; then

	echo "Detecting platform:"
	echo "board : $BOARD"
	echo "udc   : $UDC"

	echo "Creating USB gadget"

	mkdir -p $GADGET/g1

	cd $GADGET/g1 || exit 1

	echo $VID > idVendor
	echo $PID > idProduct

	mkdir -p strings/0x409

	echo $SERIAL > strings/0x409/serialnumber
	echo $MANUF > strings/0x409/manufacturer
	echo $PRODUCT > strings/0x409/product

	mkdir configs/c.1
	mkdir configs/c.1/strings/0x409

	create_uvc configs/c.1 uvc.0

	echo $UDC > UDC
fi

# -c 0 selects the first available camera
uvc-gadget -c 0 uvc.0

Save and exit:

CTRL + X
Y
ENTER

---

10. Make the Script Executable

sudo chmod +x ~/.rpi-uvc-gadget.sh

---

11. Configure Automatic Startup

Edit rc.local:

sudo nano /etc/rc.local

Add this line before exit 0:

/home/<username>/.rpi-uvc-gadget.sh &

Example complete file:

#!/bin/sh -e

_IP=$(hostname -I) || true

if [ "$_IP" ]; then
  printf "My IP address is %s\n" "$_IP"
fi

/home/<username>/.rpi-uvc-gadget.sh &

exit 0

Save and exit:

CTRL + X
Y
ENTER

---

12. Shut Down the Raspberry Pi

sudo shutdown -h now

---

13. Connect the Raspberry Pi as a USB Webcam

Important

Use the USB OTG/data port, not the power-only port.

Then:

1. Connect the Raspberry Pi to your computer
2. Power on the Pi
3. Wait approximately 30–60 seconds for boot

Your computer should automatically detect:

UVC Gadget

as a standard USB webcam.

---

Testing the Webcam

Linux

List video devices:

v4l2-ctl --list-devices

Test the webcam:

ffplay /dev/video0

---

Windows

Open one of the following:

• Camera app
• OBS Studio
• Zoom
• Microsoft Teams

Select:

UVC Gadget

---

macOS

Open:

• QuickTime Player
• OBS Studio
• Zoom

Choose:

UVC Gadget

---

Troubleshooting

Camera Not Detected

Verify the camera works:

libcamera-hello

List available cameras:

libcamera-hello --list-cameras

---

USB Device Not Appearing

Verify the OTG overlay:

cat /boot/firmware/config.txt

Ensure this line exists:

dtoverlay=dwc2,dr_mode=otg

---

Script Fails on Boot

Run the script manually:

~/.rpi-uvc-gadget.sh

Check logs:

dmesg | tail -50

---

Check USB Controller

ls /sys/class/udc

You should see a USB controller listed.

---

Performance Notes

Feature	Note
Compression	MJPEG generally performs better than uncompressed video
1080p Support	Depends on USB bandwidth and Raspberry Pi model
USB 2.0 Bandwidth	Can limit frame rates at high resolutions
Multiple Cameras	Select camera using uvc-gadget -c <camera_number> uvc.0

Example:

uvc-gadget -c 1 uvc.0

---

This guide is based on official Raspberry Pi documentation and community contributions.