版本：外骨骼手套

安装和启动

宿主机要求：ubuntu22.04：x86/arm64 宿主机必须安装适配的ros环境。
获取到项目包后解压（本机需ros环境），支持以下 3 种使用方式：
- 安装桌面快捷方式（默认 UI 版）：进入项目包，开启终端手动安装 ./scripts/install-desktop.sh 后，在桌面会出现软件图标，双击打开会弹出浏览器。
- 直接在终端上启动程序（有 UI 界面）：进入项目包，在终端运行 ./scripts/run_gateway.sh。
- Headless版（无 UI 界面）：./scripts/run_gateway.sh --headless。

界面总览

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

外骨骼和灵巧手配置模块。
外骨骼和灵巧手可视化模块。
系统监控模块。

界面总览-配置模块

界面总览-可视化模块

界面总览-系统监控模块

外骨骼手套模块配置及其可视化

外骨骼手套连接

有线连接

将外骨骼手套连接至电脑 USB 端口，软件会自动识别左右手的连接状态（刷新约耗时3秒）。

无线连接

首次使用无线模块的配网步骤

注意

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

配网流程

开启无线模块：
- "短按 + 长按"设备按钮，看到电量灯闪烁时马上松开，此时设备开机。
将无线模块切换到配对模式：
- 步骤一：开机状态下：短按一下 → 长按 3 秒（电量灯闪烁一次）→ 继续长按至 10 秒（蓝灯亮起）→ 松开 → 设备关机；
- 步骤二：重新开机：短按一下 → 长按 3 秒（电量灯闪烁一次）→ 松开 → 进入配对模式（蓝灯亮起）。
进行 ESP 配网：
- 将随附路由器通过网线连接至 PC 网口，同时确保 PC Wi-Fi 已连接至随附路由器 Wi-Fi 的 2.4G 网段（例如：IO_2.4G_*****）；
- 输入路由器 Wi-Fi 的 SSID、密码和回调 IP （在 PC 中查看路由器的网关 IP 后输入）；
- 点击「开始配网」，软件会自动校验回调 IP（点击「保存配置」可以将当前网络配置信息保存至本地配置文件）；
- 查看无线模块指示灯的状态，应由蓝色常亮短暂变红，然后变为绿色常亮。
进行设备连接：
- 将无线模块与外骨骼设备连接好，此时无线模块指示灯应变为绿色闪烁状态；
- 在前端界面点击「启动 UDP 接收」按钮，等待完成；
- 系统会自动识别并绑定左右手设备，连接成功后，软件中对应的外骨骼会显示端口信息和已连接状态。

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

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

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

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

外骨骼手套可视化

外骨骼运动实时可视化

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

左/右侧外骨骼关节数据

显示左/右侧外骨骼关节数据 exo_joint 的数值随时间的变化趋势。
可勾选需要显示的数据。

数据输出频率

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

振动反馈

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

灵巧手模块配置及其可视化

灵巧手配置

上传灵巧手型号配置文件：
- 可拖放压缩包（zip/tar.gz/tgz 等）/文件夹上传；
- 或者点击「上传配置」，在文件浏览器中选择。
选择目标灵巧手型号：如未找到所需型号可点击「刷新型号列表」。
点击「应用型号」 应用选择。

灵巧手模块可视化

灵巧手运动实时可视化

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

左/右手关节数据

显示左/右侧外骨骼关节数据 cmd_left / cmd_right 的数值随时间的变化趋势。
可勾选需要显示的数据。

左/右手输出频率

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

系统监控

状态

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

WebSocket 数据

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

REST API

前缀：/api/v1
地址：http://{host}:{port}/api/v1/...
Content-Type：JSON（上传接口除外）

方法	路径	作用	示例命令
GET	`/streams`	WebSocket stream 权威目录（id、topic、类型、方向）	`curl -s http://127.0.0.1:8080/api/v1/streams`
GET	`/status`	运行时状态：拓扑、手型、侧别、子进程、ROS 桥、sync 状态	`curl -s http://127.0.0.1:8080/api/v1/status`
GET	`/hands/configs`	获取有效手型列表（扫描 `configs/end_tools`）	`curl -s http://127.0.0.1:8080/api/v1/hands/configs`
POST	`/hands/select`	选手型并启动进程链（exo/transform/controller）	—
POST	`/hands/configs/upload`	上传手型配置包到 `configs/end_tools/<hand>/`	—
POST	`/runtime/frequency`	修改 exo 发布频率 120（默认）/ 100 Hz，写 yaml 并重启 exo_tf	—
POST	`/wifi/provision`	开始发送配网信息	—
POST	`/exo/udp/start`	启动udp识别外骨骼程序	—
GET	`/exo/udp/stop`	停止udp识别程序	—

