跳到主要内容
版本：独立版外骨骼手套

使用说明

系统要求​

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

说明：Python 3.10、FastAPI、数值库已内置在 bundle/ 目录，无需单独创建虚拟环境或编译源码。

设备性能要求（CPU）​

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

可参考如下建议：

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

部署前准备​

1. 安装 ROS 2 Humble​

若目标机器尚未安装 ROS 2 Humble，请先按 ROS 2 Humble 官方文档 完成安装，并确认以下文件存在：

test -f /opt/ros/humble/setup.bash && echo "ROS Humble OK"

2. 使用有线外骨骼前的 USB 串口权限设置​

方法一（推荐）：

sudo chmod -R 777 /dev/ttyA*
sudo chmod -R 777 /dev/ttyU*

方法二：

  • 将当前用户加入 dialout 组，并重新登录后生效：

    sudo usermod -aG dialout "$USER"

  • 建议安装项目自带的 udev 规则，以便外骨骼 USB 拔插后权限自动恢复：

    sudo cp configs/udev/99-io-exo-serial.rules /etc/udev/rules.d/
    sudo udevadm control --reload-rules && sudo udevadm trigger

3. 使用无线外骨骼前的网络配置准备​

若使用无线外骨骼模块，需确保本机存在 10.42.0.* 网段地址。关于无线连接的详细步骤请查阅 无线连接 章节。

4. 解压与权限​

