[docs] 全面校准项目说明与跨平台资源边界

2026-07-27 19:17:19 +08:00
parent 117b02bec7
commit fbb396708c
37 changed files with 131 additions and 103 deletions
@@ -1,6 +1,6 @@
-# ROS2 C++ Sim2Real 运动控制栈 - 部署指南
+# ROS 2/C++ Sim2Real v2 部署指南

-本工作区提供了一个自包含、独立的 C++ ROS2 Humble 实现，用于在 Jetson Orin 目标机上部署轮腿四足机器人控制策略。
+本工作区保存 `v0.12.0` 里程计联调快照，包含 ROS 2 Humble/C++ 主体和 Odin 驱动。系统依赖、设备标定和 TensorRT engine 仍与目标机环境绑定，不能仅凭源码声明在新设备上已复现。

 ---

@@ -90,7 +90,7 @@ chmod +x start_sim2real.sh
 强烈推荐使用 Docker 隔离依赖，避免 Jetson Orin 上的库版本冲突。

 ### 步骤 1：构建镜像
-确保在 `sim2real_ros2` 目录中（包含 `Dockerfile`）：
+确保在 `sim2real_ros2_v2` 目录中（包含 `Dockerfile`）：
 ```bash
 # 使用标准 docker build：
 docker build -t sim2real_ros2:latest .
@@ -1,6 +1,6 @@
 # ROS 2 Sim2Real v2：里程计导航联调

-本目录归档 `real/sim2real_ros2_v2(odom)`，对应重排主线的 `v0.12.0`。该阶段在 `v0.11.1` 的 Odin/TensorRT 与站姿调参基础上，固定纯里程计模式，增加 odom fallback 的 TF 冲突保护、A_min 路线和地图工具。
+本目录归档原始 `real/sim2real_ros2_v2(odom)`，对应 `v0.12.0`。该阶段在 `v0.11.1` 的 Odin/TensorRT 与站姿调参基础上，固定纯里程计模式，增加 odom fallback 的 TF 冲突保护、A_min 路线和地图工具。

 本工程保留当前 `sim2real` 已验证的部署契约，同时将运行时热路径迁移到 C++：

@@ -1,4 +1,4 @@
-# sim2real_ros2 架构说明
+# sim2real_ros2_v2 架构说明

 ## 设计目标

@@ -1,5 +1,7 @@
 # 迁移计划

+> 版本范围：ROS 2 v2 里程计联调快照（`v0.12.0`）。完成标记表示该快照中的代码迁移状态，不等于已在任意新硬件环境复现。
+
 ## Phase 1: 硬件核心迁移 ✅ 已完成

 将当前高频热路径从 Python 迁出。
@@ -39,11 +41,7 @@

 ## Phase 3: ROS 2 系统集成 ✅ 已完成

-参考的源项目：
-
- `00_ reference/odin_ros_driver`
- `00_ reference/EDULITE_A3/el_a3_ros`
- `00_ reference/rl_sar`
+参考过的外部项目包括 Odin ROS 驱动、EDULITE A3 ROS 工程和 RL-SAR；外部参考目录不属于本仓库公开内容。

 交付物：

@@ -77,4 +75,4 @@
 | 里程计中继 | `odom_relay_node` | /odin1/odometry → /odom + odom→base_link TF |
 | 导航栈 | Nav2 全套节点 | AMCL + costmap + DWB + Navfn + BT + lifecycle |
 | 传感器驱动 | `odin_ros_driver` | IMU + 点云 + 里程计原始发布 |
-| 点云转换 | `pointcloud_to_laserscan` | /odin1/cloud_slam → /scan (供 AMCL 使用) |
+| 点云转换 | `pointcloud_to_laserscan` | 外部 ROS 包；/odin1/cloud_slam → /scan（供 AMCL 使用） |
@@ -1,6 +1,6 @@
-# sim2real_ros2 遥控器调用说明
+# sim2real_ros2_v2 遥控器调用说明

-本文档说明如何在 `sim2real_ros2` 中调用已接入的 SBUS UART 遥控器节点，以及执行后系统会产生什么效果。
+本文档说明如何在 `sim2real_ros2_v2` 中调用已接入的 SBUS UART 遥控器节点，以及执行后系统会产生什么效果。

 ## 1. 当前接入关系

@@ -1,4 +1,4 @@
-# sim2real_ros2 Web UDP 调试说明
+# sim2real_ros2_v2 Web UDP 调试说明

 本文档说明本次新增的最小 Web 调试链路。

@@ -7,3 +7,5 @@
 | `map_b.pcd` | 1,080,047 | 4 | 270,012 | 8,680,283 B | `F17FC7E188C772D48E8D3FE20E3A934AFCDF59357C27BCCDCAC3C7E9AD1D1CB7` | `F3052431F217DE8FFFE87726F8E547A59C65048B0285F02AF4803C5F4E4C1B42` |
 | `A_min.pcd` | 683,908 | 3 | 227,969 | 7,300,173 B | `77C884B17D78C4D157F84093BFEA0729FA25382C70E706C4BA12913A3C90ED20` | `CC4556D472BE6E5B232B9BFEE43F5F337D710F88E88D9B90994368C580327DC1` |
 | `C.pcd` | 3,186,653 | 11 | 289,696 | 9,040,786 B | `C5C7E60B06A0FFEA15E55C14B8CFAFBC8525371C8C3AC9C72821AB736AED8A6C` | `1FC4124642D934460811DBF62EBE9C5C9CF30668BC42E4782B18F3C002ED1A25` |
+
+大小和 SHA-256 均按 Git 中保存的字节计算；根目录 `.gitattributes` 禁止对 `*.pcd` 做跨平台换行转换。
@@ -9,7 +9,7 @@ This is not the Nano runtime Web UI. Use it before a run to inspect the map and
 From the repository root:

 ```powershell
