# 天工 3.0 同构臂遥操与数采跨设备迁移手册

适用范围：天工 3.0、HBWALK、TS1P 同构臂、BrainCo Revo2 双手、EAI 本地
OmniSocket Hub，以及 PS 主机保存数采数据的当前方案。

本文按“换机器人、换 EAI 工控机、换 PS 主机、全部更换”分别说明。更底层的公网 Hub、
纯 ZMQ 备选和协议证据见
[`天工3.0本地同构臂遥操迁移部署指南.md`](天工3.0本地同构臂遥操迁移部署指南.md)。

## 1. 当前系统基线

迁移前先记录实际提交，不要只记录文件夹名称：

```bash
cd ~/Desktop/TG3_TS1P_OmniSocket_Teleop
git rev-parse HEAD
git status --short
```

本文编写时的功能基线为：

```text
TG3 项目：67c9b657688680c686f55b3f868bbc310edbfd41
OmniSocketGo：de3f5c96779dbe1571c10feb22fc7f2331b6b222
TG3 仓库：https://gitea.public.snrc.site/meiqi/TG3.git
OmniSocketGo：https://gitea.public.snrc.site/limingjie/OmniSocketGo.git
```

迁移时应优先使用 `main` 上更新且已经过现场验收的提交，并把最终提交号写入设备档案。

### 1.1 当前链路

```text
EAI 工控机
  xTELE tcp://127.0.0.1:5003（原始双臂、按钮、摇杆、扳机）
       + tcp://127.0.0.1:5001（处理后的手势目标）
  -> tg3-omnisocket-sender.service
  -> 本机 tg3-omnisocket-hub.service，UDP 0.0.0.0:14049
  -> 局域网 192.168.5.14:14049

机器人 Nvidia
  tg3-local-teleop.service
  -> 双臂、BrainCo 双手、/hric/robot/cmd_vel
  -> tg3-data-recorder.service 临时录制 MCAP

PS 主机
  tg3-data-get-sync.service
  -> SSH/rsync 从 Nvidia 拉取 READY episode
  -> SHA-256 + fsync + VERIFIED
  -> Data_Get/<episode>/
  -> 验真后精确删除 Nvidia 对应临时副本
```

EAI 不保存数采数据。Nvidia 在录制和等待 PS 同步期间必须临时落盘；最终持久副本只保留在
PS 主机。PS 离线时，机器人会保留尚未验真的 `ready/`，恢复连接后再同步和回收。

### 1.2 当前地址与标识

| 用途 | 当前值 | 变化时修改位置 |
|---|---|---|
| EAI 运维 SSH | SSH 别名 `eai` | PS 的 SSH 配置和运维命令 |
| EAI 控制局域网 IP | `192.168.5.14` | 机器人 `config.toml` 的 `omnisocket_server`；ZMQ 回退时还改 `iarm_endpoint` |
| 机器人控制局域网 IP | `192.168.5.15` | 通常只影响 EAI 防火墙规则 |
| 机器人 Nvidia SSH | `nvidia@192.168.41.2` | PS 同步 unit 的 `--remote` 和运维命令 |
| 机器人 Ubuntu SSH | `ubuntu@192.168.41.1` | 仅厂家运维；本项目不部署到 Ubuntu |
| 本地 Hub | EAI UDP `14049` | EAI Hub、EAI sender、机器人 `omnisocket_server` 和防火墙同时修改 |
| EAI Peer | `tg3-009027fa8190-iarm` | EAI `--peer-id` 与机器人 `omnisocket_expected_sender` 同时修改 |
| 机器人 Peer | `tg3-009027fa8190-robot` | EAI `--target-peer` 与机器人 `omnisocket_peer_id` 同时修改 |
| TS1P ID | `IArm009027FA8190` | 更换同构臂时修改机器人 `expected_iarm_id` |
| 本机数据目录 | `~/Desktop/TG3_TS1P_OmniSocket_Teleop/Data_Get` | PS 同步 unit 的 `WorkingDirectory`、脚本和 `--destination` |

不要把机器人内部厂家链路 `192.168.41.1/192.168.41.2` 与 EAI—机器人控制局域网
`192.168.5.0/24` 混为一谈，也不要把 EAI 本机的 `127.0.0.1:5001/5003` 改成网卡地址。

## 2. 三台设备分别需要哪些文件

