logo Mr.Robota 具身智能学习手册
/
EN
第三章:机器人硬件、lerobot及地瓜RDK-X5开发板控制教程

Robosuite Joycon Web 控制系统

基于浏览器的 Nintendo Switch Joy-Con 远程控制方案，利用 WebSocket 与 Robosuite 仿真环境实时联动，支持单臂 / 双臂、多机器人以及局域网远程操作。

🌟 核心亮点

  • ✅ 浏览器即遥控器：Gamepad API 读取 Joy-Con 输入，前端 60 Hz 采样
  • ✅ 实时双向通信：WebSocket 低延迟推送到 Python 后端
  • ✅ 完整 Robosuite 适配：复用官方 Device 接口，支持 OSC / Whole Body 控制器
  • ✅ 单 / 双 Joy-Con：默认单臂，也可一左一右控制双臂任务
  • ✅ 图形界面监控：实时显示按键、摇杆状态、连接信息
  • ✅ 跨平台：支持 Linux、Windows（含 WSL2）、macOS，只需蓝牙即可连接 Joy-Con

🧠 系统架构

┌─────────────┐          WebSocket          ┌──────────────┐
│   浏览器     │ ←────────────────────────→ │ Python 服务器 │
│  (前端界面)  │   60Hz 手柄数据            │  (Robosuite)  │
└─────────────┘                             └──────────────┘
      ↑                                            ↓
      │                                            │
  Gamepad API                               Robosuite 仿真
   (Joy-Con)                                (机器人控制)

⚡ 5 分钟快速体验

已具备 Python ≥3.8、Bun/Node.js、蓝牙 Joy-Con。（推荐）

  1. 获取代码 & 安装依赖

    bashcd /home/kewei/17robo/robosuite-joycon-web
bun install
pip install -r requirements.txt

# 安装 robosuite（首次运行需要）
cd /home/kewei/17robo/robosuite-joycon
pip install -e .
cd /home/kewei/17robo/robosuite-joycon-web

  2. 运行无渲染自检（适合 WSL/服务器）

    bashpython test_server_no_render.py

    出现 ✅ 所有测试通过！ 即表示后端逻辑正常。

  3. 蓝牙连接 Joy-Con

    • 长按 Joy-Con 侧边同步键，指示灯快闪
    • 在系统蓝牙设置中选择 Joy-Con (R) / Joy-Con (L) 连接

  4. 启动后端 & 前端

    bash# 终端 1: 单手柄默认环境（Lift + Panda）
./start_single.sh

# 终端 2: React 前端
bun run dev

    浏览器访问提示地址（默认 http://localhost:5173 ）。

  5. 开始遥控

    • 在网页里点击“连接服务器”
    • 按下任意 Joy-Con 按钮激活 Gamepad
    • 即可实时操控机器人

无显示器 / WSL 环境：若不方便开启渲染，可将 server.py 中 has_renderer 改为 False 运行。

🚀 启动方式详情

1. 后端服务器

模式 命令 说明
单手柄默认 ./start_single.sh Lift + Panda，端口 8765
单手柄自定义 ./start_single.sh [环境] [机器人] [端口] 例：./start_single.sh PickPlaceCan Sawyer 9000
双手柄默认 ./start_bimanual.sh TwoArmLift + Panda×2，parallel 配置
双手柄自定义 ./start_bimanual.sh [环境] [机器人1] [机器人2] [配置] [端口] 配置可选 parallel/opposed
核心功能测试 python test_server_no_render.py 无渲染环境必跑，用于 CI/诊断

2. 前端界面

bashcd /home/kewei/17robo/robosuite-joycon-web
bun run dev

浏览器访问终端提示地址（默认 http://localhost:5173），界面实时展示连接状态、按钮/摇杆读数。

🎮 控制映射（Joy-Con 默认布局）

输入 功能
左摇杆 X / Y 末端 X / Y 平移
R（右手柄） / L（左手柄） 末端上升（Z+）
摇杆按压 末端下降（Z−）
右摇杆 X Yaw 旋转
右摇杆 Y Pitch 旋转
SL / SR Roll 微调（右手柄顺/逆，左手柄反向）
ZR / ZL 抓取器开 / 合切换（按一下即切换状态）
+ (Plus) 触发环境重置
HOME 姿态回到初始偏置
A / Y 预留事件标志（与原 JoyConController 接口一致）

所有输入在 JoyconWebController 中做防抖与归一化处理，后端输出仍为 6+1 维动作向量，完全兼容 Robosuite 官方控制器。

