Robot Experiments (机器人实验项目)

这是一个机器人实验项目集合，包含多个实验模块，使用统一的模拟环境进行开发和测试。

项目结构

核心实验模块

• exp1_firmware/ - 固件实验

  • 蜂鸣器控制
  • PWM舵机控制
  • 电机控制
  • 串行通信

• exp2_lidar/ - 激光雷达实验

  • SLAM (gmapping)
  • 路径规划与导航
  • 障碍物规避

• exp3_depth_camera/ - 深度相机实验

  • 深度图处理
  • 颜色检测与跟踪
  • 视觉伺服

• xiaoxueqi_color_picker/ - 颜色识别与抓取实验

  • 基于深度相机的颜色识别
  • 机器人自动抓取任务

工具与基础设施

• mock/ - 统一模拟环境

  • ROS (rospy) 模拟
  • 传感器消息模拟
  • 硬件接口模拟

• data/ - 数据处理工具

  • 数据集导入 (TUM RGB-D)
  • 合成数据生成
  • 数据回放

• visualization/ - 可视化工具

  • 地图绘制
  • 实验结果统计
  • 主题监控

• tests/ - 测试套件

• tools/ - 端到端工具

快速开始

环境要求

• Python 3.6+
• 所需依赖包（见 requirements.txt）

安装依赖

pip install -r requirements.txt

运行演示

大多数实验脚本会自动使用模拟环境，无需完整ROS安装：

# 固件实验演示
python3 experiments/exp1_firmware/scripts/run_buzzer_demo.py

# 激光雷达SLAM演示
python3 experiments/exp2_lidar/scripts/run_gmapping_demo.py

# 深度相机演示
python3 experiments/exp3_depth_camera/scripts/run_depth_camera_demo.py

# 颜色抓取演示
python3 experiments/xiaoxueqi_color_picker/scripts/run_color_picker_demo.py

运行测试

python3 -m pytest tests/

模拟环境配置

项目使用统一的mock系统，可以通过环境变量配置：

# 启用调试模式
export MOCK_DEBUG=1

# 设置延迟时间
export MOCK_DELAY=0.01

# 运行演示
python3 experiments/exp2_lidar/scripts/run_gmapping_demo.py

开发环境设置

克隆项目

git clone https://github.com/yourusername/robot-experiments.git
cd robot-experiments

创建虚拟环境（推荐）

python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows
pip install -r requirements.txt

详细配置选项

模拟环境变量

变量名	默认值	描述
MOCK_DELAY	0.002	硬件/串行延迟秒数
MOCK_DEBUG	false	启用调试日志记录
MOCK_NOISE_STD	0.0	传感器噪声标准差（米）
MOCK_AUTO_REPORT	true	启用自动周期性报告
MOCK_AUTO_REPORT_FREQ	5.0	自动报告频率（Hz）
MOCK_PICKER_RETRIES	2	颜色选择器重试次数
MOCK_FILTER_WINDOW	5	颜色跟踪器过滤窗口
MOCK_FILTER_THRESHOLD	3	颜色跟踪器过滤阈值
MOCK_ARTIFACTS_DIR	experiments/artifacts	生成工件存储目录

高级配置示例

# 高精度模拟（减少噪声和延迟）
export MOCK_DELAY=0.001
export MOCK_NOISE_STD=0.01
export MOCK_DEBUG=1

# 自定义输出目录
export MOCK_ARTIFACTS_DIR=/tmp/robot_experiments_output

实验数据与输出

数据目录结构

• artifacts/ - 实验运行时生成的输出文件

  • color_pick_report.jsonl - 颜色选择器实验结果
  • exp2_run_*/ - 激光雷达实验快照和日志
  • *_stats.png - 统计图表

• data/ - 输入数据和工具

  • synthetic_lidar.jsonl - 合成激光雷达数据
  • synthetic_complex.jsonl - 复杂场景合成数据

输出文件格式

• 地图文件: map_snapshot_N.npy (numpy数组), map_snapshot_N.png (可视化)
• 日志文件: run_*.py.log (执行日志)
• 报告文件: *.jsonl (JSON Lines格式的结果)
• 轨迹数据: timeseries.csv (时间序列数据)

项目架构

模拟系统设计

项目采用轻量级模拟架构，无需安装完整ROS：

mock/
├── rospy.py          # ROS Python API模拟
├── sensor_msgs/      # 传感器消息类型
├── geometry_msgs/    # 几何消息类型
├── std_msgs/         # 标准消息类型
├── Rosmaster_Lib.py  # 硬件接口模拟
└── serial.py         # 串行通信模拟

核心组件

• 消息总线: 基于发布-订阅模式的轻量级实现
• 传感器模拟: 生成真实istic的激光雷达、深度相机数据
• 硬件接口: Rosmaster机器人平台API模拟
• 自动报告: 周期性发布机器人状态信息

故障排除

常见问题

1. ImportError: 确保PYTHONPATH正确设置

   export PYTHONPATH=/path/to/project/experiments/mock:$PYTHONPATH

2. 权限错误: 检查输出目录权限

   chmod 755 experiments/artifacts

3. 内存不足: 减少地图分辨率或实验规模

   export MOCK_DEBUG=0  # 禁用详细日志

调试模式

启用详细日志进行问题诊断：

export MOCK_DEBUG=1
python3 experiments/exp2_lidar/scripts/run_gmapping_demo.py

测试与验证

运行测试套件

# 运行所有测试
python3 -m pytest tests/

# 运行特定测试
python3 -m pytest tests/test_color_picker_detailed.py -v

# 生成覆盖率报告
python3 -m pytest --cov=experiments tests/

集成测试

# 端到端测试
python3 tools/run_end_to_end.py

# 实验聚合器
python3 tools/end_to_end_aggregator.py

API参考

模拟ROS API

项目提供以下ROS兼容API：

• rospy: init_node, Publisher, Subscriber, spin, shutdown
• 消息类型: LaserScan, Image, Twist, String, Vector3
• 硬件接口: Rosmaster类（电机控制、传感器读取、蜂鸣器等）

扩展模拟

如需添加新的传感器或API：

1. 在 mock/ 目录下添加相应模块
2. 遵循现有命名约定
3. 更新 mock/__init__.py 导出列表

限制与已知问题

• 模拟环境不完全替代真实ROS安装
• 某些高级ROS特性（如tf变换树）未实现
• 硬件接口模拟基于简化模型
• 大规模实验可能消耗较多内存

许可证

本项目采用MIT许可证 - 查看 LICENSE 文件了解详情。

贡献指南

我们欢迎贡献！请遵循以下步骤：

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

代码规范

• 使用Black格式化代码
• 添加适当的docstring
• 为新功能编写测试
• 更新相关文档

致谢

本项目基于以下开源工作：

• ROS (Robot Operating System)
• NumPy, Matplotlib, OpenCV等科学计算库
• 各种SLAM和计算机视觉算法

---

如有问题或建议，请通过GitHub Issues联系维护者。