robot-cloud-system

技术文档

1. 项目定位

robot_cloud_system 是一个面向移动机器人云控场景的 Web + ROS 2 集成项目。系统以 Flask-SocketIO 作为 Web 服务入口，以 ROS 2 节点作为机器人能力接入层，以 SQLite 作为本地任务存储，提供以下核心能力：

项目当前更偏向“教学演示 / 原型验证 / 二次开发基础仓库”，不是完整生产级平台。

2. 技术栈

3. 整体架构

项目分为四层：

3.1 Web 接入层

入口文件为 app.py，负责：

3.2 机器人服务层

位于 service_nodes/，负责封装不同类型的机器人能力：

3.3 前端展示层

位于 robot_dashboard/templates/：

3.4 数据持久化层

使用 SQLite，本地数据库文件路径来自环境变量 DATABASE_PATH。

主要表：

4. 目录说明

robot_cloud_system/
├─ app.py
├─ config.py
├─ requirements.txt
├─ .env.example
├─ maps/
├─ robot_dashboard/
│  ├─ static/
│  └─ templates/
├─ service_nodes/
├─ scripts/
│  └─ init_database.py
└─ docs/

目录职责：

5. 运行流程

5.1 启动前准备

  1. 加载 ROS 2 环境
  2. 安装 Python 依赖
  3. 初始化数据库
  4. 启动 rosbridge
  5. 启动 Flask-SocketIO 服务

5.2 系统启动顺序

app.py 启动时的核心流程：

  1. 创建 Flask 应用
  2. 创建 Socket.IO 服务
  3. 调用 init_ros_nodes()
  4. 初始化以下节点实例： WebNode、LidarProcessor、MapServer、NavigationClient、TrajectoryRecorder、TaskQueueManager、TaskStateMachine、SystemShow
  5. 创建 MultiThreadedExecutor
  6. 启动 ROS 线程执行 spin()
  7. 启动系统状态更新线程
  8. 启动 Web 服务

6. 配置说明

配置文件为 config.py，通过 .env 读取参数。

主要配置项：

7. 核心模块详解

7.1 app.py

app.py 同时承担“页面路由 + API + WebSocket + ROS 初始化”四类职责。

主要能力：

当前特点：

7.2 MapServer.py

职责：

输出给前端的数据类型：

7.3 NavigationClient.py

职责：

典型调用场景：

7.4 TaskQueueManager.py

职责：

当前实现特点：

后续可演进方向：

7.5 SystemShow.py

职责：

说明：

8. HTTP API 清单

页面路由

地图与传感器接口

任务接口

系统接口

9. WebSocket 事件清单

连接与基础状态

控制相关

导航点与导航

任务相关

系统相关

10. 数据模型

10.1 tasks

字段说明：

10.2 task_status_history

字段说明：

11. 前后端数据流

11.1 控制链路

  1. 浏览器发起控制命令
  2. Socket.IO 将事件发送到 app.py
  3. app.py 调用 WebNode.publish_cmd_vel()
  4. ROS 2 发布到 /cmd_vel

11.2 地图展示链路

  1. MapServer 接收 /map
  2. MapServer 更新内部缓存
  3. 前端通过 request_map_data 请求
  4. app.py 将地图和位姿通过 Socket.IO 推送到页面

11.3 任务执行链路

  1. 前端调用 /api/tasks 创建任务
  2. 任务写入 SQLite
  3. 前端触发 start_task
  4. app.py 从数据库读取任务
  5. 导航目标进入导航流程
  6. 状态变化写入 task_status_history

12. 已知设计特点与限制

13. 建议的后续演进方向

结构层面

工程层面

业务层面

14. 快速阅读建议

第一次接手这个项目，建议按下面顺序阅读：

  1. README.md
  2. docs/architecture.md
  3. docs/technical-reference.md
  4. app.py
  5. service_nodes/MapServer.py
  6. service_nodes/NavigationClient.py
  7. service_nodes/TaskQueueManager.py

这样可以先建立整体模型，再进入具体实现。