版本：外骨骼手套 V2

使用说明

系统要求

项目	要求
操作系统	Ubuntu 22.04 或 24.04（x86 或 arm 64）
处理器（CPU）	建议 ≥ 14 代 Intel Core i5，或 ≥ 13 代 Intel Core i7 同级性能（详见设备性能要求）
内存	建议 16 GB 及以上
网络工具	`curl`（启动脚本健康检查用）
浏览器	Head 模式需现代浏览器（Chrome / Firefox / Edge 等）
外设	外骨骼手套（USB 串口或有线/无线 UDP）；可选灵巧手型号配置

说明：使用主程序无需安装 ROS 和系统级 Python 依赖，交付包自带运行时所需 Python、依赖库与可执行程序。

设备性能要求（CPU）

本平台同时运行多个子进程，Head 模式下还有 Web 三维可视化与实时曲线，对 CPU 算力 要求较高。低于推荐配置时，可能出现界面卡顿、关节曲线掉帧、子进程响应变慢等现象。

可参考如下建议：

等级	CPU 参考	说明
推荐	14 代 Intel Core i5 或 13 代 Intel Core i7 及以上	可流畅运行 Head 模式（含 URDF 可视化与实时监控）
勉强可用	13 代 i5、12 代 i7 或同级	Headless 模式通常可接受；Head 模式可视化可能偶发卡顿
不推荐	低于上述等级的老款笔记本 / 低功耗 U 系列	易出现明显卡顿，不建议用于演示或生产

交付包和运行模式

交付包目录结构和说明如下（以您实际收到的为准）：

io_exotrans2hand_project_zenoh_22.04_x86_vX.X.X/
│
├── bundle/                  # 运行时依赖（开箱即用
│
├── configs/                 # 配置与模型资源
│   ├── config/              # 系统配置（Gateway / Zenoh / 话题）
│   ├── end_tools/           # 末端工具配置
│   ├── exoskeleton_urdf/    # 外骨骼 URDF 模型与网格
│   ├── IO.png               # 应用图标
│   └── udev/                # 串口设备规则
│
├── io-gateway.desktop       # 桌面快捷方式模板
│
├── scripts/                 # 启动脚本
│   ├── bundle-env.sh        # 环境变量加载
│   ├── install-desktop.sh   # 安装桌面快捷方式
│   └── run_gateway.sh       # 启动 Gateway 控制台
│
├── src/                     
│   ├── io_bus_proto/        # 通信消息协议
│   ├── io_gateway/          # Web 控制台（后端 + 3D 可视化）
│   └── io_unicontroller/    # 外骨骼运动控制
│
└── tools/                   # 辅助工具
    ├── tools/               # 无线模块烧录等
    ├── ws2ros_bridge.py     # WebSocket ↔ ROS 桥接
    ├── ws2ros-env.sh
    ├── zenoh2ros_bridge.py  # Zenoh ↔ ROS 桥接
    └── zenoh2ros-env.sh

本交付包提供两种运行模式：

模式	适用场景	Web 界面	操作方法
Head（默认）	本地桌面、调试、演示	有，自动打开浏览器（界面说明请查阅 Web 界面）	方法一：进入项目包，开启终端手动安装 `./scripts/install-desktop.sh` 后，双击桌面快捷方式或在应用菜单搜索「IO Gateway」/「IO Gesture」启动；方法二：进入项目包，在终端运行 `./scripts/run_gateway.sh`
Headless	SSH 远程、systemd 服务、二次集成	无	进入项目包，在终端运行 `./scripts/run_gateway.sh --headless`

交付包 tools/ 额外提供可选ROS桥接脚本（主程序不依赖 ROS）：Zenoh -> ROS/ WebSocket -> ROS

详细启动方式请查阅启动与停止章节。

首次部署

交付包解压与权限设置：