### 2.1 PS 主机

必须保留：

```text
TG3_TS1P_OmniSocket_Teleop/
  tg3_omnisocket_transport/   # 用于部署 EAI
  tg3_local_teleop/           # 用于部署机器人
  tg3_data_collection/        # PS 同步程序
  Data_Get/                   # 唯一持久数采目录，不进入 Git
  docs/
  verify.sh

~/.config/systemd/user/tg3-data-get-sync.service
~/.ssh/known_hosts
~/.ssh/config                  # 如果使用 eai 等别名
```

`Data_Get` 必须单独迁移，Git clone 不会带回 MCAP。SSH 私钥也不应提交到仓库，应在新主机
重新生成并使用 `ssh-copy-id` 登记。

### 2.2 EAI 工控机

必须具备：

```text
原厂 xTELE 与 TS1P 标定配置             # 不在本仓库
/home/eai/OmniSocketGo/                 # 固定提交，目标机原生编译
/home/eai/tg3_omnisocket_transport/
~/.config/systemd/user/tg3-omnisocket-hub.service
~/.config/systemd/user/tg3-omnisocket-sender.service
```

不要从旧 EAI 复制 Python 扩展 `.so` 到不同架构或不同 Python ABI 的新机器。不要把旧串口
路径、CAN 配置和关节偏置盲目用于另一套 TS1P。

### 2.3 机器人 Nvidia

必须具备：

```text
/home/nvidia/OmniSocketGo/              # 固定提交，aarch64 原生编译
/home/nvidia/tg3_local_teleop/          # 整个目录
~/.config/systemd/user/tg3-local-teleop.service
~/.config/systemd/user/tg3-data-recorder.service
/home/nvidia/tg3_data_collection/       # 运行时临时目录，由程序创建
```

不要把旧机器人的 `status.json`、`__pycache__`、ROS `build/install/log` 或编译好的
OmniSocket `.so` 当成部署文件。`ros2_py` 必须在新机器人重新构建。

### 2.4 机器人 Ubuntu

本项目不向 Ubuntu 安装文件，不修改厂家 `record_bag_node`、`proc_manager`、FSM 或
HBWALK 服务。迁移后仍由操作者按厂家流程切换到 HBWALK；本项目不发布 `gotoHBWALK`。

## 3. 迁移前的统一停机与备份

1. 松开所有按键和摇杆，长按 Z+C 3 秒退出遥操；
2. 等待 Home 流程结束，确认机器人 `armed=false`；
3. 若正在数采，等待本机出现完整 episode；
4. 确认同步状态为 `idle` 且 `pending_remote_cleanup=0`；
5. 停止旧 PS 的同步服务，防止两台 PS 同时拉取和回收同一个 episode；
6. 记录当前配置、提交号、设备 ID 和服务文件。

检查命令：

```bash
ssh nvidia@192.168.41.2 \
  'python3 -m json.tool /home/nvidia/tg3_local_teleop/status.json | head -80'

python3 -m json.tool \
  ~/Desktop/TG3_TS1P_OmniSocket_Teleop/Data_Get/sync_status.json

systemctl --user stop tg3-data-get-sync.service
```

至少备份以下内容：

```bash
mkdir -p ~/tg3_migration_backup

scp nvidia@192.168.41.2:/home/nvidia/tg3_local_teleop/config.toml \
  ~/tg3_migration_backup/robot-config.toml

scp eai:/home/eai/.config/systemd/user/tg3-omnisocket-sender.service \
  ~/tg3_migration_backup/eai-sender.service

scp eai:/home/eai/.config/systemd/user/tg3-omnisocket-hub.service \
  ~/tg3_migration_backup/eai-hub.service

cp ~/.config/systemd/user/tg3-data-get-sync.service \
  ~/tg3_migration_backup/ps-sync.service
```

把 `Data_Get` 复制到新磁盘或新主机时，先停同步服务，再执行：

```bash
rsync -aH --info=progress2 \
  ~/Desktop/TG3_TS1P_OmniSocket_Teleop/Data_Get/ \
  <新主机>:/home/<新用户>/Desktop/TG3_TS1P_OmniSocket_Teleop/Data_Get/
```

在新主机验证前保留旧主机副本。若状态仍为 `delete_pending`，先在旧主机完成同步回收，不要
带着未决收据更换机器人地址。

