Protobuf C++/Python SDK使用手册

1. 概述

1.1. 功能

本SDK基于Protobuf传输格式获取手部各关节角度或四元数数据，支持Windows和Linux两种环境。

1.2. SDK下载

语言	OS	OS Version	说明	下载链接	包名格式
CPP	Windows			下载	HandDriver_Win_x64_Cpp_Protobuf_src_yyyymmddmmss
CPP	Ubuntu	22&24, amd		下载	HandDriver_Linux_Cpp_Protobuf_src_yyyymmddmmss
CPP	Ubuntu	22&24, amd	需重新编译后使用	同上	同上
CPP	Ubuntu	20 amd	需重新编译后使用	同上	同上
Python	Windows Ubuntu			下载	HandDriver_Py_Protobuf_src_yyyymmddmmss

1.3. HandDriver端设置

• 打开设置面板，勾选“数据发送”，即打开数据发送开关。

• 选择传输格式Protobuf。

• 选择数据内容，欧拉角或四元数。通常机器人领域选择欧拉角。

• 附加选项：如需传输IMU数据（仅支持带IMU的手套），点选IMU选项，否则不传输IMU数据。

• 此处不适用旧插件。

• 选择发送帧率，支持120Hz、90Hz、60Hz三种帧率，发送帧率默认为120Hz。

• 点击目标地址中的“+”图标，填入接收端的IP地址和端口号，方可进行数据发送（本地发送填写127.0.0.1）。

• 可以设置多个接收目标地址。

• 设置完成后，点击“应用”按钮进行保存。

2. 坐标系及数据定义

2.1. 坐标系和数据说明

HandDriver手部模型关节和数据说明

2.2. Protocol Buffer 定义文件

Protocol Buffer定义文件（Protocol Buffer Definition File）如下：

handdriver_teleop.proto

syntax = "proto3";

package HandDriver;

import "handdriver_algebra.proto";

// Index description for joints array (Angle)
enum JointsIndex_Angle
{
    THUMB_DISTAL_PITCH = 0;         // Thumb Distal Pitch
    THUMB_INTERMEDIATE_PITCH = 1;   // Thumb Intermediate Pitch
    THUMB_PROXIMAL_PITCH = 2;       // Thumb Proximal Pitch
    THUMB_PROXIMAL_YAW = 3;         // Thumb Proximal Yaw
    INDEX_DISTAL_PITCH = 4;         // Index Distal Pitch
    INDEX_INTERMEDIATE_PITCH = 5;   // Index Intermediate Pitch
    INDEX_PROXIMAL_PITCH = 6;       // Index Proximal Pitch
    INDEX_PROXIMAL_YAW = 7;         // Index Proximal Yaw
    MIDDLE_DISTAL_PITCH = 8;        // Middle Distal Pitch
    MIDDLE_INTERMEDIATE_PITCH = 9;  // Middle Intermediate Pitch
    MIDDLE_PROXIMAL_PITCH = 10;     // Middle Proximal Pitch
    MIDDLE_PROXIMAL_YAW = 11;       // Middle Proximal Yaw
    RING_DISTAL_PITCH = 12;         // Ring Distal Pitch
    RING_INTERMEDIATE_PITCH = 13;   // Ring Intermediate Pitch
    RING_PROXIMAL_PITCH = 14;       // Ring Proximal Pitch
    RING_PROXIMAL_YAW = 15;         // Ring Proximal Yaw
    PINKY_DISTAL_PITCH = 16;        // Pinky Distal Pitch
    PINKY_INTERMEDIATE_PITCH = 17;  // Pinky Intermediate Pitch
    PINKY_PROXIMAL_PITCH = 18;      // Pinky Proximal Pitch
    PINKY_PROXIMAL_YAW = 19;        // Pinky Proximal Yaw
    THUMB_PROXIMAL_ROLL = 20;       // Thumb Proximal Roll
    INDEX_PROXIMAL_ROLL = 21;       // Index Proximal Roll
    PINKY_PROXIMAL_ROLL = 22;       // Pinky Proximal Roll
}

