将 R2 从"串口键盘遥控"升级为"ROS2 自主导航 + 感知 + AI"的完整机器人系统。
代码在
~/Lin_workspace/r2_integration/下，文档在doc/中按阶段组织。部署环境：开发在 VMware 虚拟机，实车部署在 N97 Mini PC（192.168.1.210，Ubuntu 22.04 + ROS2 Humble）。 两环境 ROS2 包一致，区别在于 CAN 硬件接口和串口设备路径。
r2_integration/
│
├── README.md ← 本文件，入口导航
│
├── doc/ ← 文档（顶层 = 规范 + 阅读主线 + 待办索引）
│ ├── standards.md 文档标准 ← 先看这个
│ ├── obsidian-tags.md Obsidian 标签体系习惯
│ ├── ros2-ops.md ROS/ROS2 操作规范（构建/启动/录包/分析）
│ ├── ros2-qos-dds.md QoS/DDS 问题手册（hz 大消息坑/兼容矩阵/排查四步法）
│ ├── obsidian-sync.md Obsidian 镜像同步规范（全局适用）
│ ├── 01-plan.md 五阶段集成方案总纲
│ ├── 02-progress.md 全局进度一览（各Phase完成度）
│ ├── 03-current_state.md 当前完成状态
│ ├── 07-handover.md 状态交接（新会话用）
│ ├── startup.md R2 启动手册（全栈启动命令唯一权威，09-04 从 07 §三 拆出）
│ ├── pending-tasks.md 近期待办汇总索引（每条一句话+源文档入口，09-03 建）
│ ├── doc-engineering.md 文档工程规范（整理/重构/校验/双仓同步，跨项目通用，09-03 建）
│ ├── analysis-methods.md 数据分析方法经验长文档（draft 层：新经验先落此，成熟后抽取入规范，09-04 建）
│ │
│ ├── minimal-loop/ 最小闭环执行史（plan + w1/w2/w3-operation.md + Nav2 bringup + 审计数据）
│ ├── minimal-loop2/ 最小闭环 2·现行（plan.md + execution/relog/costmap 执行卡）
│ │
│ ├── phase0/ ← Phase 0 专题
│ │ ├── chassis_definition.md 底盘完整定义（映射/参数/公式）
│ │ ├── sensor-mount.md 传感器安装定义（IMU/雷达位置朝向）
│ │ ├── completion_report.md Phase 0 完成记录
│ │ └── debug_log.md 踩坑调试日志
│ │
│ ├── phase1/ ← Phase 1 专题
│ │ ├── g354-wiring.md G354 IMU 接线/配置
│ │ ├── ekf-verification.md EKF 实车验证清单（测试方法+判合格标准）
│ │ ├── ekf-yaw-plan.md EKF yaw 融合预案（08-12 方案①已实施验证）
│ │ └── 2026-08-04_ekf-verification-result.md EKF 验证结果记录
│ │
│ ├── retrospect/ ← 事件记录（按日期排序；索引见目录内 README）
│ │ ├── README.md 目录索引（结论速查，09-04 建，从 07 §五/§八 拆出）
│ │ ├── 2026-08-24_n97_fan_control.md N97 风扇调速（ACPI 空壳死路→IT8613E force_id=0x8622 突破，sysfs pwm2 即刻调速可撤销）
│ │ ├── 2026-08-23_doc_source_traceback.md 文档真实性回溯：roadmap 全篇来源规范化（1.11 落地案例 + 可复用检查清单）
│ │ ├── 2026-08-18_fast_lio2_deploy.md FAST-LIO2 部署首记录（N97 编译坑：PATH 前置 /usr/bin）
│ │ ├── 2026-08-18_fastlio_laser_map_debug.md FAST-LIO /Laser_map 22MB hz 之谜排障（QoS 大消息手册源头）
│ │ ├── 2026-08-17_nav2_initialpose_inflation_fix.md 初始位姿诊断 + 膨胀参数 0.30 过缝修复（08-17 实车验证，全速暂缓）
│ │ ├── 2026-08-15_nav2_bringup.md Nav2 首闭环跑通（D4 验证 + 降额实机 + 7 条排障 + 盲区/footprint 修复）
│ │ ├── 2026-08-15_kiss_drift_170058.md KISS 长录整程漂移留档（旋转+空窗→航向漂163°，双录对比）
│ │ ├── 2026-08-15_r2_sensors_extract.md velodyne 抽包 r2_sensors + g354 marker 补全（全流程/坑/决策/经验）
│ │ ├── 2026-08-15_clean_bag_rerecord.md 干净 bag 重录 + 人形块过滤（清洗版导航图 map_0815_clean）
│ │ ├── 2026-08-15_velodyne_perf_tuning.md VLP-16 链路性能调优（供电不足根因 + organize_cloud/max_range）
│ │ ├── 2026-08-15_vscode_intellisense_include_fix.md VS Code 1696 修复（Humble include 双嵌套布局）
│ │ ├── 2026-08-14_vm_vlp16_dds_fix.md VM 单机 DDS 根因修复（bashrc 跨机配置 + daemon 缓存）
│ │ ├── 2026-08-13_layer_map_3d2d.md 分层3D→2D导航层生成（多层对比+选层+seg3剔除）
│ │ ├── 2026-08-13_map_chain_investigation.md 建图链路排查（重影根因+z_min修正+time字段之谜）
│ │ ├── 2026-08-11_kiss_frame_rate_fix.md KISS 帧率修复（3.6→9.5Hz，重影根因）
│ │ ├── 2026-08-11_r2_bringup_code_review.md r2_bringup 代码审查
│ │ ├── 2026-08-10_vocalinux语音输入.md Vocalinux 本地语音输入调试总结
│ │ ├── 2026-08-09_ekf_z_drift_fix.md EKF z 漂移修复（two_d_mode 钳位）
│ │ ├── 2026-08-09_map_double_ghost.md 地图重影排查
│ │ ├── 2026-08-06_git_ops_lessons.md Git 操作教训（reset 误伤/Co-Authored-By 规则）
│ │ ├── 2026-08-05_chassis_ekf_debug.md 底盘里程计修复+EKF过程噪声225值矩阵排障
│ │ ├── 2026-08-05_imu_covariance_ekf_nan.md IMU 协方差病态→EKF NaN 排障
│ │ ├── 2026-08-05_n97_remote_desktop.md N97 远程桌面三方案排障（NoMachine/RealVNC/TigerVNC）
│ │ ├── 2026-08-03_r2_repo_repair.md r2_integration 仓库修复全记录
│ │ ├── 2026-08-02_vlp16_switch_network.md VLP-16 交换机接入方案（+vlp16-switch-network-topology.png）
│ │ ├── 2026-08-02_ekf_tf_fusion_fix.md EKF/TF 融合排障全记录（7 问题）
│ │ ├── 2026-07-31_chassis_launch_fix.md chassis.launch.py 路径修复
│ │ ├── 2026-07-31_claude_md_import_setup.md 流程模式：Claude 优先读到文档
│ │ ├── 2026-07-31_teleop_keyboard_fix.md 键盘控制修复全记录（WASD 遥控）
│ │ ├── 2026-07-31_workspace_check_fix.md r2_integration 工作区检查与修复
│ │ ├── vlp16_slam_exploration.md VLP-16 SLAM 方案探索
│ │ ├── 2026-09-03_costmap_far_refresh_closed.md costmap 远距离刷新验证闭环（09-03）
│ │ ├── 2026-09-03_doc_engineering.md 文档工程整理复盘（09-03，规则化见 doc-engineering.md）
│ │ ├── 2026-09-04_lowobstacle_breakpoint.md 低物盲区断点定位：relog 三层精分析（09-04）
│ │ ├── 2026-09-04_experience-layer-decision.md 经验四层制定稿 + 抽取盘点方案 A（09-04，待整合 doc-engineering）
│ │ ├── 2026-09-04_bags_migration.md 数据资产目录跨仓迁移复盘（bags 入仓，09-04）
│ │ └── 2026-09-05_lowobstacle_fixB_vm_acceptance.md 修法 B VM 验收 PASS + bag 抽帧重发法模板 + 经验点（09-05）
│ │
│ ├── n97/ ← N97 部署/运维手册
│ │ ├── 02-deploy-checklist.md N97 部署清单（已部署，保留作部署手册）
│ │ ├── n97_remote_desktop.md N97 远程桌面方案（TigerVNC 定型，NoMachine/RealVNC 弃用）
│ │ ├── n97info.md N97 硬件信息·风扇调速速查（细节以 retrospect 08-24 为准）
│ │ ├── fastlio2-n97-deploy.md FAST-LIO2 N97 实车部署手册（依赖/外参/运行纪律/验证）
│ │ ├── greenwave-monitor-deploy.md R2 话题自主化监测（Greenwave Monitor）部署手册（08-25 方案 B）
│ │ └── velodyne_r2.patch FAST-LIO2 velodyne 适配补丁（fastlio2 手册附件）
│ │
│ ├── roadmaps/ ← 路线/学习计划
│ │ ├── planning-control-roadmap.md 规划控制与视觉集成路线（离线/实时两大阵营 + 标定工具线）
│ │ ├── motion-control-roadmap.md 运动控制与具身智能路线（三大方向：四足/机械臂/全车协调 + 开源生态）
│ │ ├── recruitment-learning-plan.md 求职与学习三阶段总纲（2027届，09-02 定稿，当前排期权威）
│ │ ├── recruitment-learning-plan-review.md 三阶段总纲评审稿（判断 1-3 + W1-W4 决策记录）
│ │ └── nav2-knowledge-tree.md Nav2 知识树（R2 实战版）
│ │
│ ├── surveys/ ← 调研/选型留档区（问题导向调研清单，跟项目走，2026-09-05 建）
│ │ ├── 3d-lidar-2d-navigation-survey.md 低矮障碍感知手段调研（09-05；09-06 实车更新 §三B：物理边界实锤）
│ │ ├── navigation-behavior-safety-survey.md 导航行为病×安全设计调研（Q1 灰格/Q2 转弯 margin/Q5 IMU 安全，09-06）
│ │ └── chassis-kinematics-controller-survey.md 底盘运动学×控制器选型调研（Q3 全向轮行为/Q4 舵轮 MPPI 路线，09-06）
│ │
│ ├── profiles/ ← 对象档案层（实体为中心横切视图：spec v0.1 + README，09-04 建）
│ │ ├── spec.md 对象档案规范（建档门槛/模板/纪律，v0.1 试行）
│ │ └── README.md 对象档案目录与整体介绍
│ │
│ ├── archive/ ← 过时状态档（已过时，状态以 07-handover 为准）
│ │ ├── project_status.md 全项目现状总结（08-06/08-12，已过时）
│ │ └── project_landscape.md 项目全景·R2 在更大系统中的位置（08-06，已过时）
│ │
│ └── raw_data/ ← 原始数据留档（不入 git）
│ │ ├── raw_实操路线_2026-09-02_2139.md 阶段一实操路线（AI 会话原文留档）
│ │ └── raw_*.txt ×5 终端输出实录（ekf_update_rate/imu_hz/nav2_launch_param/relog_0903/rosbag_record_log）
│
├── r2_bringup/ ← ROS2 底盘控制包
│ ├── r2_bringup/chassis_node.py 核心节点
│ ├── launch/chassis.launch.py 底盘启动文件
│ ├── launch/ekf.launch.py EKF 融合启动文件
│ ├── launch/nav2.launch.py Nav2 启动文件（map_server+amcl+MPPI 全栈）
│ ├── config/r2_params.yaml 实车标定参数
│ ├── config/ekf.yaml EKF 融合配置
│ ├── config/nav2_params.yaml Nav2 参数（全速版）
│ ├── config/nav2_params_low.yaml Nav2 参数（降额版，首次实机用）
│ ├── config/nav2.rviz Nav2 RViz 配置
│ └── config/dds/ DDS 跨机配置（fastdds_peer_n97/wellknown + README）
│
├── r2_sensors/ ← ROS2 传感器外设包（包名 r2_sensors，08-15 从 r2_bringup 抽出）
│ ├── README.md 包说明（话题/参数/启动）
│ ├── launch/velodyne.launch.py VLP-16 雷达启动（driver+transform+laserscan+TF，两机通用）
│ └── config/r2.urdf base_link→velodyne TF（z=0.56m，08-06 定案）
│
├── g354_driver/ ← ROS2 IMU 驱动包（包名 g354_imu_driver）
│ ├── README.md 包说明（话题/参数/启动）
│ ├── g354_imu_driver/imu_node.py 核心节点（Mahony + ZUPT）
│ ├── launch/g354_rviz.launch.py 启动文件（rviz:=false 可只开节点）
│ ├── config/g354_imu.rviz RViz2 配置
│ ├── doc/ G354 专题文档（completion-report/debug-log/observation-methods/test-flow）
│ └── scripts/ 测试脚本
│
├── bags/ ← 实验数据资产（N97 采集 + VM 分析副本，09-04 入仓）
│ ├── README.md 数据目录导航（bag 清单/maps 产物）
│ ├── analysis/ 分析脚本 + 输出（入库；raw/maps 不入库，白名单见 .gitignore）
│ ├── csv/ 底盘测试全帧分析导出（入库）
│ ├── raw/ bag 原始录制（不入库，本地保留）
│ ├── maps/ 建图产物（不入库，本地保留）
│ └── rviz_nav2_first_loop*.png Nav2 首闭环截图（入库）
│
└── scripts/ ← 标定/文档工具
├── r2_startup.sh CAN + 底盘 + IMU + EKF 一键启动
├── measure_r2_ticks.py 编码器 ticks/圈 测量
├── map_chassis.py CAN ID → 物理位置映射
├── calibrate_direction.py 运动方向标定（8组测试）
└── check_doc_links.py 文档链接完整性校验器（doc 工程闸门，见 doc-engineering.md）
先看规范: standards.md — 了解文档结构和管理方式
首次阅读: 01-plan.md → 02-progress.md → 03-current_state.md
技术参考: phase0/chassis_definition.md
调参回溯: phase0/debug_log.md
踩坑记录: retrospect/（修复与探索事件记录，按日期排序）
状态交接: 07-handover.md
Phase 0 底盘 ROS2 + CAN 控制 ✅ 100% 完成（含 08-06 里程计修复）
Phase 1 G354 IMU + EKF 融合 ✅ 95% 实车验证完成（08-06）；yaw 方案①验证通过（08-12）
Phase 2 3D LiDAR SLAM (VLP16+KISS-ICP) ✅ 驱动 + 3D 里程计已跑通
Phase 3 VLP16 + Nav2 导航 ⏳ 25%（08-15 首闭环；08-17 降额过缝验证通过，无碰撞；全速验证暂缓）
Phase 4 D435 + Jetson 视觉 ⏳
Phase 5 气动 + 异常处理 + Robocon 编排 ⏳
（详细状态见 doc/03-current_state.md）
开发时（VMware 虚拟机）
├── CAN 总线: slcan 转串口 (USB-CAN 适配器) → CanCmd 工具配置
├── IMU/G354: 需 USB 透传或模拟
└── LiDAR: 无硬件直连，代码准备
部署时（N97 Mini PC / 192.168.1.210）
├── CAN 总线: slcan 转串口 (USB-CAN 适配器) → CanCmd 工具配置
├── IMU/G354: ttyACM1（JLink OB Mini 串口直连）
├── LiDAR: VLP-16 经交换机转接（设备 IP 10.18.18.6）
├── 视觉: D435 USB 直连（可选 Jetson 协同）
└── OS: Ubuntu 22.04 + ROS2 Humble
# 0. 工作区编译
cd ~/Lin_workspace/r2_integration
source /opt/ros/humble/setup.bash
colcon build
# 1. CAN 总线（使用 CanCmd 工具）
# 从主页面运行 CanCmd → 选择串口设备 → 选择波特率(1M) → 确认
python3 ~/Lin_workspace/command/can_command.py
# 2. 启动底盘（在终端 1 运行；EKF 场景必须带 publish_tf:=false 让 EKF 统一发 TF，独立使用可不带）
source ~/Lin_workspace/r2_integration/install/setup.bash
ros2 launch r2_bringup chassis.launch.py publish_tf:=false
# 3. 启动 IMU（在终端 2 运行；保持静止 3s 等校准完成）
# mount_axes:=y_front_x_left_z_down 是 R2 的 G354 出厂轴定义（x左/y前/z下），见 doc/phase0/sensor-mount.md
source ~/Lin_workspace/r2_integration/install/setup.bash
ros2 launch g354_imu_driver g354_rviz.launch.py rviz:=false serial_port:=/dev/ttyACM1 mount_axes:=y_front_x_left_z_down
# 4. 启动 EKF 融合（在终端 3 运行；⚠️ 必须在 IMU 校准完成后启动，重启 IMU 须同时重启 EKF）
source ~/Lin_workspace/r2_integration/install/setup.bash
ros2 launch r2_bringup ekf.launch.py
# 5. 键盘遥控（终端 4；08-11 P3 setup.cfg 修复后 ros2 run 可直启）
source ~/Lin_workspace/r2_integration/install/setup.bash
ros2 run r2_bringup teleop_keyboard
# 6. Nav2 自主导航（终端 5，08-15 起；KISS 不启动；首次实机用降额参数）
# 启动后 rviz 里先 2D Pose Estimate(P) 设初始位姿 → Navigation2 Goal(G) 发目标
# ⚠️ 设位姿前 planner 报 "map frame does not exist" 是正常等待噪音；车静止时 AMCL 不发布粒子/位姿
source ~/Lin_workspace/r2_integration/install/setup.bash
ros2 launch r2_bringup nav2.launch.py \
map:=/home/lin/maps/map_0815_clean.yaml \
params_file:=~/Lin_workspace/r2_integration/install/r2_bringup/share/r2_bringup/config/nav2_params_low.yaml \
rviz:=true
或者
ros2 launch r2_bringup nav2.launch.py map:=/home/lin/maps/map_0815_clean.yaml params_file:=/home/lin/Lin_workspace/r2_integration/install/r2_bringup/share/r2_bringup/config/nav2_params_low.yaml rviz:=true
# 观看融合里程计
ros2 topic echo /odometry/filtered一键启动（需图形界面 + gnome-terminal）:
bash ~/Lin_workspace/r2_integration/scripts/r2_startup.sh
⚠️ 建图/导航完整启动（performance governor → CAN → 雷达 → KISS-ICP → 底盘 → IMU → EKF → 遥控， 含 N97 跨机 DDS 的 FASTRTPS 环境变量）见 w1-operation.md §1.1。注: console_script 入口经 08-11 setup.cfg 修复后已可
ros2 run直启（teleop_keyboard 等）。