## 4. 场景一：只更换 PS 主机

PS 不在实时控制链路中，因此更换 PS IP 不需要修改 EAI sender、Hub Peer 或机器人
`config.toml`。需要迁移的是代码、`Data_Get`、SSH 信任和同步服务。

### 4.1 安装代码与依赖

```bash
sudo apt update
sudo apt install -y git rsync python3

git clone https://gitea.public.snrc.site/meiqi/TG3.git \
  ~/Desktop/TG3_TS1P_OmniSocket_Teleop

cd ~/Desktop/TG3_TS1P_OmniSocket_Teleop
git checkout main
./verify.sh
```

如果迁移时使用的现场提交尚未推到 Gitea，应从旧 PS 用 `rsync` 复制完整仓库；不要只 clone
一个落后的远端版本。

### 4.2 建立到新机器人的 SSH 信任

```bash
ssh-keygen -t ed25519
ssh-copy-id nvidia@<新机器人SSH地址>
ssh nvidia@<新机器人SSH地址> true
```

首次 SSH 时应人工核对主机指纹。同步器使用 `StrictHostKeyChecking=yes`，不要为了省事关闭
主机密钥检查。机器人更换后应删除旧地址的错误 host key，再登记新机器人的真实指纹。

### 4.3 安装本机同步服务

先确认机器人已经部署：

```text
/home/nvidia/tg3_local_teleop/delete_ready_episode.py
```

然后修改仓库中的 `tg3_data_collection/tg3-data-get-sync.service`：

- `WorkingDirectory` 改成新 PS 的真实项目目录；
- `ExecStart` 中脚本路径和 `--destination` 改成新目录；
- `--remote` 改成新机器人 Nvidia SSH 地址；
- 保留 `--delete-remote-after-sync`；
- 保留远端固定根 `/home/nvidia/tg3_data_collection/ready`。

安装并**显式 restart**，仅执行 `enable --now` 不会替换已经运行的旧进程：

```bash
mkdir -p ~/.config/systemd/user
cp tg3_data_collection/tg3-data-get-sync.service \
  ~/.config/systemd/user/tg3-data-get-sync.service
systemctl --user daemon-reload
systemctl --user enable tg3-data-get-sync.service
systemctl --user restart tg3-data-get-sync.service
systemctl --user show tg3-data-get-sync.service -p ExecStart -p ActiveState
```

验收：

```bash
python3 -m json.tool Data_Get/sync_status.json
```

必须看到 `state=idle`、`last_error=""`、`pending_remote_cleanup=0`。确认新服务正常后，旧 PS
同步服务保持停用；不能让两台主机同时运行自动删除模式。

## 5. 场景二：只更换 EAI 工控机

机器人、PS 和 Home 均可保留，但必须先把原厂 xTELE 与 TS1P 在新 EAI 上独立调通。

### 5.1 先验收原厂 xTELE

```bash
ss -lntp | grep -E ':(5001|5003)[[:space:]]'
```

必须同时看到本机 TCP 5003 和 5001。可用下面的只读命令读取一个 5003 帧并记录同构臂
身份：

```bash
python3 - <<'PY'
import json, zmq
ctx = zmq.Context.instance()
s = ctx.socket(zmq.SUB)
s.setsockopt(zmq.SUBSCRIBE, b"")
s.setsockopt(zmq.CONFLATE, 1)
s.connect("tcp://127.0.0.1:5003")
d = json.loads(s.recv().decode())
print(d.get("isomorphic_arm_id"), d.get("isomorphic_arm_type"))
PY
```

输出的 ID 必须写入机器人 `config.toml` 的 `expected_iarm_id`。类型应为 `TS1P`。如果串口、
CAN、方向、偏置或频率不正常，不要启动本项目 sender。

### 5.2 在新 EAI 原生构建 OmniSocketGo

```bash
sudo apt update
sudo apt install -y git build-essential python3-dev python3-pip
python3 -m pip install --user pyzmq

git clone https://gitea.public.snrc.site/limingjie/OmniSocketGo.git \
  /home/eai/OmniSocketGo
git -C /home/eai/OmniSocketGo checkout \
  de3f5c96779dbe1571c10feb22fc7f2331b6b222
make -C /home/eai/OmniSocketGo python-ext bin/kcpserver

PYTHONPATH=/home/eai/OmniSocketGo/python python3 -c \
  'from omnisocket import Session; print(Session)'
```

