USB Camera Test

2025-08-02

The QuecPi Alpha single board computer supports USB interface cameras. Below, we will select a OV5693 5MP USB interface camera from Weixue as an example for testing.

Camera connection

Insert the USB camera cable into the Type-A interface of QuecPi Alpha.

View relevant information

  1. Run the following command in the SSH terminal to view 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 gst command later mainly operates on this node
  • /dev/video3 - Metadata node
  • /dev/media3 - Hardware topology controller that controls the entire pipeline



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

  • As shown in the figure, the camera supports image output in both MJPG and YUYV formats.



Preconditions

Connect the HDMI screen 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:
#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
#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 Ensure that when pressing Ctrl+C to stop, it will end correctly (EOS).

  • v4l2src device=/dev/video2


Collect data from V4L2 device /dev/video2.

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


Require the camera to output 1280x720@30 fps MJPEG; If the camera does not support it, the pipeline will directly 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).


Preview + 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.


Preview + 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.