RC_WheelLeg/05_software/real/sim2real_ros2_v2/README.md

ROS 2 Sim2Real v2：Odin、TensorRT 与站姿调参

本目录在 v0.11.0 导航原型基础上归档 real/sim2real_ros2_v2(z=0.380 hip=0.670 knee=-1.390)，对应重排主线的 v0.11.1。虽然源目录以站姿参数命名，但该阶段同时首次完整加入 Odin 驱动、TensorRT、多策略切换、事件日志和更完整的硬件诊断。

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

• 53D 策略观测契约不变
• 16D 动作契约不变
• 50Hz 策略循环与训练对齐
• 200Hz 电机循环为专用 C++ 热路径
• ROS 2 作为导航、TF、诊断和启动管理的系统集成层

工作区布局

• src/sim2real_interfaces 硬件桥接与策略运行时共享的 ROS 2 消息定义。
• src/sim2real_common 共享常量、部署契约辅助函数、Mahony 姿态滤波器、站立平衡控制器、安全监控。
• src/sim2real_hw 面向硬件的桥接节点：RobStride CAN 收发、IMU/Odin 数据采集、看门狗、状态发布。
• src/sim2real_runtime 策略运行时节点：53D→16D ONNX 推理、命令滤波/仲裁、目标发布。 同时包含 odom_relay_node（里程计中继与 TF 广播）。
• src/sim2real_nav2 ROS 2 Navigation2 (Nav2) 配置包：参数、启动文件、AMCL、costmap、planner/controller。
• src/sim2real_bringup 统一启动文件与运行时参数配置。
• src/odin_ros_driver Odin 传感器 ROS 2 驱动（含 IMU、点云、里程计发布）。
• docs 架构说明与迁移计划。

目标架构

Odin / IMU / Odom  --->  sim2real_hw  --->  sim2real_runtime  --->  sim2real_hw
                              |                  |                    |
                              v                  v                    v
                         RuntimeState       RuntimeTarget          电机 CAN 指令
                              |                  |
                              +-------> 诊断 / 遥测

Nav2 / cmd_vel  ------------------------------>  sim2real_runtime
                   (经 odom_relay_node 提供 odom→base_link TF)

当前状态

已完成 Phase 0-5 的全部迁移：

1. ✅ 冻结部署契约（deployment_contract.hpp）
2. ✅ ROS 2 包结构搭建
3. ✅ 硬件热路径迁移至 C++（SocketCAN 驱动、200Hz 电机循环）
4. ✅ ONNX 策略运行时迁移至 C++（50Hz 推理循环）
5. ✅ 导航与诊断通过 ROS 2 接入（Nav2 + odom_relay + TF）

契约来源

迁移过程中以下文件被视为真值源：

• sim2real/deployment_manifest.yaml
• sim2real/interface/motor_mapping.py
• sim2real/interface/real_io.py
• sim2real/policy/policy_runner.py
• sim2real/web/session.py

注意事项

• 开发目标为 Linux + ROS 2 Humble，运行于 Jetson Orin / x86_64。
• Windows 仅作为编辑环境使用。
• 观测顺序、动作缩放、默认站姿、电机映射不得独立修改， 除非训练与部署同步更新。
• Rough 默认策略为 NEWmodel_1900，优先使用比赛机生成的 TensorRT engine；Crawl 保留 ONNX，但运行配置使用 IK 后端。
• 默认 Rough 站姿为髋俯仰 0.670、膝关节 -1.390，源目录名中的 z=0.380 记录该阶段的机身高度配置意图。
• map_b.pcd 已确定性抽样到 10 MB 以下，点数和哈希见 map/README.md。
• TensorRT engine 与 JetPack、TensorRT 版本及 GPU 架构有关，其他机器应从 ONNX 重新生成。
• 源配置引用的 Odin map_a.bin 不在该备份中；使用 Relocalization 前必须从设备或建图备份补回真实文件并填写绝对路径，缺失时只能验证软件链路或使用后续 odom 配置。