// Index description for joints array (Quat)
enum JointsIndex_Quat{
    INDEX_PROXIMAL = 0;       // Index Proximal
    INDEX_INTERMEDIATE = 1;   // Index Intermediate
    INDEX_DISTAL = 2;         // Index Distal
    MIDDLE_PROXIMAL = 3;      // Middle Proximal
    MIDDLE_INTERMEDIATE = 4;  // Middle Intermediate
    MIDDLE_DISTAL = 5;        // Middle Distal
    RING_PROXIMAL = 6;        // Ring Proximal
    RING_INTERMEDIATE = 7;    // Ring Intermediate
    RING_DISTAL = 8;          // Ring Distal
    PINKY_PROXIMAL = 9;       // Pinky Proximal
    PINKY_INTERMEDIATE = 10;  // Pinky Intermediate
    PINKY_DISTAL = 11;        // Pinky Distal
    THUMB_PROXIMAL = 12;      // Thumb Proximal
    THUMB_INTERMEDIATE = 13;  // Thumb Intermediate
    THUMB_DISTAL = 14;        // Thumb Distal
}

message GloveHandDataAngle{
  string serialNumber = 1;      // Device Serial Number
  int32 battery = 2;            // Battery Level
  int32 calibrationState = 3;   // Calibration State
  bool aButton = 4;             // A Button State
  bool bButton = 5;             // B Button State
  bool menuButton = 6;          // Menu Button State
  bool joyButton = 7;           // Joystick Button State
  Vec2 joyPosition = 8;         // Joystick Position
  Quat imu = 9;                 // Hand IMU Orientation
  repeated float joints = 10;   // Joint Angles
  int32 gesture = 11;           // Recognized Gesture Index
}

message GloveHandDataQuat{
  string serialNumber = 1;      // Device Serial Number
  int32 battery = 2;            // Battery Level
  int32 calibrationState = 3;   // Calibration State
  bool aButton = 4;             // A Button State
  bool bButton = 5;             // B Button State
  bool menuButton = 6;          // Menu Button State
  bool joyButton = 7;           // Joystick Button State
  Vec2 joyPosition = 8;         // Joystick Position
  Quat imu = 9;                 // Hand IMU Orientation
  repeated Quat joints = 10;    // Joint API Rotations
  int32 gesture = 11;           // Recognized Gesture Index
}

message TeleopDataAngle
{
  int64 TimeStamp = 1; // Milliseconds
  uint64 FrameIndex = 2; // Frame index at start of transmission
  string RoleName = 3;         // User Role Name
  GloveHandDataAngle LeftHand = 4;  // Left Hand Data
  GloveHandDataAngle RightHand = 5; // Right Hand Data
}

message TeleopDataQuat
{
  int64 TimeStamp = 1; // Milliseconds
  uint64 FrameIndex = 2; // Frame index at start of transmission
  string RoleName = 3;         // User Role Name
  GloveHandDataQuat LeftHand = 4;   // Left Hand Data
  GloveHandDataQuat RightHand = 5;  // Right Hand Data
}

handdriver_teleop.proto

syntax = "proto3";

package HandDriver;

message Vec2 {
  float x = 1;
  float y = 2;
}

message Vec3 {
  float x = 1;
  float y = 2;
  float z = 3;
}

message Quat {
  float x = 1;
  float y = 2;
  float z = 3;
  float w = 4;
}

2.3. 接收的角度说明

关于接收的角度值，可参考HandDriver端数据页，此页数据与SDK接收数据一致：

• 正负一致

• 具体数值在HandDriver中显示时以整数表达

• 详细说明请查看这里：

HandDriver手部模型关节和数据说明

3. C++ SDK - Windows版

本项目是一个C++ 应用程序，专为实时接收和解析手部数据。它利用 Windows Socket (Winsock2) 进行 UDP 通信，并集成 Google Protocol Buffers (Protobuf) 进行序列化数据解析。

3.1. 项目概述

本程序作为一个 UDP 服务器运行，监听特定端口的广播或单播数据包。

核心功能：

• UDP 通信：基于 UDP 协议，确保低延迟数据传输。

• Protobuf 解析：支持解析两种核心数据包：

  • TeleopDataAngle：基于关节角度的数据（适用于机械手控制）。

  • TeleopDataQuat：基于四元数的数据（适用于 3D 渲染/Unity/UE）。

• 跨平台设计：核心逻辑兼容 Linux，网络层针对 Windows 进行了 Winsock2 适配。

3.2. 工程结构

d:/udp_receiver_cpp/
├── CMakeLists.txt              # CMake 构建脚本，管理依赖和编译规则
├── main.cpp                    # 主程序入口，包含 Socket 逻辑和数据打印
├── handdriver_teleop.proto     # 核心数据协议定义（手部数据、遥测包）
├── handdriver_algebra.proto    # 基础数学类型定义（向量、四元数）
├── build/                      # (自动生成) CMake 构建目录
   └── Release/                # 编译生成的 Release 可执行文件输出目录

