USB Camera

2025-11-26

The Quectel Pi H1 single-board computer supports USB interface cameras. The following example uses the Waveshare OV5693 5MP USB camera for testing.

Camera Connection

Insert the USB camera cable into the Type-A interface of Quectel Pi H1.

Hardware connection location:

  1. Run the following command in the SSH terminal to check the USB device information recognized by the system:
dmesg | grep usb

  1. Run the following command in the SSH terminal to view the newly added device nodes:
v4l2-ctl --list-devices

  • /dev/video2 — Main video node; the following gst commands primarily operate on this node.

  • /dev/video3 — Metadata node.

  • /dev/media3 — Hardware topology controller that manages the entire pipeline.

  1. Run the following command in the SSH terminal to check the formats supported by the video node:
v4l2-ctl --list-formats-ext --device /dev/video2

  • As shown, the camera supports two image output formats: MJPG and YUYV.

Basic Functionality

Prerequisites

Connect an HDMI display and run the following command in the SSH terminal:

mount -o rw,remount /
export XDG_RUNTIME_DIR=/dev/socket/weston
export WAYLAND_DISPLAY=wayland-1

Real-Time Preview

  1. Run the following command in the device terminal:
#The MJPG format, resolution and frame rate should correspond to the formats supported by the video node.
gst-launch-1.0 v4l2src device=/dev/video2 ! image/jpeg,width=1280,height=720,framerate=30/1 ! jpegdec ! videoconvert ! waylandsink fullscreen=true

# The YUV format, resolution and frame rate should correspond to the formats supported by the video node.
gst-launch-1.0 v4l2src device=/dev/video2 ! video/x-raw,format=YUY2,width=1280,height=720,framerate=10/1 ! videoconvert ! waylandsink fullscreen=true

Command description:

gst-launch-1.0 -e

Start the pipeline; -e ensures proper termination (EOS) when stopped using Ctrl+C.

v4l2src device=/dev/video2

Capture data from the V4L2 device /dev/video2.

image/jpeg,width=1280,height=720,framerate=30/1

Require the camera to output 1280×720@30 fps in MJPEG format; if the camera does not support this, the pipeline will report an error.

jpegdec

Decode MJPEG frames into raw YUV/RGB pixel data.

videoconvert

Convert the pixel format to a format that Waylandink can accept (usually NV12/BGRx).

waylandsink fullscreen=true

Use Wayland as the display backend and set the window to full screen (no title bar, full screen).

Video Recording

  1. Run the following command in the device terminal:
gst-launch-1.0 -e v4l2src device=/dev/video2 io-mode=2 ! \
  image/jpeg,width=1280,height=720,framerate=30/1 ! \
  jpegdec ! videoconvert ! tee name=t \
  t. ! queue ! v4l2h264enc ! h264parse ! mp4mux ! filesink location=/opt/out.mp4 \
  t. ! queue ! videoconvert ! waylandsink  fullscreen=true sync=false
  1. This command starts the camera with 720p 30 FPS configuration and saves it as a video file after h264 video encoding. If the gst pipeline status changes to "PLAYING", it indicates that the camera is running.
  2. If you want to stop the camera recording, please press CTRL+C.
  3. MP4 files are saved in the /opt/ directory.

Command Description:

  • v4l2src device=/dev/video2 io-mode=2

Capture video streams from /dev/video2 devices, with io mode=2 indicating the use of memory mapped (mmap) mode to improve performance.

  • image/jpeg,width=1280,height=720,framerate=30/1

The specified captured video stream format is MJPEG, with a resolution of 1280 × 720 and a frame rate of 30fps.

  • jpegdec

Decode the video stream in MJPEG format and convert it to the original RGB/YUV format.

  • videoconvert

Convert the decoded video format to a format suitable for subsequent processing (e.g. convert from YUV to RGBA).

  • tee name=t

Split one video stream into two streams, which can be referenced later through t..

  • t. ! queue

Extract a stream from the tee element and buffer it through the queue element.

  • v4l2h264enc

