[real] 整理最终比赛 ROS 2 Sim2Real 部署

.gitattributes

@@ -1,2 +0,0 @@
-# Keep structured point-cloud assets byte-identical across platforms.
-*.pcd -text

.gitignore

@@ -29,9 +29,10 @@ log/
 !05_software/real/sim2real/vendored/odin1_imu/build/
 !05_software/real/sim2real/vendored/odin1_imu/build/libodin1_imu_bridge.so
 !05_software/real/sim2real/vendored/odin1_imu/lib/*.a
-!05_software/real/sim2real_v2/vendored/odin1_imu/lib/*.a
-!05_software/real/sim2real_ros2_v2/src/odin_ros_driver/lib/*.a
-!05_software/real/sim2real_ros2_v3/src/odin_ros_driver/lib/*.a
+
+# Required vendored Odin SDK libraries in the final ROS 2 deployment
+!05_software/real/sim2real_ros2/src/odin_ros_driver/lib/liblydHostApi_arm.a
+!05_software/real/sim2real_ros2/src/odin_ros_driver/lib/liblydHostApi_amd.a
 
 # Training outputs
 logs/

01_doc/README.md

@@ -2,14 +2,13 @@
 
 本目录用于保存 16DOF 轮足项目自身的技术文档和使用说明。
 
-当前文档结构：
+后续建议按主题组织：
 
 ```text
 01_doc/
-├─ architecture/
-│  └─ early_software_stack.md  # 第一代训练—仿真—真机闭环
-├─ training_evolution.md       # v0.4～v0.6 训练架构演进
-└─ version_history.md          # 全项目 Tag 与里程碑
+├─ architecture/   # 系统架构和数据流
+├─ control/        # 控制与强化学习原理
+├─ deployment/     # Sim2Sim 和 Sim2Real 部署
+├─ hardware/       # 接线、标定和硬件兼容性
+└─ user_guide/     # 安装、运行和调试说明
 ```
-
-具体运行说明放在对应工程目录内，避免在顶层重复并逐渐失真：训练见 `05_software/train/rc_mjlab/`，真机部署见 `05_software/real/`。

01_doc/training_evolution.md

@@ -34,4 +34,4 @@
 比赛得分：1050
 ```
 
-`model_6800.onnx` 是比赛最终部署工件，不用模型编号替代训练代码版本号。它已随比赛部署归档；当前规范目录为 `05_software/real/sim2real_ros2_v3/policies/`。
+`model_6800.onnx` 是比赛最终部署工件，不用模型编号替代训练代码版本号。它将在最终比赛部署版本中与运行配置一起归档。

01_doc/version_history.md

@@ -1,6 +1,6 @@
 # 版本演进
 
-本项目使用里程碑 Tag 保存时间演进；同一架构的小步迭代不复制目录。ROS 2 的无后缀、`_v2`、`_v3` 目录分别代表三个架构大版本，并在 `v1.1.0` 中同时保留。
+本项目使用同一条 `16dof` 主线和里程碑 Tag 保存线性演进，不在源码目录中复制历史版本。
 
 | Tag | 阶段 | 核心内容 |
 | --- | --- | --- |
@@ -14,83 +14,7 @@
 | `v0.7.0` | MuJoCo 工具 | 姿态优化、IK 扫描、动力学、MPC 和 GUI 调试工具 |
 | `v0.8.0` | 后期 Sim2Sim | ONNX 回放、IK/路线检查工具和比赛最终 Rough 策略 |
 | `v0.8.1` | 导航打点工具 | 地图/航点编辑、路线迭代和抽样 PCD 补充包 |
-| `v0.9.0` | Python Sim2Real v2 | 反馈新鲜度、Odin odom 诊断、Web 调试和安全监控增强 |
-| `v0.10.0` | ROS 2/C++ 初版 | 50 Hz C++ 推理、200 Hz CAN 热路径和 ROS 2 系统集成 |
-| `v0.11.0` | ROS 2 导航原型 | 简单导航、PCD 交互定位、任务点和 Web 导航调试 |
-| `v0.11.1` | Odin 与站姿调参 | 完整 Odin 驱动、TensorRT、多策略切换和调参站姿 |
-| `v0.12.0` | 里程计导航联调 | 纯里程计 fallback、A_min 路线、TF 冲突保护和 model_9600 |
-| `v1.0.0` | 比赛最终部署初次归档 | last_not_slalom_1050、model_6800/model_84、最终路线和触控屏；当时暂存于无后缀目录 |
-| `v1.0.1` | 比赛成果媒体补充 | 最终机器人图片与 1050 分比赛视频 |
-| `v1.0.2` | 文档一致性修正 | 统一历史 Tag、当前快照和成果媒体的描述 |
-| `v1.1.0` | 三代目录规范化 | 恢复无后缀初版、保留 v2 里程计版、明确最终比赛 v3，并校准训练 README |
-
-> 原先临时归档为 `v0.9.0` 的最终 ROS 2/C++ 比赛部署已保存在 `backup/final-ros2-v0.9.0` 分支和 `backup-v0.9.0-ros2-final` 标签中，重排后已正式归入 `v1.0.0`。
-
-## `v0.9.0` 的 Python Sim2Real v2
-
-- 归档 `real/sim2real_v2` 真机部署版本，保持 `53D -> 16D` 策略观测和动作契约。
-- 增加电机反馈新鲜度判断、Odin odom 诊断、命令限加速度平滑和 Web 运行时诊断。
-- 保留 Python 策略运行时、ONNX/PT 模型、MJCF、Odin 接口、Web 工具和安全保护链路。
-- 排除运行日志、测试日志、临时 XML 和开发交接草稿；后续 ROS 2/C++ 版本另行归档。
-
-## `v0.10.0` 的 ROS 2/C++ Sim2Real 初版
-
-- 归档 `real/sim2real_ros2`，将 Python 部署契约迁移到 ROS 2 Humble 与 C++ 运行时。
-- 保留 53D 观测、16D 动作、50 Hz 策略循环和 200 Hz SocketCAN 电机热路径。
-- 增加消息接口、硬件桥、策略运行时、命令仲裁、Nav2 配置、Docker 和 Windows Web 调试工具。
-- 原始快照中的 `src/odin_ros_driver` 为空目录，因此本版本仍需外部 Odin 驱动，不能宣称传感器依赖已自包含。
-- 保留原始候选 ONNX 文件以记录初版部署试验；排除计划、任务和 walkthrough 草稿。
-
-## `v0.11.0` 的 ROS 2 Sim2Real v2
-
-- 归档 `real/sim2real_ros2_v2`，保持 `v0.10.0` 的 ROS 2/C++ 控制契约。
-- 增加 `simple_nav_node.py`、PCD 点击工具、任务点/任务序列配置和 Web 导航控制入口。
-- 默认命令源从遥控切换为 `NAV`，加入简单导航状态、PCD 位姿和地图显示链路。
-- 原始 `map1.pcd`、`map6.pcd` 分别约 49.05 MiB、44.24 MiB，归档时确定性抽样到 10 MB 以下并记录哈希。
-- 原始快照中的 Odin 驱动仍为空目录；排除设备运行日志和开发草稿。
-
-## `v0.11.1` 的 Odin、TensorRT 与站姿调参
-
-- 归档 `real/sim2real_ros2_v2(z=0.380 hip=0.670 knee=-1.390)`，在同一 `sim2real_ros2_v2` 目录中记录真实差异。
-- 首次随部署工程保留完整 Odin ROS 驱动、Apache-2.0 许可证、设备标定参数和预编译 SDK 静态库。
-- 策略运行时增加 TensorRT、ONNX 回退、Rough/Crawl 模式切换、事件日志和更完整的电机失效诊断。
-- 默认 Rough 策略为 `NEWmodel_1900`，默认站姿为髋俯仰 `0.670`、膝关节 `-1.390`；Crawl 配置使用 IK 后端。
-- `map_b.pcd` 从 1,080,047 点确定性抽样为 270,012 点，并保留原始和抽样哈希。
-- 排除嵌套 Git、Odin 运行日志、缓存、开发草稿和未被配置引用的候选策略。
-
-## `v0.12.0` 的里程计导航联调
-
-- 归档 `real/sim2real_ros2_v2(odom)`，继续沿用 `sim2real_ros2_v2` 目录的线性演进。
-- 将 Rough 策略切换为 `model_9600`，默认站姿恢复为髋俯仰 `0.550`、膝关节 `-1.125`。
-- Odin `custom_map_mode` 固定为纯里程计，加入 odom 新鲜度、外部 map/odom TF 冲突和任务结束交接保护。
-- 增加 A_min 路线、PCD 地图编辑工具和三份抽样点云；原始大 PCD 不直接进入 Git。
-- 保留完整 Odin 驱动、标定参数和 SDK 静态库；未找到的 `map_a.bin` 仍不伪造，重定位闭环不在本 Tag 声称已复现。
-
-## `v1.0.0` 的比赛最终部署
-
-- 首次归档原始 `sim2real_ros2_v2(last_not_slalom_1050)` 最终 ROS 2/C++ 真机工程；该 Tag 中暂存于无后缀 `real/sim2real_ros2`，目录命名在 `v1.1.0` 才修正为 `real/sim2real_ros2_v3`。`1050` 是比赛成绩，不是模型编号。
-- Rough 使用 `model_6800`，Wall 使用 `model_84`，Crawl 按比赛配置使用 IK 后端。
-- 保留最终五份路线、1 号场地抽样 PCD、Odin 驱动、CAN 硬件桥、命令仲裁、导航和 Orin 触控屏 UI。
-- 最终配置默认命令源为 `NAV`、定位模式为 `relocal`，但真实 Odin `1hao.bin` 不在备份中，重定位闭环需要从比赛设备补回。
-- 排除嵌套 Git、日志、备份、候选策略、构建产物和开发草稿；TensorRT engine 仅代表比赛机环境。
-
-## `v1.0.1` 的比赛成果媒体补充
-
-- 保持 `v1.0.0` 的比赛最终代码和部署内容不变。
-- 补充最终机器人图片和比赛视频，成绩为 1050 分、第七名（前 5%）。
-- 代码复现可查看 `v1.0.0`，包含成果媒体的对应快照可查看 `v1.0.1`。
-
-## `v1.0.2` 的文档一致性修正
-
-- 统一 ROS 2 历史 Tag、当前工作树和媒体补丁的说明。
-- 该版本仅修正文档，没有改变训练或真机运行代码。
-
-## `v1.1.0` 的目录与说明规范化
-
-- 从 `v0.10.0` 恢复无后缀 `sim2real_ros2` 初版快照。
-- `sim2real_ros2_v2` 保持 `v0.12.0` 里程计联调快照。
-- 将 `last_not_slalom_1050` 最终比赛部署正式命名为 `sim2real_ros2_v3`。
-- 依据当前源码重新校准 `rc_mjlab` README 中的物理步长、控制频率、环境数、执行器、地形、奖励和随机化说明。
+| `v0.9.0` | 最终比赛部署 | ROS 2/C++ 真机闭环、Odin、CAN、导航与屏幕 UI |
 
 ## `v0.4.0` 的模型变化
 
@@ -148,3 +72,13 @@
 - 补充 `1hao.xml`、`2hao.xml`、`A_C.xml`，并为 `1B_FF.json` 补齐其引用的 `B_C.xml`。
 - 将两份约 915 MiB 的原始 ASCII PCD 确定性抽样为各小于 10 MB 的预览点云；抽样参数、点数和哈希记录在工具 README。
 - 训练代码、MJCF、比赛策略和历史依赖锁保持 `v0.8.0` 状态不变。
+
+## `v0.9.0` 的最终比赛部署
+
+- 归档比赛得分 1050 所对应的 `last_not_slalom_1050` ROS 2 工作区；1050 是成绩，不是策略编号。
+- 保留 53D→16D C++ 策略运行时、200 Hz CAN 硬件桥、命令仲裁、安全监控和统一启动包。
+- 保留 Rough `model_6800`、Wall `model_84` 的 ONNX 与比赛 TensorRT engine；Crawl 使用 IK 后端。
+- 保留 Odin ROS 驱动及 Apache-2.0 许可证、五份比赛路线、抽样 PCD 和 Orin 触控屏 UI。
+- 排除嵌套 Git、缓存、日志、备份、候选模型、开发草稿和重复地图工具。
+- 原始备份缺少配置所引用的 Odin `1hao.bin`，因此重定位模式仍需从比赛设备补回该外部资产；纯里程计模式不受此限制。
+- 自研 ROS 包仍保留原工程的 `Proprietary` 清单字段，公开到 GitHub 前必须由权利人统一选择开源许可证。

03_hardware/README.md

@@ -3,5 +3,3 @@
 本目录用于保存 16DOF 轮足机器人的自研电路、接线图、BOM、传感器与计算平台说明。
 
 第三方硬件资料不作为自研成果提交。
-
-当前目录仅有范围说明，尚未归档 16DOF 平台的自研原理图、PCB、BOM 或正式接线图，不应将本目录视为已完成的硬件开源包。

04_firmware/README.md

@@ -3,5 +3,3 @@
 本目录用于保存运行在 MCU 或其他嵌入式控制器上的固件源码和构建工程。
 
 编译生成的 `.hex`、`.bin`、`.elf`、`.axf` 等文件不进入源码目录，可在需要时作为 Release 附件发布。
-
-当前 16DOF 主线尚未在本目录归档 MCU/Keil 工程；该目录是预留入口。8DOF 大疆 A 板 Keil 工程由 `8dof` 分支和 `v0.1.0` 保存。

05_software/README.md

@@ -9,14 +9,9 @@
 └─ real/
    ├─ ik_real/        # IK 轨迹与早期真机控制
    ├─ sim2real/       # 第一代 Python 策略真机部署
-   ├─ sim2real_v2/    # Python Sim2Real v2
-   ├─ sim2real_ros2/  # ROS 2/C++ Sim2Real 初版
-   ├─ sim2real_ros2_v2/ # ROS 2 导航原型及里程计演进
-   └─ sim2real_ros2_v3/ # 最终比赛 ROS 2/C++ 部署
+   └─ sim2real_ros2/  # 最终比赛 ROS 2/C++ 真机部署
 ```
 
-当前工作树按架构大版本同时保留三个 ROS 2 目录：无后缀目录是初版，`_v2` 是第二版演进的最终里程计快照，`_v3` 是 `last_not_slalom_1050` 最终比赛部署。各目录内部的小阶段仍可通过对应 Tag 恢复。
-
 ## 数据流
 
 ```text
@@ -29,14 +24,14 @@ MJCF + mjlab task
         |
         +----> Sim2Sim 策略验证
         |
-        +----> Python Sim2Real / v2 ----> 电机 / IMU
+        +----> Python Sim2Real ----> 电机 / IMU
         |
-        +----> ROS 2/C++ Sim2Real -----> CAN / IMU / 导航
+        +----> ROS 2/C++ Sim2Real -> CAN / Odin / 导航 / 屏幕
 
 IK real --------------------------------> 电机
 ```
 
-`rc_mjlab` 是自包含工程。训练、MJCF、MuJoCo、Sim2Sim、导航工具和策略权重通过相对路径绑定，因此保留其内部布局，没有为了目录外观拆散。第一代完整闭环见 `v0.3.0`，第一份新版 MJCF 与训练框架见 `v0.4.0`，随机化增强版见 `v0.5.0`，比赛最终训练架构见 `v0.6.0`，后期 MuJoCo 工具集见 `v0.7.0`，后期 Sim2Sim 与比赛 Rough 策略见 `v0.8.0`，完整导航打点工具见 `v0.8.1`，Python Sim2Real v2 对应 `v0.9.0`，ROS 2/C++ 初版对应 `v0.10.0`，简单导航原型对应 `v0.11.0`，完整 Odin/TensorRT 与站姿调参对应 `v0.11.1`，纯里程计导航联调对应 `v0.12.0`，1050 分比赛最终部署对应 `v1.0.0`。
+`rc_mjlab` 是自包含工程。训练、MJCF、MuJoCo、Sim2Sim、导航工具和策略权重通过相对路径绑定，因此保留其内部布局，没有为了目录外观拆散。第一代完整闭环见 `v0.3.0`，第一份新版 MJCF 与训练框架见 `v0.4.0`，随机化增强版见 `v0.5.0`，比赛最终训练架构见 `v0.6.0`，后期 MuJoCo 工具集见 `v0.7.0`，后期 Sim2Sim 与比赛 Rough 策略见 `v0.8.0`，完整导航打点工具见 `v0.8.1`，最终比赛 ROS 2 部署见 `v0.9.0`。
 
 详细说明见：
 

05_software/real/README.md

@@ -1,6 +1,6 @@
-# 真机控制版本演进
+# 真机控制与部署
 
-本目录保存 16DOF 轮足机器人从早期 Python 闭环到 ROS 2 部署的真机控制演进。
+本目录保存 16DOF 轮足机器人从早期接口验证到最终比赛 ROS 2 部署的演进。
 
 ## `ik_real`
 
@@ -20,29 +20,17 @@
 
 部署说明见 [`sim2real/README.md`](sim2real/README.md) 与 [`sim2real/DEPLOYMENT.md`](sim2real/DEPLOYMENT.md)。
 
-## `sim2real_v2`
+## `sim2real_ros2`
 
-Python Sim2Real v2，保留 `53D -> 16D` 策略接口，并增加电机反馈新鲜度、Odin odom 诊断、命令平滑、Web 运行时诊断和安全监控工具，对应 `v0.9.0`。
+`last_not_slalom_1050` 最终比赛工程的规范化归档，包含：
 
-部署说明见 [`sim2real_v2/README.md`](sim2real_v2/README.md) 与 [`sim2real_v2/DEPLOYMENT.md`](sim2real_v2/DEPLOYMENT.md)。
+- ROS 2 Humble + C++ 运行时
+- 50 Hz 策略推理与 200 Hz CAN 电机热路径
+- Rough `model_6800`、Wall `model_84` 和 Crawl IK 模式
+- Odin IMU/里程计驱动、简单导航、命令仲裁和触控屏 UI
+- 比赛路线、抽样 PCD、Docker 与部署说明
 
-## ROS 2/C++ 版本线
-
-### `sim2real_ros2`（初版，`v0.10.0`）
-
-无后缀目录固定表示 ROS 2/C++ Sim2Real 初版：将策略热路径迁移为 50 Hz C++ 推理和 200 Hz CAN 电机循环，并加入 ROS 2 消息、命令仲裁、Nav2 与统一启动结构。原始快照未随工程保存 Odin ROS 2 驱动源码，依赖边界见 [`sim2real_ros2/README.md`](sim2real_ros2/README.md)。
-
-### `sim2real_ros2_v2`（`v0.11.0`～`v0.12.0`）
-
-在 `v0.11.0` 中，该目录是 ROS 2 Sim2Real v2 导航原型，增加简单导航节点、PCD 交互定位、任务点/任务序列和 Web 导航调试。
-
-`v0.11.1` 在同一路径继续演进，首次归档完整 Odin 驱动、TensorRT、多策略切换和硬件诊断，并使用 `hip=0.670`、`knee=-1.390` 的调参站姿。
-
-`v0.12.0` 仍在同一路径上形成里程计导航联调快照：固定纯里程计模式，加入 odom fallback 的 TF 冲突保护、A_min 路线和多地图工具；默认 Rough 策略为 `model_9600`，默认站姿回到比赛站姿。当前该目录保持 `v0.12.0` 快照，阶段说明见 [`sim2real_ros2_v2/README.md`](sim2real_ros2_v2/README.md)。
-
-### `sim2real_ros2_v3`（最终比赛版；代码快照 `v1.0.0`，规范目录 `v1.1.0`）
-
-第三版来自原始目录 `sim2real_ros2_v2(last_not_slalom_1050)`，整理时正式命名为 `sim2real_ros2_v3`。它是 1050 分比赛最终部署，包含 `model_6800` Rough、`model_84` Wall、最终路线、完整 Odin 驱动、CAN 和触控屏。部署说明见 [`sim2real_ros2_v3/README.md`](sim2real_ros2_v3/README.md)。
+`1050` 是比赛得分，不是模型编号。完整入口与缺失的 Odin 重定位地图边界见 [`sim2real_ros2/README.md`](sim2real_ros2/README.md)。
 
 ## 实机记录
 

05_software/real/sim2real/DEPLOYMENT.md

@@ -1,12 +1,10 @@
 # `sim2real` 部署说明
 
-> 版本范围：第一代 Python Sim2Real（`v0.3.0`）。本文“当前”均指该快照。
-
 ## 模型
 
 当前只使用：
 
-- `policies/model_rough.pt`
+- `sim2real/policies/model_rough.pt`
 
 ## 模型契约
 
@@ -40,7 +38,7 @@
 
 ## 纯 Python 命令
 
-默认前提：当前目录是 `05_software/real/sim2real/`
+默认前提：当前目录就是 `sim2real/`
 
 ```bash
 python -m pip install -r requirements-orin.txt

05_software/real/sim2real/FACTS_AND_ASSUMPTIONS.md

@@ -1,11 +1,9 @@
 # `FACTS_AND_ASSUMPTIONS`
 
-> 版本范围：第一代 Python Sim2Real（`v0.3.0`）。事实项只适用于该快照。
-
 ## 已确认
 
-- 当前部署模型：`policies/model_rough.pt`
-- 原始说明记录的源模型名：`model_2000.pt`；同名文件未随本目录归档
+- 当前部署模型：`sim2real/policies/model_rough.pt`
+- 源模型：`model_2000.pt`
 - actor 输入：`53D`
 - actor 输出：`16D`
 - 当前 actor 不吃 `base_lin_vel`

05_software/real/sim2real/ORIN_NANO_DEPLOYMENT.md

@@ -1,7 +1,5 @@
 # `Orin Nano` 部署说明
 
-> 版本范围：第一代 Python Sim2Real（`v0.3.0`）。本文不是最终 ROS 2 v3 部署指南。
-
 ## 是否必须转 ONNX
 
 不必须。
@@ -28,7 +26,7 @@
 
 ## 纯 Python 部署命令
 
-默认前提：当前目录是 `05_software/real/sim2real/`
+默认前提：当前目录就是 `sim2real/`
 
 ```bash
 python3 -m pip install -r requirements-orin.txt

05_software/real/sim2real/README.md

@@ -1,13 +1,11 @@
 # `sim2real`
 
-本目录是第一代 Python Sim2Real 快照，对应 `v0.3.0`。下文“当前”均指该历史快照，不指仓库 `main` 的最终 ROS 2 v3。
-
-该快照只部署当时的 `53D -> 16D` Rough 模型，不兼容更早的 Crawl、多策略和其他历史观测契约。
+当前版本只部署现在这套 `53D -> 16D` 模型，不再兼容旧版 `crawl`、多策略和历史观测。
 
 ## 当前部署模型
 
-- 使用文件：`policies/model_rough.pt`
-- 原始说明记录的来源名：`model_2000.pt`；该同名源文件未随本目录归档，仓库只保留重命名后的 `policies/model_rough.pt`
+- 使用文件：`sim2real/policies/model_rough.pt`
+- 来源文件：`model_2000.pt`
 
 ## 当前 actor 输入
 
@@ -54,7 +52,7 @@
 
 ## 启动命令
 
-默认前提：当前目录是 `05_software/real/sim2real/`
+默认前提：当前目录就是 `sim2real/`
 
 纯 `python`：
 
@@ -67,12 +65,13 @@ python main.py
 python web/server.py --host 0.0.0.0 --port 8080
 ```
 
-Windows 本机可使用目标虚拟环境中的 Python；不要依赖个人机器的绝对安装路径：
+Windows 本机：
 
 ```bash
-python -m pip install -r requirements-orin.txt
-python tools\alignment_check.py --policy policies\model_rough.pt --manifest deployment_manifest.yaml
-python tools\standalone_check.py
-python main.py
-python web\server.py --host 0.0.0.0 --port 8080
+D:\Minicoda3\envs\py10\python.exe -m pip install -r requirements-orin.txt
+D:\Minicoda3\envs\py10\python.exe tools\alignment_check.py --policy policies\model_rough.pt --manifest deployment_manifest.yaml
+D:\Minicoda3\envs\py10\python.exe tools\standalone_check.py
+D:\Minicoda3\envs\py10\python.exe main.py
+D:\Minicoda3\envs\py10\python.exe web\server.py --host 0.0.0.0 --port 8080
 ```
+#sim2real/policies/model_rough.pt

05_software/real/sim2real_ros2/.gitignore

@@ -1,6 +1,14 @@
 build/
 install/
 log/
+logs_v2_web/
+map/load/
+src/odin_ros_driver/log/
+src/odin_ros_driver/recorddata/
+src/odin_ros_driver/image/
+*.bak_*
+__pycache__/
+*.py[cod]
 .colcon/
 .vscode/
 compile_commands.json

05_software/real/sim2real_ros2/DEPLOYMENT_GUIDE.md

@@ -1,6 +1,6 @@
-# ROS 2/C++ Sim2Real 初版部署指南
+# ROS2 C++ Sim2Real 运动控制栈 - 部署指南
 
-本工作区保存 `v0.10.0` 的 ROS 2 Humble/C++ 初版。控制栈主体源码已归档，但 Odin 驱动源码在该快照中缺失，因此不是自包含部署包；完成真实传感器闭环前必须补充兼容驱动。
+本工作区提供了一个自包含、独立的 C++ ROS2 Humble 实现，用于在 Jetson Orin 目标机上部署轮腿四足机器人控制策略。
 
 ---
 
@@ -156,7 +156,7 @@ sudo udevadm trigger
 统一启动文件 `sim2real_system.launch.py` 支持模块化激活传感器驱动和 Nav2 导航栈：
 
 * `launch_driver`（默认：`true`）：启动 `odin_ros_driver` 节点以获取 IMU 和点云遥测。
-* `launch_nav2`（默认：`true`）：启动 ROS2 Navigation2 规划器、控制器、costmap、AMCL 和 pointcloud_to_laserscan。
+* `launch_nav2`（默认：`false`）：按需启动 ROS2 Navigation2；比赛默认使用 `simple_nav_node.py` 的路线跟踪。
 
 #### 1. 完整真实硬件闭环（默认）
 启动运动控制运行时、物理 CAN 桥接、Odin 传感器驱动和 Nav2 导航：
@@ -175,4 +175,3 @@ ros2 launch sim2real_bringup sim2real_system.launch.py dry_run:=true launch_driv
 ```bash
 ros2 launch sim2real_bringup sim2real_system.launch.py launch_driver:=false launch_nav2:=false
 ```
-

05_software/real/sim2real_ros2/Dockerfile

@@ -62,6 +62,7 @@ COPY src/sim2real_nav2 sim2real_nav2
 # 拷贝策略文件与运行脚本
 WORKDIR /sim2real_ws
 COPY policies policies
+COPY map map
 COPY start_sim2real.sh start_sim2real.sh
 RUN chmod +x start_sim2real.sh
 

05_software/real/sim2real_ros2/README.md

@@ -1,74 +1,104 @@
-# ROS 2/C++ Sim2Real 初版
+# ROS 2 最终比赛 Sim2Real
 
-本目录归档 `real/sim2real_ros2`，对应 `v0.10.0`。这是轮腿机器人 Sim2Real 部署栈从 Python 运行时迁移到 ROS 2 + C++ 的第一版系统工程。
+本目录归档 `last_not_slalom_1050` 真机工程，对应 RC_WheelLeg 在 RoboCon 仿生足式障碍赛使用的最终 ROS 2 部署栈。`1050` 是比赛得分，不是模型编号；比赛 Rough 策略为 `model_6800.onnx`。
 
-本工程保留当前 `sim2real` 已验证的部署契约，同时将运行时热路径迁移到 C++：
+该里程碑计划标记为 `v0.9.0`。训练架构和策略来源见 `v0.6.0`，比赛 Rough 模型首次归档见 `v0.8.0`，导航打点与路线演进见 `v0.8.1`。
 
-- `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`
-  仅保留依赖边界说明；原始 `v0.10.0` 快照没有归档 Odin 驱动源码，不能独立提供 IMU、点云和里程计发布。
-- `docs`
-  架构说明与迁移计划。
-
-## 目标架构
+## 系统闭环
 
 ```text
-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)
+Odin IMU / Odom ──> hardware bridge ──> RuntimeState
+                                              |
+导航 / 遥控 / 屏幕 ──> cmd mux ──> policy runtime (50 Hz)
+                                              |
+                                      RuntimeTarget
+                                              |
+                              hardware bridge / CAN (200 Hz)
 ```
 
-## 当前状态
+核心约束：
 
-已完成 Phase 0-5 的全部迁移：
+- 53 维策略观测、16 维动作输出。
+- Rough：`model_6800`，优先 TensorRT，失败时回退 ONNX Runtime。
+- Wall：`model_84`，同样保留 TensorRT 与 ONNX 两种文件。
+- Crawl：比赛配置使用解析 IK，不加载 Crawl RL 权重。
+- 默认站姿：髋俯仰 `0.550`、膝关节 `-1.125`。
+- 默认命令源：`NAV`；默认定位模式：`relocal`。
 
-1. ✅ 冻结部署契约（deployment_contract.hpp）
-2. ✅ ROS 2 包结构搭建
-3. ✅ 硬件热路径迁移至 C++（SocketCAN 驱动、200Hz 电机循环）
-4. ✅ ONNX 策略运行时迁移至 C++（50Hz 推理循环）
-5. ✅ 导航与诊断通过 ROS 2 接入（Nav2 + odom_relay + TF）
+## 目录
 
-## 契约来源
+```text
+sim2real_ros2/
+├─ src/
+│  ├─ sim2real_interfaces/  # RuntimeState / RuntimeTarget 消息
+│  ├─ sim2real_common/      # 部署契约、滤波、平衡和安全监控
+│  ├─ sim2real_hw/          # SocketCAN、IMU 和 200 Hz 电机热路径
+│  ├─ sim2real_runtime/     # 策略、命令仲裁、导航、Web API
+│  ├─ sim2real_nav2/        # Nav2 配置入口
+│  ├─ sim2real_bringup/     # 统一参数和启动文件
+│  └─ odin_ros_driver/      # Odin ROS 驱动（Apache-2.0）
+├─ policies/                # 比赛实际使用的 Rough / Wall 模型
+├─ map/                     # 比赛路线和抽样 PCD
+├─ screen/                  # Orin 800×600 触控面板
+├─ docs/                    # 架构、遥控、Web 和迁移说明
+├─ Dockerfile
+└─ start_sim2real.sh
+```
 
-迁移过程中以下文件被视为真值源：
+## 构建与运行
 
-- `../sim2real/deployment_manifest.yaml`
-- `../sim2real/interface/motor_mapping.py`
-- `../sim2real/interface/real_io.py`
-- `../sim2real/policy/policy_runner.py`
-- `../sim2real/web/session.py`
+目标环境是 Ubuntu 22.04、ROS 2 Humble 和 Jetson Orin。系统依赖和 Docker 流程见 [`DEPLOYMENT_GUIDE.md`](DEPLOYMENT_GUIDE.md)。
 
-## 注意事项
+```bash
+cd 05_software/real/sim2real_ros2
+colcon build --merge-install --cmake-args -DCMAKE_BUILD_TYPE=Release
+./start_sim2real.sh
+```
 
-- 开发目标为 Linux + ROS 2 Humble，运行于 Jetson Orin / x86_64。
-- Windows 仅作为编辑环境使用。
-- 观测顺序、动作缩放、默认站姿、电机映射不得独立修改，
-  除非训练与部署同步更新。
-- 原始快照中的 `src/odin_ros_driver` 是空目录，本版本仍需要另行提供兼容的 Odin ROS 2 驱动；其源码从后续版本开始随工程归档。
-- 自研 ROS 包保留原始 `Proprietary` 清单字段，公开发布前仍需统一许可证和维护者信息。
+运行参数和模型/路线均使用工作区根目录相对路径，因此应从本目录启动。常用启动覆盖：
+
+```bash
+# 纯里程计模式，不等待 Odin 重定位地图
+./start_sim2real.sh localization_mode:=odom \
+  odin_config_file:=src/odin_ros_driver/config/control_command_odom.yaml
+
+# 禁止驱动，仅做软件链路检查
+./start_sim2real.sh launch_driver:=false launch_remote:=false
+```
+
+## 必须补充的部署资产
+
+最终源目录配置引用了 Odin `map/1hao.bin`，但工作区备份中不存在这个文件；全盘检索也未找到同名文件。为避免用来源不明的 `.bin` 冒充比赛地图，本仓库不伪造该资产。
+
+使用 `relocal` 前必须：
+
+1. 从比赛 Orin 或 Odin 建图备份取得真实 `1hao.bin`。
+2. 修改 `src/odin_ros_driver/config/control_command_relocal.yaml` 中的 `relocalization_map_abs_path` 为目标机绝对路径。
+3. 核对文件哈希并在发布说明中补充来源。
+
+缺少该文件时请使用 `localization_mode:=odom`，不要宣称重定位闭环已复现。地图和路线边界见 [`map/README.md`](map/README.md)。
+
+## 归档边界
+
+已保留：
+
+- 最终六个 ROS 2 包、Odin 驱动源码、比赛设备标定参数和预编译 SDK 静态库。
+- 最终 Rough/Wall ONNX 与比赛机 TensorRT engine。
+- 五份最终工程路线、1 号场地抽样 PCD、屏幕 UI 和启动脚本。
+- Odin 驱动 Apache-2.0 许可证。
+
+未保留：
+
+- 嵌套 `.git`、`__pycache__`、日志、备份、构建/安装目录。
+- 未被比赛配置引用的候选模型与候选 TensorRT engine。
+- 开发计划、任务草稿、重复地图工具和运行时轨迹。
+- 原备份中大小为 0 的浏览器静态页面；HTTP JSON API 和屏幕 UI 源码仍保留。
+
+TensorRT engine 与 JetPack、TensorRT 版本及 GPU 架构有关；其他机器应从同名 ONNX 重新生成，不应默认复用比赛 engine。模型哈希见 [`policies/README.md`](policies/README.md)。
+
+## 安全与开源状态
+
+- 真机运行前必须架空轮组验证 CAN 映射、方向、零位、急停和限幅。
+- `deployment_contract.hpp` 是电机映射和动作缩放真值源；参考 YAML 不会自动修改 C++ 契约。
+- 自研 ROS 包的 `package.xml` 仍保留原工程的 `Proprietary` 字段。迁移到 GitHub 公共开源前，需要由项目负责人选择许可证并统一修改；本次整理不代替权利人作许可证决定。
+- 当前 Windows 环境只能做静态检查，不能证明 ROS 2、SocketCAN、Odin SDK 或 TensorRT 真机运行成功。

05_software/real/sim2real_ros2/docs/MIGRATION_PLAN.md

@@ -1,7 +1,5 @@
 # 迁移计划
 
-> 版本范围：ROS 2/C++ 初版（`v0.10.0`）。这是历史迁移记录，不是最终比赛版验收报告；本快照未归档 Odin 驱动源码。
-
 ## Phase 1: 硬件核心迁移 ✅ 已完成
 
 将当前高频热路径从 Python 迁出。
@@ -41,7 +39,11 @@
 
 ## Phase 3: ROS 2 系统集成 ✅ 已完成
 
-参考过的外部项目包括 Odin ROS 驱动、EDULITE A3 ROS 工程和 RL-SAR；这些外部参考目录不属于本仓库公开内容。
+参考的源项目：
+
+- `00_ reference/odin_ros_driver`
+- `00_ reference/EDULITE_A3/el_a3_ros`
+- `00_ reference/rl_sar`
 
 交付物：
 
@@ -74,5 +76,5 @@
 | 策略运行时 | `sim2real_runtime_node` | 50Hz ONNX 推理 + 53D 观测 + raw_action clip |
 | 里程计中继 | `odom_relay_node` | /odin1/odometry → /odom + odom→base_link TF |
 | 导航栈 | Nav2 全套节点 | AMCL + costmap + DWB + Navfn + BT + lifecycle |
-| 传感器驱动 | 外部 Odin 驱动 | 本快照未归档源码，不能视为自包含组件 |
-| 点云转换 | `pointcloud_to_laserscan` | 外部 ROS 包；/odin1/cloud_slam → /scan（供 AMCL 使用） |
+| 传感器驱动 | `odin_ros_driver` | IMU + 点云 + 里程计原始发布 |
+| 点云转换 | `pointcloud_to_laserscan` | /odin1/cloud_slam → /scan (供 AMCL 使用) |

05_software/real/sim2real_ros2/docs/REMOTE_CONTROL_USAGE.md

@@ -21,7 +21,7 @@ src/sim2real_runtime/src/remote_uart_node.py
 
 ## 2. 通道映射
 
-通道映射与前一阶段 Python Sim2Real 中的遥控器实现保持一致。
+通道映射与本仓库第一代 Python Sim2Real 实现中的遥控器配置保持一致。
 
 | 遥控器通道 | ROS 2 输出 | 含义 | 默认最大值 |
 |---|---|---|---:|
@@ -64,6 +64,10 @@ remote_invert_vy: false
 remote_invert_yaw: true
 remote_publish_inactive_zero: true
 remote_estop_latch: true
+remote_estop_channel: 7
+remote_estop_level: "high"
+remote_estop_debounce_frames: 3
+remote_estop_require_remote_mode: true
 remote_poll_hz: 50.0
 ```
 
@@ -276,7 +280,7 @@ ros2 launch sim2real_bringup sim2real_system.launch.py launch_nav2:=false
 /safety/estop: true
 ```
 
-由于当前 `remote_estop_latch: true`，急停是锁存式行为：一旦 CH7 高位触发，节点会发布急停，并保持内部急停已触发状态。恢复运行通常需要重启系统或手动发布复位信号，并确认机器人安全。
+由于当前 `remote_estop_latch: true`，急停是锁存式行为：在 `REMOTE` 模式下，CH7 连续 3 帧有效高位后，节点会发布急停，并保持内部急停已触发状态。恢复运行通常需要重启系统或手动发布复位信号，并确认机器人安全。
 
 ### 8.4 机器人行为效果
 

05_software/real/sim2real_ros2/docs/competition_yaw_configuration.md

@@ -115,7 +115,7 @@ ros2 param get /sim2real_simple_nav_node nav_goal_yaw_tolerance_deg
 # 应该显示: 8.0
 
 # 3. 加载路线
-# 当前归档默认使用: sim2real_ros2_v3/map/routes/1hao_reall.json
+# 使用: sim2real_ros2_v2_ooo/map/routes/points_nav1007_optimized.json
 
 # 4. 监控
 ros2 topic echo /cmd_vel_nav

05_software/real/sim2real_ros2/image/cam_in_ex.txt

@@ -1,20 +0,0 @@
-Tcl_0: [-0.009160, -0.999960, 0.000320, 0.032150, 
-        0.002390, -0.000340, -1.000000, -0.011850, 
-        0.999960, -0.009160, 0.002390, 0.005360, 
-        0.000000, 0.000000, 0.000000, 1.000000]
-cam_0: 
-   image_width: 1600
-   image_height: 1296
-   k2: 0.000656
-   k3: -0.028961
-   k4: 0.045390
-   k5: -0.064513
-   k6: 0.038735
-   k7: -0.009903
-   p1: 0.000000
-   p2: 0.000000
-   A11: 736.894262
-   A12: -0.161150
-   A22: 736.611354
-   u0: 806.125535
-   v0: 639.650710

05_software/real/sim2real_ros2/map/README.md

@@ -4,8 +4,6 @@
 
 `1hao.pcd` 是 `v0.8.1` 导航工具中同一份抽样点云，包含 199,215 点、大小 9,876,010 字节，SHA-256 为 `48B231C52BECA51316F352300C8B2046133E92359E0855227D93DEB0D927AD34`。它用于本地规划和路线显示，不替代原始高密度点云。
 
-上述大小和 SHA-256 按 Git 中保存的 LF 字节计算；根目录 `.gitattributes` 禁止对 `*.pcd` 做跨平台换行转换。
-
 ## 缺失的 Odin 重定位地图
 
 比赛配置需要 Odin 专用二进制地图 `1hao.bin`，但源备份没有该文件。源目录中另有两个名称和时间不同的 `.bin`，无法证明它们就是比赛使用地图，因此没有复制或重命名。

05_software/real/sim2real_ros2/screen/README.md

@@ -3,7 +3,7 @@
 `fullscreen_quit.py` 是比赛 Orin 外接 `800×600` 屏幕使用的控制面板，通过本机 `http://127.0.0.1:18080/api/*` 调用 ROS 2 Web bridge，不建立第二套控制协议。
 
 ```bash
-cd <sim2real_ros2_v3工作区>
+cd <sim2real_ros2工作区>
 DISPLAY=:0 python3 screen/fullscreen_quit.py
 ```
 

05_software/real/sim2real_ros2/src/odin_ros_driver/README.md

@@ -1,5 +1,821 @@
-# Odin 驱动依赖占位
+# Odin_ROS_Driver Readme
 
-`real/sim2real_ros2` 原始快照中的 `src/odin_ros_driver` 为空目录，但启动文件、Dockerfile 和 `sim2real_bringup` 已经引用该包。
+ROS driver suite for Odin sensor modules (Manifold Tech Ltd.) 
 
-因此 `v0.10.0` 记录的是 ROS 2/C++ 迁移初版，不能仅凭本目录宣称 Odin 驱动可独立构建。兼容的 Odin ROS 2 驱动源码从后续版本开始随工程归档。
+Odin1 wiki: https://manifoldtechltd.github.io/wiki/Odin1/Cover.html
+
+## Odin_ROS_Driver
+
+Compatibility:
+
+● ROS 1(LTS Release: Noetic recommended)
+
+● ROS 2(LTS Release: Humble recommended)
+
+## Important Notice:
+
+This driver package provides core functionality for point cloud SLAM applications and targets specific use cases. It is intended exclusively for technical professionals conducting secondary development. End users must perform scenario-specific optimization and custom development to align with operational requirements in practical deployment environments.
+
+## 1. Version
+
+Current version: v0.12.0
+
+Required device firmware version: v0.12.0
+
+## 2. Preparation
+
+### 2.1 OS Requirement
+
+● Ubuntu 20.04 for ROS Noetic and ROS2 Foxy;
+
+● Ubuntu 22.04 for ROS2 Humble;
+
+● Ubuntu 18.04 is currently not supported;
+
+● Ubuntu 24.04 is not officially supported but may work with some modifications.
+
+### 2.2 Dependencies
+
+● Opencv >= 4.2.0(recommand 4.5.5/4.8.0. Make sure only one version of opencv is installed)
+
+● yaml-cpp
+
+● thread
+
+● OpenSSL
+
+● Eigen3
+
+### 2.3 Dependencies Install
+
+#### 2.3.1 System
+```shell
+sudo apt update
+sudo apt-get install build-essential cmake git libgtk2.0-dev pkg-config libavcodec-dev libavformat-dev libswscale-dev
+```
+
+#### 2.3.2 yaml-cpp
+```shell
+sudo apt update
+sudo apt install -y libyaml-cpp-dev
+```
+
+#### 2.3.3 libusb
+```shell
+sudo apt update
+sudo apt install -y libusb-1.0-0-dev
+```
+
+#### 2.3.4 opencv
+```shell
+sudo apt update
+sudo apt-get install libopencv-dev
+```
+
+#### 2.3.4 ROS install
+
+For ROS Noetic installation, please refer to:
+[ROS Noetic installation instructions](https://wiki.ros.org/noetic/Installation)
+
+For ROS2 Foxy installation, please refer to:
+[ROS Foxy installation instructions](https://docs.ros.org/en/foxy/Installation/Ubuntu-Install-Debians.html)
+
+For ROS2 Humble installation, please refer to:
+[ROS Humble installation instructions](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html)
+
+## 3. Preparation
+
+### 3.1 Create Udev rules 
+```shell
+sudo vim /etc/udev/rules.d/99-odin-usb.rules
+```
+Add the following content to the 99-odin-usb.rules file
+```shell
+SUBSYSTEM=="usb", ATTR{idVendor}=="2207", ATTR{idProduct}=="0019", MODE="0666", GROUP="plugdev"
+```
+Reload rules and reinsert devices
+```shell
+sudo udevadm control --reload
+sudo udevadm trigger
+```
+### 3.2 OS Requirement
+```shell
+git clone https://github.com/manifoldsdk/odin_ros_driver.git catkin_ws/src/odin_ros_driver
+```
+Note:
+Please clone the source code into the "[ros_workspace]/src/" folder, otherwise compilation errors will occur.
+
+### 3.3 make
+
+#### 3.3.1 ROS1 (Noetic for example):
+
+```shell
+source /opt/ros/noetic/setup.bash
+./script/build_ros.sh
+```
+
+#### 3.3.2 ROS2 (Foxy for example):
+
+```shell
+source /opt/ros/foxy/setup.bash
+./script/build_ros2.sh
+```
+
+### 3.4 run:
+
+#### 3.4.1 ROS1 (Noetic for example):
+
+```shell
+source [ros_workspace]/devel/setup.bash
+roslaunch odin_ros_driver [launch file]
+```
+● odin_ros_driver: package name;
+
+● launch file: launch file;
+
+● ros_workspace: User's ROS environment workspace;
+```shell
+roslaunch odin_ros_driver odin1_ros1.launch
+```
+#### 3.4.2 ROS2 (Foxy for example):
+
+```shell
+source [ros2_workspace]/install/setup.bash
+ros2 launch odin_ros_driver [launch file]
+```
+● odin_ros_driver: package name;
+
+● launch file: launch file;
+
+● ros2_workspace: User's ROS2 environment workspace;
+
+ROS2 Demo Launch Instructions:
+```shell
+ros2 launch odin_ros_driver odin1_ros2.launch.py
+```
+
+### 3.5 Operation Mode:
+
+The operation mode can be configured via the `custom_map_mode` parameter in config/control_command.yaml.
+
+#### Odometry mode
+
+Set `custom_map_mode = 0` to enable odometry mode. In this mode, the map frame and odom frame share the same pose.
+
+If the odom data is found to drift, the script command "./set_param.sh algo_reset 1" can be used to dynamically reset the algorithm.
+
+#### SLAM mode
+
+Set `custom_map_mode = 1` to enable slam mode. This mode provides a complete SLAM system that builds upon the Odometry Mode by adding **loop closure detection** and **map saving** capabilities.
+
+After launching the driver, odin1 will automatically perform mapping and cache map data. When the scene capture is complete, users need to execute `./set_param.sh save_map 1` in the driver's source directory to save all map data collected since the program started. The map will be saved to the location specified by the `mapping_result_dest_dir` and `mapping_result_file_name` parameters in config/control_command.yaml. If these parameters are not specified, default values will be used.
+
+After the initial save, you can execute the command again to save a new map. Each save operation will generate a new map file. (Please allow at least 5 seconds between consecutive save operations)
+
+The map origin corresponds to the odom coordinate system's origin at the program's startup.
+
+##### Relocalization mode
+
+To enable relocalization, set `custom_map_mode = 2` and specify the absolute path to the pre-built map using the `relocalization_map_abs_path` parameter in config/control_command.yaml.
+
+Once launched, odin1 will initiate the relocalization process based on the current viewpoint and the specified map. To ensure a high success rate, it is recommended to starting within 1 meter ±10 degrees of the original position and orientation from the SLAM trajectory.
+
+Note that relocalization performance is highly environment-dependent. In highly distinctive scenes, successful matching may occur even beyond the 1m/10° range, while other environments may require more stringent conditions. We advise testing in your target environment to determine practical tolerances.
+
+If relocalization fails initially, the system will temporarily operate in a fallback SLAM mode (map saving is disabled in this state). During this time, you can freely move odin1. It will continue relocalization attempts in the background. Once successful, the TF between map and odom frames will be published. (Tip: Gently shaking or moving the device after initialization can help improve relocalization accuracy.)
+
+The following topics are published in the odom frame: `/odin1/cloud_slam, /odin1/odom, /odin1/highodom and /odin1/path`. To obtain these in the map frame, apply the TF from odom frame to map frame.
+
+## 4. File structure and data format
+### 4.1 File structure
+```shell
+Odin_ROS_Driver/                // ROS1/ROS2 driver package
+    3rdparty/                   // Third-party libraries
+    src/
+        host_sdk_sample.cpp     // Example source code
+        yaml_parser.cpp         // Source code for reading yaml parameters
+        rawCloudRender.cpp      // Source code for RenderCloud
+        depth_image_ros_node.cpp //depth_image_ros_node
+        depth_image_ros2_node.cpp //depth_image_ros2_node
+        pcd2depth_ros.cpp       //Source code for pcd2depth_ros
+        pcd2depth_ros2.cpp      //Source code for pcd2depth_ros2
+        pointcloud_depth_converter.cpp //Source code for pointcloud_depth_converter
+        cloud_reprojection_ros.cpp //Source code for cloud reprojection node (ROS1/ROS2)
+        cloud_reprojector.cpp   //Core logic for cloud reprojection
+    lib/
+        liblydHostApi_amd.a     // Static library for AMD platform
+        liblydHostApi_arm.a     // Static library for ARM platform
+    include/
+        host_sdk_sample.h       // Example header file
+        lidar_api_type.h        // API data structure header file
+        lidar_api.h             // API function declarations
+        yaml_parser.h           // Parameter file reading header file
+        rawCloudRender.h        // API about RenderCloud
+        data_logger.h           // LOG about save_data
+        depth_image_ros_node.hpp // depth_image_ros_node
+        depth_image_ros2_node.hpp // depth_image_ros2_node
+        pointcloud_depth_converter.hpp // pointcloud_depth_convert
+        cloud_reprojection_ros_node.hpp // cloud_reprojection_ros_node (ROS1/ROS2)
+        cloud_reprojector.hpp   // Core class for cloud reprojection
+    config/
+        control_command.yaml    // Control parameter file for driver
+        calib.yaml              // Machine calibration yaml，differ for each individual device. Retrieved from the device everytime it connects to ROS driver
+    launch_ROS1/
+        odin1_ros1.launch       // ROS1 launch file
+    launch_ROS2/
+        odin1_ros2.launch.py    // ROS2 launch file
+    script/
+        build_ros1.sh           // Installation script for ROS1
+        build_ros2.sh           // Installation script for ROS2
+    recorddata/                 // holds recorded data that can import into MindCloud
+    log/                        // holds log files
+        Driver_{timestamp}/     // holds all log folders for each time driver started
+            Conn_{timestamp}/   // holds all log files for each odin1 device connection
+                dev_status.csv  // device status log file
+    README.md                   // Usage instructions
+    CMakeLists.txt              // CMake build file
+    License                     // License file
+```
+### 4.2 File structure
+| Launch File Name         | Description |
+|--------------------------|-------------|
+| odin1_ros1.launch        | Launch file for ROS1 - Odin1 Basic Operations Demo |
+| odin1_ros2.launch.py     | Launch file for ROS2 - Odin1 Basic Operations Demo |
+
+
+### 4.3 ROS topics
+Internal parameters of the Odin ROS driver are defined in config/control_command.yaml. Below are descriptions of the commonly used parameters:
+
+| Topic               |control_command.yaml  | Detailed Description |
+|---------------------|----------------------|----------------------|
+| odin1/imu                     | sendimu           | Imu Topic |
+| odin1/image                   | sendrgb           | RGB Camera Topic, decoded from original jpeg data from device, bgr8 format |
+| odin1/image_undistort         | sendrgbundistort  | undistorted RGB Camera Topic, processed with calib.yaml from device |
+| odin1/image/compressed        | sendrgbcompressed | RGB Camera compressed Topic, original jpeg data from device |
+| odin1/cloud_raw               | senddtof          | Raw_Cloud Topic |
+| odin1/cloud_render            | sendcloudrender   | Render_Cloud Topic, processed with raw point cloud, rgb image, and calib.yaml from device |
+| odin1/cloud_slam              | sendcloudslam     | Slam_PointCloud Topic |
+| odin1/odometry                | sendodom          | Odom Topic |
+| odin1/odometry_high           | sendodom          | high frequency Odom Topic |
+| odin1/path                    | showpath          | Odom Path Topic |
+| tf                            | sendodom          | tf tree Topic |
+| odin1/depth_img_competetion   | senddepth         | Dense depth image Topic. Demo, high computing power required. One-to-one with odin1/image_undistort. To utilize the data please directly subscribe to this topic instead of echoing it. Original value is already depth data, no need for further convert. |
+| odin1/depth_img_competetion_cloud  | senddepth         | Dense Depth_Cloud Topic. Demo, high computing power required |
+| odin1/reprojected_image       | sendreprojection  | Reprojected cloud to image Topic. Projects cloud_slam to camera image using odometry. Processed on host device. |
+
+### 4.4 Data format
+
+1. The raw point cloud (cloud_raw) has the following fields:
+```
+float32 x             // X axis, in meters
+float32 y             // Y axis, in meters
+float32 z             // Z axis, in meters
+uint8  intensity      // Reflectivity, range 0–255
+uint16 confidence     // Point confidence, actual value range from 0 to around 1300 in typical scene, higher value means more reliable. Recommanded filtering threshold is 30-35, should be adjusted accordingly.
+float32 offset_time   // Time offset relative to the base timestamp unit: s 
+```
+
+To work with this custom format in PCL, first define the point type:
+```cpp
+/*** LS ***/
+namespace ls_ros {
+    struct EIGEN_ALIGN16 Point {
+        float x;
+        float y;
+        float z;
+        uint8_t intensity;
+        uint16_t confidence;
+        float offset_time;
+        EIGEN_MAKE_ALIGNED_OPERATOR_NEW
+    };
+}  // namespace ls_ros
+
+POINT_CLOUD_REGISTER_POINT_STRUCT(ls_ros::Point,
+      (float, x, x)
+      (float, y, y)
+      (float, z, z)
+      (uint8_t, intensity, intensity)
+      (uint16_t, confidence, confidence)
+      (float offset_time , offset_time)
+)
+```
+Then, you can easily convert a ROS sensor_msgs::PointCloud2 message into a PCL point cloud:
+```
+pcl::PointCloud<ls_ros::Point> ls_cloud;
+pcl::fromROSMsg(*msg, ls_cloud);
+```
+
+2. The slam point cloud (cloud_slam) and directly rendered point cloud (cloud_render) has the following fields:
+```
+float32 x             // X axis, in meters
+float32 y             // Y axis, in meters
+float32 z             // Z axis, in meters
+float32 rgb           // RGB value
+```
+
+### 4.5 Other functionalities
+
+|control_command.yaml   | Detailed Description |
+|-----------------------|----------------------|
+| use_host_ros_time     | Time synchronization mode: 0 - use odin internal system time as data timestamp (typical and recommended); 1 - use host ROS time upon receive (not recommended for most users); 2 - align odin1 time to host time via NTP-like synchronization, timestamp is the sensor data reception time on host time axis. |
+| strict_usb3.0_check   | Strict USB3.0 check, if off, allow connection even if usb connection is below usb 3.0 |
+| recorddata            | Record data in specific format that can be imported into MindCloud(TM) for post-processing. Please be aware that this will consume a lot of storage space. Testing shows 9.5G for 10mins of data. The per-frame timestamps written into the recorded files (IMU / image / point cloud / pose / rotate) follow the same alignment policy as `use_host_ros_time`, so under NTP mode (`use_host_ros_time=1` or `2`) the recorded timestamps are NTP-aligned host time instead of odin1 boot time. <br>录制文件 (IMU / 图像 / 点云 / Pose / Rotate) 中每帧的时间戳与 `use_host_ros_time` 采用相同对齐策略：在 NTP 模式 (`use_host_ros_time=1` 或 `2`) 下，录制时间戳为 NTP 对齐后的主机时间，而非 odin1 开机时间。 |
+| devstatuslog          | Device status logging, currently save device status (soc temperature, cpu usage, ram usage, dtof sensor temp .etc) and data tx & rx rate to devstatus.csv under log folder. A new file will be created every time the driver is started. |
+| showcamerapose        | Display Camera Pose and Field of View. |
+| custom_map_mode        | Operation Modes: Mode 0 - Odometry mode: The map frame and odom frame share the same pose. Mode 1 - Mapping (with loop closure) mode: This mode supports map saving. Mode 2 - Relocalization mode: Requires specifying the absolute path to the map file. After successful relocalization, it will output the TF relationship between the map and odom frames.|
+| custom_init_pos        | Initialization Position (currently unused). |
+| relocalization_map_abs_path        | Absolute Path to Map File: Used for relocalization mode. |
+| mapping_result_dest_dir and mapping_result_file_name| Path and Name for Saving Maps in Mapping Mode: If not specified, default values will be used. |
+
+### 4.6 Runtime AE/AWB Tuning via ROS Service / 通过 ROS Service 在线调节 AE/AWB
+
+The driver hosts four ROS services that let a side terminal tune the
+camera's auto exposure (AE) and auto white balance (AWB) at runtime,
+while the main data streams keep flowing. The same SDK call is shared
+with the driver's main control path and serialised by an internal
+mutex, so it is safe to invoke these services concurrently with normal
+operation.
+
+驱动启动后会注册 4 个 ROS Service，允许在不重启 driver 的前提下，从另一个终端动态调节
+相机的自动曝光（AE）和自动白平衡（AWB）。底层 SDK 调用与驱动主控制路径共享同一把
+互斥锁，因此可以与正常数据流并发调用。
+
+**Service list / Service 一览**
+
+| Service name | Type / 类型 | Purpose / 用途 |
+|---|---|---|
+| `/odin1/get_ae`  | `odin_ros_driver/srv/GetAe`  | Query current AE status / 查询当前 AE 状态 |
+| `/odin1/get_awb` | `odin_ros_driver/srv/GetAwb` | Query current AWB status / 查询当前 AWB 状态 |
+| `/odin1/set_ae`  | `odin_ros_driver/srv/SetAe`  | Set AE mode and (manual) exposure / gain / 设置 AE 模式和手动曝光/增益 |
+| `/odin1/set_awb` | `odin_ros_driver/srv/SetAwb` | Set AWB mode and (manual) R/B gain / 设置 AWB 模式和手动 R/B 增益 |
+
+#### 4.6.1 Request fields, ranges, physical meaning / 请求字段、范围与物理含义
+
+**`SetAe.Request`**
+
+| Field | Range / 范围 | Meaning / 含义 |
+|---|---|---|
+| `mode` | `0` (AUTO) or / 或 `1` (MANUAL) | `0` = device runs its own AE loop, the two floats below are ignored / 设备自动调 AE，下方参数被忽略<br>`1` = device locks AE and applies the provided values / 设备锁 AE 并应用提供的值 |
+| `exposure_time` | `0.0001` ~ `0.033` s (manual only / 仅手动模式) | Sensor exposure time per frame. Longer = brighter but more motion blur / 每帧传感器曝光时间。越长越亮但运动模糊增大 |
+| `gain` | `1.0` ~ `64.0` (manual only / 仅手动模式) | Analog gain. Higher = brighter output but worse SNR / 模拟增益。越大越亮但信噪比越差 |
+
+**`SetAwb.Request`**
+
+| Field | Range / 范围 | Meaning / 含义 |
+|---|---|---|
+| `mode`  | `0` (AUTO) or / 或 `1` (MANUAL) | `0` = device runs its own AWB loop / 设备自动 AWB<br>`1` = device locks AWB and applies provided gains / 设备锁定 AWB 并应用所给增益 |
+| `rgain` | `0.1` ~ `4.0` (manual only / 仅手动模式) | R channel gain. Higher `rgain` vs `bgain` shifts the image warm (yellow/red) / R 通道增益，相对 bgain 越大，画面越偏暖 |
+| `bgain` | `0.1` ~ `4.0` (manual only / 仅手动模式) | B channel gain. Higher `bgain` vs `rgain` shifts the image cool (blue) / B 通道增益，相对 rgain 越大，画面越偏冷 |
+
+> Gr / Gb channels are fixed to 1.0 by the device and are not adjustable.
+> Gr / Gb 通道被设备固定为 1.0，不可调节。
+
+#### 4.6.2 Response fields / 响应字段
+
+All four services return a `success` (bool) and `rc` (int32). Get
+services additionally return the queried state.
+4 个 Service 都返回 `success` (bool) 与 `rc` (int32)。Get 类还会返回查询到的状态字段。
+
+**`GetAe.Response`**
+
+| Field | Typical range / 典型范围 | Meaning / 含义 |
+|---|---|---|
+| `exposure_time` | `0.0001`~`0.033` s | Current exposure / 当前曝光时间 |
+| `gain` | `1.0`~`64.0` | Current analog gain / 当前模拟增益 |
+| `iso` | `100`~`6400` | Equivalent ISO / 等效 ISO |
+| `brightness` | `0`~`255` | Average frame brightness / 平均帧亮度 |
+| `is_converged` | `0` or `1` | `1` = AE settled / AE 已收敛 |
+| `env_lv` | `0`~`15` | Ambient luminance index, higher = brighter / 环境光强度指数，越大越亮 |
+| `fps` | `~10` / `~14.5` / `~29` | Current frame rate / 当前帧率 |
+
+**`GetAwb.Response`**
+
+| Field | Typical range / 典型范围 | Meaning / 含义 |
+|---|---|---|
+| `rgain` / `bgain` | `0.1`~`4.0` | R / B channel gain / R / B 通道增益 |
+| `grgain` / `gbgain` | `1.0` (fixed / 固定) | Gr / Gb gain, device-fixed / Gr / Gb 增益，设备固定 |
+| `cct` | `2500`~`8000` K | Correlated color temperature / 相关色温 |
+| `ccri` | `-50`~`50` | Color temp deviation index, 0 = on Planckian locus / 色温偏离指数，0 表示在普朗克轨迹上 |
+| `is_converged` | `0` or `1` | `1` = AWB settled / AWB 已收敛 |
+
+#### 4.6.3 `rc` return code / `rc` 返回码
+
+| `rc` | Meaning / 含义 |
+|---|---|
+| `0` | Success / 成功 |
+| `400` | Device payload too short / 设备载荷过短 |
+| `401` | Device opcode not supported / 设备不支持该 opcode |
+| `402` | Device parameter length wrong / 参数长度错误 |
+| `403` | **Parameter out of range** / 参数越界 — most common when manual values exceed the table above / 手动值超出上表范围时最常见 |
+| `404` | Device-side socket error / 设备端 socket 错误 |
+| `405` | Device-side `ae_control` did not respond / 设备端 `ae_control` 无应答（确认 lydapp 已运行） |
+| `255` (`0xFF`) | Unknown opcode reported by ae_control / ae_control 报未知 opcode |
+| `-1` | SDK not initialised / SDK 未初始化 |
+| `-2` ~ `-5` | USB transfer / timeout / malformed reply / USB 传输异常、超时、应答畸形 |
+| `-100` | **Driver has not opened the device yet** / driver 还未打开设备，请等设备连接成功 |
+
+#### 4.6.4 Usage examples / 调用示例
+
+ROS2 (Humble) — start the driver in one terminal, then in a side terminal:
+ROS2（Humble）—— 在一个终端启动 driver，在另一个终端：
+
+```bash
+source install/setup.bash
+
+# Query current state / 查询当前状态
+ros2 service call /odin1/get_ae  odin_ros_driver/srv/GetAe
+ros2 service call /odin1/get_awb odin_ros_driver/srv/GetAwb
+
+# Set AE to AUTO / 设置 AE 为自动
+ros2 service call /odin1/set_ae odin_ros_driver/srv/SetAe "{mode: 0}"
+
+# Set AE to MANUAL with 10 ms exposure and gain 4.0
+# 设置 AE 为手动，10 毫秒曝光，增益 4.0
+ros2 service call /odin1/set_ae odin_ros_driver/srv/SetAe \
+  "{mode: 1, exposure_time: 0.010, gain: 4.0}"
+
+# Set AWB to MANUAL with rgain=1.5, bgain=2.0
+# 设置 AWB 为手动，rgain=1.5、bgain=2.0
+ros2 service call /odin1/set_awb odin_ros_driver/srv/SetAwb \
+  "{mode: 1, rgain: 1.5, bgain: 2.0}"
+
+# Restore AUTO / 一键回自动
+ros2 service call /odin1/set_ae  odin_ros_driver/srv/SetAe  "{mode: 0}"
+ros2 service call /odin1/set_awb odin_ros_driver/srv/SetAwb "{mode: 0}"
+
+# Inspect srv definition / 查看 srv 完整定义
+ros2 interface show odin_ros_driver/srv/SetAe
+```
+
+ROS1 (Noetic) — start the driver, then in a side terminal:
+ROS1（Noetic）—— 启动 driver 后，新开终端：
+
+```bash
+source devel/setup.bash
+
+# Query / 查询
+rosservice call /odin1/get_ae
+rosservice call /odin1/get_awb
+
+# Set AE manual / 设置 AE 手动
+rosservice call /odin1/set_ae  "{mode: 1, exposure_time: 0.010, gain: 4.0}"
+
+# Set AWB manual / 设置 AWB 手动
+rosservice call /odin1/set_awb "{mode: 1, rgain: 1.5, bgain: 2.0}"
+
+# Restore AUTO (ROS1 requires all fields to be present)
+# 一键回自动（ROS1 要求填齐全部字段）
+rosservice call /odin1/set_ae  "{mode: 0, exposure_time: 0.0, gain: 0.0}"
+rosservice call /odin1/set_awb "{mode: 0, rgain: 0.0, bgain: 0.0}"
+
+# Inspect srv definition / 查看 srv 完整定义
+rossrv show odin_ros_driver/SetAe
+```
+
+#### 4.6.5 Recommended starting points by scene / 不同场景推荐起步参数
+
+**AE (`exposure_time`, `gain`)**
+
+| Scene / 场景 | `exposure_time` | `gain` |
+|---|---|---|
+| Bright outdoor / 明亮室外 | `0.001` ~ `0.005` s | `1.0` ~ `2.0` |
+| Normal indoor / 普通室内 | `0.008` ~ `0.015` s | `2.0` ~ `8.0` |
+| Dim light / 暗光环境 | `0.020` ~ `0.030` s | `8.0` ~ `32.0` |
+| Very dark / 极暗 | `0.033` s | `32.0` ~ `64.0` |
+
+**AWB (`rgain`, `bgain`)**
+
+| Target tone / 目标色调 | `rgain` | `bgain` |
+|---|---|---|
+| Warm (tungsten, sunset) / 暖（钨丝灯、夕阳） | `2.0` ~ `2.5` | `1.0` ~ `1.2` |
+| Neutral (D65 daylight) / 中性（D65 日光） | `1.5` ~ `1.7` | `1.8` ~ `2.0` |
+| Cool (cloudy, fluorescent) / 冷（阴天、荧光） | `1.2` ~ `1.4` | `2.2` ~ `2.6` |
+| Very cool / 极冷 | `1.0` | `3.0` ~ `4.0` |
+
+#### 4.6.6 Caveats / 注意事项
+
+- The service blocks for up to ~10 s waiting for the device to reply;
+  typical latency is tens of milliseconds.
+  Service 最长阻塞约 10 秒等设备应答；正常几十毫秒返回。
+- Manual mode is **not** persisted across driver / device restart;
+  it falls back to AUTO on each new connection.
+  手动模式**不会**跨重启保留；每次重连默认回到 AUTO。
+- `rc = -100` means the driver has not yet opened the device.
+  Wait until the driver logs `device connected` before calling.
+  返回 `rc = -100` 表示 driver 还没打开设备，等到 driver 日志显示 `device connected` 再调用。
+- The effective maximum `exposure_time` is bounded by the frame
+  period `1 / fps`. With `dtof_fps = 290` (29 Hz, period ~34 ms)
+  the upper limit 0.033 s is already at the frame boundary.
+  最大可用 `exposure_time` 受帧周期 `1/fps` 限制。在 `dtof_fps = 290`（29 Hz、周期 ~34 ms）下，上限 0.033 s 已经贴到帧边界。
+
+## 5. FAQ
+### 5.1 Segmentation fault upon re-launching host SDK
+**Error Message**  
+No device connected after 60 seconds 
+
+**Solution**  
+1. Please power on Odin module again # Disconnect and reconnect odin power
+
+2. Reinitialize Odin SDK # Execute SDK after device reboot
+
+
+### 5.2 Library binding failure during compilation
+
+**Error Message**  
+ld: cannot find -llydHostApi or symbol lookup errors
+
+**Resolution** 
+
+1. Clean previous build artifacts
+
+ROS1 
+```shell
+rm -rf devel/ build/  
+```
+ROS2
+```shell
+rm -rf devel/ install/ log/ 
+```
+2. Re-run script installation
+
+### 5.3 Docker GUI passthrough failure
+
+**Error Message**  
+Unable to open X display or No protocol specified
+
+**Resolution** 
+```shell
+xhost + #This command enables graphical passthrough to Docker containers
+```
+
+### 5.4 ROS driver exit with get version failed error
+
+**Error Message**  
+```shell
+<ERROR><api.cpp:lidar_get_version:672>: get device version fail.
+get version failed.
+```
+
+**Resolution** 
+
+Device firmware version is too low, please update to latest version.
+
+
+### 5.5 RVIZ has not responded for a long time
+
+**Error Message**  
+Rviz does not respond, and after a while the terminal prints Device disconnected, waiting for reconnection...
+
+**Resolution** 
+
+Please power on Odin module again
+
+### 5.6 Device not responding
+
+**Error Message**  
+Missed ok response from device,probably wrong interaction procedure.
+
+**Resolution** 
+
+Please adopt the solution mentioned in 5.1
+
+### 5.7 Device has no external calibration file 
+
+**Error Message**  
+ERROR：Missing camera node 'cam_0'
+
+**Resolution** 
+
+Please plug and unplug the USB again
+
+### 5.8 ROS Driver report device disconnected immediately after stream started
+
+**Error Message**  
+
+```shell
+Device ready and streams activated
+Device detaching...
+Wating for device reconnection...
+Device disconnected, waiting for reconnection...
+```
+
+**Reason**
+
+Mostly common on ros2 environment and connected to complex network environment, such as office wifi & ethernet. ROS2 default to broadcast, and complex network environment will cause ros2 publish to block, leading to device disconnection.
+
+**Resolution** 
+
+If cross-device communication is not required, please restrict ros2 to localhost only with:
+```shell
+export ROS_LOCALHOST_ONLY=1
+```
+
+If cross-device communication is required, please simplify the network environment as much as possible. Mini local network with only required devices is recommended.
+
+### 5.9 ROS Driver died immediately after stream started
+
+**Error Message**  
+
+```shell
+Device ready and streams activated
+[host_sdk_sample-2] process has died ......
+```
+
+**Test**
+
+Disable odin1/image	with sendrgb = 0 in control_command.yaml and try again. If the driver now works, it is likely that the issue is related to multiple version of opencv is installed on the system.
+
+**Resolution** 
+
+Purge the unused version of opencv and maintain a single complete version, then rebuild the driver and try again.
+
+### 5.10 ROS Driver printing "TF_OLD_DATA ignoring data" warning
+
+**Error Message**  
+
+```shell
+[rviz2-3] Warning: TF_OLD_DATA ignoring data from the past for frame odin1_base_link at time 20.547632 according to authority Authority undetectable
+[rviz2-3] Possible reasons are listed at http://wiki.ros.org/tf/Errors%20explained
+[rviz2-3]          at line 294 in ./src/buffer_core.cpp
+```
+
+**Reason**
+
+This is a ros & rviz feature to warn user that some tf data is being ignored due to timestamp conflicts. It happens when user keeps ros driver running and power-cycles odin device, which cause odin's internal system time being reset and now data timestamps conflicts with old data recieved by rviz during last run.
+
+**Resolution** 
+
+There's a reset button on bottom of rviz gui. Click on this button will reset rviz's internal state and stop the warning.
+
+### 5.11 ROS Driver printing "unknown cmd code: xx" error
+
+**Error Message**  
+
+```shell
+<ERROR><api.cpp:cmd_data_deal:418>: unknow command code 21.
+```
+
+**Reason**
+
+This is due to ros driver version mismatch with device firmware version, resulting in ros driver unable to decode new data added in newer firmware.
+
+**Resolution** 
+
+Please make sure you are using most up-to-date ros driver and device firmware.
+
+### 5.12 USB device access error (LIBUSB_ERROR_BUSY or LIBUSB_ERROR_ACCESS)
+
+**Error Message**  
+
+```shell
+libusb: error [udev_hotplug_event] ignoring udev action bind
+LIBUSB_ERROR_BUSY
+```
+
+or
+
+```shell
+libusb: error [_get_usbfs_fd] libusb couldn't open USB device /dev/bus/usb/xxx/xxx, errno=13
+LIBUSB_ERROR_ACCESS
+```
+
+**Reason**
+
+- **LIBUSB_ERROR_BUSY**: Another process is already using the USB device. This commonly happens when multiple instances of the ROS driver are running, or another application (such as a previous crashed instance) still holds the device handle.
+
+- **LIBUSB_ERROR_ACCESS**: The current user does not have permission to access the USB device. This is typically caused by missing udev rules or insufficient user privileges.
+
+**Resolution** 
+
+For **LIBUSB_ERROR_BUSY**:
+
+1. Check if another instance of the driver is running:
+```shell
+ps aux | grep host_sdk_sample
+```
+
+2. Kill any existing instances:
+```shell
+killall host_sdk_sample
+```
+
+3. If the issue persists, unplug and replug the USB device to reset the device state.
+
+For **LIBUSB_ERROR_ACCESS**:
+
+1. Add udev rules for the device. Create a file `/etc/udev/rules.d/99-odin.rules` with the following content:
+```shell
+SUBSYSTEM=="usb", ATTR{idVendor}=="2207", ATTR{idProduct}=="0019", MODE="0666", GROUP="plugdev"
+```
+
+2. Reload udev rules:
+```shell
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
+
+3. Alternatively, run the driver with sudo (not recommended for production):
+```shell
+sudo -E ros2 launch odin_ros_driver odin_ros_driver.launch.py
+```
+
+4. Make sure your user is in the `plugdev` group:
+```shell
+sudo usermod -aG plugdev $USER
+```
+Then log out and log back in for the group change to take effect.
+
+### 5.13 ros2 bag drops high-frequency topics (IMU / odometry_highfreq) / ros2 bag 录制丢失高频话题（IMU / odometry_highfreq）
+
+**Symptom / 现象**
+
+When recording with `ros2 bag record`, low-frequency topics (cloud, image, odometry, wiwc) are intact, but `/odin1/imu` (400 Hz) and `/odin1/odometry_highfreq` (400 Hz) show missing samples — analysis scripts report inter-message intervals that are 2× or more of the expected period, while no drop is reported on the SDK side or by an online subscriber such as `ros2 topic hz`.
+
+使用 `ros2 bag record` 录制时，低频话题（cloud、image、odometry、wiwc）完整无丢，但 `/odin1/imu`（400 Hz）和 `/odin1/odometry_highfreq`（400 Hz）会出现丢帧——分析脚本上看到消息间隔达到正常周期的 2 倍以上，而 SDK 侧不报丢，独立的 `ros2 topic hz` 订阅者也看不到丢。
+
+**Reason / 原因**
+
+The driver publishes `/odin1/imu` and `/odin1/odometry_highfreq` with `RELIABLE` QoS. By default `ros2 bag record` subscribes with `history = keep_last`, `depth = 10`, which only buffers ~25 ms of samples at 400 Hz. Whenever the recorder is briefly delayed (disk flush, mcap/sqlite chunk write, scheduler jitter), its subscription queue overflows and DDS silently drops the oldest samples on the **subscriber side**. The SDK and publisher are unaffected, which is why no drop appears in the driver logs or in `ros2 topic hz`.
+
+驱动以 `RELIABLE` QoS 发布 `/odin1/imu` 与 `/odin1/odometry_highfreq`。`ros2 bag record` 默认订阅使用 `history = keep_last`、`depth = 10`，在 400 Hz 下只能缓冲约 25 ms。一旦录制端有短暂阻塞（落盘 flush、mcap/sqlite chunk 写入、调度抖动），订阅队列就会溢出，DDS 在**订阅端**静默丢掉最旧的样本。SDK 与 publisher 不受影响，因此驱动日志和 `ros2 topic hz` 都看不到丢。
+
+**Resolution / 解决方案**
+
+Use the provided QoS override file `script/rosbag2_qos.yaml` to raise the subscriber-side queue depth on the recorder for the two high-rate topics:
+
+使用本仓库提供的 QoS 配置 `script/rosbag2_qos.yaml`，把高频话题的录制订阅 depth 拉大：
+
+```yaml
+# script/rosbag2_qos.yaml
+/odin1/imu:
+  reliability: reliable
+  history: keep_last
+  depth: 4000
+
+/odin1/odometry_highfreq:
+  reliability: reliable
+  history: keep_last
+  depth: 4000
+```
+
+Apply it when recording / 录制时通过 `--qos-profile-overrides-path` 应用：
+
+```shell
+ros2 bag record -a \
+    --qos-profile-overrides-path src/odin_ros_driver/script/rosbag2_qos.yaml \
+    -o my_bag
+```
+
+Or only the high-rate topics / 也可以只录制高频话题：
+
+```shell
+ros2 bag record \
+    --qos-profile-overrides-path src/odin_ros_driver/script/rosbag2_qos.yaml \
+    -o my_bag \
+    /odin1/imu /odin1/odometry_highfreq /odin1/odometry /odin1/wiwc /odin1/cloud_raw
+```
+
+**Optional further tuning / 可选的进一步优化**
+
+If drops still occur after applying the override (typically on slower disks), try the following in addition / 套用上述 override 后仍有丢包时（通常发生在慢盘上），可叠加以下措施：
+
+```shell
+# Use mcap backend with a larger internal cache (faster than sqlite3).
+# 使用 mcap 后端 + 更大的内部缓存（比 sqlite3 快）。
+ros2 bag record -s mcap --max-cache-size 1073741824 \
+    --qos-profile-overrides-path src/odin_ros_driver/script/rosbag2_qos.yaml \
+    -o my_bag \
+    /odin1/imu /odin1/odometry_highfreq ...
+
+# Enlarge kernel UDP socket buffers (the most common hidden bottleneck for
+# 400 Hz RELIABLE traffic, default is only 208 KB).
+# 放大内核 UDP socket buffer（400 Hz RELIABLE 流量最常见的隐藏瓶颈，默认仅 208 KB）。
+sudo sysctl -w net.core.rmem_max=33554432
+sudo sysctl -w net.core.wmem_max=33554432
+```
+
+**Does ROS1 have the same problem? / ROS1 是否存在同样的问题？**
+
+No. ROS1 uses TCP-based publish/subscribe with a single `queue_size` parameter on each side, and has no QoS profile mismatch between publisher and subscriber. The ROS1 publisher path in this driver already sizes the IMU and `odometry_highfreq` publishers to `queue_size = 4000` (`include/host_sdk_sample.h`, see `initialize_publishers` ROS1 branch), and `rosbag record` uses TCP transport which is reliable by construction. As a result this specific drop pattern does not occur under ROS1; no additional configuration is required.
+
+不存在。ROS1 使用基于 TCP 的发布/订阅，发布端与订阅端各自只有一个 `queue_size` 参数，不存在 ROS2 那种 QoS profile 不匹配的问题。本驱动 ROS1 路径已经把 IMU 与 `odometry_highfreq` 的发布队列设置为 `queue_size = 4000`（见 `include/host_sdk_sample.h` 中 `initialize_publishers` 的 ROS1 分支），并且 `rosbag record` 使用 TCP 传输本身即可靠传递。因此在 ROS1 下不会出现该丢帧现象，也不需要额外配置。
+
+## 6.  Contact Information​​
+
+You can contact our support through support@manifoldtech.cn
+
+To help diagnose the issue, please provide the following details to our FAE engineer:
+
+1. Current firmware version​​ 
+```shell
+[device_version_capture]: ros_driver_version: [Version Number]
+```
+2. Photos of power adapter and converter cable​​ in use.
+
+3. Does the issue happen occasionally or consistently?
+
+4. Provide images of the problem scenario.
+
+5. Did the troubleshooting methods in ​​Section V​​ resolve the issue?
+
+6. Expected timeline for issue resolution.