From 3391fa4d607ab7be076ed5fc847873213bb5d9d3 Mon Sep 17 00:00:00 2001 From: lyq Date: Thu, 12 Mar 2026 16:46:57 +0800 Subject: [PATCH] README --- README.md | 517 ++---------------------------------------------------- 1 file changed, 15 insertions(+), 502 deletions(-) diff --git a/README.md b/README.md index f3b4d87..ffae4d5 100644 --- 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. 提交规范 - -``` -(): - - - -