3.1.2 USB Camera User Guide

Last Version: 10/09/2025

This guide explains how to set up a USB camera on SpacemiT development board, capture images using the JDK C++ interface, and troubleshoot common issues.

Environment Preparation

Hardware Connection

Connect the USB camera module to the USB port on the development board, as shown below:
Connect the development board to a monitor using an HDMI cable to enable image output.

C++ Interface Usage Example

The following example demonstrates how to use the JDK C++ API to capture, decode, and display frames from a USB camera:

// Open the camera node
auto camera = JdkUsbCam::create(device, width, height, V4L2_PIX_FMT_MJPEG);
// Create a JPEG decoder
auto decoder = std::make_shared<JdkDecoder>(width, height, CODING_MJPEG, PIXEL_FORMAT_NV12);
// Initialize the display module (vo)
auto jdkvo = std::make_shared<JdkVo>(width, height, PIXEL_FORMAT_NV12);
// Get a frame of image data
auto frame = camera->getFrame();
// Decode JPEG images
auto decFrame = decoder->Decode(frame);
// Send the image frame to the display module
auto ret = jdkvo->sendFrame(decFrame);

Quick Integration: JDK Camera Capture SDK

Download and Install the JDK SDK

wget https://archive.spacemit.com/ros2/code/jdk_sdk.tar.gz
sudo tar xvf jdk_sdk.tar.gz -C /opt/
mv /opt/jdk_sdk /opt/jdk

Directory structure after installation:

/opt/jdk
├── include
├── jdk_examples
├── ko
├── lib
├── Makefile
└── README.md

Download and Extract `jdk_usbca`

wget https://archive.spacemit.com/ros2/code/jdk_usbcam.tar
tar xvf jdk_usbcam.tar

Directory structure after extraction:

jdk_usbcam/
├── Makefile
├── src/
│   └── main.cpp
└── workspace/

Compile and Run

cd jdk_usbcam
make all
insmod /opt/jdk/ko/jdk_dma.ko

Execute the program through the command line and specify the camera device node:

./workspace/jdk_usbcam /dev/video20

🚨 Tip: Please confirm the device node path according to the actual situation, such as /dev/video20 above. Device information can be viewed through the command:
v4l2-ctl --list-devices

Once executed, the terminal displays logs from module initialization and image acquisition.

Example Startup Log

Below is a sample of expected log output during initialization and runtime:

