README

2026-03-12 16:46:57 +08:00 · 2026-03-12 16:46:57 +08:00 · 3391fa4d60
commit 3391fa4d60
parent e1efdb45ab
1 changed files with 15 additions and 502 deletions
--- a/README.md
+++ b/README.md
@ -1,524 +1,37 @@
+
 # ZXOS

-## 项目概述
+## 1. 文档概述

-智行智驾低速自主驾驶体系 -- 车端 ROS2 固件（ZXOS）。该固件适配 ZX200/ZX800 自主智能清扫车，提供完整的自主驾驶、感知、控制和通信功能。
+智行智驾低速自主驾驶体系 -- 车端ROS2固件（ZXOS）。该固件适配ZX200/ZX800自主智能清扫车。

-### 项目特点
+## 2. 依赖环境

- **模块化架构**：清晰的功能模块划分，易于维护和扩展
- **多控制源支持**：无线遥控器、远程控制、自主驾驶三种模式
- **安全机制**：超时自动刹车、故障检测和上报
- **实时通信**：MQTT 协议实现车云通信
- **感知融合**：激光雷达 + RTK GPS 定位
- **可扩展性**：支持 ROS2 生态系统，易于添加新功能
- **统一日志系统**：所有节点使用统一的 Logger 系统
+### 2.1 系统环境

-## 依赖环境
+* **Ubuntu 版本**：Ubuntu 22.04.5 LTS (Jammy Jellyfish)
+* **ROS2 版本**：ROS 2 Humble
+* **CUDA 版本**：12.2 (V12.2.140)
+* **GCC/G++**：gcc-11.4.0 / g++-11.4.0
+* **Python 版本**：Python 3.10.12
+* **CMake 版本**：3.22.1

-### 系统环境
+## 3. 启动

