SDS3 CameraService

Overview

SDS3 CameraService is a camera capture service for the Satellite Brain platform. It reads task configuration files, controls USB and GigE network cameras, and writes captured images, videos, logs, and inference-ready files to predefined runtime directories.

The service is designed for deployments where camera tasks are generated as JSON files and consumed by a long-running camera control process.

Repository Layout

CameraService/
|-- README.md
|-- README.zh-CN.md
|-- LICENSE
|-- install.sh
|-- imaging_defines.json
|-- src/
|   |-- BuildFile/
|   |   |-- makefile
|   |   |-- multi_camera_control_gstreamer.c
|   |   |-- network_cameras.json
|   |-- EnvironmentFile/
|   |   |-- README.md
|   |-- TestFile/
|       |-- send_json.py
|-- systemctrl/
|   |-- CameraService.service
|   |-- CleanImagesToInfer.service

The imaging program executable is built from source during installation or Debian package generation. Prebuilt project binaries are not stored in this repository.

Third-party SDK Notice

Hikrobot MVS SDK is third-party software. This repository does not redistribute Hikrobot MVS .deb packages.

Before running the installer, download the tested ARM Linux MVS client package from the official Hikrobot download page.

Required/tested package:

MVS V3.0.1 ARM
MVS-3.0.1_aarch64_20241128.deb

https://www.hikrobotics.com/cn/machinevision/service/download/?module=0

Place the downloaded package in:

src/EnvironmentFile/

Example package name:

src/EnvironmentFile/MVS-3.0.1_aarch64_20241128.deb

When installing the Debian release package, install the tested Hikrobot MVS SDK first. The package checks for /opt/MVS/lib/aarch64/libMvCameraControl.so during installation and stops with an error if the SDK is missing.

Dependency Model

APT-managed dependencies are kept aligned with install.sh. The project builds the camera executable from source, so the dependency set includes build-essential, pkg-config, libjson-c-dev, libtiff-dev, libgstreamer1.0-dev, libgstreamer-plugins-base1.0-dev, moreutils, and systemd.

JetPack, DeepStream, CUDA, GStreamer, and the NVIDIA multimedia plugins are treated as part of the target SDS3 system environment, consistent with install.sh. They are documented in the reference environment instead of being installed by this project.

Hikrobot MVS SDK is not declared as an APT dependency because it is distributed separately by Hikrobot and is not redistributed by this project. This project is validated against MVS V3.0.1 ARM (MVS-3.0.1_aarch64_20241128.deb).

No requirements.txt is provided at this time. The included Python helper script only uses Python standard-library modules.

Installation

chmod +x ./install.sh
./install.sh

The installer checks whether Hikrobot MVS SDK is already installed. If the SDK is missing, it looks for MVS-3.0.1_aarch64_20241128.deb under src/EnvironmentFile/. If the package is not found, the installer prints the official download URL and stops.

Runtime Paths

Program installation directory:

/opt/SatService/CameraService

Runtime data directory:

/var/opt/SatService/CameraService/
|-- image/
|   |-- json/
|   |-- task_1/
|   |-- task_2/
|   |-- ...
|-- imagesToInfer/
|-- log/

TTC Command Format

imaging_defines.json defines the uplink camera command format used by the spacecraft TTC service. It maps binary command fields to CameraService task parameters, including command output path, pre-execution command, camera activation mask, timing fields, image quality settings, and per-camera capture parameters.

Camera application developers may update this file when the task format changes. During installation, install.sh deploys it to the TTC configuration directory:

/opt/SatService/ttc/config/imaging_defines.json

Task Generation

src/TestFile/send_json.py provides a quick way to generate a camera task file. Edit the capture parameters in the script, then run:

python3 src/TestFile/send_json.py

By default, task files are written to:

/var/opt/SatService/CameraService/image/json

CameraService monitors this directory. Once a task file is generated, the service reads the task parameters and starts the capture workflow.

Network Camera Configuration

network_cameras.json is stored next to the camera executable and maps network camera IDs to IP addresses. After installation, the file is located at:

/opt/SatService/CameraService/network_cameras.json

Only network cameras required by the deployment need to be listed in this file. USB cameras are not configured here. A deployment may list one, two, four, or more network cameras as required.

Example:

{
  "network_cameras": [
    { "id": 0, "ip": "192.168.106.200" },
    { "id": 3, "ip": "192.168.107.200" },
    { "id": 4, "ip": "192.168.108.200" },
    { "id": 5, "ip": "192.168.109.200" }
  ]
}

Current camera ID convention:

CAMERA0: network camera
CAMERA1: USB camera
CAMERA2: USB camera
CAMERA3: network camera
CAMERA4: network camera
CAMERA5: network camera

Camera Activation Mask

ACTIVE_CAMERA_ID is a bitmask. Camera IDs are mapped from the least significant bit. Read the binary value from right to left: the rightmost bit is bit0, which controls CAMERA0.

binary:  0b  1       1       1       1       1       1
bit:         bit5    bit4    bit3    bit2    bit1    bit0
camera:      CAM5    CAM4    CAM3    CAM2    CAM1    CAM0

For example, 0b111111 enables all six cameras from CAMERA0 to CAMERA5. Its decimal value is 63.

A bit value of 0 means the corresponding camera is not activated for the current capture task:

binary:  0b  0       1       1       1       1       1
bit:         bit5    bit4    bit3    bit2    bit1    bit0
camera:      CAM5    CAM4    CAM3    CAM2    CAM1    CAM0
state:       off     on      on      on      on      on

In this example, 0b011111 enables CAMERA0 to CAMERA4, and does not activate CAMERA5.

send_json.py uses a Python dictionary template so parameter comments can be kept close to the values being edited:

{
    "START_TIME": 20260612091330, # Capture time in UTC, format YYYYMMDDHHMMSS
    "ACTIVE_CAMERA_ID": 0b111111, # Enables CAMERA0-CAMERA5; decimal value is 63
    "FRAME_TIME": 20,             # Video capture duration in seconds
    "FILENAMEPREFIX": "TEST2026", # Output filename prefix / task name
    "JPEG_QUALITY": 90,           # JPEG quality
    "I_FRAME_INTERVAL": 10,       # I-frame interval
    "I_FRAME_QUALITY": 10,        # I-frame QP value
    "P_FRAME_QUALITY": 20,        # P-frame QP value
    "B_FRAME_QUALITY": 30,        # B-frame QP value
    "B_FRAME_COUNT": 0,           # Number of B-frames
    "CAMERA0": {                  # Network camera
        "FRAME_FREQUENCY": 5,
        "FRAME_WIDTH": 4096,
        "FRAME_HEIGHT": 3072,
        "EXPOSURE_TIME": 100000,
        "GAIN": 18,
        "AUTO_GAIN": True,
        "AUTO_EXPOSURE": True
    }
}

Reference Environment

Ubuntu Version: 22.04
JetPack Version: 6.0
GStreamer Version: 1.20.3
v4l2-ctl Version: 1.22.1
MVS Version: MVS 3.0.1 ARM Linux client package, downloaded separately from Hikrobot official website
deepstream-app version: 7.0.0
DeepStreamSDK: 7.0.0
CUDA Version: 12.2.140
CUDA Driver Version: 12.2
CUDA Runtime Version: 12.2
TensorRT Version: 8.6.2.3
cuDNN Version: 8.9.4.25
libNVWarp360 Version: 2.0.1d3
Python Version: 3.10.12
GCC Version: gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0
C Standard: C17

License

This project is licensed under the MIT License. See LICENSE for details.