Encode the video stream into H.264 format.

  • h264parse

Analyze the H.264 encoded video stream to meet the requirements of the MP4 file format.

  • mp4mux

Encapsulate H.264 video streams into MP4 file format.

  • filesink location=/opt/out.mp4

Save the packaged MP4 file to /opt/out. mp4.

  • t. ! queue

Extract another stream from the tee element and buffer it through the queue element.

  • videoconvert

Convert the video format to a format suitable for display on Wayland monitors.

  • waylandsink fullscreen=true sync=false

Output the video stream to the Wayland monitor to display the video in full screen mode, disable sync mode, and avoid the Wayland monitor waiting for the data stream, thereby improving display performance.

  1. To play a video file, please run the following command in the device terminal:
gst-launch-1.0 -e filesrc location=/opt/out.mp4 ! qtdemux ! queue ! h264parse ! v4l2h264dec capture-io-mode=5 output-io-mode=5 !  videocrop top=0 bottom=40 left=0 right=0 ! videoconvert ! waylandsink  fullscreen=true enable-last-sample=false

Command Description:

  • filesrc location=/opt/out.mp4

Read data from the /opt/out.mp4 file.

  • qtdemux

Separate the video and audio streams from the MP4 file.

  • queue

Buffer data to avoid data loss during processing.

  • h264parse

Analyze the H.264 encoded data in the video stream.

  • v4l2h264dec capture-io-mode=5 output-io-mode=5

Use the V4L2 decoder to decode the H.264 video stream, where capture io mode=5 and output io mode=5 are hardware acceleration related parameters.

  • videocrop top=0 bottom=40 left=0 right=0

Due to automatic alignment of video streams, additional pixel information is filled in. Resulting in a green edge at the bottom of the video, therefore cropping the bottom by 40 pixels.

  • videoconvert

Format conversion elements ensure that the cropped video stream format is suitable for Wayland monitors.

  • waylandsink fullscreen=true enable-last-sample=false

Output the decoded video to the Wayland monitor and set it to full screen mode, while disabling the display of the last frame.

Photo

  1. Run the following command in the device terminal:
gst-launch-1.0 -e v4l2src device=/dev/video2 io-mode=2 ! \
  image/jpeg,width=1280,height=720,framerate=30/1 ! \
  tee name=t \
  t. ! queue ! jpegdec ! videoconvert ! waylandsink sync=false \
  t. ! queue ! multifilesink location=/opt/shot-%05d.jpg max-files=5
  1. Press CTRL+C to automatically save the last 5 images.

Command Description:

  • v4l2src device=/dev/video2 io-mode=2

Collect MJPEG data from a USB camera.

  • image/jpeg,width=1280,height=720,framerate=30/1

Require the camera to output 1280x720@30 MJPEG stream with fps .

  • tee name=t

Divide the same flow into multiple, and use t. to reference it later.

  • t. ! queue ! jpegdec ! videoconvert ! waylandsink sync=false

Preview branch: decode MJPEG → convert to RGB → send to Wayland window for real-time display. Sync=false reduces latency.

  • t. ! queue ! multifilesink location=shot-%05d.jpg max-files=5

Photography branch: Each frame is saved intact as JPG, and the file name is automatically numbered % 05d (5 digits). Max files=5 Only the most recent 5 files are retained, and old files are automatically deleted.

  1. To view photos, please enter the following command in the device terminal:
gst-launch-1.0 filesrc location=/opt/shot-00036.jpg ! jpegdec ! imagefreeze ! waylandsink fullscreen=true
  1. To exit the view, please press CTRL+C.

Command Description:

  • filesrc location=/opt/shot-00036.jpg

Read /opt/hot-00036. jpg from the file system.

  • jpegdec

Decode JPEG compressed data into raw RGB/YUV pixel frames.

  • imagefreeze

Keep only the first frame and repeat it continuously thereafter to achieve a 'still image' effect.

  • waylandsink fullscreen=true

Send the image to the Wayland synthesizer for full screen display.