cd /path/to/io_exotrans2hand_project_22.04_x86_v1.0.7
chmod +x scripts/*.sh

目录结构和运行模式​

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

io_exotrans2hand_project_22.04_x86_vX.X.X/
├── scripts/
│   ├── run_gateway.sh       # 主启动脚本（head / headless）
│   ├── install-desktop.sh   # 安装桌面快捷方式
│   ├── bundle-env.sh        # 加载 bundle 环境与 ROS
│   └── bundle-ws-setup.bash # ROS 工作空间 setup
├── configs/
│   ├── config/
│   │   ├── gateway.yaml     # 网关主配置（端口、命令、数据流等）
│   │   └── topics.yaml      # exo_tf 等 ROS 话题参数
│   ├── end_tools/           # 灵巧手型号配置（可上传扩展）
│   ├── exoskeleton_urdf/    # 外骨骼 URDF 与网格
│   ├── udev/                # USB 串口 udev 规则
│   └── IO.png               # 应用图标
├── src/
│   ├── io_gateway/          # 网关服务（Web / API / 编排）
│   └── io_unicontroller/    # 灵巧手控制器脚本
├── bundle/                  # 预编译运行时（Python、ROS 包、依赖库）
├── logs/                    # 运行日志（按日期分目录，启动后自动创建）
└── io-gateway.desktop       # 桌面快捷方式模板

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

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

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

启动方式​

所有启动方式均通过 scripts/run_gateway.sh，它会自动加载 bundle/ 内 Python 与 ROS 环境。

Head 模式（推荐）​

./scripts/run_gateway.sh

  • 默认访问地址：http://127.0.0.1:8080/

  • 可选：

    • 不自动打开浏览器（仍提供 Web UI）：

      GATEWAY_NO_BROWSER=1 ./scripts/run_gateway.sh
      # 或
      ./scripts/run_gateway.sh --no-browser

    • 桌面快捷方式：

      ./scripts/install-desktop.sh

      安装后可在桌面或应用菜单搜索「IO Gateway」/「IO Gesture」启动。

Headless 模式​

./scripts/run_gateway.sh --headless

  • 启动后终端会提示：

    [run_gateway] mode=headless  API=http://127.0.0.1:8080/api/v1  WS=ws://127.0.0.1:8080/ws

  • 访问根路径 http://127.0.0.1:8080/ 将返回 JSON 指引，而非 HTML 页面。

  • Headless 快速验证：

    # 健康检查
    curl -s http://127.0.0.1:8080/api/v1/status | python3 -m json.tool

    # 选手型（示例）
    curl -s -X POST http://127.0.0.1:8080/api/v1/hands/select \
    -H "Content-Type: application/json" \
    -d '{"hands": ["YourHandModel"]}'
备注

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

Web 界面​

界面总览​

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

  • 外骨骼和灵巧手配置模块。
  • 外骨骼和灵巧手可视化模块。
  • 系统监控模块。
界面总览-配置模块

外骨骼和灵巧手配置模块

界面总览-可视化模块

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

界面总览-系统监控模块

系统监控模块

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

界面总览-配置模块

外骨骼连接与配置​

有线连接​
  • 将外骨骼手套通过随附的 USB C-A 转接线连接至电脑 USB 端口，软件会自动识别左右手的连接状态（刷新约耗时3秒）。
  • 连接成功后，设备状态会显示为已连接，同时会显示端口信息。
无线连接​
  • 将随附的路由器接入电源启动。
  • 将电脑连接至路由器 Wi-Fi（此步骤也可以通过网线连接电脑与路由器）。
  • 将电脑的 IPv4 地址设置为 10.42.0.2。
  • 将外骨骼手套与无线模块连接。
无线模块背面
  • 开启无线模块："短按 + 长按"设备按钮，看到电量灯闪烁时马上松开，此时设备开机，等待无线模块指示灯变为绿色闪烁状态。
  • 在 Web 界面点击 「启动 UDP 接收」按钮，等待完成。
  • 连接成功后，设备状态会显示为已连接，同时会显示端口信息。
附：无线模块的配网流程​
注意

无线模块在出厂时已完成配网流程，此说明仅供需要再次配网时参考，如无需要可跳过。

提示

两个无线模块需要分别单独进行配网，即按下述流程先完成其中一个无线模块的配网，将其关机后，再进行另一个无线模块的配网。两个无线模块均完成配网后，即可开机使用。

  1. 开启无线模块：
    • "短按 + 长按"设备按钮，看到电量灯闪烁时马上松开，此时设备开机。
  2. 将无线模块切换到配对模式：
    • 步骤一：开机状态下：短按一下 → 长按 3 秒（电量灯闪烁一次）→ 继续长按至 10 秒（蓝灯亮起）→ 松开 → 设备关机；
    • 步骤二：重新开机：短按一下 → 长按 3 秒（电量灯闪烁一次）→ 松开 → 进入配对模式（蓝灯亮起）。
  3. 进行 ESP 配网：
    • 将随附的路由器接入电源启动，与您希望运行 IO Gesture 程序的电脑连接（为了确保配网成功，配网时请确保电脑只与此路由器保持连接）：
      • 将电脑通过网线连接至路由器；
      • 或者将电脑连接至路由器 Wi-Fi 的 2.4G 网段（例如：IO_2.4G_*****）。
    • 输入路由器 Wi-Fi 的 SSID（名称）、密码和回调 IP (10.42.0.1)。
    • 需确认除上述电脑外，还有其他设备已连接至路由器。
    • 点击「开始配网」，软件会自动校验回调 IP（点击「保存配置」可以将当前网络配置信息保存至本地配置文件）；
    • 查看无线模块指示灯的状态，应由蓝色常亮短暂变红，然后变为绿色常亮（如果连接了外骨骼手套则为绿色闪烁）。
附：无线模块设备按钮使用方法​
功能操作方法
开机短按一下 → 长按 3 秒（电量灯闪烁一次）→ 松开
关机短按一下 → 长按 3 秒（电量灯闪烁一次）→ 松开
关机状态下查询电量短按一下
进入配对模式1. 开机状态下：短按一下 → 长按 3 秒（电量灯闪烁一次）→ 继续长按至 10 秒（蓝灯亮起）→ 松开 → 设备关机
2. 重新开机：短按一下 → 长按 3 秒（电量灯闪烁一次）→ 松开 → 进入配对模式（蓝灯亮起）
附：无线模块设备指示灯说明​
状态指示灯
无 Wi-Fi 连接红色常亮
监听模式 / 配对模式蓝色常亮
Wi-Fi 已连接、无设备数据传输绿色常亮
Wi-Fi 已连接、有设备数据传输绿色闪烁
读取内参蓝色闪烁
发现设备蓝绿色闪烁

灵巧手连接与配置​

  • 将灵巧手与电脑连接，并进行必要的部署适配。
  • 上传灵巧手型号配置文件：
    • 可拖放压缩包（zip/tar.gz/tgz 等）/文件夹上传。
    • 或者点击「上传配置」，在文件浏览器中选择。
  • 选择目标灵巧手型号：如未找到所需型号可点击「刷新型号列表」。
  • 点击「应用型号」应用选择。

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

界面总览-可视化模块

外骨骼运动实时可视化​

  • 可使用鼠标指针拖动旋转图像，使用鼠标滚轮缩放。
左/右侧外骨骼关节数据​
  • 显示左/右侧外骨骼关节数据 exo_joint 的数值随时间的变化趋势。
  • 可勾选需要显示的数据。
数据输出频率​
  • 显示数据源 exo_joint 的输出频率随时间的变化趋势。
  • 数据输出频率图像可设置固定/动态轴。
振动反馈​
  • 显示灵巧手发送给外骨骼的振动反馈强度 exo_vibration 数值。
  • 末端 1~10 对应外骨骼的 10 根手指末端。

灵巧手可视化​

灵巧手运动实时可视化​
  • 可使用鼠标指针拖动旋转图像，使用鼠标滚轮缩放。
左/右手关节数据​
  • 显示左/右侧外骨骼关节数据 cmd_left / cmd_right 的数值随时间的变化趋势。
  • 可勾选需要显示的数据。
左/右手输出频率​
  • 显示数据源 cmd_left / cmd_right 的输出频率随时间的变化趋势。
  • 数据输出频率图像可设置「固定」/「动态轴」。

系统监控模块​

界面总览-系统监控模块

状态​

  • 实时显示 /status 接口数据，包括运行时状态：拓扑、灵巧手型号、侧别、子进程、ROS 桥、sync 状态。

WebSocket 数据​

  • 实时显示外骨骼手套 exo_joint 和已应用的灵巧手 cmd_left / cmd_right 的数值。
  • 可点击下拉框选择。

常用环境变量​

变量说明默认值
GATEWAY_PORT监听端口读 gateway.yaml 中 listen_port（8080）
GATEWAY_NO_BROWSERHead 模式下禁止自动打开浏览器未设置
IO_EXOTRANS2HAND_ROOT项目根目录脚本所在目录的上级

示例：指定端口 9000 并以 headless 运行：

GATEWAY_PORT=9000 ./scripts/run_gateway.sh --headless

日志与排障​

类型路径
网关主进程logs/YYYY-MM-DD/io_gateway.log
子进程logs/YYYY-MM-DD/ 下各组件独立日志

常见问题：

  1. 启动失败 / 找不到 Python
    确认 bundle/opt/python/bin/python3 存在且可执行；勿删除 bundle/ 目录。

  2. ROS 相关报错
    确认 /opt/ros/humble/setup.bash 存在；在终端手动 source /opt/ros/humble/setup.bash 后重试。

  3. 检测不到 USB 外骨骼
    检查用户是否在 dialout 组；是否安装 udev 规则；设备是否被其他进程占用。

  4. Head 模式浏览器未自动打开
    手动访问 http://127.0.0.1:8080/；或使用 GATEWAY_NO_BROWSER=1 后自行打开。

  5. 无线 UDP 无法启动
    确认本机 10.42.0.* 网段地址已配置。

  6. 无可用灵巧手型号
    通过 Web 控制台上传配置包，或将合法手型目录放入 configs/end_tools/<型号名>/。

  7. 界面卡顿 / 可视化掉帧 / 整体响应慢
    多为 CPU 性能不足。请查阅 设备性能要求。可改用 ./scripts/run_gateway.sh --headless 减轻负载，或关闭浏览器中不必要的标签页与其他占 CPU 的程序。

提示

如遇其他问题，请联系技术支持并提供以下信息：

  • 操作系统版本与硬件连接方式（USB / UDP）
  • 启动命令（head 或 headless）及完整终端输出
  • logs/ 下当日 io_gateway.log 及相关子进程日志