-*   **ROS2 版本**：ROS2 Humble Hawksbill
-*   **Ubuntu 版本**：Ubuntu 22.04 LTS
-*   **编译工具**：CMake 3.8+
-*   **编程语言**：C++（主要）、Python（辅助）
-
-## 项目结构
-
-```
-/home/ubuntu/project/zxwl/sweeper/sweeper_200/
-├── README.md                 # 项目主文档
-├── start_all.sh              # 启动所有节点的脚本
-├── remote_ctrl.sh            # 启动远程控制模式的脚本
-├── radio_ctrl.sh             # 启动无线遥控器模式的脚本
-├── prepare.sh                # 系统准备脚本
-├── can.sh                    # CAN 总线配置脚本
-├── config.json               # 全局配置文件
-├── gps_load_now.txt          # GPS 数据文件
-├── .clang-format             # C++ 代码格式化配置
-├── .cmake-format.yaml        # CMake 格式化配置
-├── .gitignore                # Git 忽略文件
-├── routes/                   # 路径数据目录
-│   └── gps_load_*.txt        # GPS 路径文件（17个）
-├── src/                      # 源代码目录
-│   ├── autonomy/             # 自主驾驶模块
-│   ├── base/                 # 基础模块
-│   ├── common/               # 通用组件
-│   ├── communication/        # 通信模块
-│   ├── control/              # 控制模块
-│   └── perception/           # 感知模块
-└── .git/                     # Git 仓库
-```
-
-## 核心功能模块
-
-### 1. 基础模块（Base）
-
-**位置**：`/home/ubuntu/project/zxwl/sweeper/sweeper_200/src/base/`
-
-#### sweeper_interfaces（自定义接口）
- **功能**：定义项目所需的 ROS2 自定义消息和服务接口
- **主要消息类型**：
-  - `CanFrame.msg` - CAN 帧数据
-  - `DetectLine.msg` - 检测线数据
-  - `Fu.msg` - 浮动障碍物数据
-  - `McCtrl.msg` - 电机控制指令
-  - `Pl.msg` - 路径规划数据
-  - `Route.msg` - 路径数据
-  - `Rtk.msg` - RTK GPS 数据
-  - `Sub.msg` - 订阅数据
-  - `Task.msg` - 任务数据
-  - `VehicleIdentity.msg` - 车辆身份信息
-
-#### vehicle_params（车辆参数）
- **功能**：管理车辆的物理参数和配置信息
- **参数类型**：车辆尺寸、最大速度、加速度等
-
-#### mc（电机控制）
- **功能**：直接控制车辆的电机系统
- **通信方式**：CAN 总线通信
- **核心功能**：接收控制指令，驱动车辆运动
-
-### 2. 控制模块（Control）
-
-**位置**：`/home/ubuntu/project/zxwl/sweeper/sweeper_200/src/control/`
-
-#### ctrl_arbiter（控制仲裁器）
- **功能**：控制源仲裁和安全管理
- **控制优先级**：无线遥控器 > 远程控制 > 自主驾驶
- **安全机制**：200ms 超时机制，超时后自动发布刹车指令
- **核心逻辑**：从三个控制源接收指令，根据优先级选择执行
-
-#### radio_ctrl（无线遥控器控制）
- **功能**：处理无线遥控器的控制指令
- **通信方式**：串口通信
- **操作方式**：支持前进、后退、转向、速度调节等
-
-#### remote_ctrl（远程控制）
- **功能**：处理远程服务器的控制指令
- **通信方式**：MQTT 协议
- **操作方式**：支持远程指令和任务控制
-
-### 3. 自主驾驶模块（Autonomy）
-
-**位置**：`/home/ubuntu/project/zxwl/sweeper/sweeper_200/src/autonomy/`
-
-#### fu（浮动障碍物检测）
- **功能**：检测和识别浮动障碍物
- **感知技术**：激光雷达 + 路径规划
- **处理逻辑**：根据障碍物位置调整路径
-
-#### pl（路径规划）
- **功能**：规划车辆的行驶路径
- **技术特点**：基于 GPS 路径的动态规划
- **路径优化**：考虑障碍物和车辆动力学
-
-#### route（路径管理）
- **功能**：管理和加载 GPS 路径数据
- **路径存储**：routes/ 目录下的文本文件
- **数据格式**：GPS 坐标序列
-
-### 4. 感知模块（Perception）
-
-**位置**：`/home/ubuntu/project/zxwl/sweeper/sweeper_200/src/perception/`
-
-#### airy（激光雷达驱动）
- **功能**：激光雷达数据采集和处理
- **支持型号**：RSLIDAR 系列激光雷达
- **SDK**：RSLIDAR SDK
- **数据类型**：点云数据
-
-#### rslidar_pointcloud_merger（点云合并）
- **功能**：合并多个激光雷达的点云数据
- **技术特点**：空间坐标转换和数据融合
- **输出**：统一坐标系的点云数据
-
-#### rtk（RTK GPS 定位）
- **功能**：提供高精度 GPS 定位
- **定位精度**：厘米级定位
- **通信方式**：串口通信
-
-### 5. 通信模块（Communication）
-
-**位置**：`/home/ubuntu/project/zxwl/sweeper/sweeper_200/src/communication/`
-
-#### mqtt_report（MQTT 报告系统）
- **功能**：向云端服务器上报车辆状态
- **上报内容**：位置、速度、姿态、传感器数据等
- **通信协议**：MQTT
-
-#### sub（MQTT 订阅系统）
- **功能**：接收云端服务器的指令
- **支持指令**：控制指令、任务指令、参数更新等
- **通信协议**：MQTT
-
-#### task_manager（任务管理）
- **功能**：管理和执行清扫任务
- **任务类型**：路径清扫、区域清扫、定时任务等
- **调度机制**：任务队列管理
-
-### 6. 通用组件（Common）
-
-**位置**：`/home/ubuntu/project/zxwl/sweeper/sweeper_200/src/common/`
-
-#### launch_system（启动系统）
- **功能**：统一管理 ROS2 节点的启动
- **启动文件**：`start_all.launch.py` - 启动所有节点
- **特性**：支持节点自动重启（respawn=True）
-
-#### logger（日志系统）
- **功能**：统一的日志管理和输出
- **日志级别**：DEBUG、INFO、WARN、ERROR、FATAL
- **输出方式**：控制台输出 + 文件记录
-
-## 启动方式
-
-### 1. 系统准备
-
-在启动前，需要确保系统环境已正确配置：
-
-```bash
-./prepare.sh
-```
-
-**功能**：
- 配置 CAN 总线
- 设置串口权限
- 配置网络路由
- 检查系统依赖
-
-### 2. 无线遥控器模式
-
-启动无线遥控器控制模式：
+### 3.1 单遥控

 ```bash
 ./radio_ctrl.sh
 ```

