# ROS2传感器数据采集和回流系统

**Repository Path**: jasonttm/ros2-sensor-data-reflow

## Basic Information

- **Project Name**: ROS2传感器数据采集和回流系统
- **Description**: data_reflow 是一个基于 ROS2 开发的自动驾驶车辆传感器数据回流系统，核心功能是实现摄像头、激光雷达等传感器数据的实时采集、线程安全缓存，并支持通过碰撞事件触发“事件前后历史数据查询”，适用于自动驾驶场景下的事故回溯、数据复盘与算法验证。
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-22
- **Last Updated**: 2025-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: ROS, Cpp, Python

## README

# data_reflow：自动驾驶传感器数据回流系统

## 项目概述
`data_reflow` 是基于 **ROS 2** 开发的自动驾驶车辆传感器数据回流系统，核心功能为实现摄像头、激光雷达等传感器数据的**实时采集、线程安全缓存**，并通过**碰撞事件触发“事件前后历史数据查询”**，适用于自动驾驶场景下的事故回溯、数据复盘与算法验证。

系统采用模块化设计，通过**单例模式**保证配置与缓存的全局唯一性，结合互斥锁（`mutex`）实现线程安全，支持灵活的参数配置（如采集频率、缓存大小、事件时间窗口），满足不同场景下的传感器数据管理需求。


## 核心功能
1. **配置管理**：单例模式加载 YAML 配置文件，支持整数、布尔、浮点型参数读取，提供默认值 fallback 机制。
2. **传感器数据采集**：
   - 摄像头数据：实时发布 + 可选缓存存储（通过配置开关控制）。
   - 激光雷达数据：实时发布（可选存储，默认仅发布）。
   - 采集频率可通过配置文件动态调整。
3. **数据缓存**：按传感器类型（摄像头/激光雷达）分类缓存，支持：
   - 数据追加（缓存满时自动淘汰最旧数据）。
   - 按传感器类型 + 时间范围查询数据。
   - 单类型/全类型数据清空。
4. **事件驱动数据查询**：
   - 碰撞事件发布：模拟碰撞场景，发布事件时间戳。
   - 事件订阅与处理：接收碰撞事件后，自动查询“事件前 *N* 秒 ~ 事件后 *N* 秒”的传感器历史数据，用于回溯分析。
5. **一键启动**：通过 Launch 文件自动管理节点启动顺序，避免订阅/发布时序问题。


