安装与环境要求 | Qnbot Docs Center

QnBot C++ SDK 用于连接 QnBot 设备、管理手套、读取手套姿态与 retargeting 输出，以及控制手套指尖震动。核心接口面向 C++17；需要 coroutine 时，可以单独启用 C++20 支持。

本文档适用于 qnbot-sdk-glove 1.3.0 对应的 QnBot C++ SDK/Glove 交付包。你只需选择与当前平台匹配的完整交付包，不需要单独选择兼容依赖的版本。

环境要求

macOS 14+ ARM64：支持 C++17 的编译器，CMake 3.16 或更高版本
x86_64 glibc Linux：支持 C++17 的编译器，CMake 3.16 或更高版本
aarch64 glibc Linux：支持 C++17 的编译器，CMake 3.16 或更高版本
Windows x86_64：Visual Studio 2022 (MSVC)，CMake 3.21 或更高版本
与当前平台匹配的 QnBot C++ SDK 交付 ZIP
QnBot VetraSense Glove 或 VetraGlove Nano
使用 C++20 coroutine 支持时，需要支持 coroutine 和 std::stop_token 的编译器

1.3.0 当前提供 macOS 14+ ARM64、glibc 2.34+ Linux x86_64、glibc 2.34+ Linux ARM64 和 Windows 10 x64 四种平台安装包。

SDK 核心 target 保持 C++17，适合需要稳定 C++17 基线的机器人应用。C++20 只由 coroutine target 传递给选择使用它的 target。

需要更改 SDK 的应用数据目录，或让 CLI 与 SDK 共用同一目录时，见应用数据目录。

安装

请从 docs.qnbot.com 下载与操作系统和 CPU 架构匹配的 Core 与 Glove 1.3.0 交付包。两个组件必须使用同一版本，交付目录中的头文件、库、CMake package 和运行时资源应保持在一起，不能跨平台或跨版本混用。

macOS

macOS ARM64 使用 qnbot-cpp-sdk-1.3.0-mac-arm.zip：

unzip qnbot-cpp-sdk-1.3.0-mac-arm.zip -d qnbot-cpp-sdk

Linux

x86_64 glibc Linux 使用 qnbot-cpp-sdk-1.3.0-linux-x64.zip：

unzip qnbot-cpp-sdk-1.3.0-linux-x64.zip -d qnbot-cpp-sdk

aarch64 glibc Linux 使用 qnbot-cpp-sdk-1.3.0-linux-arm64.zip：

unzip qnbot-cpp-sdk-1.3.0-linux-arm64.zip -d qnbot-cpp-sdk

Windows

Windows x86_64 使用 PowerShell：

Expand-Archive `
  -Path .\qnbot-cpp-sdk-1.3.0-windows-x64.zip `
  -DestinationPath .\qnbot-cpp-sdk

配置 CMake 项目

应用的 CMakeLists.txt 通过交付目录中的公开 CMake package 引入 SDK：

cmake_minimum_required(VERSION 3.16)
project(my_qnbot_app LANGUAGES CXX)

find_package(qnbot_glove CONFIG REQUIRED)

add_executable(my_qnbot_app main.cpp)
target_link_libraries(my_qnbot_app PRIVATE qnbot::glove)

qnbot::glove 提供 C++17 Glove 接口并传递所需依赖。只有使用 coroutine 的 target 才额外链接 qnbot::core_coro：

target_link_libraries(my_qnbot_coro_app PRIVATE
  qnbot::glove qnbot::core_coro)

应用不需要手动添加 include 目录或 library 目录。

配置项目时，将解压后的安装前缀传给 CMAKE_PREFIX_PATH。macOS 和 Linux：

cmake -S . -B build -DCMAKE_PREFIX_PATH=/absolute/path/to/qnbot-cpp-sdk
cmake --build build --config Release

Windows PowerShell：

cmake -S . -B build `
  -DCMAKE_PREFIX_PATH=C:\absolute\path\to\qnbot-cpp-sdk
cmake --build build --config Release

验证安装

下面的检查只验证 CMake package、头文件、编译、链接和程序启动，不连接手套，也不需要 retargeting 算法包。将 CMakeLists.txt 中的可执行文件改为：

find_package(qnbot_glove CONFIG REQUIRED)

add_executable(qnbot_sdk_check verify_install.cpp)
target_link_libraries(qnbot_sdk_check PRIVATE qnbot::glove)

创建 verify_install.cpp：

#include <qnbot/glove.hpp>

#include <iostream>

int main() {
    qnbot::GloveConfig glove_config;
    const qnbot::DeviceConfig device_config = glove_config;
    (void)device_config;
    std::cout << "QnBot C++ SDK ready\n";
}

macOS 和 Linux 运行：

cmake -S . -B build/app \
  -DCMAKE_PREFIX_PATH=/absolute/path/to/qnbot-cpp-sdk \
  -DCMAKE_BUILD_TYPE=Release
cmake --build build/app --config Release
./build/app/qnbot_sdk_check

Windows PowerShell 运行：

cmake -S . -B build\app `
  -G "Visual Studio 17 2022" -A x64 `
  -DCMAKE_PREFIX_PATH=C:\absolute\path\to\qnbot-cpp-sdk
cmake --build build\app --config Release
build\app\Release\qnbot_sdk_check.exe

预期输出：

QnBot C++ SDK ready