cd /path/to/io_exotrans2hand_project_zenoh_22.04_x86_vX.X.X
chmod +x scripts/*.sh

./scripts/install-desktop.sh

该脚本会：

安装桌面快捷方式「IO Gateway」/「IO Gesture」。
安装串口 udev 规则（ttyACM* / ttyUSB* → dialout 组）。
将当前用户加入 dialout 组。

重要提示

若本次才加入 dialout 组，请注销并重新登录（或重启）后再插拔外骨骼。

提示

若脚本执行完成后仍出现串口权限问题，请尝试手动执行：

sudo chmod -R 777 /dev/ttyA*

启动与停止

启动 Head 模式（推荐）

cd /path/to/io_exotrans2hand_project_zenoh_22.04_x86_vX.X.X
./scripts/run_gateway.sh

默认打开 Web 控制台：http://127.0.0.1:8080/。
端口读取 gateway.yaml 的 listen_port，也可用环境变量 GATEWAY_PORT 覆盖。
不自动打开浏览器：./scripts/run_gateway.sh --no-browser。

也可从桌面启动器搜索 IO Gateway / IO Gesture 启动。

启动 Headless 模式

./scripts/run_gateway.sh --headless

此时提供 REST API、WebSocket 与进程编排，不挂载 Web 页面。

说明

Headless 与 Head 共用同一套后端；差异仅为不提供 HTML 控制台与静态资源。

使用ROS桥接工具

交付包 tools/ 提供可选桥接脚本（主程序不依赖 ROS）：

Zenoh -> ROS

source /opt/ros/<发行版>/setup.bash
source tools/zenoh2ros-env.sh
python3 tools/zenoh2ros_bridge.py

WebSocket -> ROS

source /opt/ros/<发行版>/setup.bash
source tools/ws2ros-env.sh
python3 tools/ws2ros_bridge.py

停止

运行时在后台终端按 Ctrl+C 即可停止网关及子进程。

日志

日志按日期保存在 logs/YYYY-MM-DD/，例如：

文件	内容
`io_gateway.log`	网关主进程
`exo_tf.log` / `exo_tf_udp.log`	外骨骼采集
`transform_<型号>.log`	坐标变换
`controller_left/right_<型号>.log`	左右手控制器

Web 界面介绍

界面总览

前端 Web 界面从上到下依次为：

外骨骼和灵巧手配置模块

外骨骼和灵巧手可视化模块

系统监控模块

右上角可切换 中文 / EN（偏好保存在浏览器本地）。

外骨骼和灵巧手配置模块

外骨骼连接与配置

有线连接

用 USB 连接左/右外骨骼手套。
在「设备连接」面板查看 左手 / 右手 状态：显示串口路径且状态为「已连接」，表示连接成功。
系统自动扫描端口的周期约为约 2～3 秒，无需手动点击连接。
连接/断开/切换端口时，右上角会弹出提示。

有线与无线互斥：插入有线外骨骼后，系统优先使用串口模式。

无线连接

方法一：使用出厂默认网络配置快速开始

将随附的路由器启动。
将电脑通过网线连接至路由器（推荐），或者连接至路由器 Wi-Fi。
将电脑的 IPv4 地址设置为 10.42.0.2（默认）。
将外骨骼手套与无线模块连接。
开启无线模块："短按 + 长按"设备按钮，看到电量灯闪烁时马上松开，此时设备开机，等待无线模块指示灯变为绿色闪烁状态。
连接成功后，设备状态会显示为已连接，同时会显示端口信息。

如遇到连接问题，请检查：

PC 已连接到目标 Wi-Fi。
能 ping 通路由器/网关地址（例如 10.42.0.1）。
gateway.yaml 中 udp_probe.bind_ip 修改为本机在该网段的 IP（例如 10.42.0.2）。
如果需要更换运行程序的电脑，需确保更换前后的 IP 与无线模块配网时的 IP 与保持一致。

方法二：自定义网络配置（需要重新进行无线模块配网流程）

开启无线模块：
- "短按 + 长按"设备按钮，看到电量灯闪烁时马上松开，此时设备开机。
将无线模块切换到配对模式：
- 步骤一：开机状态下：短按一下 → 长按 3 秒（电量灯闪烁一次）→ 继续长按至 10 秒（蓝灯亮起）→ 松开 → 设备关机；
- 步骤二：重新开机：短按一下 → 长按 3 秒（电量灯闪烁一次）→ 松开 → 进入配对模式（蓝灯亮起）。
进行 ESP 配网：
- 将随附的路由器接入电源启动，与您希望运行 IO Gesture 程序的电脑连接（为了确保配网成功，配网时请确保电脑只与此路由器保持连接）：
  - 将电脑通过网线连接至路由器，或者将电脑连接至路由器 Wi-Fi 的 2.4G 网段（例如：IO_2.4G_*****）。
  - 在「无线模块配网」填写：
    - SSID：Wi-Fi 名称。
    - 密码：Wi-Fi 密码，至少 8 位（可用眼睛图标显示/隐藏）。
    - 回调 IP：路由器/网关地址，不要填本机 IP。
- 需确认除上述电脑外，还有其他设备已连接至路由器。
- 点击 开始配网，等待「配网信息广播成功」（可选：点击 保存网络，将上述三项写入配置，下次打开页面自动填充）。
- 查看无线模块指示灯的状态，应由蓝色常亮短暂变红，然后变为绿色常亮（如果此时已连接了外骨骼手套则为绿色闪烁）。
- 配网成功后，「无线模块状态」会显示在线模块 IP（最多显示 2 个）。
- 后台自动发现模块并确认外骨骼设备后启动 UDP 接收；设备状态变为「已连接」后即可选手型遥操作。

附：无线模块设备按钮使用方法

功能	操作方法
开机	短按一下 → 长按 3 秒（电量灯闪烁一次）→ 松开
关机	短按一下 → 长按 3 秒（电量灯闪烁一次）→ 松开
关机状态下查询电量	短按一下
进入配对模式	1. 开机状态下：短按一下 → 长按 3 秒（电量灯闪烁一次）→ 继续长按至 10 秒（蓝灯亮起）→ 松开 → 设备关机 2. 重新开机：短按一下 → 长按 3 秒（电量灯闪烁一次）→ 松开 → 进入配对模式（蓝灯亮起）

附：无线模块设备指示灯说明

状态	指示灯
无 Wi-Fi 连接	红色常亮
监听模式 / 配对模式	蓝色常亮
Wi-Fi 已连接、无设备数据传输	绿色常亮
Wi-Fi 已连接、有设备数据传输	绿色闪烁
读取内参	蓝色闪烁
发现设备	蓝绿色闪烁

附：无线模块固件升级方法

交付包 tools/tools/ 目录提供无线模块（ESP32-S3）USB 固件烧录工具，无需安装 pip 依赖，使用包内自带的 esptool 二进制。

环境要求
- Ubuntu 22.04 / 24.04，Python 3.10+。
- 用户已在 dialout 组。
- 无线模块通过 USB 连接 PC，出现 /dev/ttyUSB* 或 /dev/ttyACM* 节点。
- 升级前建议关闭 IO Gateway，避免串口被占用。

烧录模式

模式	命令	说明
`full`（默认）	`python3 flash_wifi_module_usb_app.py`	全片擦除后烧整片固件，会清空 WiFi 配网信息，升级后需重新配网
`app`	`python3 flash_wifi_module_usb_app.py app`	仅重烧 app 分区，保留配网等 NVS 信息

固件文件默认取脚本同目录下的 merged-flash.bin（full）或 USB_WiFi_UDP.bin（app）；也可用 --image 指定其它 .bin。

典型用法

在项目根目录执行：

# 全片烧录（清空配网，升级后须重新配网）
python3 tools/tools/flash_wifi_module_usb_app.py

# 仅升级固件，保留配网
python3 tools/tools/flash_wifi_module_usb_app.py app

# 指定单块模块
python3 tools/tools/flash_wifi_module_usb_app.py app --port /dev/ttyUSB0

# 指定固件包
python3 tools/tools/flash_wifi_module_usb_app.py app --image path/to/USB_WiFi_UDP.bin

不指定 --port 时，脚本会自动探测并批量烧录所有识别到的 Wi-Fi 模块（经 esptool 确认为 ESP32-S3 才烧录）。
烧录完成后脚本会校验启动横幅 WIFI UDP App Software version:X,Y，确认新固件真正运行。
更详细的参数说明见 tools/tools/README.md。

灵巧手连接与配置

将灵巧手与电脑连接，并进行必要的部署适配。
上传灵巧手型号配置文件：
- 顶层必须是唯一文件夹，文件夹名即为型号名（仅允许英文字母、数字、下划线）：
```
<型号名>/
urdf/                         # 目录内须有文件
meshes/                       # 目录内须有文件
tf_transform_v2.yml
controller_v2_3_left.yml
controller_v2_3_right.yml
```
  支持压缩包：zip、tar、tar.gz、tgz、tar.bz2、tar.xz 等（压缩包内同样须含一层型号名目录）。
- 点击上传区域选择压缩包，或 Shift + 点击 选择型号根文件夹（不支持拖放上传）。
- 确认「识别型号名」自动填写正确。
- 点击 上传配置。
- 若型号已存在，按提示确认是否覆盖。
在「型号选择」勾选一个或多个可用型号：如未找到所需型号可点击「刷新型号列表」。
点击「应用」。

说明：

「当前型号」显示已应用列表：
- 「已保存，等待外骨骼」：型号已记录，待外骨骼接入后自动拉起链路。
- 「进程未就绪」：外骨骼或 transform/controller 尚未就绪，请查看系统监控与日志。
清空型号：取消全部勾选后点应用，确认后停止 transform / controller（外骨骼采集可继续运行）。
刷新：重新拉取型号列表。
删除型号：
- 点击垃圾桶图标进入删除模式。
- 删除未应用的型号。
- 已应用的型号不可删除，需先清空应用再删。
左右手侧别由外骨骼自动探测决定，界面无需手动选择侧别。
若 hand_choose 已配置且检测到外骨骼，启动时会自动应用保存的型号。

外骨骼和灵巧手可视化模块

外骨骼运动实时可视化

可使用鼠标指针拖动旋转图像，使用鼠标滚轮缩放。

左/右侧外骨骼关节数据

显示左/右侧外骨骼关节数据的数值随时间的变化趋势。
可勾选图例显示/隐藏；悬停后可放大全屏查看。

数据输出频率

显示数据源的输出频率随时间的变化趋势。
约 1 秒滑动窗口。
可设置固定/动态轴。

振动反馈

柱状图显示灵巧手发送给外骨骼的振动反馈强度数值。
末端 1~10 对应外骨骼的 10 根手指末端。

灵巧手可视化

灵巧手运动实时可视化

可使用鼠标指针拖动旋转图像，使用鼠标滚轮缩放。

左/右手关节数据

显示左/右侧外骨骼关节数据的数值随时间的变化趋势。
可勾选图例显示/隐藏；悬停后可放大全屏查看。

左/右手输出频率

显示数据源的输出频率随时间的变化趋势。
可设置固定/动态轴。

系统监控模块

状态

每秒刷新 GET /api/v1/status，可关注：

已应用 / 已配置 / 可用型号
外骨骼传输方式：serial / udp / none
左右绑定端口或 IP:端口
无线在线 IP
各子进程是否 running 及日志路径

网关离线时会出现黄色提示条；恢复后自动继续刷新。

WebSocket 数据

页面自动连接 /ws，断线会自动重连。
可用下拉框切换查看各数据流最新一帧。
默认订阅外骨骼关节、左右 IMU、振动反馈，以及已应用型号的左右关节指令流。
全部可用流见：GET /api/v1/streams。

常用配置说明

主配置文件：configs/config/gateway.yaml

配置项	说明
`udp_probe.bind_ip`	无线模式本机绑定 IP（须为本机实际地址）
`listen_host` / `listen_port`	Web 监听地址与端口（默认 `0.0.0.0:8080`）
`logs_dir`	日志目录
`wifi_provision`	配网默认 SSID / 密码 / 回调 IP
`udp_allowed_ips`	无线 IP 白名单（最多 2 个，可选）

灵巧手资源目录：configs/end_tools/<型号名>/。

常见问题

现象	处理建议
状态区提示无法连接网关	确认已启动 `run_gateway.sh`；检查端口与 `logs/.../io_gateway.log`
有线一直「未连接」	确认已加入 `dialout` 并重新登录；检查 USB；查看 `logs/.../exo_tf.log`
配网失败 / 无法获取路由器 MAC	确认 PC 已连目标 Wi-Fi；回调 IP 填网关而非本机；先 ping 通网关
无线无法收数 / bind_ip 不符	确认本地 IP、无线模块配网时的电脑 IP、 `udp_probe.bind_ip` 三者一致
型号「进程未就绪」	先确保外骨骼已连接；查看对应 transform/controller 日志
删除型号失败	先取消应用该型号，再删除
上传失败	检查顶层目录名与 `urdf/`、`meshes/`、三个 yml 是否齐全
外骨骼 3D 空白	将 STL 放入 `configs/exoskeleton_urdf/meshes/`
WebSocket 无数据	确认外骨骼在线且已应用型号；查看系统监控中的进程状态
固件升级找不到设备	确认 USB 连接、`dialout` 权限；关闭网关避免占串口；可用 `--port` 指定节点
升级后无线无法连接	`full` 模式会清空配网，须重新执行配网

快速命令索引

# 安装桌面图标与串口权限
./scripts/install-desktop.sh

# 启动 Web 控制台
./scripts/run_gateway.sh

# 无界面启动
./scripts/run_gateway.sh --headless

# 不自动打开浏览器
./scripts/run_gateway.sh --no-browser

# 无线模块固件升级
cd tools/tools && python3 flash_wifi_module_usb_app.py

控制台地址：http://127.0.0.1:8080/

如需技术支持，请提供当日 logs/YYYY-MM-DD/ 下相关日志与控制台输出，便于快速定位。

系统要求​

设备性能要求（CPU）​

交付包和运行模式​

首次部署​

启动与停止​

启动 Head 模式（推荐）​

启动 Headless 模式​

使用ROS桥接工具​

Zenoh -> ROS​

WebSocket -> ROS​

停止​

日志​

Web 界面介绍​

界面总览​

外骨骼和灵巧手配置模块​

外骨骼连接与配置​

有线连接​

无线连接​

附：无线模块设备按钮使用方法​

附：无线模块设备指示灯说明​

附：无线模块固件升级方法​

灵巧手连接与配置​

外骨骼和灵巧手可视化模块​

外骨骼运动实时可视化​

左/右侧外骨骼关节数据​

数据输出频率​

振动反馈​

灵巧手可视化​

灵巧手运动实时可视化​

左/右手关节数据​

左/右手输出频率​

系统监控模块​

状态​

WebSocket 数据​

常用配置说明​

常见问题​

快速命令索引​

系统要求

设备性能要求（CPU）

交付包和运行模式

首次部署

启动与停止

启动 Head 模式（推荐）

启动 Headless 模式

使用ROS桥接工具

Zenoh -> ROS

WebSocket -> ROS

停止

日志

Web 界面介绍

界面总览

外骨骼和灵巧手配置模块

外骨骼连接与配置

有线连接

无线连接

附：无线模块设备按钮使用方法

附：无线模块设备指示灯说明

附：无线模块固件升级方法

灵巧手连接与配置

外骨骼和灵巧手可视化模块

外骨骼运动实时可视化

左/右侧外骨骼关节数据

数据输出频率

振动反馈

灵巧手可视化

灵巧手运动实时可视化

左/右手关节数据

左/右手输出频率

系统监控模块

状态

WebSocket 数据

常用配置说明

常见问题

快速命令索引