若新用户名不是 `eai`，把所有 `/home/eai` 改成实际绝对路径。服务模板和 Python 扩展必须
使用同一个用户环境。

### 5.3 部署 sender 和本地 Hub

在 PS 执行：

```bash
rsync -av --exclude=__pycache__ \
  ~/Desktop/TG3_TS1P_OmniSocket_Teleop/tg3_omnisocket_transport/ \
  eai@<新EAI地址>:/home/eai/tg3_omnisocket_transport/
```

新 EAI 上修改两个 unit：

```text
tg3-omnisocket-hub.service
  ExecStart=.../kcpserver -mode hub -listen 0.0.0.0:14049

tg3-omnisocket-sender.service
  --server 127.0.0.1:14049
  --peer-id tg3-<机器人编号>-iarm
  --target-peer tg3-<机器人编号>-robot
  --zmq-endpoint tcp://127.0.0.1:5003
  --cmd-zmq-endpoint tcp://127.0.0.1:5001
```

Peer 等式必须成立：

```text
EAI --peer-id       == 机器人 omnisocket_expected_sender
EAI --target-peer   == 机器人 omnisocket_peer_id
```

安装服务：

```bash
mkdir -p ~/.config/systemd/user
cp /home/eai/tg3_omnisocket_transport/tg3-omnisocket-hub.service \
  ~/.config/systemd/user/
cp /home/eai/tg3_omnisocket_transport/tg3-omnisocket-sender.service \
  ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now tg3-omnisocket-hub.service
systemctl --user enable --now tg3-omnisocket-sender.service
sudo loginctl enable-linger eai
```

EAI 控制局域网 IP 变化后，在机器人修改：

```toml
[network]
omnisocket_server = "<新EAI局域网IP>:14049"
iarm_endpoint = "tcp://<新EAI局域网IP>:5003" # 仅保留作 ZMQ 回退
```

KCP 使用 UDP 14049，不是 TCP。防火墙只允许机器人控制局域网 IP 访问该 UDP 端口。修改后
重启机器人 `tg3-local-teleop.service`。

### 5.4 EAI 验收

```bash
systemctl --user is-active \
  tg3-omnisocket-hub.service tg3-omnisocket-sender.service
ss -lunp | grep ':14049'
python3 -m json.tool /home/eai/tg3_omnisocket_transport/status.json
```

待机时应看到：

- `frames_received` 持续增长；
- `teleop_active=false`；
- `connected=0`；
- `frames_sent` 不增长；
- `last_error` 为空。

Hub 未启动时长按 Z+C 只消费本次请求，不会在 Hub 恢复后自行启动。必须稳定松开至少
0.5 秒，再重新长按 3 秒。

## 6. 场景三：只更换机器人

这是风险最高的单项迁移。旧机器人的 Home、手部校准和编译产物不能直接当成新机器人的
实测配置。

### 6.1 新机器人前置条件

确认：

```bash
uname -m
test -f /opt/ros/jazzy/setup.bash
test -f /home/nvidia/xos/setup.bash
test -f /opt/robot_tele_server/install/setup.bash
ros2 topic type /hric/robot/rl_state
ros2 topic type /freq_change/arm_status
ros2 topic type /encoder_identical_joint
ros2 topic type /hric/robot/cmd_vel
```

目标应仍为天工 3.0、14 维双臂，并提供当前项目使用的 Topic。若型号、SDK 或消息类型不同，
先适配代码，不能只改 IP。

确认灵巧手：

```bash
grep -E 'left_hand_type|right_hand_type' \
  /home/nvidia/data/param/hand_driver.yaml
```

只有左右均为 BrainCo 时才能直接启用现有 `[hands]`。因时手或其他型号必须单独适配消息和
映射。

### 6.2 在新机器人原生构建 OmniSocketGo

在 PS 执行，复制源码但排除其他架构的二进制：

