rosbag-checker 4.3.1

ROS2 Bag 录制规范检查工具

ROS2 Bag 录制规范检查工具

全面验证 ROS2 bag 录制是否符合飞书文档规范要求的 Python 检查工具。

📊 项目概览

项目	说明
当前版本	v4.3.1
测试框架	配置驱动架构
测试用例	100+ 项 (图像 36 + 运动状态 34 + 运动指令 24 + 传感器 5 + TF 7 + 诊断 5)
性能	20秒 bag 文件 ~10秒 完成检查
包管理	uv (现代化 Python 包管理)
Python 版本	3.10+

---

📖 文档导航

核心文档

• 📘 使用指南 - 快速开始、结果解读、常见问题
• 📋 测试用例文档 - 完整的110+测试用例定义 (P0/P1/P2分级)
• 📊 测试覆盖率分析 - 已实现vs文档定义的对比分析
• 📚 完整文档索引 - 所有文档导航

技术文档

• 🏗️ 测试框架架构 - 测试框架设计说明
• 🔧 测试规范 - 从飞书文档提取的完整规范
• 🚀 开发路线图 - 项目发展规划
• 🔬 ROS2扩展指南 - 高级开发文档

参考

• 🔗 飞书规范文档 - 官方测试规范

🎯 核心特性

配置驱动测试框架

• ✅ YAML 配置驱动 - 无需修改代码即可添加/修改测试
• ✅ 4 种测试状态 - PASS/FAIL/WARN/SKIP，简化状态系统
• ✅ 灵活测试控制 - 每项测试支持独立的 SKIP/WARN 参数配置
• ✅ 代码量大幅减少 - 667行硬编码 → 101行配置加载

测试覆盖范围 (100+ 项)

测试类别	测试项数	主要内容
图像数据	36 项	6相机 × 6测试 (帧率/质量/camera_info/时间戳同步等)
运动状态	34 项	joint_states + robot_control_state(8关节组) + 位姿(4组) + 力传感器(6组) + xsens
运动指令	24 项	mobile_base_servo_cmd 末端执行器(4组) + 关节(8组) + 导纳控制(左右2项)
传感器数据	5 项	IMU 完整检查（时间戳/角速度/加速度/四元数/帧率稳定性）
TF 坐标变换	7 项	/tf 存在性/时间戳有效性 + TF 树连通性 + /tf_static 完整性
诊断信息	5 项	diagnostics ERROR 检测 + robot_description

测试结果状态

状态	含义	颜色
✓ PASS	测试完全符合规范	🟢 绿色
✗ FAIL	发现明确问题，需要修复	🔴 红色
⚠ WARN	测试失败但配置为警告级别（不阻塞）	🟡 黄色
○ SKIP	通过配置跳过的测试	⚪ 灰色

🚀 快速开始

1. 安装 uv 包管理器

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或使用 pip
pip install uv

2. 克隆项目并安装依赖

git clone [e-mail]:ad_test/robot-test/rosbag_checker.git
cd rosbag_checker

# 同步依赖并创建虚拟环境
uv sync

3. 选择安装方式

# 方式 1: 可编辑安装（推荐开发使用）
uv tool install -e .

# 方式 2: 系统安装（推荐个人使用）
uv tool install .

# 方式 3: 打包后安装（推荐分发给他人）
uv build
pip install dist/rosbag_checker-*-py3-none-any.whl

4. 运行检查

# 基本用法
rosbag-check /path/to/bag_directory/

# 上传 html 文件到 fds
rosbag-check /path/to/bag_directory/ --upload

# 查看帮助
rosbag-check --help

# 查看版本
rosbag-check --version

# 查看配置文件路径
rosbag-check --config

5. 输出示例

=================== ROS2 Bag 检查报告 ===================
📁 Bag: rosbag2_2026_01_22-11_40_19
📊 测试统计:
  ✓ 通过: 85项 (85.0%)
  ✗ 失败: 8项 (8.0%)
  ⚠ 警告: 5项 (5.0%)
  ○ 跳过: 2项 (2.0%)

🎯 综合判定: PASS (警告不阻塞)
📄 HTML报告: complete_test_rosbag2_2026_01_22-11_40_19.html

运行后会自动生成：

• 彩色终端报告 - 实时显示在控制台
• HTML 报告 - 保存为 complete_test_<bag_name>.html，可在浏览器中打开查看

⚙️ 配置文件

查看配置文件路径

rosbag-check --config

输出示例：

测试配置文件路径: /path/to/config/tests_config.yaml
配置文件包含 6 个测试类别:
  - image_tests
  - motion_state_tests
  - motion_command_tests
  - sensor_tests
  - tf_tests
  - diagnostics_tests

修改测试配置

编辑 config/tests_config.yaml 文件（安装后路径见 rosbag-check --config 输出）：

# 跳过某项测试
- id: 1.1.1-wrist_left
  SKIP: true

# 将失败降级为警告（不阻塞整体通过）
- id: 3.2.12
  WARN: true

# 修改测试参数
- id: 2.2.15
  params:
    joint_group: waist
    threshold: 0.1

添加自定义测试

