Walker S2 EDU 探索者：仿真平台¶
Walker S2 EDU 探索者 仿真基于 NVIDIA Isaac Sim（Isaac Lab 2.2.0）构建，通过 ROS2-ZMQ 桥接将仿真状态与图像以与真机一致的 ROS2 话题对外发布，实现 sim-to-real 一致的遥操作与数据采集。整套环境运行在 Docker 容器内。
快速开始¶
1. 构建环境（宿主机）¶
容器构建流程各机型一致，见 仿真平台 · 容器构建与使用（build / start / init / check / bash）。
⚠️ 构建镜像前必须修改：编辑
ubt_sim/docker/fastdds_no_shm.xml的interfaceWhiteList，将<address>改为192.168.11.99（Walker S2 直连网段）。该文件构建时 COPY 进镜像，构建后再改无效。
2. 启动仿真（容器内）¶
bash run.sh bash # 进入容器（自动 source ROS2 + Walker SDK 环境）
UBT_SIM_TASK=UBTSim-WalkerS2-PickPart-v0 bash /ubt_sim/scripts/start_sim.sh # 启动仿真 + 自动拉起桥接
通过 UBT_SIM_TASK 选择任务场景。
| 任务 ID | 场景 | 说明 |
|---|---|---|
UBTSim-WalkerS2-PartSorting-v0 |
零件分拣 | 4 个零件 + 收纳箱（默认任务） |
UBTSim-WalkerS2-PickPart-v0 |
零件分拣 | 单零件抓取：桌面只保留单个零件，配合 pick_part.py 采集 |
运行效果（抓放任务）：
- 按
R键可复位机器人/场景；也可通过采集脚本--reset-scene发布/sim/cmd_reset。 - 关闭仿真窗口时，
start_sim.sh的退出陷阱会自动停止桥接进程。
常用环境变量/参数（可叠加）：
| 变量 | 作用 | 默认 |
|---|---|---|
UBT_SIM_TASK |
任务名（同时决定机器人类型） | UBTSim-TienkungPro-Parlor-v0，Walker S2 EDU 探索者 见任务场景列表 |
--headless |
无窗口运行 | 无显示器/服务器场景最常用 |
--perf_stats |
打印性能统计 | 排查帧率 |
--device cpu\|cuda\|cuda:N |
运行设备 | 非 load_only 换卡时用 |
3. 数据采集（容器内，使用系统 Python 3.10）¶
# 机器人抓取并录制
/usr/bin/python3 /ubt_sim/teleoperation/control/walker_s2/pick_part.py --save --reset-scene --robot-init
# 批量循环采集（默认 400 次）
bash /ubt_sim/teleoperation/control/walker_s2/save_data.sh
pick_part.py执行一次零件抓放：实时读取/sim/part_states零件位置 -> pregrasp -> 夹取 -> 抬升 -> 放入箱中 -> 归位。--save开启录制：17 维身体关节 + 双手 + 夹爪 + 四路相机 RGB 与时间戳写入 HDF5（默认仅任务成功落盘）。--reset-scene运行时先初始化场景，--robot-init机器人初始位置（前置操作，不写入录制数据）。save_data.sh批量采集脚本：注意需根据不同任务修改内部参数，当前默认单零件 400 次抓取任务。- 产物路径：
/ubt_sim/dataset/walker_s2/<时间戳>/trajectory.hdf5。
详细参数：
| 参数 | 默认 | 说明 |
|---|---|---|
--part <名> |
part_a_red |
零件名（part_a_ori / part_a_red / part_b_blue / part_b_ori） |
--all-parts / --parts <名...> |
- | 依次抓取四个零件 / 自定义抓取顺序 |
--side left\|right |
right |
抓取手臂 |
--reset-scene |
关 | 抓取前发布 /sim/cmd_reset 重置场景 |
--robot-init |
关 | 抓取前移动到 READY_POSE（等价 state --init） |
--randomize-parts / --no-randomize-parts |
开 | 多零件抓取前随机化零件位置 |
--save |
关 | 录制 HDF5（配合 --save-only-success，默认仅任务成功落盘） |
--capture-hz <Hz> |
15.0 |
写入 HDF5 的采集频率 |
--unlock-waist |
关 | 是否解锁腰部 IK |
4. 机器人控制器（容器内，系统 Python 3.10）¶
统一入口 walker_s2_controller.py，可用于真机/仿真场景机器人控制：
# 机器人位置初始化动作（分段移动到 READY_POSE 预备姿态）
/usr/bin/python3 /ubt_sim/teleoperation/control/walker_s2/walker_s2_controller.py --init
# 更多控制通过 --help 查看；子命令完整参数：<子命令> --help
子命令一览：
| 子命令 | 说明 | 常用参数 |
|---|---|---|
state |
关节/夹爪/末端状态、单关节移动、预备姿态、夹爪控制 | --print-state --init --grip-open --move-joint --joint <名> --pos <rad> |
joint |
关节/手部调试 | --print --move JOINT=ANGLE --hand-open --monitor |
endpoint |
末端/TCP 位姿测试 | --no-move --side left |
home |
分段回 home 全零位 + 张开双手 | 无参数 |
analyze |
关节阶跃/正弦响应分析 + CSV | --joint <名> --step <rad> --sine --listen --csv <路径> |
camera |
相机话题信息/预览/保存 | --preview --save --count 5 --topic <话题> |
常用示例：
/usr/bin/python3 walker_s2_controller.py state --print-state # 查看关节/夹爪/末端状态
/usr/bin/python3 walker_s2_controller.py state --init # 分段移动到预备姿态
/usr/bin/python3 walker_s2_controller.py joint --move R_elbow_yaw_joint=0.5 # 单关节移动到 0.5 rad（回车确认）
/usr/bin/python3 walker_s2_controller.py home # 分段回 home 全零位 + 张开双手
/usr/bin/python3 walker_s2_controller.py analyze --joint R_elbow_yaw_joint --step 0.5 # 关节阶跃分析
/usr/bin/python3 walker_s2_controller.py camera --preview # 相机实时预览
相机测试（camera 子命令）¶
Walker S2 EDU 探索者 发布四路相机（头部双目 stereo_left/right + 腕部 wrist_left/right）ZMQ（5657）和 ROS2 话题：
# 实时预览（cv2.imshow，需 X11；SSH 进入容器需 -X 转发，按 Q/ESC 退出）
/usr/bin/python3 /ubt_sim/teleoperation/control/walker_s2/walker_s2_controller.py camera --preview
# 查看/保存四路相机图像
/usr/bin/python3 /ubt_sim/teleoperation/control/walker_s2/walker_s2_controller.py camera --save --count 5
| 参数 | 默认 | 说明 |
|---|---|---|
--topic |
bridge config -> /sensor/camera/stereo/color/raw |
订阅的相机话题 |
--msg-type |
Image2m |
消息类型（Image8k/Image512k/Image1m/Image2m/Image4m/Image6m/Image8m/sensor_msgs/Image） |
--preview |
关 | cv2.imshow 实时预览（按 Q/ESC 退出，需 X11） |
--save |
关 | 保存帧为 PNG（camera_frame_<时间戳>.png） |
--count <N> |
0（无限） |
保存/预览帧数上限，达到即退出 |
--interval <秒> |
1.0 |
打印/保存循环的间隔 |
--no-print |
关 | 不打印帧信息（所有模式生效） |
5. 数据集预览与回放（容器内）¶
读取 dataset/walker_s2/<时间戳>/trajectory.hdf5，预览相机+关节曲线（Rerun），或把录制动作直发回放（仿真/真机同话题）。
# 预览 HDF5 数据集
/usr/bin/python3 /ubt_sim/teleoperation/tools/playback_walker_s2.py \
--episode dataset/walker_s2/1786681892 --mode preview --web-port 9090
# 动作回放（仿真/真机）
/usr/bin/python3 /ubt_sim/teleoperation/tools/playback_walker_s2.py \
--episode dataset/walker_s2/1786681892 --mode control
完整参数与安全须知见 数据可视化与回放。
仿真模块¶
| 模块 | 路径 | 说明 |
|---|---|---|
| Docker 编排 | ubt_sim/docker/run.sh |
镜像构建、容器生命周期、桥接启停 |
| 环境变量 | ubt_sim/docker/env.sh |
容器名、镜像、ROS_DOMAIN_ID |
| 仿真启动器 | ubt_sim/scripts/start_sim.sh |
按 UBT_SIM_TASK 识别机器人、拉起桥接 |
| 任务定义 | ubt_sim/source/ubt_sim/task/walker_*/ |
Walker S2 EDU 探索者 场景定义 |
| 仿真配置 | ubt_sim/config/walker_s2/ |
part_sorting.yaml / pick-part.yaml / parlor.yaml |
| ROS2-ZMQ 桥接 | ubt_sim/teleoperation/bridges/walker_s2/ |
桥接脚本 + walker_s2_bridge_config.yaml |
| 遥操作与采集 | ubt_sim/teleoperation/control/walker_s2/ |
walker_s2_controller.py / pick_part.py / carry_box.py / keyboard_ee_control.py / save_data.sh |
| 数据输出 | ubt_sim/dataset/walker_s2/<时间戳>/trajectory.hdf5 |
采集产物 |
Walker S2 EDU 探索者 特殊说明¶
GPU 渲染 + CPU PhysX¶
Walker S2 EDU 探索者 默认采用 GPU 渲染 + CPU PhysX 架构：start_sim.sh / sim_runner.py 将渲染/AppLauncher 设备设为 cuda:0，但 Isaac Lab physics/env 设备设为 cpu。这是为了规避 Isaac Sim 5.0 + Isaac Lab 2.2 在 Walker S2 EDU 探索者 articulation 初始化时 get_dof_velocities() 触发的 PhysX GPU tensor device mismatch。不要默认改回 GPU physics；如需实验可显式设置 UBT_SIM_WALKER_S2_PHYSICS_DEVICE=cuda:0。
Walker SDK ROS2 消息包¶
桥接与采集脚本依赖 Walker SDK ROS2 消息（rosa_msgs / shm_msgs / mc_task_msgs / mc_state_msgs / ecat_task_msgs），由 bash run.sh init 构建到 /opt/ubt_sim/walker_sdk_ros2_msgs/install，run.sh bash 进入容器时自动 source。DDS 中间件使用 rmw_cyclonedds_cpp。
故障排查¶
bash run.sh check报错：按提示重跑bash run.sh init；确认numpy<2、bodyctrl_msgs、Walker SDK ROS2 消息包均已就绪。- 采集脚本报 rclpy / 消息类型导入失败：确认用的是
/usr/bin/python3而非 Isaac Sim Python；确认已bash run.sh init构建消息包。 save_data.sh连续失败熔断：多为桥接未就绪。先确认仿真窗口在运行、桥接进程存在（pgrep -f walker_s2_ros2_zmq_bridge），或单独bash run.sh bridge-start。- 仿真启动报 Walker SDK messages not built：容器内执行
cd /ubt_sim/docker && bash run.sh init。 - X11 不可用 / 仿真窗口不显示：宿主机执行
xhost +，确认DISPLAY已透传；无显示器时仅可用UBT_SIM_LOAD_ONLY=1预览。 - 键盘遥操作无法捕获键鼠：headless 容器内无法使用 pynput，请在宿主机（有图形界面）执行
keyboard_ee_control.py。
采集完成后进入下一步：模仿学习平台。