WebSocket 数据流

Stream 目录

base_id	scope	ROS topic（模板）	ROS 类型	方向
`io_esk.tf`	global	`/io_fusion/tf_exoskeleton`	TFMessage	subscribe
`io_esk.joint_data`	global	`/io_esk/joint_data`	JointState	subscribe
`io_esk.joystick_data`	global	`/io_esk/joystick_data`	Joy	subscribe
`io_align.tf.robotname`	hand	`/io_align/tf_hand`	TFMessage	subscribe
`io_align.poses_left.robotname`	hand	`/io_align/<手型名>/poses_<new_parent_frame>`	PoseArray	subscribe
`io_align.poses_right.robotname`	hand	`/io_align/<手型名>/poses_<new_parent_frame>`	PoseArray	subscribe
`io_teleop.joint_cmd_left.robotname`	hand	`/io_teleop/joint_cmd_finger_left`	JointState	subscribe
`io_teleop.joint_cmd_right.robotname`	hand	`/io_teleop/joint_cmd_finger_right`	JointState	subscribe
`io_esk.vibration_feedback`	—	`/io_esk/vibration_feedback`	Float64MultiArray	publish

Stream 数据帧

时间戳统一为 stamp_ns（int64，纳秒）。

字段	类型	说明
`stream`	string	stream id
`data`	object	ROS 消息转 JSON

{
  "stream": "exo_joint",
  "data": {
    "stamp_ns": 1717401234567890123,
    "names": ["joint1", "joint2", "..."],
    "position": [0.1, 0.2, "..."],
    "velocity": [],
    "effort": []
  }
}

各 Stream 的 data 类型

TFMessage — `exo_tf`、`align_tf.*`

{
  "stamp_ns": 1717401234567890123,
  "transforms": [
    {
      "parent": "world",
      "child": "base_link",
      "translation": [0.0, 0.0, 0.0],
      "rotation": [0.0, 0.0, 0.0, 1.0]
    }
  ]
}

JointState — `exo_joint`、`cmd_left.`、`cmd_right.`、`teleop_joint_states.*`

{
  "stamp_ns": 1717401234567890123,
  "names": ["joint1", "joint2", "..."],
  "position": [0.1, 0.2, "..."],
  "velocity": [],
  "effort": []
}

Joy — `exo_joy`

{
  "stamp_ns": 1717401234567890123,
  "axes": [0.0, 0.0, 0.0, 0.0],
  "buttons": [0, 1, 0, 0, 0, 0, 0, 0]
}

PoseArray — `align_poses_left_hand_ee_link.`、`align_poses_right_hand_ee_link.`

{
  "stamp_ns": 1717401234567890123,
  "poses": [
    {
      "position": [0.0, 0.0, 0.0],
      "orientation": [0.0, 0.0, 0.0, 1.0]
    }
  ]
}

Float64MultiArray — publish `exo_vibration`

{"data": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]}

界面总览

外骨骼手套模块配置及其可视化

外骨骼手套连接​

有线连接​

无线连接​

首次使用无线模块的配网步骤​

配网流程​

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

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

外骨骼手套可视化​

外骨骼运动实时可视化​

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

数据输出频率​

振动反馈​

灵巧手模块配置及其可视化

灵巧手配置​

灵巧手模块可视化​

灵巧手运动实时可视化​

左/右手关节数据​

左/右手输出频率​

系统监控

状态​

WebSocket 数据​

REST API

WebSocket 数据流

Stream 目录​

Stream 数据帧​

各 Stream 的 data 类型​

TFMessage — exo_tf、align_tf.*​

JointState — exo_joint、cmd_left.*、cmd_right.*、teleop_joint_states.*​

Joy — exo_joy​

PoseArray — align_poses_left_hand_ee_link.*、align_poses_right_hand_ee_link.*​

Float64MultiArray — publish exo_vibration​

外骨骼手套连接

有线连接

无线连接

首次使用无线模块的配网步骤

配网流程

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

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

外骨骼手套可视化

外骨骼运动实时可视化

左/右侧外骨骼关节数据

数据输出频率

振动反馈

灵巧手配置

灵巧手模块可视化

灵巧手运动实时可视化

左/右手关节数据

左/右手输出频率

状态

WebSocket 数据

Stream 目录

Stream 数据帧

各 Stream 的 data 类型

TFMessage — `exo_tf`、`align_tf.*`

JointState — `exo_joint`、`cmd_left.`、`cmd_right.`、`teleop_joint_states.*`

Joy — `exo_joy`

PoseArray — `align_poses_left_hand_ee_link.`、`align_poses_right_hand_ee_link.`

Float64MultiArray — publish `exo_vibration`