1. 在 config/tests_config.yaml 添加测试配置
2. 指定测试类 (test_class) 和参数 (params)
3. 无需修改代码，配置即生效

详见 测试框架架构文档

📊 性能指标

测试环境: 73MB MCAP 文件，24634 条消息，20 秒录制

指标	数值
测试执行时间	~10 秒
测试用例数	100+ 项
吞吐量	~7.3 MB/s

性能预估:

• 小文件 (<100MB): 5-15 秒
• 中等文件 (100-500MB): 15-60 秒
• 大文件 (>500MB): 60-180 秒

📁 项目结构

rosbag_checker/
├── bin/                        # 可执行脚本
│   └── run_complete_tests.py  # 主测试程序
├── test_framework/             # 测试框架核心
│   ├── test_case.py           # 测试用例基类
│   ├── specialized_tests.py   # 专门测试实现
│   ├── test_registry.py       # 测试注册表
│   ├── runner.py              # 测试执行引擎
│   └── protocol_loader.py     # 协议加载器
├── validators/                 # 检查器实现 (14个)
│   ├── videoclip_checker.py
│   ├── camera_info_checker.py
│   ├── joint_states_checker.py
│   ├── robot_control_state_checker.py
│   ├── mobile_base_servo_cmd_checker.py
│   ├── imu_checker.py
│   ├── xsens_checker.py
│   ├── tf_checker.py
│   └── diagnostics_checker.py
├── utils/                      # 工具模块
│   ├── bag_reader.py          # MCAP 读取封装
│   ├── colored_reporter.py    # 彩色终端报告
│   ├── html_reporter.py       # HTML 报告生成
│   └── config_loader.py       # 配置加载器
├── config/                     # 配置文件
│   └── tests_config.yaml      # 测试用例配置 (100+ 项)
├── docs/                       # 文档目录
├── tests/                      # 测试目录
├── msg/                        # 自定义消息定义
├── pyproject.toml             # 项目配置
├── uv.lock                    # uv 依赖锁文件
└── README.md                  # 项目文档

🔧 高级用法

开发环境设置

# 克隆仓库
git clone [e-mail]:ad_test/robot-test/rosbag_checker.git
cd rosbag_checker

# 安装开发依赖
uv sync --extra dev

# 代码格式化
uv run black .
uv run ruff check .

添加自定义测试

配置驱动方式（推荐）:

1. 在 config/tests_config.yaml 添加测试配置
2. 指定测试类 (test_class) 和参数 (params)
3. 无需修改代码即可生效

代码方式:

1. 在 test_framework/specialized_tests.py 创建新 TestCase 类
2. 实现 run() 方法，返回 TestResult
3. 在 config/tests_config.yaml 注册测试用例

详见 测试框架架构

📚 文档导航

核心文档

• 📘 使用指南 - 快速开始、结果解读、常见问题
• 📋 测试用例文档 - 完整的 110+ 测试用例定义
• 📊 测试覆盖率分析 - 已实现 vs 文档定义对比
• 📚 完整文档索引 - 所有文档导航

技术文档

• 🏗️ 测试框架架构 - 测试框架设计说明
• 🔧 测试规范 - 从飞书文档提取的完整规范
• 🚀 开发路线图 - 项目发展规划
• 🔬 ROS2 扩展指南 - 高级开发文档

参考

• 🔗 飞书规范文档 - 官方测试规范

🐛 常见问题

依赖冲突或环境问题

# 重新同步依赖
uv sync --reinstall

# 清理并重建虚拟环境
rm -rf .venv uv.lock
uv sync

相机帧率不足

问题: videoclip 帧率检查 ✗ - 帧率 1.5 Hz < 29.8 Hz

解决方案:

1. 检查相机驱动配置文件
2. 确认 frame_rate 参数 ≥ 30
3. 重新录制 bag

多相机时间戳不同步

问题: 多相机时间戳同步检查 ✗ - 偏差 201.6ms > 50ms

解决方案:

1. 启用硬件时间同步 (PTP/gPTP)
2. 验证系统 NTP 配置
3. 确认所有相机使用统一时间源

更多问题见 使用指南

🤝 贡献与开发路线图

欢迎提交 Issue 和 Pull Request！

版本历史

版本	状态	主要功能
v3.0	✅	测试框架完整实现 (51 项)
v4.0	✅	测试框架扩展 (78 项)
v4.1	✅	IMU/TF 完整集成 (82 项)
v4.3	✅	camera_info/xsens/TF_static (87 项)
v5.0	✅	配置驱动框架 (100+ 项) - 667行硬编码 → 101行配置 - 4种状态系统 - SKIP/WARN 灵活控制
v5.1	📋 计划中	补全所有关节组和传感器测试
v6.0	🚀 规划中	性能优化 + 测试报告增强

📄 许可证与致谢

本项目采用 MIT License 开源协议。

感谢所有贡献者对项目的支持！

技术规范参考

• 官方规范: 飞书文档 - ROS2 Bag 录制规范
• 本地规范: ROSBAG_TEST_SPECIFICATION.md

---

维护团队: ROS2 Bag Checker Team
最后更新: 2026-04-30
项目状态: 🟢 活跃维护