Touch Glove SDK

Touch Glove 数据采集与实时推理 SDK。本项目包含由 Rust 实现的高性能底层驱动库，对外提供 Python 绑定（touchglove）与标准 C API 接口。

SDK 的核心功能包括：

• 高吞吐数据传输：支持 5 个通道（手套传感器）实时 192x192 灰度图像流的高频采集。
• PTP / RTC 硬件时间同步：支持手套硬件 RTC 与主机系统时间同步及精准时间戳查询。
• 设备 SN 读写工具：提供读写和校验手套硬件 SN 的命令行工具 write_sn.py。
• 实时物理推理：集成 ONNX Runtime / OpenVINO 推理引擎，支持直接推理 3D 位移场与 3D 力场，并提供去皮基线校准。
• H.265 视频录制：支持高效率 H.265 (HEVC) MP4 视频录制，并生成多通道精准逐帧微秒级时间戳 JSON。
• ROS 2 实时发布：支持将原始图像、位移场和力场实时广播至 ROS 2 话题。

1. 项目源码结构

.
├── example.py                     # Python 综合示例（支持 stream, gui, ros2, inference, record 五大模式）
├── write_sn.py                    # 硬件 SN 序列号写入与校验工具
├── pyproject.toml                 # Maturin Python SDK 构建配置
├── TacSP_上行协议规范.md           # TacSP 串口通信协议设计规范
├── README.md                      # 本说明文档
├── LICENSE                        # 项目开源许可证
├── include/
│   └── touch_glove_api.h          # C/C++ 接口头文件
├── api/                           # Rust/C 底层驱动与推理引擎源码项目
│   ├── Cargo.toml                 # Cargo 项目配置
│   ├── build.rs                   # Rust build 脚本
│   ├── touch_glove_api.c          # C API 实现源码
│   ├── touch_glove_api.h          # C API 头文件
│   └── src/
│       ├── lib.rs                 # Rust 库入口
│       ├── serial_io.rs           # 串口通信与 PTP 时钟同步
│       ├── protocol.rs            # TacSP 协议解析器
│       ├── parser.rs              # 图像帧解码
│       ├── context.rs             # SDK 句柄上下文与状态流
│       ├── encoder.rs             # H.265 视频录制与多通道时间戳导出
│       ├── inference.rs           # ONNX / OpenVINO 多引擎推理
│       └── python/                # PyO3 Python 扩展绑定
└── scripts/                       # SDK 依赖获取与打包辅助脚本
    ├── fetch_onnxruntime.py
    └── package_sdk.py

2. 编译与构建

2.1 构建 Python SDK 包 (touchglove)

推荐使用 maturin 编译 Rust 底层库并安装为 Python 包：

# 1. 安装 maturin
pip3 install maturin

# 2. 编译并以 release 模式安装到当前 Python 环境
maturin develop --release --features python

2.2 编译 C/C++ 原生动态库 (libtouch_glove.so)

如果需要在 C/C++ 项目中使用 SDK，进入 api/ 目录进行构建：

cd api
cargo build --release

编译生成的共享库文件位于 api/target/release/libtouch_glove.so。

3. 示例程序使用说明

3.1 Python 综合示例 example.py

example.py 是 SDK 的核心功能演示程序，支持 5 种运行模式：

# 模式 1: Simple Stream (基础控制台终端实时数据流输出)
python3 example.py /dev/ttyACM0 --mode stream

# 模式 2: GUI Display (OpenCV 网格图形界面展示 5 通道实时图像)
python3 example.py /dev/ttyACM0 --mode gui

# 模式 3: ROS 2 Publishing (作为 ROS 2 Publisher 实时发布 /touch_glove/ch{0..4} 图像话题)
python3 example.py /dev/ttyACM0 --mode ros2

# 模式 4: Inference (实时 ONNX 物理推理，计算 3D 位移场与 3D 力场，支持按 'b' 键实时基线去皮标定)
python3 example.py /dev/ttyACM0 --mode inference --model /path/to/dense_3ch.onnx --device cuda

