diff --git a/README.md b/README.md index 8622f28..f3b4d87 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,524 @@ # ZXOS -## 1. 文档概述 +## 项目概述 -智行智驾低速自主驾驶体系 -- 车端ROS2固件（ZXOS）。该固件适配ZX200/ZX800自主智能清扫车。 +智行智驾低速自主驾驶体系 -- 车端 ROS2 固件（ZXOS）。该固件适配 ZX200/ZX800 自主智能清扫车，提供完整的自主驾驶、感知、控制和通信功能。 -## 2. 依赖环境 +### 项目特点 -### 2.1 系统环境 +- **模块化架构**：清晰的功能模块划分，易于维护和扩展 +- **多控制源支持**：无线遥控器、远程控制、自主驾驶三种模式 +- **安全机制**：超时自动刹车、故障检测和上报 +- **实时通信**：MQTT 协议实现车云通信 +- **感知融合**：激光雷达 + RTK GPS 定位 +- **可扩展性**：支持 ROS2 生态系统，易于添加新功能 +- **统一日志系统**：所有节点使用统一的 Logger 系统 -* **ROS2 版本**：ROS2 Humble -* **Ubuntu 版本**：Ubuntu 22.04 +## 依赖环境 -## 3. 启动 +### 系统环境 -### 3.1 单遥控 +* **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. 无线遥控器模式 + +启动无线遥控器控制模式： ```bash ./radio_ctrl.sh ``` -### 3.1 单远控 +**启动节点**： +- vehicle_params → radio_ctrl → mc → ctrl_arbiter → mqtt_report + +**适用场景**：近距离直接操作车辆 + +### 3. 远程控制模式 + +启动远程控制模式： ```bash ./remote_ctrl.sh ``` -### 3.1 全部节点 +**启动节点**： +- vehicle_params → remote_ctrl → mc → ctrl_arbiter → mqtt_report + +**适用场景**：远程监控和操作车辆 + +### 4. 全部节点启动 + +启动所有节点，包括完整的自主驾驶功能： ```bash ./start_all.sh -``` \ No newline at end of file +``` + +**启动节点**：所有 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. 提交规范 + +``` +(): + + + +