ℹ️ 默认情况下浏览器仅能通过 Gamepad API 读取按键/摇杆，因此需使用右摇杆与 SL/SR 进行姿态调节。启用下方的 WebHID 实验特性后，便可以像原生控制器那样通过旋转 Joy-Con 直接驱动末端姿态。

WebHID 版 IMU 支持（实验特性）

  • 在 Chrome / Edge（需 HTTPS 或 localhost）中点击“连接 Joy-Con IMU”按钮，可通过 WebHID 访问 Joy-Con 传感器。
  • 连接成功后，网页会实时展示 Roll / Pitch / Yaw，并将其回传至服务器，实现“旋转 Joy-Con 控制姿态”的体验。
  • 目前每个浏览器会话仅支持连接 1 个 Joy-Con；若需要切换，请刷新页面并重新连接。
  • 不支持 WebHID 的浏览器将维持原有“摇杆 + SL/SR”姿态控制模式。

🧪 测试清单

推荐在上线或大改动后完整跑一遍，勾选表示通过。

基础环境

  • [ ] Python 依赖安装成功
  • [ ] Bun 前端依赖安装成功
  • [ ] Joy-Con 蓝牙连接稳定

核心功能

  • [ ] python test_server_no_render.py 通过
  • [ ] 单手柄模式可启动并执行动作
  • [ ] 双手柄模式可分别控制左右臂
  • [ ] 抓取器切换、生效及时
  • [ ] 20 Hz 控制循环稳定

界面与通信

  • [ ] 浏览器能识别 Joy-Con（按钮高亮）
  • [ ] WebSocket 状态显示“已连接”
  • [ ] 断开/重连后可恢复控制

性能

  • [ ] 控制延迟 < 100 ms
  • [ ] 长时间运行 (>30 min) 无明显漂移

更多细化步骤见 test_server_no_render.py 输出与历史测试记录。

🛠️ 常见问题 & 排查

问题 原因 解决方案
Action vector ... got 12 动作维度错误 已修复，确保使用当前版本 server.py
服务器在 WSL 卡住 无 GUI 渲染阻塞 关闭渲染：has_renderer=False，或配置 X11 / VNC
前端未识别 Joy-Con Gamepad 未激活 在浏览器按任意按钮；刷新页面；检查蓝牙连接
WebSocket 连接失败 端口被占用或服务未起 确认后端 log；lsof -i :8765；pkill -f "python server.py"
控制延迟大 网络或 CPU 繁忙 建议本机运行；关闭无关程序；仅在局域网内远程

新手建议：先运行 python test_server_no_render.py，确认核心控制无误后再接入渲染与前端。

📊 项目状态一览

  • 发布日期：2025-10-05
  • 版本：v1.0.0
  • 完成度：✅ 全功能可用
  • 涵盖功能：Gamepad API、WebSocket 服务、单/双 Joy-Con、前端监控、脚本化启动、自动化测试
  • 性能指标：
    • 控制频率 ~20 Hz
    • 手柄采样 60 Hz
    • WebSocket 延迟 <5 ms（本地）
    • 无渲染 CPU 占用 <30%

🔍 技术实现 & 修复要点

  • 完整复用 robosuite.devices.Device 逻辑：input2action、get_arm_action、状态机与坐标系转换全部保持一致
  • 输出动作维度固定为 6（末端位姿）+1（抓取器），兼容 OSC、Whole Body IK 控制器
  • 采用 button edge 检测消除按键抖动，ZR/ZL 实现抓取器状态切换
  • test_server_no_render.py 用于验证动作向量、奖励返回与持续控制
  • Start 脚本 start_single.sh / start_bimanual.sh 封装常见参数，便于部署

📂 目录与脚本速览

路径 说明
server.py WebSocket 服务器 & JoyconWebController 核心实现
src/App.tsx React 前端 UI，实时手柄可视化
start_single.sh / start_bimanual.sh 启动脚本（单臂 / 双臂）
test_server_no_render.py 无渲染自动化测试脚本
package.json / bun.lock 前端依赖定义
requirements.txt Python 依赖列表

🧭 下一步可以做什么？

  • 🚗 接入移动底座或自定义机器人，在 server.py 里扩展动作映射
  • 🌐 部署在局域网服务器，结合 HTTPS / WebRTC 远程控制
  • 🧪 接入 CI：在管线中运行 python test_server_no_render.py
  • 🧩 若需额外传感器（IMU/摄像头），可继续扩展 WebSocket 消息格式

如需新增或修改文档，请直接更新本 README，确保所有信息保持同步。祝操控顺利！🎉