VLA/TURTLE2_STARTUP.md

# Wall-X + Turtle2 启动命令

本页对应 checkpoint `/home/xiehaolv/huanghuagui/wall-x-model/finetuned/1`。推流端和桥接端运行在推理服务器上，机器人端运行在 `arm-pc` 上。更换数据集或训练配置时，先按 [重训与部署迁移流程](TURTLE2_RETRAIN_DEPLOYMENT.md) 核对配置，再更新本页命令。

相机对应关系：机器人 camera1/`camera_left` = 左臂固定视角 → `left_wrist_view`；camera2/`camera_front` = 面部视角 → `face_view`；camera3/`camera_right` = 右臂视角 → `right_wrist_view`。当前模型只输出右臂动作，桥接端保持左臂不动，并对底盘发送相对零位移。

## 1. Wall-X 推流服务端

如果 `32196` 端口上还没有 serving 服务，在推理服务器终端执行：

```bash
cd /home/xiehaolv/huanghuagui/zhanyifeng/wall-x

PYTHON_BIN=/home/xiehaolv/huanghuagui/conda-envs/wallox_0.5/bin/python \
bash scripts/run_serving.sh \
  --checkpoint-path /home/xiehaolv/huanghuagui/wall-x-model/finetuned/19 \
  --train-config-path /home/xiehaolv/huanghuagui/wall-x-model/finetuned/19/config.yml \
  --port 32196 \
  --cuda-id 1 \
  --env X2ROBOT \
  --robot-type turtle \
  --serialize-actions \
  --action-horizon 32 \
  --robot-action-interpolate-multiplier 1 \
  --robot-action-end-ratio 1.0 \
  --model-device cuda \
  -- \
  --model-config.cam-names face_view left_wrist_view right_wrist_view \
  --model-config.norm-key pick_paper_lerobot_v21_3cam
```

该命令使用 checkpoint `/home/xiehaolv/huanghuagui/wall-x-model/finetuned/1` 的训练配置：三路相机最长边均为 448，动作长度 32，右臂相对位置 + 相对 6D 旋转 + 夹爪，后接 16 维虚拟填充。服务端会使用 checkpoint 内的两份 26 维 `.pth` 归一化文件。`run_serving.sh` 会在载入模型前核对命令里的动作长度与 `config.yml`，不一致会直接退出。

新 checkpoint 尚未携带训练时的 `lora_config.json`，因此加载日志会提示暂用旧系数 `alpha/r=2`。这不妨碍服务启动，但在真机执行前，应核对训练时使用的 LoRA JSON 是否为 `lora_r=16`、`lora_alpha=32` 且未启用 `use_rslora`；如不同，复制原始 JSON 到 checkpoint 目录并命名为 `lora_config.json`，加载器会自动按该文件计算系数。不要用部署仓库里的同名示例文件冒充训练原件。

## 2. TCP/WebSocket 桥接端

第一次先进行不发送动作的推理与协议检查：

```bash
cd /home/xiehaolv/huanghuagui/zhanyifeng/wall-x

/home/xiehaolv/huanghuagui/conda-envs/wallox_0.5/bin/python \
  scripts/tcp_ws_bridge.py \
  --ws-url ws://127.0.0.1:32196 \
  --tcp-port 30124 \
  --instruction "pick up the paper towel" \
  --action-horizon 32 \
  --fixed-lift 0.1 \
  --action-end-ratio 0.2 \
  --action-interpolate-multiplier 32 \
  --max-position-delta 0.005 \
  --max-rotation-delta 0.0125 \
  --clip-action-delta \
  --max-action-cycles 1 \
  --require-right-feedback
```
/home/xiehaolv/huanghuagui/conda-envs/wallox_0.5/bin/python \
  scripts/tcp_ws_bridge.py \
  --ws-url ws://127.0.0.1:32196 \
  --tcp-port 30124 \
  --instruction "pick up the paper" \
  --action-horizon 32 \
  --fixed-lift 0.3 \
  --action-end-ratio 0.7 \
  --action-interpolate-multiplier 6 \
  --max-position-delta 2 \
  --max-rotation-delta 2 \
  --clip-action-delta \
  --max-action-cycles 0 \
  --require-right-feedback \
  --allow-send







 --action-horizon 32 \
  --fixed-lift 0.1 \
  --require-right-feedback \
  --max-position-delta 0.010 \
  --max-rotation-delta 0.0250 \
  --clip-action-delta \
  --max-action-cycles 0 \
  --allow-send



`--clip-action-delta` 会保持模型轨迹形状，并把整个推理动作包相对当前机械臂位姿的最大变化限制在上述范围。它不会再把每个采样点分别累加成固定步长斜坡。

上述命令不带 `--allow-send`，只检查三路图像、推理返回、32 步序列和 `follow2_pos` 解析，不发送动作包。`--fixed-lift 0.1` 会把升降柱目标设为 0.1 米；若当前高度不是 0.1 米，在真机试验前确认这项高度变化可执行。底盘默认发送相对零位移 `[0, 0, 0]`。

