ROS Qt5 GUI App: one Qt interface for ROS1 and ROS2 mobile robots

One code base, three ways to reach the robot

Ros_Qt5_Gui_App is a cross-platform human computer interface for mobile robots, built on Qt5 and CMake. The claim in the project description is that a single unified code base supports ROS1 and ROS2 at the same time, and that the build stage identifies the target ROS runtime automatically from environment variables.

That last point is the mechanism behind the promise. The communication layer and the interface layer are decoupled, so the same window code can drive a ROS1 node, a ROS2 node, or a machine that speaks ROSBridge, and the difference is settled at build or configuration time rather than scattered through the code. Decoupling the two layers is what keeps the cross-version adaptation cost down, and it is the design decision everything else follows from.

The rendering is built on the Qt Graphics View system. The stated reason is that it keeps interactive capability while keeping resource use in mind, for the case of deploying the screen on a compute constrained edge device. That is a real constraint for a robot that also has to run its own stack, and it explains a lot about the interface, which is dense with panels rather than sparse with whitespace.

The audience is a robotics developer who needs a remote console for a mobile robot: someone who wants to watch a map, drive the robot by hand, set a navigation goal and edit a route, without writing a UI.

The channel directory holds the ROS1, ROS2 and RosBridge paths

The repository layout makes the architecture visible. Under `src/` there is `core/` for the core module and program entry point, `mainwindow/` for the main window and interface, `common/` for shared code, `basic/` for basic data structures, `channel/` for the communication channel covering ROS1, ROS2 and ROSBridge, and `plugin/` for the plugin system.

The `channel/` directory is the heart of the design. A channel is a transport, and the interface talks to whichever one is selected without knowing the details. The feature list names the three options, and the documentation for configuration tells the user to pick the correct communication channel in the configuration screen, so the choice is a runtime setting rather than a compile time one.

RosBridge is the odd one out and the most useful for a specific case. The project states that Windows support is delivered through RosBridge communication, and the RosBridge channel supports WebSocket connections with reconnection on disconnection. A Windows workstation therefore talks to a robot that is running ROS1 or ROS2 on Linux through a WebSocket, and the reconnection behaviour matters because a dropped link on a moving robot is a normal event rather than an exception.

The plugin system under `src/plugin/` is the other structural element worth noting. It gives a place to add panels without touching the main window, which is how a project of this size stays navigable.

The three channels also have different maturity levels, and the documentation is blunt about it. ROS1 communication support is described as basic functionality implemented and still being optimised, while ROS2 communication support is the one described as stable and maintained for long term support. If you are choosing a channel for production use, that difference is the deciding fact.

The displays cover maps, trajectories, sensors and manual driving

The feature list is long enough to be worth summarising by area, because it shows what a real operator console has to cover.

Mapping and visualisation come first. Global and local map display handles OccupancyGrid maps, laser scan display visualises LaserScan data, and the robot body outline is drawn from the footprint topic. The robot's real time position is derived from TF transforms, and both global and local planned trajectories are shown as the planner produces them. Camera images can be displayed, and the description says multiple image streams are supported, which matters for a robot with more than one camera.

State comes next. The velocity dashboard shows linear and angular speed in real time, and the battery level is read by subscribing to the BatteryState topic. Manual control of the robot by velocity is supported, along with relocalisation through the 2D Pose Estimate message.

Navigation goals are supported as a single point or as multiple points, and the topological layer adds more. Topological points can be edited visually, and topological paths can be edited visually, which is a different thing from the planner's trajectory. The planner produces a trajectory for the immediate path, while a topological map is a set of waypoints that a person edits by hand to describe the routes a robot should follow around a building.

The map editing features go further than display. Obstacles can be edited in the map, and maps can be loaded and saved as files.

The build detects the ROS runtime, but the environment still has to be sourced

Building on Linux is documented in three layers, and the requirements are stated up front: Ubuntu 18.04 or newer or Windows 10 or newer, ROS1 Melodic or Noetic or ROS2 Foxy, Galactic or Humble, Qt 5.12 or newer with the Core, Widgets and SVG modules, CMake 3.16 or newer, and GCC 7 or newer or MSVC 2019 or newer.

The system dependencies are a single apt invocation:

sudo apt-get update
sudo apt-get install -y \
  qtbase5-dev \
  qtbase5-private-dev \
  libqt5svg5-dev \
  qtbase5-dev-tools \
  libeigen3-dev \
  libgtest-dev \
  libsdl2-dev \
  libsdl2-image-dev

There is a known wrinkle with CMake. The documentation states that the version shipped with Ubuntu 20.04 and older is too old and has to be upgraded to 3.16 or newer, and that Ubuntu 22.04 and newer can skip that step. The upgrade itself is a download of the official installer:

wget https://cmake.org/files/v3.16/cmake-3.16.4-Linux-x86_64.sh -O cmake-install.sh
chmod +x cmake-install.sh
sudo ./cmake-install.sh --prefix=/usr/local --skip-license

After that the repository is cloned and built. The script route is the short one, and the manual route is a plain CMake configure and a parallel make:

git clone https://github.com/chengyangkj/Ros_Qt5_Gui_App.git
cd Ros_Qt5_Gui_App

mkdir build && cd build

cmake ..
make -j$(nproc)

The alternative is `./build.sh`, and there is a separate `./build_cn.sh` that swaps the third party library sources for Gitee mirrors to speed up the build from China, with the mirror repository for each dependency passed to CMake as a variable such as `-Dwebsocketpp_GIT_REPOSITORY`.

Three ways to launch it, and the library path that matters

Running the built binary has three documented methods, and the differences are about where the libraries come from.

The recommended one is the launcher script, which is copied into the build directory after the build. The script sets the library path and starts the program:

cd build
./start.sh

The manual method sets the library path yourself and runs the binary directly:

cd build
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./lib
./ros_qt5_gui_app

The third installs it and runs the installed copy from `install/bin`. The `install/` directory in the repository holds the launcher scripts for both platforms, with `linux/bin/` and `windows/bin/`.

On Windows the same three options exist with the Windows equivalents, and the binary is `ros_qt5_gui_app.exe` with `start.bat` as the launcher. The documentation is explicit that the Windows build environment has to be prepared by the user, naming Visual Studio C++ toolchain, CMake and vcpkg, and pointing at the Windows build workflow in the repository's CI configuration as the reference for the process. The repository also carries a `vcpkg.json`, which is how the Windows dependency set is declared.

Whichever route you take, the documentation asks for three things before the first run: the ROS environment sourced, the topic names in the configuration screen checked against your own system, and the communication channel selected. That last step is the one that catches people out, since the default channel will not necessarily be the one your robot speaks.

Release candidates, a CI matrix and a copyleft licence

The version line is the thing to know before you plan around this project. The most recent releases are v1.0.7-rc9 on 2026-04-23, v1.0.7-rc8 on 2026-04-21 and v1.0.7-rc7 on 2026-04-21, so three release candidates for the same 1.0.7 version were published within a few days of each other. The project has not published a final 1.0.7, and the series is still in the release candidate phase.

The repository is not archived and the last push was on 2026-05-19, so the tree is being worked on, and the CI configuration shows what that work is checked against. There are separate build workflows for ROS Melodic, Noetic, Foxy, Galactic and Humble, and a separate one for Windows, which matches the claim in the project description that the pipeline continuously validates multiple ROS versions across multiple system combinations.

The licence is GPL-2.0, and that is a consideration rather than a detail. GPL-2.0 is a copyleft licence, so a derived work distributed to others carries the obligation to offer the corresponding source. For an internal operator console that never leaves the organisation this is usually a non-issue. For a console that is bundled with a robot sold to customers, it is a conversation to have before the code is embedded in a product, and the licence file in the repository root is the text to read.

The documentation set in `doc/` covers usage, development setup and a FAQ with troubleshooting notes, and the `README_en.md` file holds the English version of the same overview that the Chinese README carries.

Editorial conclusion

Ros_Qt5_Gui_App suits a robotics team that needs an operator console for a mobile robot on either ROS1 or ROS2 and does not want to maintain two interfaces. It is the wrong tool if you need a finished, stable 1.0 release, since the published versions are release candidates, and the wrong tool for a machine that cannot run the full Qt stack. Verify first which channel you will use, because ROS1 support is described as basic and still being optimised while ROS2 support is the one described as stable, then confirm the topic names in the configuration screen match your own robot before you trust the displays.

Frequently asked questions

Official sources

1. chengyangkj/Ros_Qt5_Gui_App on GitHub
2. Issues
3. License: GPL-2.0
4. README
5. Releases