VIDIOC_STREAMON succeeded
[MPP-DEBUG] 10800:module_init:159 +++++++++++++++ module init, module type = 9
[MPP-DEBUG] 10800:find_v4l2_linlonv5v7_plugin:83 yeah! we have v4l2_linlonv5v7_codec plugin---------------
[MPP-DEBUG] 10800:module_init:199 ++++++++++ V4L2_LINLONV5V7 (/usr/lib/libv4l2_linlonv5v7_codec.so)
[MPP-DEBUG] 10800:module_init:199 ++++++++++ open (/usr/lib/libv4l2_linlonv5v7_codec.so) success !
[MPP-DEBUG] 10800:al_dec_create:337 init create
[MPP-DEBUG] 10800:al_dec_init:398 input para check: foramt:0x4745504a output format:0x3231564e input buffer num:12 output buffer num:8
[MPP-DEBUG] 10800:al_dec_init:421 video fd = 4, device path = '/dev/video0'
[MPP-DEBUG] 10800:createCodec:115 create a codec, width=1280 height=720 align=1 inputtype=2 outputtype=9 inputformat=4745504a outputformat=3231564e inputbufnum=12 outputbufnum=8
[MPP-DEBUG] 10800:createPort:80 create a port, type=2 format_fourcc=1195724874
[MPP-DEBUG] 10800:createPort:80 create a port, type=9 format_fourcc=842094158
[MPP-DEBUG] 10800:getTrySetFormat:196 width=1280 height=720 align=1 pixel_format=4745504a
[MPP-DEBUG] 10800:printFormat:294 PRINTFORMAT ===== type: 2, format: 1195724874, width: 1280, height: 720, bytesperline: 0, sizeimage: 1048576
[MPP-DEBUG] 10800:getTrySetFormat:196 width=1280 height=720 align=1 pixel_format=3231564e
[MPP-DEBUG] 10800:printFormat:283 PRINTFORMAT ===== type: 9, format: 842094158, width: 1280, height: 720, nplanes: 2, bytesperline: [1280 1280 0], sizeimage: [921600 460800 0]
[MPP-DEBUG] 10800:allocateBuffers:340 Request buffers. type:2 count:12(12) memory:1
[MPP-DEBUG] 10800:allocateBuffers:340 Request buffers. type:9 count:8(8) memory:4
[MPP-DEBUG] 10800:streamon:558 Stream on 1751956058513
[MPP-DEBUG] 10800:streamon:558 Stream on 1751956058513
[MPP-DEBUG] 10800:al_dec_init:449 init finish
[MPP-DEBUG] 10800:VO_CreateChannel:43 create VO Channel success!
[MPP-DEBUG] 10800:module_init:159 +++++++++++++++ module init, module type = 101
[MPP-DEBUG] 10800:check_vo_sdl2:121 yeah! have vo_sdl2---------------
[MPP-DEBUG] 10800:find_vo_sdl2_plugin:86 yeah! we have vo_sdl2_plugin plugin---------------
[MPP-DEBUG] 10800:module_init:207 ++++++++++ VO_SDL2 (/usr/lib/libvo_sdl2_plugin.so)
[MPP-DEBUG] 10800:module_init:207 ++++++++++ open (/usr/lib/libvo_sdl2_plugin.so) success !
[MPP-ERROR] 10800:al_vo_init:93 SDL could not initialize! SDL_Error: wayland not available
[MPP-ERROR] 10800:al_vo_init:128 k1 vo_sdl2 init fail
[MPP-DEBUG] 10800:VO_Init:66 init VO Channel, ret = -400
[MPP-ERROR] 10800:JdkVo:32 VO_init failed, please check!
[MPP-INFO] 10801:runpoll:321 Now k1 hardware decoding ...
select: Resource temporarily unavailable
Failed to capture frame 0
NO data, return.
[MPP-DEBUG] 10801:handleEvent:453 get V4L2_EVENT_SOURCE_CHANGE event, do notify!
[MPP-DEBUG] 10800:handleOutputBuffer:1509 Resolution changed:0 new size: 1280 x 720
[MPP-DEBUG] 10800:streamoff:571 Stream off 1751956060839
[MPP-DEBUG] 10800:allocateBuffers:340 Request buffers. type:9 count:0(0) memory:4
[MPP-DEBUG] 10800:getTrySetFormat:196 width=1280 height=720 align=1 pixel_format=3231564e
[MPP-DEBUG] 10800:printFormat:283 PRINTFORMAT ===== type: 9, format: 842094158, width: 1280, height: 720, nplanes: 2, bytesperline: [1280 1280 0], sizeimage: [921600 460800 0]
[MPP-DEBUG] 10800:allocateBuffers:340 Request buffers. type:9 count:12(12) memory:4
[MPP-DEBUG] 10800:streamon:558 Stream on 1751956060850
[MPP-ERROR] 10800:queueBuffer:461 Failed to queue buffer. type = 9 (Invalid argument)
[MPP-ERROR] 10800:al_dec_return_output_frame:652 queueBuffer failed, this should not happen, please check!
[MPP-DEBUG] 10800:VO_Process:82 vo one packet, ret = 0
index:1,dma_fd:33 width:1280,height:720,size:1382400
[MPP-DEBUG] 10800:VO_Process:82 vo one packet, ret = 0
index:2,dma_fd:33 width:1280,height:720,size:1382400
[MPP-DEBUG] 10800:VO_Process:82 vo one packet, ret = 0
index:3,dma_fd:33 width:1280,height:720,size:1382400

Execution Result

When the program runs successfully, real-time images from the camera are displayed on the monitor:

Common Issues and Recommendations

Issue	Description
Camera not detected	Check USB connection, try other ports, or verify the camera model
Camera won't open	Possibly not recognized or unsupported by driver
SDL error	Missing graphical library dependency; does not affect image capture
No image display	Check `vo` initialization logs and verify display channel & permissions

3.1.2 USB Camera User Guide

Environment Preparation​

Hardware Connection​

C++ Interface Usage Example​

Quick Integration: JDK Camera Capture SDK​

Download and Install the JDK SDK​

Download and Extract jdk_usbca​

Compile and Run​

Example Startup Log​

Execution Result​

Common Issues and Recommendations​