zwu528303-wq/uhand-haptic-teleoperation

# uHand Haptic Teleoperation [](https://github.com/zwu528303-wq/uhand-haptic-teleoperation/actions/workflows/validate.yml)   ## 项目概述 本项目研究低成本机械手遥操作中的接触感知问题，围绕 uHand2.0 与配套体感 手套的单食指通道，完成了系统架构建模、厂商固件数据链路追踪、通信帧解析、 可执行协议参考、实验方法设计和端到端延迟分析工具。 仓库中的核心成果是一条可以审查的工程证据链：从原始文件完整性记录，到 具体源码行号、信号变换、串口封包，再到带自动测试的数据分析程序。 ## 核心成果 | 成果 | 内容 | | --- | --- | | 系统建模 | 区分原装单向动作链路与双向触觉架构中的信号边界 | | 固件溯源 | 为 10 个厂商源文件保存 SHA-256 完整性记录 | | 数据流追踪 | 定位五路 ADC、平滑、启动校准、位置映射与舵机输出 | | 协议解析 | 从源码还原多舵机二进制命令，并实现可执行的编码与解码工具 | | 测量方法 | 定义高帧率视频下的可见运动起始帧测量方法 | | 分析工具 | 自动计算均值、样本标准差、范围与帧级时间分辨率 | | 工程验证 | 16 个单元测试，覆盖协议、计算、命令输出与关键异常输入 | | 持续集成 | GitHub Actions 在 Python 3.10 与 3.12 上自动验证 | ## 一分钟复现 项目运行时只使用 Python 标准库： git clone https://github.com/zwu528303-wq/uhand-haptic-teleoperation.git cd uhand-haptic-teleoperation make verify `make verify` 会运行全部测试、重新生成演示分析结果，并编译检查 Python 源码。 ## 固件数据链路 flowchart LR P["五路手指电位器"] --> ADC["A0 / A1 / A2 / A3 / A6"] ADC --> LPF["二点递归平均"] LPF --> CAL["启动端点校准"] CAL --> MAP1["映射并限幅到 500..2500"] MAP1 --> MAP2["映射到 1100..1950"] MAP2 --> PKT["五舵机二进制命令"] PKT --> BT["SoftwareSerial 9600 baud"] BT --> U["uHand2.0 控制器"] ## 源码分析结论 对厂商手套程序 `lehand.ino` 及其串口控制库的静态分析确认： - 五路手指输入使用 `A0`、`A1`、`A2`、`A3` 和 `A6`。 - 每路输入采用“上一次状态与本次 ADC 读数取平均”的一阶平滑。 - 开机状态机采集五路校准端点，并将信号映射、限幅到 `500..2500`。 - 手掌控制模式将数据进一步映射到舵机位置范围 `1100..1950`。 - 蓝牙链路使用 Arduino `SoftwareSerial`，引脚为 11/12，波特率为 9600。 - 多舵机命令以 `0x55 0x55` 开始，包含长度、命令、舵机数、执行时间、 舵机 ID 与位置。 - USB 调试串口初始化为 115200；原程序默认不执行传感器打印函数。 完整的文件、行号、推导过程和证据边界见 [`docs/code_walkthrough.md`](docs/code_walkthrough.md)。 ## 硬件平台 项目硬件覆盖机器人执行、动作采集、接触检测和触觉反馈四个部分： - **机器人执行：** uHand2.0、STM32 控制板、五个 LFD-01 手指舵机和 LD-1501MG 底座舵机。 - **动作采集：** 幻尔体感手套、五路手指电位器、MPU6050 和蓝牙模块。 - **接触检测：** FSR402 类薄膜压力传感器与独立 ESP32 采集控制器。 - **触觉反馈：** MG90S、单指拉索／齿条机构、快速释放绑带和独立 5 V / 2 A 舵机电源。 - **实验搭建：** 第二块 ESP32、10 kΩ 电位器、电阻、面包板、杜邦线、 USB 数据线、断电装置和高帧率摄像设备。 完整数量与用途见 [`docs/hardware_inventory.md`](docs/hardware_inventory.md)。 ## 双向触觉架构 flowchart LR H["Human finger"] --> G["Glove sensing"] G --> M["Motion mapping"] M --> R["uHand index channel"] R --> C["Fingertip contact signal"] C --> S["Bounded safety logic"] S --> F["Haptic rendering"] F --> H 该架构把动作输入、机器人目标、接触信号和触觉命令分成独立信号，避免把 舵机防堵转行为误写成可读取的指尖力反馈。架构说明见 [`docs/system_architecture.md`](docs/system_architecture.md)。 ## 可执行协议参考 根据厂商 `LobotServoController` 源码还原的多舵机命令已经实现为独立、 零依赖的编码与解码模块： python3 tools/servo_packet.py --time 30 1:1500 2:1700 输出： 55 55 0b 03 02 1e 00 01 dc 05 02 a4 06 该结果对应两个舵机、30 ms 执行时间，并包含帧头、长度、命令、舵机数和 小端序位置字段。实现见 [`tools/servo_packet.py`](tools/servo_packet.py)，协议测试见 [`tests/test_servo_packet.py`](tests/test_servo_packet.py)。 ## 可复现延迟分析 输入 CSV 使用以下字段： trial,human_start_frame,robot_start_frame,fps,notes 运行： python3 tools/analyze_latency.py measurements.csv --output-dir results 输出： results/latency_summary.md results/latency_distribution.svg 运行自动测试： python3 -m unittest discover -s tests -v 该方法测量的是人手与机械手“可见运动开始帧”之间的近似端到端延迟，结果 包含传感、滤波、调度、蓝牙、控制器、舵机机械响应、视频量化和人工选帧误差。 下面的图由仓库脚本从明确标注为 synthetic demo 的示例 CSV 自动生成，不作为 硬件实验结果：  完整复现入口见 [`examples/README.md`](examples/README.md)。 ## 仓库导航 - [`docs/project_overview.md`](docs/project_overview.md)：研究问题、系统边界与评价指标 - [`docs/system_architecture.md`](docs/system_architecture.md)：原装链路与双向触觉架构 - [`docs/code_walkthrough.md`](docs/code_walkthrough.md)：厂商固件静态分析报告 - [`docs/hardware_inventory.md`](docs/hardware_inventory.md)：硬件与资料依据 - [`docs/development_log.md`](docs/development_log.md)：工程工作记录 - [`experiments/latency_analysis.md`](experiments/latency_analysis.md)：延迟测量方法 - [`examples/README.md`](examples/README.md)：可复现的演示数据与生成结果 - [`tools/analyze_latency.py`](tools/analyze_latency.py)：统计与 SVG 图表生成工具 - [`tools/servo_packet.py`](tools/servo_packet.py)：uHand 多舵机协议参考实现 - [`tests/`](tests/)：延迟分析与协议模块自动测试 ## 安全与证据边界 - 阻挡机械手的实验物只能使用海绵等软物体，不能使用人体。 - 舵机防堵转不等于可读取的力反馈。 - FSR 只适合作为相对接触信号，不能在未标定时写成精确牛顿值。 - 主动阻力反馈必须具有限幅、超时释放和独立断电能力。 - 静态源码分析能够证明发送端的数据处理与封包逻辑，但不能替代接收端源码 或真实硬件测量。 厂商材料未附公开再分发许可，因此仓库只保存来源说明、文件哈希和 分析结果，不重新分发完整第三方源码。

标签：Python, 体感交互, 固件分析, 无后门, 机器人, 机械手遥操作, 通信协议解析