sweeper_200/README.md

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

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

```bash
./prepare.sh
```

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

### 2. 无线遥控器模式

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

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

**启动节点**：
- vehicle_params → radio_ctrl → mc → ctrl_arbiter → mqtt_report

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

### 3. 远程控制模式

启动远程控制模式：

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

**启动节点**：
- vehicle_params → remote_ctrl → mc → ctrl_arbiter → mqtt_report

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

### 4. 全部节点启动

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

```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