# 模式 5: Record (录制 5 通道 H.265 MP4 视频，并导出微秒级多通道时间戳 JSON)
python3 example.py /dev/ttyACM0 --mode record --record-path output.mp4 --duration 10.0

参数说明：

• port：串口路径（如未指定，程序会自动扫描并弹出可交互列表供选择）。
• --mode：选择运行模式（stream | gui | ros2 | inference | record）。
• --model：指定 ONNX 推理模型路径（inference 模式下必需）。
• --device：指定推理硬件（cuda / gpu 或 cpu）。
• --record-path：录制模式输出 MP4 视频路径。
• --duration：录制时长（秒）。

3.2 硬件 SN 写入与校验工具 write_sn.py

write_sn.py 用于读写和校验手套硬件内部存储的序列号（SN）：

# 交互式运行（自动检测串口并提示输入 SN）
python3 write_sn.py

# 指定 SN 自动写入（自动匹配串口）
python3 write_sn.py 30L260803001P

# 指定 SN 与串口写入
python3 write_sn.py 30L260803001P /dev/ttyACM0

4. Python SDK API 极简示例

在您自己的 Python 代码中，可以直接导入 touchglove：

from touchglove import TouchGlove, list_ports

# 1. 查询可用串口
ports = list_ports()
print("可用串口:", ports)

# 2. 打开设备并开启数据流
with TouchGlove(port=ports[0]) as glove:
    # 2.1 获取设备 SN 与 同步系统时间至硬件 RTC
    sn = glove.get_sn()
    print("设备 SN:", sn)
    glove.sync_rtc()
    
    # 2.2 启动数据流
    glove.start()
    
    # 2.3 轮询拉取数据帧
    while True:
        frames = glove.poll()
        for frame in frames:
            print(f"通道 {frame.channel} | 帧号: {frame.seq_id} | 时间戳 (PTP): {frame.timestamp_us} us | 图像形状: {frame.image.shape}")

5. C API 文档说明

底层 Rust 驱动库导出标准 C 接口（定义见 include/touch_glove_api.h）。

5.1 核心数据类型

typedef struct ts_frame_t {
    uint8_t addr;                  // 设备地址
    uint8_t type;                  // 帧类型
    uint8_t cmd;                   // 命令 / 通道号 (0x11-0x15 对应 Ch 0-4)
    uint16_t param_len;            // 参数长度 (图像为 36864 字节)
    uint32_t seq_id;               // 序列号 (丢包检测)
    uint64_t timestamp_us;         // 硬件接收 PTP 时间戳 (微秒)
    uint8_t sensor_id[8];          // 通道传感器 UID
    uint8_t param[36864];          // 192x192 灰度图像原始字节
} ts_frame_t;

5.2 核心 C 函数

• touch_glove_handle_t touch_glove_create(void)：创建 SDK 句柄实例。
• void touch_glove_destroy(touch_glove_handle_t h)：断开连接并销毁实例。
• int touch_glove_open(touch_glove_handle_t h, const char* port_name)：打开串口设备。
• void touch_glove_close(touch_glove_handle_t h)：关闭串口。
• int touch_glove_send_start(touch_glove_handle_t h)：启动硬件数据流。
• int touch_glove_send_stop(touch_glove_handle_t h)：停止硬件数据流。
• void touch_glove_poll_read(touch_glove_handle_t h)：非阻塞轮询读取并解析串口缓冲区。
• int touch_glove_init_model(touch_glove_handle_t h, const char* model_path)：初始化 ONNX 推理引擎。
• int touch_glove_calibrate(touch_glove_handle_t h)：执行零点基线去皮标定。
• int touch_glove_infer(touch_glove_handle_t h, const uint8_t* last_images, float* out_disp, float* out_force)：传入 5 通道图像数据，推理输出 3D 位移场与 3D 力场。

6. 通信协议规范

关于手套串口通信协议格式、寄存器指令集、硬件 RTC 时间戳同步规范及 SN 数据帧格式的完整说明，请参阅：

• TacSP_上行协议规范.md