ROS Flutter GUI App

April 24, 2026 · View on GitHub

中文说明 | English

GitHub last commit GitHub stars GitHub forks GitHub issues QQ 群 Flutter version

app build ROS 2 Humble backend

1. 项目简介

基于 C/S 架构的 ROS 人机交互软件。借助 Flutter 的跨端能力，可在 Web、Android、iOS、macOS 等多端运行（界面布局侧重移动端）。

自 v2.0 起，为提高渲染与通信效率，采用自定义 C++ 后端与前端直连，不再依赖 rosbridge。仍使用 rosbridge 的版本见 v1.2.5。

模块说明
backend运行于机器人侧，与 ROS 2 对接，提供 HTTP、WebSocket 等接口；当前主要兼容 ROS 2（ROS 1 接口预留，欢迎 PR）
appFlutter 客户端 / Web 前端，与后端通信并完成展示

更细的接口、目录与配置见：

文档内容
backend/README.md · backend/README_EN.md后端编译与部署、进程结构、数据目录、config.yaml、HTTP / ROS 摘要
app/README.md · app/README_EN.md前端依赖与构建、连接方式、功能与设置、使用流程

2. 项目预览

界面以瓦片地图为画布，叠加机器人位姿、激光/路径/代价等图层；顶部为速度/电池/导航与诊断状态，左右为图层与工具，可拖动的相机浮窗便于边看图边操作。

主界面：地图与图层

主界面 · 瓦片地图 · 图层开关 · 遥控 / 导航入口

地图编辑

地图管理

地图编辑管理· 障碍与拓扑

ssh

ssh qucik cmd

SSH 功能

diago page

健康诊断

3. 功能一览

功能说明
连接与配置连接页配置 IP 与后端端口；设置页：语言、朝向、手柄映射、图像相关、速度上限等仍存本地；ROS 话题/帧名走后端
地图显示瓦片底图；叠加激光、点云、全局/局部路径、轨迹、代价地图、footprint、拓扑等（数据来自 WS）
位姿后端在地图坐标系下封装位姿并推送
重定位与导航通过后端 HTTP 发布初始位姿与导航目标；拓扑与地图编辑走 HTTP
遥控屏幕摇杆与手柄映射；速度通过机器人 WebSocket 二进制消息下发（ClientRobotMessage.cmd_vel）
相机图像话题订阅由后端转发到 WS；失败时见占位或无画面
地图编辑障碍与拓扑编辑通过 REST 与后端交互
诊断后端推送 DiagnosticArray；主界面可对 ERROR/WARN Toast
电池后端推送 'BatteryState' 话题的电池状态
国际化中/英；横竖屏等应用侧设置
SSH见下文 §3.1

3.1 SSH 远程（快捷指令 / 终端）功能说明

SSH 功能用于局域网远程执行命令和打开交互终端，和地图功能共用同一个后端地址。

  1. 在连接页连接机器人后，可在主界面使用「SSH 快捷指令」和「SSH 终端」。
  2. 前端通过 /ws/ssh 与后端通信，再由后端连接机器人 SSH 服务（SshHost:SshPort）。
  3. 需要在设置 -> SSH 中配置主机、端口、用户名、密码；配置会保存到机器人侧 gui_app_settings.json（通过 /api/settings）。
  4. 公网场景建议使用 HTTPS + WSS，避免明文传输风险。

3.2 地图显示与管理功能说明

  1. 软件动态地图为 map，存储路径在后端的 ~/.maps/map。
  2. 后端启动时会订阅 /map 话题，将收到的数据存储至 ~/.maps/map。在地图管理界面切换地图时，软件会同时将切换到的地图发布到 /map 话题。
  3. 下次启动后端时，也会自动发布当前使用地图到 /map。理论上，软件后端可替代 ROS 的 map server。
  4. 切换地图后，软件默认显示切换后的地图；
  5. 在建图时，如果需要显示原始 /map 话题内容，请切换至 map 地图/由于瓦片地图为了提高绘制效率不会自动更新，软件为了解决这个问题，在开启遥控手柄时会5s强制刷新一次瓦片地图，以实现动态效果。

4. 编译与部署

4.1 从源码构建（推荐：仓库根目录一键）

git clone https://github.com/chengyangkj/ROS_Flutter_Gui_App.git
cd ROS_Flutter_Gui_App
./build.sh

根目录 build.sh 会依次：生成 Dart protobuf → 构建 backend → flutter build web，并将 Web 产物同步到 backend/build/install/bin/dist（供后端静态托管）。

运行前请先安装并配置好 Flutter（flutter 命令需在 PATH 中）。仅构建后端时可进入 backend/ 按该目录 README 使用 CMake；仅构建前端时需先完成协议生成，见 app/README.md。

4.2 仅构建后端

cd backend
sh ./build.sh

4.3 仅构建前端

cd app
flutter pub get
flutter build web --release

其他目标（APK、Linux、Windows 等）参见 app/README.md。建议 Flutter / Dart 版本与工程 pubspec.yaml 中 environment.sdk 一致。

5. 预构建产物（GitHub Releases）

如果不想手动配置环境编译运行，可在 Releases 页面可下载与当前 tag 对应的后端压缩包与多平台客户端，例如（名称随版本变化，以 Release 列表为准）：

类型典型文件名
后端（含 Web dist，x86_64）backend-<tag>-x86_64.zip
后端（arm64）backend-<tag>-arm64.zip
Webapp-<tag>-web.tar.gz
Linuxapp-<tag>-linux-x64.tar.gz
Androidapp-<tag>-android.apk
Windowsapp-<tag>-windows-x64.zip

6. 使用说明

6.1 启动后端

cd backend/build/install/bin
sh ./start.sh

（若从 Release 解压部署，请将路径换为解压后的 bin 目录。）

6.2 打开前端

先启动 6.1 中的后端。默认 HTTP 端口为 8080，浏览器访问例如：

http://127.0.0.1:8080

亦可从 Release 下载对应平台的客户端，配置同一后端地址进行连接。

7. 仓库结构

路径说明
protocol/.proto 定义；根目录 build.sh 生成 Dart 与后端共用的协议代码
backend/C++ 后端，CMake 工程
app/Flutter 应用
build.sh根目录一键构建（protobuf → backend → flutter build web + 拷贝 dist）

8. 📊 Star 历史

Star History Chart