3.3. 环境搭建与编译

本项目依赖 CMake 进行构建管理，依赖 vcpkg 进行第三方库（Protobuf）管理。

3.3.1. 依赖准备

1. 安装 Visual Studio: 需包含 "使用 C++ 的桌面开发" 工作负载。

2. 安装 CMake: 建议版本 3.10 以上。

3. 安装 vcpkg：

   1. 下载 vcpkg 并运行 bootstrap-vcpkg.bat。

   2. 安装 Protobuf 库： powershell vcpkg install protobuf:x64-windows

3.3.2. 编译步骤

我们提供了两种编译模式：Release (推荐，性能更优) 和 Debug (用于调试)。

第一步：生成工程文件

在项目根目录下，使用 CMake 配置项目。请确保将路径替换为您本地的 vcpkg 路径。

# 将 <path_to_vcpkg> 替换为实际路径，例如 C:/vcpkg
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=<path_to_vcpkg>/scripts/buildsystems/vcpkg.cmake -DCMAKE_BUILD_TYPE=Release

第二步：执行编译

cmake --build build --config Release

编译产物：

编译成功后，可执行文件 udp_receiver.exe 及其所需的 DLL (libprotobuf.dll, abseil_dll.dll) 会自动生成在 build/Release 目录下。

3.4. 运行与参数说明

程序是一个命令行工具，支持通过参数灵活配置。

3.4.1. 启动命令格式

./udp_receiver.exe [--port 端口号] [--type 数据类型]

3.4.2. 参数详解

参数	简写	必填	默认值	数据类型	说明
--port	-p	否	5555	整数	程序监听的本地 UDP 端口。需确保该端口未被防火墙拦截。
--type	-t	否	angle	字符串	这里指定解析协议：angle: 解析关节角度数据quat: 解析关节四元数数据

3.4.3. 运行示例

* 场景 1：默认运行

监听 5555 端口，解析角度数据。

powershell build\Release\udp_receiver.exe

* 场景 2：接收 Unity 客户端数据

假设 Unity 发送的是四元数数据到 6666 端口。

powershell build\Release\udp_receiver.exe -p 6666 -t quat

3.5. 代码逻辑分析

main.cpp 的核心流程如下：

1. 初始化 Winsock: 调用 `WSAStartup` 初始化 Windows 网络库。

2. 参数解析: 解析命令行参数获取端口和类型。

3. 创建 Socket: 建立一个 UDP 套接字 (`SOCK_DGRAM`)。

4. 绑定端口 (Bind): 将 Socket 绑定到 `INADDR_ANY` 和指定端口，允许接收所有网卡的流量。

5. 接收循环 (While Loop):

   1. recvfrom: 阻塞等待，直到收到数据包。

   2. 反序列化: 根据 `--type` 选择 `TeleopDataAngle` 或 `TeleopDataQuat` 对象，调用 `ParseFromString()` 解析二进制数据。

   3. 数据处理: 若解析成功，调用 `print_*_data` 函数打印数据内容的字符串表示 (`DebugString()`)。

6. 资源释放: 关闭 Socket 并清理 Winsock。

3.6. 二次开发指南

如果您需要自己编写代码来读取数据，请参考以下 C++ 示例：

1

引入头文件

#include "handdriver_teleop.pb.h" // 自动生成的头文件

2

解析逻辑

// 假设 buffer 是接收到的 char* 数据，n 是长度
std::string raw_data(buffer, n);
HandDriver::TeleopDataAngle packet;

if (packet.ParseFromString(raw_data)) {
    // 1. 获取时间戳
    long long ts = packet.timestamp();
    
    // 2. 获取左手拇指末端弯曲度
    // 访问路径: TeleopData -> LeftHand -> Joints Array -> Index 0
    float thumb_bend = packet.lefthand().joints(0); 
    
    // 3. 获取手腕姿态
    auto imu = packet.lefthand().imu();
    printf("Wrist Quat: x=%.2f, y=%.2f\n", imu.x(), imu.y());
}

4. C++ SDK - Linux版

4.1. 项目简介

本项目是一个基于 C++ 的 UDP 网络接收程序，专门设计用于接收和解析通过 Google Protocol Buffers (Protobuf) 序列化的手套数据。程序支持两种主要的数据传输模式：角度模式 (Angle) 和 四元数模式 (Quat)。