```bash
ssh nvidia@<新机器人SSH地址> 'mkdir -p /home/nvidia/OmniSocketGo'

rsync -av \
  --exclude=.git \
  --exclude=bin \
  --exclude=python/build \
  --exclude='python/omnisocket/_omnisocket*.so' \
  ~/Desktop/OmniSocketGo/ \
  nvidia@<新机器人SSH地址>:/home/nvidia/OmniSocketGo/

ssh nvidia@<新机器人SSH地址> \
  'cd /home/nvidia/OmniSocketGo && make python-ext'

ssh nvidia@<新机器人SSH地址> \
  'PYTHONPATH=/home/nvidia/OmniSocketGo/python python3 -c \
  "from omnisocket import Session; print(Session)"'
```

EAI 的 x86_64 `.so` 不能复制给 aarch64 机器人。

### 6.3 部署机器人项目并构建消息 overlay

```bash
rsync -av \
  --exclude=__pycache__ \
  --exclude=status.json \
  --exclude=ros2_py/build \
  --exclude=ros2_py/install \
  --exclude=ros2_py/log \
  ~/Desktop/TG3_TS1P_OmniSocket_Teleop/tg3_local_teleop/ \
  nvidia@<新机器人SSH地址>:/home/nvidia/tg3_local_teleop/

ssh nvidia@<新机器人SSH地址> 'bash -lc '\''
  source /opt/ros/jazzy/setup.bash
  cd /home/nvidia/tg3_local_teleop/ros2_py
  colcon build --symlink-install --packages-select ros2_bridge_msgs
'\''
```

录制器还需要 `python3-yaml` 和 `rsync`：

```bash
ssh nvidia@<新机器人SSH地址> \
  'sudo apt install -y python3-yaml rsync'
```

### 6.4 修改新机器人专属配置

先不要安装或启动 publish-capable service。编辑：

```text
/home/nvidia/tg3_local_teleop/config.toml
```

至少修改或重新确认：

```toml
[network]
transport = "omnisocket"
omnisocket_server = "<EAI局域网IP>:14049"
omnisocket_peer_id = "tg3-<新机器人编号>-robot"
omnisocket_expected_sender = "tg3-<新机器人编号>-iarm"
expected_iarm_id = "<实际TS1P ID>"
expected_iarm_type = "TS1P"

[home]
joint_goal_rad = [<新机器人实测的14个弧度值>]
```

还要核对：

- `[hands].open_normalized` 与新 BrainCo 手的实测打开位；
- `[hands].closed_normalized` 和单食指姿态；
- `[control]` 关节限位是否仍对应当前型号和 SDK；
- `[locomotion]` 的 Topic、方向和厂家速度上限；
- `base_directory` 是否仍是 `/home/nvidia/tg3_data_collection`；
- 相机 Topic 是否仍为 `/ob_camera_head/...` 和 `/ob_camera_waist/...`。

### 6.5 新机器人必须重新采集 Home

当前仓库的 Home 是旧机器人实测姿态，不是“型号统一零位”。先用厂家认可方法把新机器人
双臂移动到希望保存的安全 Home，然后以 monitor-only 方式运行桥，不带
`--allow-publish`：

```bash
ssh nvidia@<新机器人SSH地址>
cd /home/nvidia/tg3_local_teleop
timeout 15 ./run.sh || true

python3 -c 'import json; p="/home/nvidia/tg3_local_teleop/status.json"; \
print(json.load(open(p))["robot_arm_position_rad"])'
```

把输出的 14 个弧度值写入 `[home].joint_goal_rad`。在防护、净空和急停有效的前提下，首次
只做低速 Home 验证。Home 未确认前不要启用正式遥操服务。

### 6.6 配对 Peer 并安装服务

在 EAI sender unit 中把 `--target-peer` 改成新机器人 Peer；如果 EAI Peer 也改名，机器人
`omnisocket_expected_sender` 必须同步修改。

在机器人安装：

```bash
mkdir -p ~/.config/systemd/user
cp /home/nvidia/tg3_local_teleop/tg3-local-teleop.service \
  ~/.config/systemd/user/
cp /home/nvidia/tg3_local_teleop/tg3-data-recorder.service \
  ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable tg3-data-recorder.service tg3-local-teleop.service
systemctl --user restart tg3-data-recorder.service
systemctl --user restart tg3-local-teleop.service
```

在新机器人启用自动回收所需 helper 已包含在 `tg3_local_teleop/` 中：

```text
/home/nvidia/tg3_local_teleop/delete_ready_episode.py
```

最后在 PS 修改 `tg3-data-get-sync.service` 的 `--remote`，重新登记 SSH host key，并显式
restart 本机同步服务。

