docs: add cross-device migration runbook
This commit is contained in:
@@ -14,7 +14,9 @@
|
|||||||
- `tg3_data_collection/`：部署在本机；通过本地 SSH/rsync 拉取已完整收尾并校验的
|
- `tg3_data_collection/`：部署在本机；通过本地 SSH/rsync 拉取已完整收尾并校验的
|
||||||
episode，原子保存到 `Data_Get/`；持久化验真凭据后自动回收机器人上的对应副本。
|
episode，原子保存到 `Data_Get/`；持久化验真凭据后自动回收机器人上的对应副本。
|
||||||
- `Data_Get/`：最终数采目录。实际 MCAP、清单和同步状态默认不提交 Git。
|
- `Data_Get/`：最终数采目录。实际 MCAP、清单和同步状态默认不提交 Git。
|
||||||
- `docs/`：可提交的跨机器人迁移步骤。含实测帧和现场拓扑的汇报/证据文档只保留在
|
- `docs/`：跨设备迁移先看
|
||||||
|
[`天工3.0同构臂遥操与数采跨设备迁移手册.md`](docs/天工3.0同构臂遥操与数采跨设备迁移手册.md)，
|
||||||
|
更底层的公网/本地 Hub 与 ZMQ 细节见原迁移部署指南。含实测帧和现场拓扑的汇报/证据文档只保留在
|
||||||
当前本地工作副本，不同步到匿名可读的远端仓库。
|
当前本地工作副本，不同步到匿名可读的远端仓库。
|
||||||
|
|
||||||
## 外部依赖（不随仓库提交）
|
## 外部依赖（不随仓库提交）
|
||||||
|
|||||||
744
docs/天工3.0同构臂遥操与数采跨设备迁移手册.md
Normal file
744
docs/天工3.0同构臂遥操与数采跨设备迁移手册.md
Normal file
@@ -0,0 +1,744 @@
|
|||||||
|
# 天工 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. 右 C + 左摇杆小幅验证前后，松开任一输入应立即零速；
|
||||||
|
7. 左 Z + 右摇杆小幅验证原地转向；
|
||||||
|
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：
|
||||||
|
机器人临时副本回收：
|
||||||
|
```
|
||||||
|
|
||||||
Reference in New Issue
Block a user