4.2. 编译与构建

本项目使用 CMake 进行构建管理。

4.2.1. 环境依赖安装

本项目在 Linux (Ubuntu/Debian) 环境下运行。请按照以下步骤安装所需依赖：

1

更新软件源

sudo apt-get update

2

安装基础编译工具

安装 C++ 编译器 (g++) 和 CMake 构建工具：

sudo apt-get install -y build-essential cmake

3

安装 Protocol Buffers

本项目依赖 Google Protocol Buffers 进行数据序列化。需要安装编译器 (protoc) 和 C++ 开发库 (libprotobuf-dev)：

sudo apt-get install -y protobuf-compiler libprotobuf-dev

4.2.2. 编译步骤

请在项目根目录下执行以下命令：

# 1. 生成构建文件
cmake .

# 2. 编译可执行文件
make

编译成功后，将在当前目录下生成可执行文件 udp_receiver。

4.3. 使用说明

程序通过命令行参数进行配置，支持自定义监听端口和数据类型。

4.3.1. 参数说明

参数	简写	是否必选	默认值	说明
--port	-p	否	5555	设置 UDP 监听端口
--type	-t	否	angle	设置数据解析类型，可选值: angle, quat

4.3.2. 运行示例

1. 默认运行 (监听端口 5555，解析 Angle 类型数据)：

./udp_receiver

1. 指定端口和类型 (监听端口 6000，解析 Quat 类型数据):

./udp_receiver --port 6000 --type quat

4.4. 代码逻辑与接口

4.4.1. 主程序流程 (`main.cpp`)

1. 参数解析: 使用 `getopt_long` 解析命令行参数 port 和 type。

2. Socket 初始化: 创建 UDP socket 并绑定到指定端口 (INADDR_ANY)。

3. 循环接收:

• recvfrom 阻塞接收 UDP 数据包。

• 根据 type 选择对应的 Protobuf 消息类型 (TeleopDataAngle 或 TeleopDataQuat) 进行反序列化 (ParseFromString)。

• 解析成功调用对应的打印函数。

• 解析失败输出错误信息并继续下一轮循环。

4.4.2. 关键函数

- **`void print_angle_data(const HandDriver::TeleopDataAngle& data)`**

• 功能：打印 Angle 类型的遥测数据详情。

• 实现：调用 Protobuf 自动生成的 DebugString() 方法输出格式化文本。

- **`void print_quat_data(const HandDriver::TeleopDataQuat& data)`**

• 功能：打印 Quaternion 类型的遥测数据详情。

• 实现：同上，调用 DebugString()。

5. Python SDK - Linux/Win版

该SDK同时支持windows和Linux。该工具通过 UDP 协议监听指定端口，接收二进制数据包，并根据指定的数据类型（angle 或 quat）使用 Google Protocol Buffers (Protobuf) 进行反序列化，最终将解析后的数据打印到控制台。

5.1. 环境依赖

• Python 3.x

• Protobuf 库

安装依赖：

pip install protobuf==3.20.3

5.2. 接口说明与数据调用

5.2.1. 通信协议

* 协议: UDP* 默认端口: 5555* 数据格式: Protobuf 序列化二进制流

5.2.2. 接收流程 (Python)

1. 创建 Socket: 建立 UDP socket。

2. 绑定端口: 绑定到指定 IP (`0.0.0.0`) 和端口。

3. 循环接收: 使用 `recvfrom` 接收数据包。

4. 反序列化:

   1. 如果数据类型为 angle，使用 TeleopDataAngle.ParseFromString(data)。

   2. 如果数据类型为 quat，使用 TeleopDataQuat.ParseFromString(data)。

5. 数据使用: 访问解析后的对象字段（如 `msg.LeftHand.joints[0]`）。

5.3. 使用 Demo

脚本 udp_receiver.py 提供了简单的命令行接口。

5.3.1. 参数说明

• --port: 指定监听端口 (默认: 5555)

• --type: 指定预期的数据类型 (angle 或 quat，默认: angle)

5.3.2. 示例 1: 接收角度数据 (默认)

python udp_receiver.py

或显式指定：

python udp_receiver.py --port 5555 --type angle

5.3.3. 示例 2: 接收四元数数据

如果发送端发送的是四元数格式的数据：

python udp_receiver.py --port 5555 --type quat

5.3.4. 示例 3: 更改监听端口

监听 6000 端口：

python udp_receiver.py --port 6000