# ros2_web_controller

**Repository Path**: djboy1021/ros2_web_controller

## Basic Information

- **Project Name**: ros2_web_controller
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-14
- **Last Updated**: 2026-02-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ros_web_controller

一个面向ROS2的轻量级Web控制与监控解决方案：后端以C++/ROS2节点提供HTTP API与静态文件服务，前端为纯静态页面（无需打包），开箱即用，适合集成到机器人控制台或远程运维面板。

**核心能力**
- Web控制：通过浏览器下发速度、动作与预设命令
- 实时监控：订阅话题并在前端可视化（内置Chart.js）
- 统一API：HTTP接口覆盖控制、订阅、历史与预设
- 易部署：`colcon + ament_cmake` 构建，静态前端随包安装
- 可扩展：C++14编写，模块清晰，便于二次开发

---

**环境要求**
- `Ubuntu`（推荐在UTM虚拟机中开发）
- `ROS2`（任何支持 `ament_cmake` 与 `rclcpp` 的发行版）
- 系统依赖：`Boost (system, thread)`、`Threads`、`yaml-cpp`

可选：执行 `scripts/install_deps.sh` 安装系统与ROS依赖。

---

**快速开始**
- 准备ROS环境：
  - 配置ROS发行版：`source /opt/ros/<distro>/setup.bash`
- 编译与安装：
  - 在工作空间根目录执行：
    - `colcon build --symlink-install`
    - `source install/setup.bash`
- 启动（推荐）
  - 使用Launch文件：
    - `ros2 launch ros_web_controller ros_web_controller.launch.py web_port:=8527`
  - 直接运行可执行：
    - `ros2 run ros_web_controller ros_web_controller_node`
- 访问前端：
  - 浏览器打开：`http://<host>:8527/`

---

**目录结构**
- 后端源码：`src/*.cpp`，头文件：`include/*.h`
- 前端静态：`web/index.html`、`web/app.js`、`web/style.css`
- 启动配置：`launch/ros_web_controller.launch.py`
- 运行脚本：`scripts/start_controller.sh`、`scripts/test_controller.sh`
- 预设配置：`config/preset_commands.yaml`
- 构建文件：`CMakeLists.txt`、`package.xml`

安装后资源位置（示例）：
- 二进制：`lib/ros_web_controller/ros_web_controller_node`
- 静态前端：`share/ros_web_controller/web`
- 启动与配置：`share/ros_web_controller/{launch,config}`

---

**HTTP API**
- `POST /api/control/velocity`
  - 用途：发送速度命令
  - 示例：
    ```json
    { "vx": 0.2, "vy": 0.0, "vw": 0.1 }
    ```
- `GET /api/topics/list`
  - 用途：查询可订阅话题列表
- `POST /api/monitor/subscribe`
  - 用途：订阅话题并推送数据
  - 示例：
    ```json
    { "topic": "/odom", "type": "nav_msgs/Odometry" }
    ```
- `POST /api/command/send`
  - 用途：下发即时命令
  - 示例：
    ```json
    { "name": "dock", "params": {"force": true} }
    ```
- `GET /api/command/history`
  - 用途：查询命令历史
- `GET /api/command/preset`
  - 用途：获取预设命令清单
- `POST /api/command/execute_preset`
  - 用途：执行预设命令
  - 示例：
    ```json
    { "id": "rotate_90" }
    ```

静态资源路由：`/` 与文件路径映射到 `web_root`（默认 `share/ros_web_controller/web`）。

---

**前端说明**
- 入口：`web/index.html`
- 依赖：`Chart.js`（CDN加载）
- 交互：`web/app.js` 实现控制面板、订阅与图表渲染
- 样式：`web/style.css`

---

**开发与构建**
- 语言/标准：C++14
- 构建系统：`ament_cmake`（见 `CMakeLists.txt`）
- 包清单：`package.xml`（声明依赖与许可证）
- 代码质量：`ament_lint_auto`、`ament_lint_common`

编译选项与安装规则已在 `CMakeLists.txt` 配置，新增源文件后请同步目标与安装节。

---

**测试**
- 集成测试脚本：`scripts/test_controller.sh`
  - 覆盖内容：连通性、速度控制、话题订阅、命令与历史、前端可用性与性能
- 运行示例：
  - `bash scripts/test_controller.sh http://localhost:8527`

---

**配置与预设**
- 预设命令文件：`config/preset_commands.yaml`
- 可通过Launch参数覆盖：
  - `web_port`（默认 `8527`）
  - `web_root`（静态文件根目录）

---

**部署建议（UTM虚拟机）**
- 网络：UTM使用桥接或端口转发，确保宿主机可访问虚拟机端口 `8527`
- 资源：分配充足内存与CPU以保障图表渲染与HTTP响应
- 安全：若对外开放，建议在反向代理层启用TLS与鉴权

---

**常见问题**
- 无法访问前端
  - 检查 `web_port` 是否被占用；确认路由未被防火墙拦截
- 订阅无数据
  - 确认对应ROS话题存在并发布；检查消息类型匹配
- 命令执行失败
  - 查看后端日志；确认负载参数与权限

---

**许可证**
- 依据 `package.xml` 声明，本项目遵循 `MIT` 许可证
- 建议在仓库根目录添加 `LICENSE` 文件（MIT全文）

---

**致谢**
- 感谢ROS2与社区生态，感谢Chart.js开源项目

---

**变更日志与路线图**
- 初版：提供Web控制、监控与HTTP API
- 规划：
  - 增加鉴权与速率限制
  - 引入单元测试与CI
  - 丰富前端组件与暗色主题

---

**贡献指南**
- Fork并创建特性分支，遵循 `clang-format` 与 `ament` 规范
- 提交PR前运行测试脚本，附带说明与截图
- Issue中请包含环境信息（ROS2发行版、系统版本、网络拓扑）