diff --git a/docs/天工3.0本地同构臂遥操迁移部署指南.md b/docs/天工3.0本地同构臂遥操迁移部署指南.md index ad4e718..7beb68a 100644 --- a/docs/天工3.0本地同构臂遥操迁移部署指南.md +++ b/docs/天工3.0本地同构臂遥操迁移部署指南.md @@ -8,7 +8,7 @@ BrainCo Revo2 的情况。 | 地址/标识 | 示例 | IP 变化时是否修改运行配置 | |---|---|---| | 新机器人 SSH 地址 | `nvidia@192.168.41.2` | 只影响安装、维护命令；公网 OmniSocket 运行时不使用这个地址 | -| EAI SSH 地址/别名 | `eai` | 只影响安装、维护命令；xTELE 使用本机回环地址，不依赖 EAI 局域网 IP | +| EAI SSH 地址/局域网 IP | `eai` / `192.168.5.14` | 公网 OmniSocket 模式只影响运维；第 6 节纯 ZMQ 直连时必须写入机器人 `iarm_endpoint` | | OmniSocket Hub 地址 | `175.178.116.187:14049` | 必须同时修改 EAI 发送服务和机器人 `config.toml` | | OmniSocket Peer ID | `tg3-...-iarm/robot` | 每套链路必须成对匹配；换机器人时建议使用新的机器人唯一 ID | @@ -256,7 +256,7 @@ foreign_hand_source_seen = false `iarm_age_s` 为空或逐渐变旧属于预期。身份、频率和扳机原始值先在 EAI 本机检查，完整 启动门控在 START 首帧到达机器人后执行。 -然后再保存新 Home、核对手部打开位，并按第 6 节进行现场验收。 +然后再保存新 Home、核对手部打开位，并按第 7 节进行现场验收。 ## 4. 场景 B：EAI 工控机也更换 @@ -386,11 +386,241 @@ omnisocket_server = "203.0.113.10:15000" 2. EAI `tg3-omnisocket-sender.service`； 3. 机器人接收端。2 秒业务帧看门狗只在活动会话内生效，待机不会反复重启。 -## 6. 新机器人首次现场验收顺序 +## 6. 场景 C：完全不经过 Hub 的局域网 ZMQ 直连 + +这一路径不启动公网或本地 OmniSocket Hub，也不经过 +`tg3-omnisocket-sender.service`： + +```text +TS1P + -> EAI xTELE tcp://0.0.0.0:5003（原始 JSON） + -> 同一可信局域网内的 TCP/ZMQ + -> 机器人 tg3_local_teleop，network.transport="zmq" + -> /encoder_identical_joint、BrainCo 手和 /hric/robot/cmd_vel +``` + +这里的“本地”是机器人直接订阅 EAI 的局域网地址，不是把 +`tcp://127.0.0.1:5003` 原样写到机器人。机器人配置中的 `127.0.0.1` 会指向机器人自身， +无法访问 EAI。 + +### 6.1 适用条件和网络检查 + +- EAI 与机器人必须在同一可信 Wi-Fi、有线路由可达网段，或使用两端静态地址的直连网线； +- EAI 地址应固定，至少配置 DHCP 保留；地址变化后必须同步修改机器人 + `network.iarm_endpoint`； +- 只需机器人访问 EAI 的 TCP `5003`。不要把 5003 暴露到公网，防火墙应只允许机器人地址； +- xTELE 必须监听非回环地址。当前 EAI 实测为 `0.0.0.0:5003` 和 + `0.0.0.0:5001`；新工控机仍需重新检查； +- ZMQ/TCP 直连没有 OmniSocket 的 Peer ID、包龄过滤或身份认证，只应在隔离、可信的控制网 + 使用。 + +在 EAI 检查地址和监听： + +```bash +ip -br -4 address +ss -lntp | grep -E ':(5001|5003)\b' +``` + +若 5003 只显示 `127.0.0.1:5003`，机器人不能直接连接。应按厂家 xTELE 配置修改监听地址， +不要用公网端口转发代替局域网隔离。 + +从机器人检查到 EAI 的路由；把示例 IP 换成实际 EAI 局域网 IP： + +```bash +ping -c 3 192.168.5.14 +python3 -c 'import socket; s=socket.create_connection(("192.168.5.14",5003),2); s.close(); print("TCP 5003 OK")' +``` + +上面的 TCP 检查只证明端口可达。还应在机器人实际订阅一帧 ZMQ JSON： + +```bash +python3 - <<'PY' +import json +import zmq + +context = zmq.Context() +socket = context.socket(zmq.SUB) +socket.setsockopt(zmq.SUBSCRIBE, b"") +socket.connect("tcp://192.168.5.14:5003") +if socket.poll(3000) == 0: + raise SystemExit("3 秒内未收到 xTELE 5003 数据") +data = json.loads(socket.recv()) +print(data.get("isomorphic_arm_id"), data.get("isomorphic_arm_type"), data.get("freq")) +socket.close() +context.term() +PY +``` + +Wi-Fi 和有线的配置方法相同，`iarm_endpoint` 始终填写“机器人能够访问到的 EAI 地址”。 +不要因为使用机器人内部 SSH 地址 `192.168.41.2`，就把它误写成 EAI 地址。 + +当前现场 Wi-Fi 已验证为 EAI `192.168.5.14`、机器人 Nvidia `wlan0` +`192.168.5.15`。若改用直连网线，应选择双方确认未被厂家系统占用的物理网卡，配置一个 +独立静态网段，例如 EAI `192.168.50.1/24`、机器人 `192.168.50.2/24`，随后把 +`iarm_endpoint` 改为 `tcp://192.168.50.1:5003`。网卡名必须现场确认；不要改动机器人 +Ubuntu `192.168.41.1` 与 Nvidia `192.168.41.2` 之间的厂家内部链路。 + +### 6.2 切换前停止公网链路 + +先用正常 Z+C 3 秒 STOP 结束当前遥操，等待自动 Home 完成，并在机器人确认： + +```bash +python3 -c 'import json; d=json.load(open("/home/nvidia/tg3_local_teleop/status.json")); print({k:d.get(k) for k in ("armed","returning_home","home_status")})' +``` + +必须看到 `armed=false` 且 `returning_home=false`。然后在 EAI 停止并禁用公网 sender： + +```bash +systemctl --user disable --now tg3-omnisocket-sender.service +systemctl --user is-active tg3-omnisocket-sender.service +``` + +第二条应输出 `inactive`。不要删除 sender、OmniSocketGo 或原来的 service；保留它们用于 +回切公网模式。纯 ZMQ 模式下 EAI 的 sender `status.json` 不再是运行状态依据。 + +### 6.3 修改机器人配置 + +在机器人编辑： + +```text +/home/nvidia/tg3_local_teleop/config.toml +``` + +只修改以下字段： + +```toml +[network] +transport = "zmq" +iarm_endpoint = "tcp://192.168.5.14:5003" # 改成实际 EAI 局域网 IP +``` + +`omnisocket_server`、`omnisocket_peer_id` 和 `omnisocket_expected_sender` 可以保留，ZMQ +模式不会读取它们，回切公网时仍可继续使用。`expected_iarm_id` 和 +`expected_iarm_type` 仍会检查，换 TS1P 时必须同步修改真实设备 ID。 + +当前版本在纯 ZMQ 断流时会保留最后一帧。`locomotion.enabled=false` 只能先排除最危险的 +持续速度输出，仍不足以让双臂和手安全投用；配置阶段先设置： + +```toml +[locomotion] +enabled = false +``` + +这会禁用我们桥发布的 HBWALK 速度。完成第 6.5 节所述本地断流保护之前，双臂、手和 +行走都只能做无发布监测，不能长按 Z+C 武装。 + +不要立即启动带 `--allow-publish` 的 systemd 服务。先停止并暂时禁用我们自己的机器人桥， +然后以前台、无 `--allow-publish` 的监测模式运行 30 秒： + +```bash +systemctl --user disable --now tg3-local-teleop.service +cd /home/nvidia/tg3_local_teleop +./run.sh --duration 30 +/home/nvidia/tg3_local_teleop/status.sh +``` + +`run.sh` 只有显式收到 `--allow-publish` 才能发布；上述命令应显示 +`mode=monitor-only`。如果 systemd 服务仍为 `active`，先停掉，避免同时启动第二个桥实例。 + +状态至少应满足： + +```text +iarm_transport = zmq +iarm_endpoint = tcp://:5003 +iarm_transport_status.frames_accepted 持续增长 +iarm_id = 当前 TS1P ID +iarm_frequency_hz 左右均高于 30 Hz +armed = false +foreign_source_seen = false +mode = monitor-only +``` + +不要只看 `iarm_transport_status.connected`：当前 ZMQ 接收器收到过首帧后会保持该布尔值， +判断链路是否仍在更新要连续观察 `frames_accepted` 和 `iarm_age_s`。 + +服务重启和检查期间必须保持 Z+C 完全松开。ZMQ 回退门控在机器人端计时，若服务启动时 +已经按住 Z+C，连续 3 秒后也可能被当成新的启动请求。 + +### 6.4 直连模式下协议字段与功能差异 + +下表说明数据和代码路径是否存在，不代表当前版本已经允许运动。第 6.5 节的 ZMQ 断流门控 +完成前，所有运动项都保持 monitor-only。 + +| 功能 | 纯 ZMQ 直连的数据/代码情况 | +|---|---| +| 双臂 14 关节、启动限位和 ROS 状态门控 | 字段与代码路径保留；当前禁止武装 | +| 左右扳机 BrainCo 手控 | 5003 原始 `hand.position` 存在；当前禁止武装 | +| 右 B 长按 1 秒单食指 | 5003 原始 B 键存在；当前禁止武装 | +| Z+C 长按 3 秒启动/停止、STOP 后限速 Home | 改由机器人本地计时；断流可锁存按键，当前禁止武装 | +| C + 左摇杆行走、Z + 右摇杆转向 | 代码路径存在；当前必须 `enabled=false` | +| xTELE 5001 处理后的其他六维组合手势 | 不保留；机器人只订阅 5003 | +| OmniSocket session ID、Peer 校验、300 ms 晚包过滤 | 不使用 | +| 公网 Hub、EAI OmniSocket sender | 不需要 | + +若必须完整保留 5001 组合手势，不能只把机器人指向 5003。需要另行实现一个 EAI 本地 +5003+5001 合并代理，或在局域网内运行 OmniSocket Hub；后者不经过公网，但仍属于本地 +Hub 模式，不是本节的“完全无 Hub”直连。 + +### 6.5 当前版本的断流风险 + +此前按现场要求删除了机器人桥“输入陈旧超过 0.25 秒立即解除遥操”的自定义门控；而 +`omnisocket_restart_after_stale_s=2.0` 只在 `transport="omnisocket"` 时生效。 +因此纯 ZMQ 模式断网后： + +- 最后一帧双臂和手目标仍会以桥的周期重复发布； +- 如果行走仍启用且最后一帧是非零速度组合，非零 `/hric/robot/cmd_vel` 也会持续发布； +- 如果最后一帧仍按住 Z+C，本地 3 秒计时会在没有新数据时继续，可能在断网后武装或停止； +- 网络恢复后会直接继续当前 armed 会话，不要求重新 Z+C； +- `connected=true` 不能证明数据仍然新鲜。 + +所以当前纯直连配置只能按第 6.3 节以 monitor-only 验证链路。正式启用前必须实现仅作用于 +`transport="zmq"` 的断流门控，至少满足： + +1. 陈旧样本不得继续 Z+C 或右 B 计时； +2. 已武装时陈旧输入必须立即发布零速、解除双臂/手发布并锁定为需要重新松开、长按； +3. 网络恢复不得自动恢复原 armed 会话； +4. 阈值应作为 ZMQ 专用配置经现场验证，不能把已删除的通用 0.25 秒门控悄悄加回来； +5. 完成断网、拔线、xTELE 停止和恢复的无运动测试后，才能重新启用 + `tg3-local-teleop.service --allow-publish`，行走还需单独验证零速帧。 + +这不是厂家默认保护的变化；厂家关节限位、电机、碰撞和手部保护仍保持原样。 + +### 6.6 从纯直连恢复公网 OmniSocket + +先正常 STOP、完成 Home 并保持 Z+C 松开，然后把机器人恢复为： + +```toml +[network] +transport = "omnisocket" + +[locomotion] +enabled = true # 仅在现场仍需要并已确认安全时恢复 +``` + +确认保留的 `omnisocket_server`、双方 Peer ID 仍匹配。按“先机器人接收端、后 EAI +sender”的顺序恢复： + +```bash +# 机器人 +systemctl --user enable --now tg3-local-teleop.service + +# EAI +systemctl --user enable --now tg3-omnisocket-sender.service +``` + +机器人先确认 `armed=false`、`iarm_transport=omnisocket`；EAI 待机时仍只读本地 +5003/5001，不会在新的 Z+C 3 秒 START 前发送业务数据。 + +## 7. 新机器人首次现场验收顺序 全程确认防护、活动空间、急停和 HBWALK 状态。 +纯 ZMQ 当前版本若尚未完成第 6.5 节断流门控，只执行下面第 1～4 步的 monitor-only 检查， +不得执行第 5 步及后续任何武装或运动测试；完成并验证断流门控后才能继续。 -1. 服务启动后保持未武装；在 EAI 状态中确认本地接收计数增长而公网发送计数不增长； +1. OmniSocket 模式：服务启动后保持未武装，在 EAI sender 状态中确认本地接收计数增长而 + 公网发送计数不增长；纯 ZMQ 模式：sender 已停用，应在机器人 monitor-only 状态中确认 + `frames_accepted` 持续增长、`iarm_age_s` 接近 0，不读取旧的 EAI sender + `status.json`； 2. 不武装时分别扣左右扳机，在 EAI 本地数据中确认左右值独立从 0 到 1； 3. 确认左右手物理默认打开位和 `robot_hand_states` 正常； 4. 把 TS1P 双臂摆到与机器人当前位置尽量接近的安全姿态； @@ -399,18 +629,24 @@ omnisocket_server = "203.0.113.10:15000" 7. 分别小幅扣左右扳机，验证双手方向、范围和限速； 8. 保持右摇杆回中，连续长按右 B 1 秒，确认右手以 `400 units/s` 限速进入厂商 “单食指”姿态；松开至少 0.5 秒后再次长按 1 秒，确认退出并恢复正常右手跟随； -9. 先停止并确认 `armed=false`，按飞书指南逐个选择其他手势组合键；检查 EAI +9. 仅在 OmniSocket/5001 合并模式下：先停止并确认 `armed=false`，按飞书指南逐个选择 + 其他手势组合键；检查 EAI `status.json` 的 `command_frames_accepted` 增长，并在 EAI 本机 5001 抓帧确认处理后的 `hand.position` 为六维数组；待机不会构包，`command_hand_merges` 此时不应增长； -10. 再次武装后检查 `command_hand_merges` 增长和机器人 `iarm_hand_position` 为六维， +10. 仅在 OmniSocket/5001 合并模式下：再次武装后检查 `command_hand_merges` 增长和机器人 + `iarm_hand_position` 为六维， 再只做小幅动作，逐个验证所需的其他组合手势方向和限速； -11. 保持右 C，把左摇杆小幅向前推出死区，确认下一个 50 Hz 周期立即响应；松 C，确认 +11. 仅在 `[locomotion].enabled=true` 且相应链路断流保护已经验证后：保持右 C，把左摇杆 + 小幅向前推出死区，确认下一个 50 Hz 周期立即响应；松 C，确认 立即零速停止。再次按 C/推杆也应立即响应，不再等待 3 秒； -12. 保持左 Z，把右摇杆小幅横推，确认机器人原地转向；松开任一输入应立即清零角速度； +12. 在同一行走前提下，保持左 Z，把右摇杆小幅横推，确认机器人原地转向；松开任一输入 + 应立即清零角速度； 13. 再次长按 Z+C 停止，观察双臂限速回到新机器人保存的 Home； -14. 测试 Hub 短暂断线：短于 2 秒不应解除会话；持续约 2 秒无帧会重建机器人接收进程， - 恢复后先确认未武装，再重新长按启动； -15. 记录最终 Peer ID、Hub、SSH 地址、Home、行走限速、手部端点和单食指姿态到该机器人的设备档案。 +14. 仅在 OmniSocket 模式测试 Hub 短暂断线：短于 2 秒不应解除会话；持续约 2 秒无帧会 + 重建机器人接收进程，恢复后先确认未武装，再重新长按启动；纯 ZMQ 模式在完成本地 + 断流门控前禁止做运动中的断链测试； +15. 记录 SSH 地址、Home、行走限速、手部端点和单食指姿态到设备档案；OmniSocket 模式 + 另记 Peer ID/Hub，纯 ZMQ 模式改记 EAI 固定局域网 IP、TCP 5003 防火墙范围和断流门控参数。 迁移时确认目标机提供 `/hric/robot/cmd_vel`（`geometry_msgs/msg/TwistStamped`），并保持 `locomotion.command_topic` 与目标固件一致。行走限速、死区、曲线和方向符号均在机器人 @@ -418,7 +654,7 @@ omnisocket_server = "203.0.113.10:15000" 范围配置：`max_forward_m_s=1.0`、`max_reverse_m_s=0.8`、 `max_angular_rad_s=0.8`；迁移到不同型号或固件时应重新核对其官方 Topic 范围。 -## 7. 常见问题 +## 8. 常见问题 ### 机器人 SSH IP 变了，需要改 `config.toml` 吗？ @@ -426,7 +662,9 @@ omnisocket_server = "203.0.113.10:15000" ### EAI IP 变了，需要改 `tcp://127.0.0.1:5003/5001` 吗？ -不需要。`127.0.0.1` 永远表示 EAI 本机，和网卡地址无关。 +公网 OmniSocket sender 不需要修改：`127.0.0.1` 永远表示 EAI 本机，和网卡地址无关。 +但第 6 节纯 ZMQ 直连时，机器人 `iarm_endpoint` 使用 EAI 局域网地址；该地址变化就必须 +修改并重启机器人桥。 ### Hub 没启动时已经长按了 Z+C，服务器恢复后怎么办？ @@ -456,7 +694,7 @@ omnisocket_server = "203.0.113.10:15000" 不可以。当前桥导入并发布 BrainCo 消息，因时手是不同消息类型和 13 自由度映射，需要 单独实现适配后再部署。 -## 8. 迁移时真正需要修改的最小清单 +## 9. 迁移时真正需要修改的最小清单 同一 EAI、同一 TS1P、同一 Hub、换一台同配置 BrainCo 天工 3.0 时，最少修改： @@ -469,3 +707,9 @@ omnisocket_server = "203.0.113.10:15000" 6. SSH 命令中的新机器人 IP。 Hub IP/端口变化时，额外同时修改 EAI `--server` 和机器人 `omnisocket_server`。 + +完全不经过 Hub、切换为第 6 节纯 ZMQ 直连时，最少修改机器人 +`network.transport="zmq"`、`network.iarm_endpoint="tcp://:5003"`，并在 +当前没有直连断流门控的版本中设置 `locomotion.enabled=false`，同时停用 EAI 的 +`tg3-omnisocket-sender.service`，并仅以机器人 monitor-only 模式验证；完成第 6.5 节的 +ZMQ 专用断流门控前不得启用运动发布。 diff --git a/tg3_local_teleop/README.md b/tg3_local_teleop/README.md index f82167e..f269469 100644 --- a/tg3_local_teleop/README.md +++ b/tg3_local_teleop/README.md @@ -128,7 +128,12 @@ systemctl --user stop tg3-local-teleop.service 当前 `config.toml` 由桥接程序直接建立 OmniSocket Session，不再经过机器人本机 ZMQ 接收代理。若需回退到机器人与工控机的局域网直连，可把 `network.transport` 改成 -`zmq`；保留的 `iarm_endpoint` 为 `tcp://192.168.5.14:5003`。 +`zmq`；保留的 `iarm_endpoint` 为 `tcp://192.168.5.14:5003`。纯 ZMQ 模式只读取 +5003 原始帧，不合并 5001 的其他六维手势；此前删除的 0.25 秒输入陈旧门控和下面的 +2 秒 OmniSocket 重建看门狗都不作用于 ZMQ，因此断流会保留最后输入。当前切换到纯直连 +时仅允许 monitor-only 链路验证：只停用行走仍不能防止陈旧 Z+C 在断网后计时或双臂/手 +继续使用旧帧。完成 ZMQ 专用断流门控前不得启用运动；完整步骤和回切方法见 +`docs/天工3.0本地同构臂遥操迁移部署指南.md` 第 6 节。 机器人侧不再以 `0.25 s` 公网输入间隔解除武装。活动会话超过 `2 s` 仍无帧时重建机器人 OmniSocket 进程；在此之前桥会保持最后一帧目标。未 START 或收到 STOP 后没有业务帧是