02 快速上手

本文配套 Hybrid Vision Toolkit 使用——读完介绍后，按本页命令即可在 5 分钟内跑通最小采集。

克隆 SDK 仓库

下面所有命令都在仓库根目录下执行。如果还没拉取：

git clone https://gitee.com/ShiMetaPi_0/shimetapi_hybrid_vision_toolkit.git   # 国内推荐
# 或（海外）git clone https://github.com/ShiMetaPi/shimetapi_hybrid_vision_toolkit.git
cd shimetapi_hybrid_vision_toolkit

仓库以预编译 .so 形式分发；run.sh 是构建入口。

系统要求

  • C++ 标准：C++17 或更高
  • CMake：3.16+
  • 操作系统：Linux（x86_64 主机 + ARM64 板卡）
  • 依赖：libusb-1.0（USB）、aarch64 工具链（S100/X5 交叉）、OpenCV（可选）

构建

run.sh 封装 cmake 配置 + 编译，自动处理工具链 / sysroot / 平台选项（也可直接 cmake -B out/<arch>/build -S .）。

x86_64（USB）

sudo apt-get install build-essential cmake libusb-1.0-0 libopencv-dev
./run.sh build        # x86_64 主机上默认即 x86_64

验证产物：

ls out/x86_64/build/libshimetapi_*.so                              # 自动捆绑的 4 个库
ls out/x86_64/build/samples/cpp/get_started/hv_sample_get_started  # 示例可执行文件

S100（MIPI / 交叉编译）

# 前置：aarch64 工具链 + 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
# 或（海外）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   # 工具链文件自动注入
file out/s100/build/samples/cpp/get_started/hv_sample_get_started  # 应为 ELF aarch64

X5（MIPI / 交叉编译）

# 前置：aarch64 工具链（同 S100）+ X5 SDK 源码树
# 与 S100 共用同一仓库 evs_device_vendor_sdk，但走 x5_v3.4.1 分支
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
# 或（海外）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    # 应为 ELF aarch64

交叉编时 OpenCV 类样例

S100 / X5 交叉编时，player / live_record_display 用仓库自带 third_party/aarch64_opencv，7 个样例全编。

查看支持的平台

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

运行示例程序

本节用最小样例 get_started 演示三个平台的运行效果。完整 7 个样例（callback / record / viewer / bench_hw / live_record_display / player）的用途、构建路径与依赖见 示例程序总览 → C++ 样例。

产物在 out/<arch>/build/samples/cpp/<name>/hv_sample_<name>；采集类样例默认 USB 后端，--mipi 切 EVS-only、--mipi-hvs 切双 VC；USB 模式可用前两个位置参数指定 VID/PID（默认 0x1d6b 0x0105）。

x86_64（USB）

cd out/x86_64/build/samples/cpp
./get_started/hv_sample_get_started    # 最小采集：Init → StartStream → GetFrame → StopStream

get_started 在 x86_64 上运行（USB 后端）

S100（MIPI / 交叉编译）

out/s100/build 是自包含目录——构建时已把预编译库捆绑进去，样例 rpath 用 $ORIGIN 相对寻址，整个目录拷上板即可：

# 宿主机：部署到板卡
scp -r out/s100/build root@<板卡IP>:/app/
export LD_LIBRARY_PATH=/app/build:$LD_LIBRARY_PATH
# 板卡上直接跑（无需 LD_LIBRARY_PATH）
cd /app/build/samples/cpp
./get_started/hv_sample_get_started --mipi

get_started 在 S100 上运行（--mipi）

X5（MIPI / 交叉编译）

out/x5/build 是自包含目录；部署与运行同 S100，只换 out/s100/build → out/x5/build。

scp -r out/x5/build root@<板卡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 在 X5 上运行（--mipi）

Python 示例

Python 绑定（单一 hv_toolkit 模块，x86_64 预编译，Python 3.10）随 lib/x86_64/python/ 分发：

# 最省事：先装库进系统路径，模块直接 import
sudo ./run.sh install x86_64
python3 samples/python/get_started.py

最小采集示例（USB）—— frame.evs 是原始事件字节，用 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 结构数组 (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 只换 backend 与解码器（Frame.evs 是 RAW8 子帧流，必须用 MipiRaw8Decoder）：

cfg = hv.DeviceConfig()
cfg.backend      = hv.Backend.MipiHvs
cfg.sensor_index = 9       # S100 当前配置；X5 使用其 SDK 配置的索引（当前样例为 49）
cfg.evs_fps      = 500     # 帧率档（0=默认 240），Init 时生效
dec = hv.MipiRaw8Decoder()

帧率档

cfg.evs_fps（0=默认 240）。档位与 EVS 整包子帧数对应：

档位 (fps)1202403005007501000
整包子帧数16324064100128

MipiRaw8Decoder.decode 不传 subframe_count 时自动按数据长度适配。档位在 Init 时选定，MIPI 运行中切档需重建管线（不支持 SetFrameRate）。

预编译 Python 模块是 x86_64 专属

发布仓随附的 Python .so 仅有 x86_64 预编译版本，不能直接复制到 S100/X5；如需板卡 Python，需按对应架构从源码交叉编译绑定。没有板卡 Python 产物时请使用 C++。完整接口见 Python API。

USB 设备权限

首次运行若报 LIBUSB_ERROR_ACCESS，推荐配置 udev 规则（免 sudo）：

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

🚨 故障排除

无法找到 USB 设备

出现 no match devices found，说明设备未成功连接——检查 USB 连接与 vendor_id / product_id 是否正确：

替代文本

替代文本

LIBUSB_ERROR_ACCESS

设备已连接且 VID/PID 正确，但报 Cannot open device: LIBUSB_ERROR_ACCESS —— 权限不足：

# 临时：放开 USB 总线权限
sudo chmod -R 777 /dev/bus/usb/
# 推荐：配置 udev 规则（见上文，免 sudo、持久）

交叉编译报 file in wrong format

./run.sh build s100（或 x5）在未装 aarch64 工具链时会提前报错并给出安装指引。若自行用 cmake 且未传工具链，host 编译器会在链接期报 libshimetapi_hv.so: file in wrong format —— 解决：apt install g++-aarch64-linux-gnu 后用 ./run.sh build <arch>，或显式传 -DCMAKE_TOOLCHAIN_FILE。