先确认 serving 日志出现 LoRA 合并、`load_state_dict result: <All keys matched successfully>`；桥接日志出现 `predicted follow2 T=192`，并检查右臂第一点、末点及夹爪数值。若报 `Image features and image tokens do not match`，不要发送动作，检查三路图像尺寸与当前推理预处理代码。若只有 `predict_action` 而没有 `follow2_pos`，检查 serving 是否带 `--serialize-actions`，桥接端会拒绝未序列化动作。

确认以上结果和现场状态后，**停止 dry-run 桥接端**，用完全相同的命令重新启动，并在最后一行改为：

```bash
  --require-right-feedback \
  --allow-send
```

保持 `--max-action-cycles 1`，仅发送一个动作包。机器人端需由现场人员确认空域、夹爪和升降柱状态后启动。执行完检查 `/follow2_pos_back` 与 `/joint_information2` 的右臂反馈，再考虑连续运行。

确认一次动作后 `/follow2_pos_back` 与 `/joint_information2` 都产生了相应的小变化，且右臂末端和夹爪动作方向符合任务，再把 `--max-action-cycles 1` 改为 `--max-action-cycles 0` 并重启桥接端，进入连续推理。`0` 表示连接内动作包数量不限，**并不是重抓次数上限**。

不要添加 `--allow-base-motion`。默认情况下桥接端发送相对零位移，禁止模型动作驱动底盘。

连续运行时桥接端使用以下参数（单包命令中的其余参数保持不变）：

```bash
  --action-horizon 32 \
  --fixed-lift 0.1 \  --max-position-delta 0.005 \
  --max-rotation-delta 0.0125 \
  --clip-action-delta \
  --max-action-cycles 0 \
  --allow-send
```

## 3. Turtle2 机器人端

在 `arm-pc` 上执行：

```bash
source /opt/ros/noetic/setup.bash
source /home/arm/prj/turtle2/modules/devel/setup.bash

export PYTHONPATH=/home/arm/prj/turtle2/modules/src/turtlesys/turtle_monitor/scripts:$PYTHONPATH

infer 172.25.5.237 30124
```

## 模式选择

- 单包 dry-run 时，在推理模式提示输入 `2`；桥接端不带 `--allow-send`，因此不执行机械臂动作。完成解析检查后，停止旧桥接端并带 `--allow-send` 重复单包测试。
- 当前 checkpoint 只训练右臂。桥接默认保持左臂的当前位姿；不要添加 `--allow-left-arm-motion`。
- 单包实机验证建议增加 `--require-right-feedback`。若下一个机器人状态中右臂末端反馈没有变化，桥接会在发送下一包前停止，并提示检查 `/follow_pos_cmd_2`、`/follow2_pos_back`、`/joint_information2` 与右臂控制器。
- 连续推理时输入 `1`，同时桥接端必须使用 `--max-action-cycles 0`。机器人端仍会调用底盘 pose 分支，但桥接端发送的是相对零位移，因此会看到 `exec car pose [0.0, 0.0, 0.0]` 日志。
- `mode1: 0`、`mode2: 0` 是现有机器人脚本固定填写的字段；R5 末端控制回调不使用它们，不是机械臂停止的原因。
- 桥接端每次打印 `recv state`、`predicted ... T=<插值后长度>`、`sent action back`，表示完成了一次动作包；32 步动作按默认旧版节奏在 `--action-end-ratio 0.2`、`--action-interpolate-multiplier 32` 下通常会扩展为约192个点，具体以日志为准。`Robot closed the connection` 表示机器人端或桥接端已退出，不是推理失败。
- `--clip-action-delta` 目前只限制右臂位置和姿态，不限制夹爪。日志中若出现 `gripper` 大幅跳变（例如 `0.8` 或 `-0.8`），先确认夹爪动作范围和现场安全，再继续执行抓取任务。
- `--require-right-feedback` 只检查右臂末端是否按上一包发生运动，不检测物品滑脱或抓取成功。
- `/head/control unavailable` 是头部服务缺失产生的独立错误；它不会改变右臂末端控制，但会造成高频日志。

## 验证要求（checkpoint `/home/xiehaolv/huanghuagui/wall-x-model/finetuned/1`）

- 先用不带 `--allow-send` 的命令确认 serving 日志出现 LoRA 合并、`All keys matched successfully`，桥接日志出现 `predicted follow2 T=192`。现在的 checkpoint 如出现 `LoRA scale metadata is missing` 警告，按上文核对训练时的原始 LoRA JSON 后再做真机试验。
- 单包实机验证只在机器人端预览确认后增加 `--allow-send`，并保持 `--max-action-cycles 1`。
- 确认 `/follow2_pos_back` 与 `/joint_information2` 的右臂反馈发生变化后，再改为 `--max-action-cycles 0` 连续执行。

本次服务器侧已验证：checkpoint 能在 GPU 1 上加载；三路 640×480 合成图像的推理返回 33 行 `follow2_pos`，桥接端解析为 192 点；三路 448×448 合成图像的完整图像 token 也通过回归测试。以上输入均为合成观测，不能证明真实相机映射、模型抓取效果或真机动作方向。

## 端口和停止

- Wall-X serving：`32196`
- TCP 桥接端：`30124`
- 机器人连接地址：`172.25.5.237:30124`
- 停止服务：在对应终端按 `Ctrl+C`，建议先停止机器人端，再停止桥接端和推流端。