10 UVC Webcam Application

This chapter describes the GK7206 UVC (USB Video Class) webcam application example — uvc_app. The application demonstrates how to present the development board as a USB camera to the host, so that the host can access the camera's video stream over the USB interface.

The application source code is located in the SDK directory sample/uvc_app/, and serves as a reference template for developing USB camera applications.

1 Application Overview

1.1 Features

  • USB camera mode: presents the development board as a USB camera to the host
  • Video streaming: pushes an MJPEG video stream over the USB interface
  • Plug-and-Play: the host automatically recognizes the device and loads the driver
  • Cross-platform support: works on Windows, Linux, and macOS

1.2 Technical Parameters

ParameterValue
USB interfaceUSB 2.0 Device
Video formatMJPEG
Resolution640×480, 320×240, etc.
Frame rate30 FPS
DependenciesUSB connected to host; Sensor

1.3 Directory Structure

sample/uvc_app/
├── Makefile              # Build script
├── ConfigUVC.sh          # UVC configuration script
├── application.c        # Main program
└── uvc_gadget.c         # UVC gadget implementation

2 Build and Deployment

2.1 Prerequisites

Before building this application, make sure the following preparations are complete:

  1. SDK environment ready: set up the cross-compilation toolchain and SDK configuration by following SDK Build
  2. USB interface ready: a USB data cable connected to the host
  3. Sensor connected: an SC465SL or compatible image sensor

2.2 Build the Application

# Enter the sample directory
cd <SDK_PATH>/sample

# Build the uvc_app sample
make -C uvc_app clean && make -C uvc_app

2.3 Deploy to the Board

# Transfer to the development board via SCP
scp sample/uvc_app/application root@<board IP>:/sd_card/
scp sample/uvc_app/ConfigUVC.sh root@<board IP>:/sd_card/

2.4 Run the Application

# Add execute permission
chmod +x /sd_card/application
chmod +x /sd_card/ConfigUVC.sh

# Enter the SD card directory
cd /sd_card

# Configure the UVC gadget
sh ConfigUVC.sh

# Run the application
./application

# Or specify the log level
./application 1

2.5 Host-Side Usage

Windows

  1. After connecting USB, Device Manager recognizes the new camera device
  2. Open the Camera app or third-party software (e.g. OBS, AmCap)
  3. Select the corresponding USB camera

Linux

# View the camera with guvcview
guvcview /dev/video0

# Or use ffmpeg
ffmpeg -f v4l2 -i /dev/video0 -f sdl output

2.6 Expected Output

After a successful run, the terminal prints output similar to the following:

uvc application running
configfs gadget setup complete
USB gadget connected
streaming started...

The live camera picture is visible on the host side.

3 Internal Execution Logic

3.1 Application Architecture

The application adopts the following architecture:

Sensor → VI → VPSS → VENC(MJPEG) → USB Gadget → Host

3.2 UVC Initialization Flow

// Step 1: configure the USB gadget
system("sh ConfigUVC.sh");

// Step 2: initialize the video pipeline
sample_comm_sys_init(&sys_config);
sample_comm_isp_init();
sample_comm_vi_start(...);
sample_comm_vpss_start(...);
sample_comm_venc_start(...);

// Step 3: initialize the UVC gadget
uvc_gadget_init();

// Step 4: start video streaming
uvc_gadget_start_streaming();

// Step 5: push frames in a loop
while (running) {
    xmedia_venc_get_stream(venc_chn, &stream, -1);
    uvc_gadget_send_frame(&stream);
    xmedia_venc_release_stream(venc_chn, &stream);
}

// Step 6: clean up resources
uvc_gadget_stop_streaming();
uvc_gadget_exit();
sample_comm_venc_stop(...);

3.3 USB Gadget Configuration

The ConfigUVC.sh script configures the USB gadget:

#!/bin/sh

# Load the USB gadget driver
modprobe libcomposite

# Configure configfs
cd /sys/kernel/config/usb_gadget
mkdir g1
cd g1

# Configure device information
echo 0x1d6b > idVendor
echo 0x0104 > idProduct
echo "GK7206 UVC" > product

# Create a configuration
mkdir configs/c.1
cd configs/c.1
echo 250 > MaxPower

# Create the UVC function
cd ../../
mkdir functions/uvc.usb0
cd functions/uvc.usb0

# Link the configuration to the function
ln -s configs/c.1 functions/uvc.usb0

# Enable the gadget
echo "$(ls /sys/class/udc)" > UDC

4 Key Programming Points

4.1 MJPEG Encoding Configuration

xmedia_venc_chn_attr_t venc_chn_attr;

venc_chn_attr.type = XMEDIA_PT_MJPEG;
venc_chn_attr.max_width = 640;
venc_chn_attr.max_height = 480;
venc_chn_attr.rc_mode = VENC_RC_MODE_MJPEGCBR;

xmedia_venc_create_chn(venc_chn, &venc_chn_attr);

4.2 Sending Frames over USB

// Get a frame from VENC
xmedia_venc_get_stream(venc_chn, &stream, -1);

// Send the frame over USB
uvc_gadget_send_frame(stream.pack[0].vir_addr, stream.pack[0].len);

// Release the frame
xmedia_venc_release_stream(venc_chn, &stream);

5 Troubleshooting

ProblemPossible CauseSolution
Host cannot recognize the USB deviceUSB gadget configuration failedCheck that ConfigUVC.sh runs correctly
Host recognizes the device but no video streamVideo pipeline initialization failedCheck the sensor connection and VI/VPSS/VENC configuration
Choppy video streamInsufficient USB bandwidthLower the resolution or frame rate
Abnormal video colorsIncorrect MJPEG encoding parametersCheck the VENC encoding configuration

6 References