lyq/sweeper_200

Fork 0

lyq ee5f90c9ff docs: 完善 README 文档，补充项目架构、功能模块、配置说明等完整信息

2026-01-30 10:50:35 +08:00

13 KiB

Raw Blame History

ZXOS

项目概述

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

项目特点

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

依赖环境

系统环境

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. 系统准备

在启动前，需要确保系统环境已正确配置：

./prepare.sh

功能：

配置 CAN 总线
设置串口权限
配置网络路由
检查系统依赖

2. 无线遥控器模式

启动无线遥控器控制模式：

./radio_ctrl.sh

启动节点：

vehicle_params → radio_ctrl → mc → ctrl_arbiter → mqtt_report

适用场景：近距离直接操作车辆

3. 远程控制模式

启动远程控制模式：

./remote_ctrl.sh

启动节点：

vehicle_params → remote_ctrl → mc → ctrl_arbiter → mqtt_report

适用场景：远程监控和操作车辆

4. 全部节点启动

启动所有节点，包括完整的自主驾驶功能：

./start_all.sh

启动节点：所有 13+ 个 ROS2 节点

功能：

完整的感知系统（激光雷达 + RTK GPS）
自主驾驶功能（路径规划 + 障碍物检测）
通信系统（MQTT 上报 + 远程控制）
控制系统（控制仲裁 + 电机控制）

适用场景：完全自主作业

配置文件

config.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

# 按照 ROS2 Humble 官方文档安装
# https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html

2. 克隆项目

git clone <项目地址>
cd sweeper_200

3. 编译项目

colcon build --symlink-install

4. 激活环境

source install/setup.bash

5. 运行项目

# 查看可用的启动文件
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. 部署到目标车辆

# 在开发环境编译
colcon build --symlink-install

# 将编译后的文件传输到目标车辆
rsync -av install/ <目标车辆IP>:~/sweeper_200/install/

2. 运行监控

# 查看 ROS2 节点状态
ros2 node list

# 查看主题列表
ros2 topic list

# 查看主题数据
ros2 topic echo /topic_name

# 查看节点信息
ros2 node info /node_name

3. 调试方法

# 查看日志输出
ros2 run logger logger_node --ros-args --log-level debug

# 使用 rqt 工具
rqt_graph  # 查看节点图
rqt_plot   # 数据可视化
rqt_console # 查看日志

常见问题

Q1：无法启动节点

可能原因：

系统依赖未安装
ROS2 环境未激活
权限问题（如串口权限）

解决方法：

# 检查依赖
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 配置错误
防火墙设置

解决方法：

# 检查网络连接
ping 36.153.162.171

# 检查 MQTT 配置
cat config.json

# 检查防火墙
sudo ufw allow 19683/tcp

Q3：激光雷达数据异常

可能原因：

激光雷达未连接
驱动未正确安装
通信故障

解决方法：

# 检查激光雷达连接
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

13 KiB Raw Blame History Unescape Escape

ZXOS

项目概述

项目特点

依赖环境

系统环境

项目结构

核心功能模块

1. 基础模块（Base）

sweeper_interfaces（自定义接口）

vehicle_params（车辆参数）

mc（电机控制）

2. 控制模块（Control）

ctrl_arbiter（控制仲裁器）

radio_ctrl（无线遥控器控制）

remote_ctrl（远程控制）

3. 自主驾驶模块（Autonomy）

fu（浮动障碍物检测）

pl（路径规划）

route（路径管理）

4. 感知模块（Perception）

airy（激光雷达驱动）

rslidar_pointcloud_merger（点云合并）

rtk（RTK GPS 定位）

5. 通信模块（Communication）

mqtt_report（MQTT 报告系统）

sub（MQTT 订阅系统）

task_manager（任务管理）

6. 通用组件（Common）

launch_system（启动系统）

logger（日志系统）

启动方式

1. 系统准备

2. 无线遥控器模式

3. 远程控制模式

4. 全部节点启动

配置文件

config.json（全局配置）

routes/（路径数据）

开发环境搭建

1. 安装 ROS2 Humble

2. 克隆项目

3. 编译项目

4. 激活环境

5. 运行项目

通信协议

MQTT 通信

ROS2 消息接口

安全机制

1. 控制超时保护

2. 异常检测

3. 控制优先级

部署和运行

1. 部署到目标车辆

2. 运行监控

3. 调试方法

常见问题

Q1：无法启动节点

Q2：无法连接 MQTT 服务器

Q3：激光雷达数据异常

项目文档

1. 模块文档

2. 代码规范

贡献指南

1. 代码风格

2. 提交规范

3. 分支管理

联系方式

许可证

13 KiB

Raw Blame History