-**启动节点**：
- vehicle_params → radio_ctrl → mc → ctrl_arbiter → mqtt_report
-
-**适用场景**：近距离直接操作车辆
-
-### 3. 远程控制模式
-
-启动远程控制模式：
+### 3.1 单远控

 ```bash
 ./remote_ctrl.sh
 ```

-**启动节点**：
- vehicle_params → remote_ctrl → mc → ctrl_arbiter → mqtt_report
-
-**适用场景**：远程监控和操作车辆
-
-### 4. 全部节点启动
-
-启动所有节点，包括完整的自主驾驶功能：
+### 3.1 全部节点

 ```bash
 ./start_all.sh
 ```
-
-**启动节点**：所有 13+ 个 ROS2 节点
-
-**功能**：
- 完整的感知系统（激光雷达 + RTK GPS）
- 自主驾驶功能（路径规划 + 障碍物检测）
- 通信系统（MQTT 上报 + 远程控制）
- 控制系统（控制仲裁 + 电机控制）
-
-**适用场景**：完全自主作业
-
-## 配置文件
-
-### config.json（全局配置）
-
-**位置**：项目根目录
-
-**主要配置项**：
-
-```json
-{
-  "mqtt": {
-    "external_net_address": "36.153.162.171",
-    "external_net_port": 19683,
-    "username": "zxwl",
-    "password": "zxwl1234@"
-  },
-  "detect_line_tolerance": 0.2,
-  "detect_head_tolerance": 0.1,
-  "lidar_detect_locate": {
-    "front": 5.0,
-    "rear": 2.0,
-    "left": 1.5,
-    "right": 1.5
-  }
-}
-```
-
-**配置说明**：
- `mqtt`：MQTT 服务器配置
- `detect_line_tolerance`：路径检测的横向容忍度（米）
- `detect_head_tolerance`：路径检测的航向容忍度（弧度）
- `lidar_detect_locate`：激光雷达检测范围（米）
-
-### routes/（路径数据）
-
-**位置**：项目根目录
-
-**文件格式**：
-
-```
-39.123456,116.123456
-39.123457,116.123457
-39.123458,116.123458
-```
-
-**内容说明**：
- 每行代表一个 GPS 坐标点
- 格式：纬度,经度
- 用于路径规划和导航
-
-## 开发环境搭建
-
-### 1. 安装 ROS2 Humble
-
-```bash
-# 按照 ROS2 Humble 官方文档安装
-# https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html
-```
-
-### 2. 克隆项目
-
-```bash
-git clone <项目地址>
-cd sweeper_200
-```
-
-### 3. 编译项目
-
-```bash
-colcon build --symlink-install
-```
-
-### 4. 激活环境
-
-```bash
-source install/setup.bash
-```
-
-### 5. 运行项目
-
-```bash
-# 查看可用的启动文件
-ros2 launch common_launch start_all.launch.py
-```
-
-## 通信协议
-
-### MQTT 通信
-
-**服务器配置**（config.json）：
- 地址：`36.153.162.171`
- 端口：`19683`
- 用户名：`zxwl`
- 密码：`zxwl1234@`
-
-**主要主题**：
- `vehicle/status`：车辆状态上报
- `vehicle/control`：远程控制指令
- `vehicle/task`：任务指令
-
-### ROS2 消息接口
-
-**基础接口**（sweeper_interfaces）：
- `McCtrl.msg`：电机控制指令
- `Rtk.msg`：RTK 定位数据
- `Pl.msg`：路径规划数据
- `Fu.msg`：障碍物数据
- 其他自定义消息
-
-## 安全机制
-
-### 1. 控制超时保护
-
- **超时时间**：200ms
- **保护机制**：如果超过超时时间未收到控制指令，自动发布刹车指令
- **实现位置**：`ctrl_arbiter` 节点
-
-### 2. 异常检测
-
- **系统监控**：实时监控各个传感器状态
- **故障上报**：异常情况通过 MQTT 上报到云端
- **安全响应**：根据故障类型采取相应的安全措施
-
-### 3. 控制优先级
-
- **第一优先级**：无线遥控器（最高）
- **第二优先级**：远程控制
- **第三优先级**：自主驾驶（最低）
-
-## 部署和运行
-
-### 1. 部署到目标车辆
-
-```bash
-# 在开发环境编译
-colcon build --symlink-install
-
-# 将编译后的文件传输到目标车辆
-rsync -av install/ <目标车辆IP>:~/sweeper_200/install/
-```
-
-### 2. 运行监控
-
-```bash
-# 查看 ROS2 节点状态
-ros2 node list
-
-# 查看主题列表
-ros2 topic list
-
-# 查看主题数据
-ros2 topic echo /topic_name
-
-# 查看节点信息
-ros2 node info /node_name
-```
-
-### 3. 调试方法
-
-```bash
-# 查看日志输出
-ros2 run logger logger_node --ros-args --log-level debug
-
-# 使用 rqt 工具
-rqt_graph  # 查看节点图
-rqt_plot   # 数据可视化
-rqt_console # 查看日志
-```
-
-## 常见问题
-
-### Q1：无法启动节点
-
-**可能原因**：
- 系统依赖未安装
- ROS2 环境未激活
- 权限问题（如串口权限）
-
-**解决方法**：
-```bash
-# 检查依赖
-rosdep install --from-paths src --ignore-src -r -y
-
-# 激活环境
-source /opt/ros/humble/setup.bash
-source install/setup.bash
-
-# 设置权限
-sudo chmod 666 /dev/ttyUSB*
-sudo chmod 666 /dev/can*
-```
-
-### Q2：无法连接 MQTT 服务器
-
-**可能原因**：
- 网络连接问题
- MQTT 配置错误
- 防火墙设置
-
-**解决方法**：
-```bash
-# 检查网络连接
-ping 36.153.162.171
-
-# 检查 MQTT 配置
-cat config.json
-
-# 检查防火墙
-sudo ufw allow 19683/tcp
-```
-
-### Q3：激光雷达数据异常
-
-**可能原因**：
- 激光雷达未连接
- 驱动未正确安装
- 通信故障
-
-**解决方法**：
-```bash
-# 检查激光雷达连接
-lsusb  # 查看 USB 设备
-dmesg | grep ttyUSB  # 查看串口
-
-# 检查激光雷达状态
-ros2 topic echo /rslidar_points
-```
-
-## 项目文档
-
-### 1. 模块文档
-
- **src/common/logger/README.md** - 日志系统文档
- **src/perception/airy/rslidar_sdk-main/src/rs_driver/README.md** - 激光雷达 SDK 文档（含中文）
-
-### 2. 代码规范
-
- **C++ 规范**：使用 .clang-format 配置
- **CMake 规范**：使用 .cmake-format.yaml 配置
- **Python 规范**：遵循 PEP8 规范
-
-## 贡献指南
-
-### 1. 代码风格
-
- 严格遵守项目的代码风格规范
- 提交前进行代码格式化
-
-### 2. 提交规范
-
-```
-<type>(<scope>): <subject>
-
-<body>
-
-<footer>
-```
-
-**type 类型**：
- feat：新功能
- fix：修复
- docs：文档更新
- style：代码格式修改
- refactor：重构
- test：测试更新
- chore：构建过程或辅助工具的变动
-
-### 3. 分支管理
-
- **master**：主分支，稳定版本
- **develop**：开发分支，包含最新功能
- **feature/xxx**：功能开发分支
- **hotfix/xxx**：紧急修复分支
-
-## 联系方式
-
-如有问题或建议，可通过以下方式联系：
-
- 项目维护团队：[团队名称]
- 邮箱：[邮箱地址]
- 问题反馈：通过 GitHub Issues 提交
-
-## 许可证
-
-[项目许可证信息]
-
---
-
-**文档最后更新时间**：2024年1月
-
-**版本**：v1.0