## 7. 场景四：机器人、EAI 和 PS 全部更换

按以下顺序，不要同时边改边做运动测试：

1. 在旧系统退出遥操和数采，等待同步 `idle/pending=0`；
2. 备份 Git 工作树、Data_Get、机器人 config 和三个用户服务；
3. 部署新 PS，但暂不启动同步服务；
4. 在新 EAI 完成原厂 xTELE/TS1P 标定，确认 5003/5001；
5. 在新 EAI 原生编译 OmniSocket，启动本地 Hub；
6. 在新机器人原生编译 OmniSocket 和 ROS 消息 overlay；
7. 生成全新 Peer 对，设置新 TS1P ID；
8. 以 monitor-only 模式确认机器人 ROS 状态和新 Home；
9. 启动机器人 recorder、机器人 bridge，再启动 EAI sender；
10. 在新 PS 登记机器人 SSH key，启动同步服务；
11. 先做无运动链路验收，再按第 9 节逐级做实机验收；
12. 验收全部通过后再退役旧设备，旧 Data_Get 至少保留一份只读备份。

## 8. 修改项速查表

| 发生变化 | 必须修改 |
|---|---|
| 只换 PS IP | 实时控制无需修改；检查 PS 到 Nvidia SSH 可达 |
| PS 用户名或项目路径变化 | PS 同步 unit 的 `WorkingDirectory`、脚本路径、`--destination` |
| Nvidia SSH IP 变化 | PS 同步 unit 的 `--remote`、SSH host key 和运维命令 |
| EAI SSH IP 变化 | 仅 PS SSH 配置/运维命令；控制配置取决于 EAI 局域网 IP 是否变化 |
| EAI 控制局域网 IP 变化 | 机器人 `omnisocket_server`；防火墙；保留的 `iarm_endpoint` |
| Hub UDP 端口变化 | EAI Hub listen、EAI sender `--server`、机器人 `omnisocket_server`、防火墙 |
| 换机器人 | Robot Peer、EAI target Peer、新 Home、手型/端点、PS `--remote` |
| 换 TS1P | EAI 原厂标定、EAI Peer、机器人 `expected_iarm_id`，必要时方向和按键复核 |
| 换灵巧手型号 | 必须改代码和消息映射；不能只换 Topic 字符串 |
| 相机未安装或未启动 | 不阻塞数采；manifest 标记 `absent` |
| 头/腰相机启动 | 下一条数采自动包含对应压缩 RGB-D，并记录质量状态 |

## 9. 统一启动顺序与现场验收

### 9.1 启动顺序

确认机器人未武装后：

```bash
# 1. EAI 本地 Hub
ssh eai 'systemctl --user restart tg3-omnisocket-hub.service'

# 2. 机器人 recorder 和 bridge
ssh nvidia@<机器人SSH地址> \
  'systemctl --user restart tg3-data-recorder.service tg3-local-teleop.service'

# 3. EAI sender
ssh eai 'systemctl --user restart tg3-omnisocket-sender.service'

# 4. PS 数据同步
systemctl --user restart tg3-data-get-sync.service
```

### 9.2 无运动验收

```bash
cd ~/Desktop/TG3_TS1P_OmniSocket_Teleop
./verify.sh

ssh eai 'systemctl --user is-active \
  tg3-omnisocket-hub.service tg3-omnisocket-sender.service'

ssh nvidia@<机器人SSH地址> \
  'systemctl --user is-active tg3-data-recorder.service tg3-local-teleop.service'

ssh nvidia@<机器人SSH地址> \
  'python3 -m json.tool /home/nvidia/tg3_local_teleop/status.json | head -120'

python3 -m json.tool Data_Get/sync_status.json
```

必须确认：

- 机器人处于 `HBWALK/HBWALK/running`，但 `armed=false`；
- 14 个手臂反馈错误码为 0；
- 左右手反馈存在且型号正确；
- OmniSocket receiver 已连接并注册；
- EAI 本地 5003/5001 数据持续更新；
- 待机时 EAI 不发送业务帧；
- PS 同步无错误且 pending 为 0；
- 头/腰相机未启动不影响 recorder 服务 active。

### 9.3 逐级运动验收

全程确保防护、净空、急停有效，操作者先按厂家流程进入 HBWALK：

