跳到主要内容

使用说明

IO Gesture 软件基础信息​

系统要求​

项目要求
操作系统Ubuntu 22.04 或 24.04（x86 或 arm64）
处理器（CPU）建议 ≥ 14 代 Intel Core i5，或 ≥ 13 代 Intel Core i7 同级性能（详见 设备性能要求）
内存建议 16 GB 及以上
命令行工具curl（启动脚本用于本地健康检查）
浏览器Head 模式需现代浏览器（Chrome / Firefox / Edge 等）

说明：软件包自带运行时所需 Python、依赖库与可执行程序，使用主程序无需安装 ROS 和系统级 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
附：常用配置说明（点击展开）

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

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

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

软件运行模式​

IO Gesture 提供两种运行模式：

模式适用场景Web 界面操作方法
Head（默认）本地桌面、调试、演示有，自动打开浏览器（界面说明请查阅 界面总览）方法一：进入软件包目录，在终端执行 ./scripts/install-desktop.sh 后，双击桌面快捷方式或在应用菜单搜索「IO Gateway」/「IO Gesture」启动；

方法二：进入软件包目录，在终端运行 ./scripts/run_gateway.sh
HeadlessSSH 远程、systemd 服务、二次集成无进入软件包目录，在终端运行 ./scripts/run_gateway.sh --headless
  • 软件包 tools/ 额外提供可选 ROS 桥接脚本（主程序不依赖 ROS）：Zenoh → ROS / WebSocket → ROS

详细启动方式请查阅 IO Gesture 使用方法 章节。

IO Gesture 部署方法​

  1. 软件包解压与权限设置：
cd /path/to/io_exotrans2hand_project_zenoh_22.04_x86_vX.X.X
chmod +x scripts/*.sh
  1. 在项目根目录执行：
./scripts/install-desktop.sh

该脚本会：

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

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

提示

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

sudo chmod -R 777 /dev/ttyA*

IO Gesture 使用方法​

启动 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 启动。

界面总览​

启动成功后，浏览器打开的 Web 控制台界面从上到下依次为：

界面总览-配置模块

外骨骼和灵巧手配置模块

界面总览-可视化模块

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

界面总览-系统监控模块

系统监控模块

启动 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左右手控制器

外骨骼连接与配置​

有线连接​

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

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

无线连接​

方法一：使用随附路由器快速开始​

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

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

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

方法二：使用其它路由器或自定义网络配置​

  1. 开启无线模块：
    • “短按 + 长按”设备按钮，看到电量灯闪烁时马上松开，此时设备开机。
  2. 将无线模块切换到配对模式：
    • 步骤一：开机状态下：短按一下 → 长按 3 秒（电量灯闪烁一次）→ 继续长按至 10 秒（蓝灯亮起）→ 松开 → 设备关机；
    • 步骤二：重新开机：短按一下 → 长按 3 秒（电量灯闪烁一次）→ 松开 → 进入配对模式（蓝灯亮起）。
  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 二进制。

  1. 环境要求

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

  2. 烧录模式

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

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

  3. 典型用法

    在项目根目录执行：

    # 全片烧录（清空配网，升级后须重新配网）
    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。

标定​

IO Gesture 提供外骨骼手套对指标定功能，支持在 Head 或 Headless 模式下进行。

Head 模式下，功能入口如下图所示：

外骨骼标定
  • 选择配置文件后，点击「应用」按钮即可将其应用至当前连接的外骨骼手套。
  • 选择配置文件后，点击「修改」按钮进入标定界面，按照指引操作即可对此文件中的结果进行重新标定。
  • 点击「新建」按钮进入标定界面，按照指引操作可创建一个新的配置文件。
  • 点击「删除」图标可删除配置文件。
  • 点击「导入」图标可导入本地配置文件。
提示

配置文件的命名格式固定为 <用户名>_L_<左手外骨骼手套 SN 码>_R_<右手外骨骼手套 SN 码>.yml。

Headless 模式下，另起一个终端，执行 ./scripts/run_calib_guide.sh 即可进入终端标定指引。

灵巧手连接与配置​

灵巧手连接与配置
  1. 将灵巧手与电脑连接，并进行必要的部署适配。
  2. 上传灵巧手型号配置文件：

    • 顶层必须是唯一文件夹，文件夹名即为型号名（仅允许英文字母、数字、下划线）：

      <型号名>/
      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 + 点击 选择型号根文件夹（不支持拖放上传）。

    • 确认「识别型号名」自动填写正确。

    • 点击 上传配置。

    • 若型号已存在，按提示确认是否覆盖。

  3. 在「型号选择」勾选一个或多个可用型号：如未找到所需型号可点击「刷新型号列表」。
  4. 点击「应用」。

说明：

  • 「当前型号」显示已应用列表：
    • 「已保存，等待外骨骼」：型号已记录，待外骨骼接入后自动拉起链路。
    • 「进程未就绪」：外骨骼或 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。

快速命令索引​

# 安装桌面图标与串口权限
./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/

常见问题​

现象处理建议
状态区提示无法连接网关确认已启动 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 模式会清空配网，须重新执行配网

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