01 Camera Client Tutorial

Learn how to build a C++ application that reads camera frames from a Sol3 camera module and optionally controls camera settings.

Prerequisites

Overview

This tutorial shows how to build and deploy a camera client application that runs on Sol3 hardware to access camera frames and control camera settings.

Important

This application runs on the Sol3 device, not on your development machine. It requires deploying the application container to Sol3 hardware following the deployment workflow.

Tutorial Code

The SDK includes a complete camera client tutorial at:

sol3-sdk/apps/tutorials/01_camera_client.cpp

Local Testing on x64 (No Hardware)

You can exercise the camera client on an x64 development machine without Sol3 hardware using the mock camera server. It serves synthetic RAW10 frames (a deterministic color-bar test pattern) over the same shared-memory transport as the on-device camera server.

Build both targets with the x64 preset. The binaries are linked against the x64 sysroot, so run them through sol3_activate_sysroot (or source /opt/sysroots/x64/activate.sh once per shell) so the dynamic loader finds the sysroot libraries.

The server and client communicate over shared-memory endpoints in /run/sol3. On the device this directory is created at boot, but on a development host you must create it yourself:

sudo mkdir -p -m 777 /run/sol3

Note

/run is a tmpfs, so this directory disappears on reboot.

In one terminal, start the server:

sol3-sdk/scripts/sol3_activate_sysroot x64 ./out/build/x64/bin/sol3_camera_server_mock

and in another, run the client against it:

sol3-sdk/scripts/sol3_activate_sysroot x64 ./out/build/x64/bin/tutorial_01_camera_client --camid 1 --control --fps 5 --color-pipeline

To view the synthetic frames, add --save-jpg and an output path:

mkdir -p out/images
sol3-sdk/scripts/sol3_activate_sysroot x64 ./out/build/x64/bin/tutorial_01_camera_client --camid 1 --control --fps 5 --color-pipeline --save-jpg --output-path ./out/images

--save-jpg with --color-pipeline writes debayered color JPEGs to the output path.

This validates the connect, control, frame-delivery, scheduling, and debayer/JPEG paths end to end before deploying to hardware. The same pairing backs the camera_server_client_integration SDK test; run it with ctest --preset x64 -R camera_server_client_integration, which applies the sysroot environment automatically (no manual activation needed).

Note

The mock serves a single camera (--camid 1) and only the MIPI_RAW10 sensor stream. It does not publish a YUV stream, so --yuv and the multi-camera flows in tutorials 03/04 require real hardware. It also does not publish an encoded video stream, so RTSP streaming via sol3_rtsp_server is not available in the x64 mock flow.

How It Works

The camera client application demonstrates two modes of operation:

Read-Only Mode (Default)

Subscribes to camera frames without controlling camera settings.

The client:

  1. Connects to the camera’s shared memory endpoint

  2. Receives camera frames as they’re published

  3. Logs frame metadata (frame number, timestamps, format)

  4. Optionally saves frames to disk

Control Mode

Actively controls camera settings (exposure, ISO, frame rate).

The client:

  1. Connects to both camera frame and control endpoints

  2. Publishes control messages to configure the camera

  3. Receives frames captured with the specified settings

Build and Deploy

Step 1: Build Application Image

Build the ARM64 container image for Sol3:

sol3_build_app_image tutorial_01_camera_client arm64 --cmake-preset arm64 --tag latest

Step 2: Deploy to Sol3 Device

Deploy the image to your Sol3 device:

sol3_deploy_app_image tutorial-01-camera-client-arm64:latest <USER@HDK_IP>

Step 3: Run on Sol3 Device

SSH to the Sol3 device and run the application.

# SSH to device
ssh <USER@HDK_IP>

# Run the camera client
docker run --rm \
  -v /run/sol3:/run/sol3 \
  -v /dev:/dev \
  --privileged \
  tutorial-01-camera-client-arm64:latest <ARGS>

Usage Examples

All commands below run on the Sol3 device after SSH connection. In order to save images to a host directory, create a new directory, e.g. /tmp/camera_output, and mount it in the docker run command using the -v /tmp/camera_output:/camera_output flag.

For brevity, the commands below use <CAMERA-CLIENT-CMD> to represent:

docker run --rm \
  -v /run/sol3:/run/sol3 \
  -v /dev:/dev \
  -v /tmp/camera_output:/camera_output \
  --privileged \
  tutorial-01-camera-client-arm64:latest <ARGS>

Basic Read-Only Client

Receive camera frames without changing settings:

<CAMERA-CLIENT-CMD> --camid 1

Control Frame Rate

Set camera to 10 FPS with default exposure:

<CAMERA-CLIENT-CMD> --camid 1 --control --fps 10

Control Exposure and ISO

Set specific exposure time and ISO:

<CAMERA-CLIENT-CMD> --camid 1 --control --exposure_ns 10000000 --iso 400

Capture Single Snapshot

Take a snapshot 5 seconds from now:

<CAMERA-CLIENT-CMD> --camid 1 --control --abs-time $(date -d '+5 seconds' +%s)

Note

--abs-time sets snapshot_target, which controls when the capture request is submitted to the camera pipeline, not when exposure starts. Exposure begins 2 to 3 frame intervals after submission, and the target must be at least 100 ms in the future. See Camera Capture Timing.

Save Images to Disk

Save frames as JPEG files to a mounted volume:

<CAMERA-CLIENT-CMD> --camid 1 --save-jpg --output-path /camera_output

Save raw binary frames and metadata:

<CAMERA-CLIENT-CMD> --camid 1 --save-bin --save-meta --output-path /camera_output

Finally, simply copy the files from the device directory (/tmp/camera_output in this case) to your host PC to view the images:

# On host
scp -r <USER@HDK_IP>:/tmp/camera_output ./camera_output