1. 松开扳机和摇杆，TS1P 与机器人姿态尽量接近；
2. 长按左 Z + 右 C 3 秒启动；
3. 先验证双臂小幅单关节跟随；
4. 小幅验证左右扳机对应的双手；
5. 长按右 B 1 秒验证左右手同时单食指，再松开 0.5 秒、长按 1 秒退出；
6. 确认双摇杆回中后，直接小幅推动左摇杆验证前后，回中应立即零速；
7. 直接小幅横推右摇杆验证原地转向，回中应立即零速；
8. L3 长按 1 秒开始短数采，再次长按 1 秒结束；
9. 长按 Z+C 3 秒结束遥操，确认限速回新机器人的 Home。

不要用本项目发布 `gotoHBWALK`，不要向厂家 `/proc_manager/config/notify` 发送伪进程启停
JSON，也不要为了迁移删除厂家限位、电流、碰撞或急停保护。

### 9.4 数采验收

结束短数采后，在 PS 检查：

```bash
python3 -m json.tool Data_Get/sync_status.json
find Data_Get -mindepth 1 -maxdepth 1 -type d -printf '%T@ %f\n' | sort -nr | head
```

最新 episode 必须包含：

```text
READY
VERIFIED
manifest.json
bag/metadata.yaml
bag/*.mcap
```

`manifest.json` 中应满足：

- `state=complete`、`status=ready`；
- `bag_info_validation.passed=true`；
- 所有 `required_topic_message_counts` 大于 0；
- 已启动的相机为 `healthy`，未启动为 `absent`；
- `data_quality_warnings` 为空，或已明确接受其中的相机降级说明。

同步状态应为 `idle`、`pending_remote_cleanup=0`。Nvidia 的 `active/ready/failed` 最终应为空；
本机完整验真前不得人工删除机器人 `ready/`。

## 10. 回滚与故障边界

### 10.1 新机器人 Home 未确认

保持 `tg3-local-teleop.service` 停止，只运行 monitor-only。不要把旧 Home 当作新机器人的
零位，也不要测试自动回 Home。

### 10.2 EAI 5003 或 5001 不正常

停止 sender，先修复原厂 xTELE。5003 缺失时双臂和按键无数据；5001 缺失时厂家处理后的
组合手势不会进入机器人。

### 10.3 本地 Hub 不可用

先恢复 EAI `tg3-omnisocket-hub.service` 和 UDP 14049，再重启机器人桥。已经失败的 Z+C
请求不会自动恢复，必须松开 0.5 秒后重新长按。

### 10.4 同步显示 delete_pending

本机数据已经发布，但机器人回收尚未确认。不要删除本机 episode。检查 SSH、host key、
`delete_ready_episode.py` 和机器人磁盘；服务会按 30 秒至 15 分钟退避自动重试。

若 pending 收据属于旧机器人 IP，系统会保守拒绝把它用于新机器人删除，但不会阻塞其他新
episode。迁移前应在旧地址完成 pending，或人工核对本机与旧机器人 manifest 后再处理。

### 10.5 回到旧设备

1. 退出遥操并停止新系统的 EAI sender、机器人 bridge 和 PS sync；
2. 恢复备份的 unit 与机器人专属 config；
3. 按 Hub → recorder/bridge → sender → sync 顺序启动；
4. 仍从无运动验收开始，不能直接恢复大幅跟随或行走。

## 11. 每套设备的迁移记录模板

```text
迁移日期：
项目 Git commit：
OmniSocketGo commit：de3f5c96779dbe1571c10feb22fc7f2331b6b222

PS 主机：
  用户/项目路径：
  Data_Get 路径：
  Nvidia SSH 地址：

EAI：
  SSH 地址：
  控制局域网 IP：
  xTELE 版本：
  TS1P ID/类型：
  EAI Peer：
  Hub UDP 地址：

机器人：
  机器人编号：
  Nvidia SSH 地址：
  控制局域网 IP：
  Robot Peer：
  SDK/固件版本：
  左右手型号：
  Home 14 维值：
  头相机服务/Topic：
  腰相机服务/Topic：

验收：
  离线测试：
  双臂：
  双手：
  单食指：
  前后行走：
  原地转向：
  自动 Home：
  数采/VERIFIED：
  机器人临时副本回收：
```