-python .\tools\pcd_map_viewer\server.py --http-port 8090
+python .\05_software\real\sim2real_ros2_v2\tools\pcd_map_viewer\server.py --http-port 8090
 ```

 Open:
@@ -84,21 +84,15 @@ waypoints:
    obstacle_name: wall_1
 ```

-Default runtime route:
+The current `v0.12.0` runtime route is configured separately in `src/sim2real_bringup/config/runtime.yaml`:

 ```text
-map/routes/map1/test_route.yaml
+map/routes/A_min/A_min_route.json
 ```

-## Runtime Test
-
-```bash
-ros2 topic pub --once /route_runner/cmd std_msgs/msg/String "{data: reload}"
-ros2 topic pub --once /route_runner/cmd std_msgs/msg/String "{data: start}"
-ros2 topic pub --once /route_runner/cmd std_msgs/msg/String "{data: stop}"
-```
+The editor can also save YAML, but the archived runtime does not provide the `/route_runner/cmd` interface described by an earlier draft. Use the current JSON task file and Web/navigation controls documented by this snapshot.

 See also:

- [Maps And Routes](../../docs/ROUTES_AND_MAPS.md)
- [Common Commands](../../docs/COMMANDS.md)
+- [Archived map data](../../map/README.md)
+- [ROS 2 v2 snapshot](../../README.md)
@@ -7,7 +7,7 @@
 在仓库根目录：

 ```powershell
-python .\tools\pcd_map_viewer\server.py --http-port 8090
+python .\05_software\real\sim2real_ros2_v2\tools\pcd_map_viewer\server.py --http-port 8090
 ```

 打开：
@@ -26,3 +26,7 @@ http://127.0.0.1:8090
 - `tolerance`

 不保存 `z` 和 `action`。
+
+当前 `v0.12.0` 运行配置使用 `map/routes/A_min/A_min_route.json`。编辑器也能保存 YAML，但本快照没有旧文档曾描述的 `/route_runner/cmd` 控制接口。
+
+地图抽样边界见 [`../../map/README.md`](../../map/README.md)，版本说明见 [`../../README.md`](../../README.md)。
@@ -15,7 +15,7 @@ Use this tool only when you want the browser and HTTP server to run on Windows w
 From the repository root:

 ```powershell
-python .\tools\win_web_debug\server.py --nano-host <nano-ip> --http-port 8088
+python .\05_software\real\sim2real_ros2_v2\tools\win_web_debug\server.py --nano-host <nano-ip> --http-port 8088
 ```

 Or from this folder:
@@ -40,5 +40,5 @@ src/sim2real_runtime/src/web_udp_bridge_node.py

 See:

- [Runtime Web](../../docs/RUNTIME_WEB.md)
- [Common Commands](../../docs/COMMANDS.md)
+- [Runtime Web and UDP bridge](../../docs/WEB_DEBUG_USAGE.md)
+- [ROS 2 v2 snapshot](../../README.md)
@@ -13,7 +13,7 @@ http://<nano-ip>:18080
 在仓库根目录：

 ```powershell
-python .\tools\win_web_debug\server.py --nano-host <nano-ip> --http-port 8088
+python .\05_software\real\sim2real_ros2_v2\tools\win_web_debug\server.py --nano-host <nano-ip> --http-port 8088
 ```

 打开：
@@ -21,3 +21,5 @@ python .\tools\win_web_debug\server.py --nano-host <nano-ip> --http-port 8088
 ```text
 http://127.0.0.1:8088
 ```
+
+运行时 Web 与 UDP 配置见 [`../../docs/WEB_DEBUG_USAGE.md`](../../docs/WEB_DEBUG_USAGE.md)。