Quick Start

This guide goes with the Hybrid Vision Toolkit — after reading the introduction, the commands below get minimal capture running in 5 minutes.

Clone the SDK repository

All commands below run from the repository root. If you haven't cloned it yet:

git clone https://gitee.com/ShiMetaPi_0/shimetapi_hybrid_vision_toolkit.git   # recommended for mainland China
# or (overseas) git clone https://github.com/ShiMetaPi/shimetapi_hybrid_vision_toolkit.git
cd shimetapi_hybrid_vision_toolkit

The repository is distributed as prebuilt .so libraries; run.sh is the build entry point.

System requirements

  • C++ standard: C++17 or later
  • CMake: 3.16+
  • OS: Linux (x86_64 host + ARM64 boards)
  • Dependencies: libusb-1.0 (USB), aarch64 toolchain (S100/X5 cross-compiling), OpenCV (optional)

Build

run.sh wraps cmake configuration + compilation and handles toolchain / sysroot / platform options automatically (you can also run cmake -B out/<arch>/build -S . directly).

x86_64 (USB)

sudo apt-get install build-essential cmake libusb-1.0-0 libopencv-dev
./run.sh build        # on an x86_64 host the default target is x86_64

Verify the artifacts:

ls out/x86_64/build/libshimetapi_*.so                              # the 4 auto-bundled libraries
ls out/x86_64/build/samples/cpp/get_started/hv_sample_get_started  # sample executable

S100 (MIPI / cross-compile)

# Prerequisites: aarch64 toolchain + S100 sysroot
sudo apt-get install g++-aarch64-linux-gnu
git clone -b s100_v4.0.5 --single-branch https://gitee.com/ShiMetaPi_0/evs_device_vendor_sdk.git
# or (overseas) git clone -b s100_v4.0.5 --single-branch https://github.com/ShiMetaPi/evs_device_vendor_sdk.git
export S100_SYSROOT=$PWD/evs_device_vendor_sdk/source/hobot-multimedia/debian/usr

./run.sh build s100   # toolchain file injected automatically
file out/s100/build/samples/cpp/get_started/hv_sample_get_started  # should be ELF aarch64

X5 (MIPI / cross-compile)

# Prerequisites: aarch64 toolchain (same as S100) + X5 SDK source tree
# Shares the same evs_device_vendor_sdk repository as S100, but on the x5_v3.4.1 branch
sudo apt-get install g++-aarch64-linux-gnu
git clone -b x5_v3.4.1 --single-branch https://gitee.com/ShiMetaPi_0/evs_device_vendor_sdk.git
# or (overseas) git clone -b x5_v3.4.1 --single-branch https://github.com/ShiMetaPi/evs_device_vendor_sdk.git

./run.sh build x5
file out/x5/build/samples/cpp/get_started/hv_sample_get_started    # should be ELF aarch64

OpenCV-dependent samples when cross-compiling

When cross-compiling for S100 / X5, player / live_record_display use the repository-bundled third_party/aarch64_opencv, so all 7 samples build.

List supported platforms

./run.sh --list
# ARCH    STATUS        PREBUILT LIBS
# x86_64  ready         .../lib/x86_64
# s100    ready         .../lib/s100
# x5      ready         .../lib/x5

Run the sample programs

This section uses the minimal get_started sample to demonstrate running on the three platforms. For the purpose, build path, and dependencies of all 7 samples (callback / record / viewer / bench_hw / live_record_display / player), see Samples Overview → C++ samples.

Artifacts land in out/<arch>/build/samples/cpp/<name>/hv_sample_<name>; capture samples default to the USB backend, --mipi switches to EVS-only and --mipi-hvs to dual VC; in USB mode the first two positional arguments set VID/PID (default 0x1d6b 0x0105).

x86_64 (USB)

cd out/x86_64/build/samples/cpp
./get_started/hv_sample_get_started    # minimal capture: Init → StartStream → GetFrame → StopStream

get_started running on x86_64 (USB backend)

S100 (MIPI / cross-compile)

out/s100/build is a self-contained directory — the prebuilt libraries are bundled in at build time and the samples' rpath resolves via $ORIGIN, so you can copy the whole directory onto the board:

# On the host: deploy to the board
scp -r out/s100/build root@<board-IP>:/app/
export LD_LIBRARY_PATH=/app/build:$LD_LIBRARY_PATH
# Run directly on the board (no LD_LIBRARY_PATH needed)
cd /app/build/samples/cpp
./get_started/hv_sample_get_started --mipi

get_started running on S100 (--mipi)

X5 (MIPI / cross-compile)

out/x5/build is self-contained; deployment and running are the same as S100, just swap out/s100/build → out/x5/build.

scp -r out/x5/build root@<board-IP>:/app/
export LD_LIBRARY_PATH=/app/build:$LD_LIBRARY_PATH
cd /app/build/samples/cpp
./get_started/hv_sample_get_started --mipi

get_started running on X5 (--mipi)

Python samples

The Python binding (a single hv_toolkit module, x86_64 prebuilt, Python 3.10) ships with lib/x86_64/python/:

# Simplest path: install the libraries into the system path, then import directly
sudo ./run.sh install x86_64
python3 samples/python/get_started.py

Minimal capture sample (USB) — frame.evs is raw event bytes, decoded with Evt2Decoder:

import hv_toolkit as hv

cfg = hv.DeviceConfig()
cfg.backend    = hv.Backend.Usb
cfg.vendor_id  = 0x1d6b
cfg.product_id = 0x0105

cam = hv.Camera(); cam.init(cfg); cam.start_stream()
dec = hv.Evt2Decoder()
f = hv.Frame()
for _ in range(10):
    if cam.get_frame(f, 1000):
        events = dec.decode(bytes(f.evs))   # → numpy structured array (x, y, t, polarity)
        print(f"frame {f.frame_id} {f.width}x{f.height}: {len(events)} events, aps={f.aps.nbytes} bytes")
cam.stop_stream(); cam.destroy()

MIPI HVS only changes the backend and decoder (Frame.evs is a RAW8 subframe stream, which must use MipiRaw8Decoder):

cfg = hv.DeviceConfig()
cfg.backend      = hv.Backend.MipiHvs
cfg.sensor_index = 9       # current S100 configuration; X5 uses the index configured by its SDK (49 in the current sample)
cfg.evs_fps      = 500     # frame-rate tier (0 = default 240), applied at Init
dec = hv.MipiRaw8Decoder()

Frame-rate tiers

cfg.evs_fps (0 = default 240). Tiers map to the number of subframes per full package:

Tier (fps)1202403005007501000
Subframes per pkg16324064100128

MipiRaw8Decoder.decode adapts by data length automatically when subframe_count is omitted. The tier is selected at Init; switching tiers while MIPI is running requires rebuilding the pipeline (SetFrameRate not supported).

The prebuilt Python module is x86_64-only

The Python .so shipped in the release repository is prebuilt for x86_64 only and cannot be copied directly onto S100/X5; for on-board Python, cross-compile the binding from source for the target architecture. Until a board Python artifact exists, use C++. For the full interface see the Python API.

USB device permissions

If the first run fails with LIBUSB_ERROR_ACCESS, configure a udev rule (sudo-free) :

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="1d6b", ATTR{idProduct}=="0105", MODE="0666"' \
  | sudo tee /etc/udev/rules.d/99-hv-camera.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

🚨 Troubleshooting

No USB device found

no match devices found means the device did not connect — check the USB connection and whether vendor_id / product_id are correct:

Alternative text

Alternative text

LIBUSB_ERROR_ACCESS

The device is connected and VID/PID are correct, but you get Cannot open device: LIBUSB_ERROR_ACCESS — insufficient permissions:

# Quick fix: open up USB bus permissions
sudo chmod -R 777 /dev/bus/usb/
# Recommended: configure a udev rule (see above — sudo-free and persistent)

Cross-compiling reports file in wrong format

./run.sh build s100 (or x5) fails early with install guidance when the aarch64 toolchain is missing. If you invoke cmake yourself without passing a toolchain, the host compiler reports libshimetapi_hv.so: file in wrong format at link time — fix: after apt install g++-aarch64-linux-gnu, build with ./run.sh build <arch>, or pass -DCMAKE_TOOLCHAIN_FILE explicitly.