## 环境依赖
| 依赖项                | 要求                              | 安装说明                                  |
|-----------------------|-----------------------------------|-----------------------------------------|
| ROS 2                 | Foxy/Humble/Iron 等 LTS 版本       | 参考 [ROS 2 官方安装指南](https://docs.ros.org/) |
| CMake                 | ≥ 3.16                            | 系统预装或通过 `sudo apt install cmake` 安装 |
| yaml-cpp              | ≥ 0.6.0                           | 通过 `sudo apt install libyaml-cpp-dev` 安装 |
| `data_reflow_interfaces` | 自定义 ROS 2 接口包（项目内包含） | 需优先编译该包                            |
| C++ 标准              | C++17                             | ROS 2 工作空间默认支持                    |


## 项目目录结构
```
data_reflow_project/  # ROS 2 工作空间下的项目根目录
├── data_reflow/      # 主功能包：实现传感器采集、缓存、事件处理
│   ├── CMakeLists.txt          # 编译配置文件
│   ├── package.xml             # ROS 2 包信息（依赖、作者等）
│   ├── config/                 # 配置文件目录
│   │   └── config.yaml         # 系统核心配置（缓存大小、采集频率等）
│   ├── include/data_reflow/    # 头文件目录
│   │   ├── config_manager.h    # 配置管理器（单例）
│   │   ├── data_buffer.h       # 数据缓存（单例）
│   │   ├── data_catcher.h      # 传感器数据采集
│   │   ├── event_subscriber.h  # 事件订阅与处理
│   │   └── sensor_type.h       # 传感器类型枚举
│   └── src/                    # 源码目录
│       ├── config_manager/     # 配置管理模块
│       │   ├── config_manager.cpp    # 核心逻辑
│       │   └── test_config_manager.cpp  # 配置加载测试节点
│       ├── data_buffer/        # 数据缓存模块
│       │   └── data_buffer.cpp       # 缓存核心逻辑
│       ├── data_catcher/       # 数据采集模块
│       │   ├── data_catcher.cpp      # 采集核心逻辑
│       │   └── test_data_catcher_node.cpp  # 采集测试节点
│       ├── event_monitor/      # 事件处理模块
│       │   ├── collision_event_publisher.cpp  # 碰撞事件发布
│       │   ├── event_subscriber.cpp  # 事件订阅逻辑
│       │   └── test_event_subscriber_node.cpp  # 事件测试节点
│       └── launch/             # Launch 文件目录
│           └── test_data_reflow_launch.py  # 一键启动所有节点
└── data_reflow_interfaces/  # 自定义接口包：定义消息、服务格式
    ├── CMakeLists.txt          # 接口编译配置
    ├── package.xml             # 接口包信息
    ├── msg/                    # 自定义消息目录
    │   ├── GetEvent.msg        # 碰撞事件消息格式
    │   └── SensorData.msg      # 传感器数据消息格式
    └── srv/                    # 自定义服务目录
        └── GetBufferData.srv   # 历史数据查询服务格式
```


## 编译与构建
### 1. 创建 ROS 2 工作空间（若未创建）
```bash
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src
```

### 2. 添加项目包
将 `data_reflow` 和 `data_reflow_interfaces` 文件夹复制到 `src` 目录下。

### 3. 编译自定义接口包
优先编译 `data_reflow_interfaces` 以生成消息/服务的中间代码：
```bash
cd ~/ros2_ws
colcon build --packages-select data_reflow_interfaces
```

### 4. 编译主功能包
```bash
colcon build --packages-select data_reflow
```

### 5. 加载环境变量
每次打开终端或编译后，需加载工作空间的环境变量：
```bash
source ~/ros2_ws/install/setup.bash
```


## 快速启动
通过 Launch 文件**一键启动所有核心节点**（无需手动逐个启动）：
```bash
ros2 launch data_reflow test_data_reflow_launch.py
```

### Launch 节点说明
| 节点名称                  | 功能描述                                  |
|---------------------------|-----------------------------------------|
| `test_data_catcher_node`  | 传感器数据采集节点（摄像头 + 激光雷达）      |
| `test_event_subscriber_node` | 事件订阅 + 数据缓存管理节点              |
| `collision_event_publisher` | 碰撞事件模拟发布节点（延迟启动，避免时序问题） |


## 配置说明
核心配置文件为 `data_reflow/config/config.yaml`，支持以下参数调整（修改后需重新编译生效）：

| 参数名                  | 类型    | 默认值 | 功能描述                                  |
|-------------------------|---------|--------|-----------------------------------------|
| `buffer_size`           | `int`   | `1000` | 单个传感器的最大缓存帧数（超出时淘汰最旧数据） |
| `publish_frequency_camera` | `int` | `30`   | 摄像头数据发布频率（单位：Hz）|
| `publish_frequency_lidar`  | `int` | `15`   | 激光雷达数据发布频率（单位：Hz）|
| `record_camera`         | `bool`  | `true` | 摄像头数据是否存入缓存（`true` 为存入）    |
| `record_lidar`          | `bool`  | `false`| 激光雷达数据是否存入缓存（`false` 为仅发布）|
| `event_pre_time`        | `int`   | `5`    | 事件触发后，查询“事件前”的时间窗口（单位：秒）|
| `event_post_time`       | `int`   | `3`    | 事件触发后，查询“事件后”的时间窗口（单位：秒）|


## 核心模块详解
### 1. 配置管理器（`ConfigManager`）
- **设计模式**：单例模式（全局唯一实例，通过 `ConfigManager::get_instance()` 获取）。
- **功能**：加载 YAML 配置文件，提供类型安全的参数读取接口（`get_int()`、`get_bool()` 等），配置不存在时返回默认值并打印警告。
- **线程安全**：通过互斥锁（`std::mutex`）保证多线程下配置读取的安全性。
- **测试**：运行测试节点验证配置加载：
  ```bash
  ros2 run data_reflow test_config_manager
  ```


### 2. 数据缓存（`DataBuffer`）
- **设计模式**：单例模式（全局唯一缓存实例，通过 `DataBuffer::get_instance()` 获取）。
- **功能**：
  - `add_data()`：按传感器类型缓存数据，缓存满时自动淘汰最旧数据。
  - `query_by_type_and_time()`：按传感器类型和时间范围查询历史数据。
  - `clear_by_type()` / `clear_all()`：清空指定类型或所有类型的缓存。
- **线程安全**：通过互斥锁保护缓存操作，支持多节点并发读写。


### 3. 数据采集（`DataCatcher`）
- **核心类**：`SensorDataPub`（继承自 `rclcpp::Node`）。
- **功能**：
  - 从配置文件加载采集频率，周期性发布摄像头、激光雷达数据。
  - 可选将数据存入 `DataBuffer`（由 `record_camera` / `record_lidar` 控制）。
- **测试**：运行测试节点单独启动采集功能：
  ```bash
  ros2 run data_reflow test_data_catcher_node
  ```


### 4. 事件处理（`Event Monitor`）
#### 4.1 碰撞事件发布者（`CollisionEventPublisher`）
- **功能**：发布碰撞事件（话题 `event_topic`），包含事件类型、时间戳等信息。
- **运行**：
  ```bash
  ros2 run data_reflow collision_event_publisher
  ```

#### 4.2 事件订阅者（`EventSubscriber`）
- **功能**：
  - 订阅碰撞事件，计算查询时间窗口（事件前/后 *N* 秒）。
  - 订阅传感器数据并缓存，事件触发后查询历史数据并打印结果。
- **测试**：运行测试节点单独启动订阅功能：
  ```bash
  ros2 run data_reflow test_event_subscriber_node
  ```


## 测试说明
### 1. 配置加载测试
运行配置管理器测试节点，验证配置文件加载与参数读取：
```bash
ros2 run data_reflow test_config_manager
```
- 预期结果：打印 `config.yaml` 中的参数（如 `buffer_size=1000`、`record_camera=true` 等），无错误日志。

### 2. 数据采集与缓存测试
1. 启动数据采集节点：
   ```bash
   ros2 run data_reflow test_data_catcher_node
   ```
2. 启动事件订阅节点（负责缓存数据）：
   ```bash
   ros2 run data_reflow test_event_subscriber_node
   ```
3. 查看缓存状态：订阅节点会周期性打印“缓存中摄像头帧数”等日志信息。

### 3. 事件触发查询测试
1. 启动采集、订阅节点（步骤同上）。
2. 启动碰撞事件发布节点：
   ```bash
   ros2 run data_reflow collision_event_publisher
   ```
3. 预期结果：订阅节点接收事件后，查询并打印“事件前后 *N* 秒内的摄像头数据”。


## 常见问题
### 1. 配置文件加载失败
- 报错：`配置文件不存在` 或 `解析错误`。
- 解决：
  - 确认 `config.yaml` 位于 `data_reflow/config/` 目录。
  - 检查 YAML 语法（避免缩进错误、特殊字符）。

### 2. 数据查询无结果
- 报错：`未查询到事件前后的传感器数据`。
- 解决：
  - 确认 `record_camera` / `record_lidar` 为 `true`（配置文件中）。
  - 确保采集节点先于碰撞事件发布节点启动（保证缓存有“事件前”数据）。

### 3. 节点启动提示“包未找到”
- 解决：执行 `source ~/ros2_ws/install/setup.bash` 加载 ROS 2 环境变量。


## 扩展建议
1. **新增传感器支持**：
   - 在 `sensor_type.h` 扩展传感器类型（如毫米波雷达、超声波传感器）。
   - 在 `DataCatcher` 中添加对应数据采集逻辑，配置文件新增采集频率参数。

2. **数据持久化**：
   - 在 `DataBuffer` 中添加数据写入文件功能（如 ROS Bag、CSV），支持查询后自动保存。

3. **多事件类型**：
   - 在 `GetEvent.msg` 中扩展事件类型（如车道偏离、障碍物碰撞），并在 `EventSubscriber` 中添加对应处理逻辑。


## 联系方式
由于本人能力有限，可能会有很多错误疏漏，敬请谅解，若有问题或功能需求，可通过以下方式交流：
- 项目维护者：[Hongjian Yin/感谢贡献者：Yang/Jie Chen]
- 邮箱：[867789467@qq.com]
- 仓库地址：[[Gitee仓库](https://gitee.com/jasonttm/ros2-sensor-data-reflow)]