适用系统Ubuntu 22.04.5 LTS开发环境ROS2 Humble界面Qt5编辑器VSCode目录1. 工作目标2. 系统与 ROS2 版本选择3. ROS2 Humble 安装流程4. ROS2 基础通信验证5. 开发工具安装与 rosdep 配置6. ROS2 工作空间与目录结构7. Python ROS2 包配置8. C ROS2 包配置9. Qt5 开发环境安装与测试10. ROS2 Qt GUI 包配置11. Python/C 后端与 Qt 界面通信12. VSCode 配置与头文件虚线处理1. 工作目标目标是在 Ubuntu 22.04.5 LTS 中搭建一套可用于后续机器人二次开发的 ROS2 开发环境并逐步扩展到 Python 后端、C 后端、Qt 图形界面和 VSCode 工程化开发。安装并配置 ROS2 Humble。验证 ROS2 topic 发布/订阅通信是否正常。创建自己的 ROS2 工作空间 Ros2Project。在工作空间内分别建立 Python、C、Qt 三类功能包。配置 VSCode 用于 ROS2、C、Qt、Python 混合开发。实现后端数据通过 ROS2 topic 传递到 Qt 界面显示。排查安装过程中出现的 GitHub 网络、Typora 源、Python 虚拟环境、Qt 头文件识别等问题。2. 系统与 ROS2 版本选择当前系统是 Ubuntu 22.04.5 LTS其系统代号是 jammy。该系统最适配的 ROS2 长期支持版本是 ROS2 Humble Hawksbill。项目选择原因Linux 系统Ubuntu 22.04.5 LTS当前机器已经安装稳定适合 ROS2 HumbleROS2 版本Humble Hawksbill官方支持 Ubuntu 22.04资料多机器人项目兼容性好Qt 版本Qt5Ubuntu 22.04 apt 源支持成熟Qt Widgets 开发方便编辑器VSCode适合管理 ROS2 工作空间支持 C、Python、CMake、Qt 插件结论当前环境采用 Ubuntu 22.04.5 LTS ROS2 Humble Qt5 VSCode 的组合适合后续进行机器人应用层开发、后端数据处理、图形界面显示和 ROS2 topic/service 调试。3. ROS2 Humble 安装流程3.1 更新系统sudo apt updatesudo apt upgrade -y作用更新 apt 软件源和系统已有软件包避免后续安装 ROS2 时出现依赖版本冲突。3.2 设置 UTF-8 语言环境sudo apt install locales -ysudo locale-gen en_US en_US.UTF-8sudo update-locale LC_ALLen_US.UTF-8 LANGen_US.UTF-8export LANGen_US.UTF-8locale作用确保 ROS2、Python、colcon、rosdep 等工具处理文本时不会出现编码问题。3.3 启用 Universe 仓库sudo apt install software-properties-common -ysudo add-apt-repository universe作用Ubuntu 的部分依赖包位于 universe 仓库ROS2 安装需要该仓库中的依赖。3.4 添加 ROS2 软件源安装时最初尝试通过 GitHub 下载 ros2-apt-source.deb但由于终端访问 GitHub 超时出现连接超时。之后改用传统方式添加 packages.ros.org 的 ROS2 源。sudo apt updatesudo apt install curl gnupg lsb-release -ysudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \-o /usr/share/keyrings/ros-archive-keyring.gpgecho deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release echo $UBUNTU_CODENAME) main | \sudo tee /etc/apt/sources.list.d/ros2.list /dev/nullsudo apt update3.5 安装 ROS2 Humble Desktopsudo apt install ros-humble-desktop -y安装内容作用ROS2 核心库提供 node、topic、service、parameter 等基础能力demo_nodes用于 talker/listener 安装验证RViz2后续可视化地图、点云、路径和机器人模型常用消息包如 std_msgs、sensor_msgs、nav_msgs 等ROS2 CLI提供 ros2 topic、ros2 node、ros2 service 等命令3.6 配置 ROS2 环境变量source /opt/ros/humble/setup.bashecho source /opt/ros/humble/setup.bash ~/.bashrcsource ~/.bashrcros2 --help如果 ros2 --help 能正常显示帮助信息说明 ROS2 命令行环境配置成功。4. ROS2 基础通信验证安装完成后使用官方 talker/listener 验证 ROS2 topic 发布/订阅通信。4.1 第一个终端运行 talkersource /opt/ros/humble/setup.bashros2 run demo_nodes_cpp talker4.2 第二个终端运行 listenersource /opt/ros/humble/setup.bashros2 run demo_nodes_py listener验证项目结果ros2 命令可用正常C 节点可运行正常Python 节点可运行正常topic 发布/订阅通信正常ROS2 Humble 安装成功5. 开发工具安装与 rosdep 配置5.1 安装 colcon、rosdep 和开发工具sudo apt install ros-dev-tools -ysudo apt install python3-colcon-common-extensions -ysudo apt install python3-rosdep -y工具作用colconROS2 工作空间构建工具rosdep根据 package.xml 自动安装依赖ros-dev-toolsROS2 开发常用工具集合5.2 初始化 rosdepsudo rosdep initrosdep update如果 sudo rosdep init 提示 default sources list file already exists说明之前已经初始化过直接执行 rosdep update 即可。6. ROS2 工作空间与目录结构创建了自己的 ROS2 工作空间 Ros2Project。工作空间遵循 ROS2 标准结构src 中放源码包build/install/log 是编译自动生成目录。mkdir -p ~/Ros2Project/srccd ~/Ros2Projectcolcon buildsource install/setup.bash6.1 最终推荐目录结构Ros2Project/├── src/│ ├── RosPython/│ │ └── my_first_pkg/│ ├── RosCpp/│ │ └── ros_cpp_demo/│ └── RosQt/│ └── robot_qt_gui/├── build/├── install/├── log/└── .vscode/目录作用src/RosPython存放 Python ROS2 功能包src/RosCpp存放 C ROS2 功能包src/RosQt存放 Qt ROS2 图形界面功能包build编译中间文件不手动修改install编译安装结果source 后 ROS2 才能识别包log编译日志用于排查错误.vscodeVSCode 工程配置7. Python ROS2 包配置Python 包路径~/Ros2Project/src/RosPython/my_first_pkg。该包用于快速写后端数据节点、接口测试节点和订阅节点。cd ~/Ros2Project/src/RosPythonros2 pkg create my_first_pkg --build-type ament_python --dependencies rclpy std_msgs7.1 Python 包中的可执行节点ros2 pkg executables my_first_pkg节点作用first_node第一个 Python ROS2 测试节点cpp_listener订阅 C 节点发布的话题用于测试 C 到 Python 通信backend_publisher后端数据发布节点向 /backend_status 发布数据供 Qt 界面显示7.2 setup.py 中的 entry_pointsentry_points{console_scripts: [first_node my_first_pkg.first_node:main,cpp_listener my_first_pkg.cpp_listener:main,backend_publisher my_first_pkg.backend_publisher:main,],},作用告诉 ROS2 哪些 Python 文件可以通过 ros2 run 启动。如果没有配置 entry_pointsros2 pkg executables 可能没有输出。8. C ROS2 包配置C 包路径~/Ros2Project/src/RosCpp/ros_cpp_demo。该包用于编写 C 后端节点适合后续处理实时性更高或性能要求更高的功能。cd ~/Ros2Project/src/RosCppros2 pkg create ros_cpp_demo --build-type ament_cmake --dependencies rclcpp std_msgs --node-name cpp_node8.1 C 包结构ros_cpp_demo/├── CMakeLists.txt├── package.xml├── include/└── src/└── cpp_node.cpp8.2 CMakeLists.txt 核心内容cmake_minimum_required(VERSION 3.8)project(ros_cpp_demo)if(NOT CMAKE_CXX_STANDARD)set(CMAKE_CXX_STANDARD 17)endif()if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES Clang)add_compile_options(-Wall -Wextra -Wpedantic)endif()find_package(ament_cmake REQUIRED)find_package(rclcpp REQUIRED)find_package(std_msgs REQUIRED)add_executable(cpp_node src/cpp_node.cpp)ament_target_dependencies(cpp_node rclcpp std_msgs)install(TARGETScpp_nodeDESTINATION lib/${PROJECT_NAME})ament_package()配置语句作用find_package(rclcpp REQUIRED)引入 ROS2 C 客户端库find_package(std_msgs REQUIRED)引入标准消息类型add_executable(cpp_node src/cpp_node.cpp)将源文件编译成可执行节点ament_target_dependencies链接 ROS2 依赖install(TARGETS ...)让 ros2 run 可以找到 cpp_nodeament_package()声明当前包为 ROS2 ament 包9. Qt5 开发环境安装与测试9.1 安装基础构建工具sudo apt install build-essential cmake ninja-build gdb git pkg-config -y9.2 安装 Qt5 开发包sudo apt install qtbase5-dev qtbase5-dev-tools qttools5-dev qttools5-dev-tools qtchooser qt5-qmake -ysudo apt install libqt5serialport5-dev libqt5svg5-dev -y9.3 检查 Qt 安装qmake -vwhich qmake如果 qmake -v 可以输出 Qt 版本说明 Qt5 开发包安装成功。9.4 QtTest 测试项目曾创建普通 QtTest 文件夹用于验证 Linux VSCode Qt 是否能正常弹出窗口。该测试通过后正式开发已经迁移到 src/RosQt/robot_qt_gui因此 QtTest 可以删除。cd ~/Ros2Projectrm -rf QtTest10. ROS2 Qt GUI 包配置创建 robot_qt_gui 作为正式的 Qt ROS2 图形界面包。该包本质是一个 C ROS2 ament_cmake 包同时链接 Qt5 Widgets。cd ~/Ros2Project/srcmkdir -p RosQtcd RosQtros2 pkg create robot_qt_gui --build-type ament_cmake --dependencies rclcpp std_msgs10.1 robot_qt_gui 的 CMakeLists.txtcmake_minimum_required(VERSION 3.8)project(robot_qt_gui)if(NOT CMAKE_CXX_STANDARD)set(CMAKE_CXX_STANDARD 17)endif()set(CMAKE_CXX_STANDARD_REQUIRED ON)set(CMAKE_AUTOMOC ON)set(CMAKE_AUTOUIC ON)set(CMAKE_AUTORCC ON)if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES Clang)add_compile_options(-Wall -Wextra -Wpedantic)endif()find_package(ament_cmake REQUIRED)find_package(rclcpp REQUIRED)find_package(std_msgs REQUIRED)find_package(Qt5 REQUIRED COMPONENTS Widgets)add_executable(robot_qt_gui_nodesrc/main.cpp)ament_target_dependencies(robot_qt_gui_noderclcppstd_msgs)target_link_libraries(robot_qt_gui_nodeQt5::Widgets)install(TARGETSrobot_qt_gui_nodeDESTINATION lib/${PROJECT_NAME})ament_package()10.2 Qt GUI 节点能力弹出 Qt 窗口。创建 ROS2 节点 robot_qt_gui_node。订阅 /backend_status 话题。将接收到的后端数据实时显示到界面 Label 上。通过 QTimer 定时执行 rclcpp::spin_some(node_)让 Qt 事件循环和 ROS2 回调同时工作。11. Python/C 后端与 Qt 界面通信当前后端与界面之间采用 ROS2 topic 通信。后端节点负责发布数据Qt 界面节点订阅数据并显示。链路话题说明Python 后端 → Qt/backend_statusbackend_publisher 发布字符串robot_qt_gui_node 显示C 后端 → Qt/backend_statuscpp_node 修改为同一话题后Qt 无需修改即可显示C → Python/cpp_chatter 或自定义 topic用于验证跨语言节点通信11.1 Python 后端运行cd ~/Ros2Projectsource /opt/ros/humble/setup.bashsource install/setup.bashros2 run my_first_pkg backend_publisher11.2 Qt 界面运行cd ~/Ros2Projectsource /opt/ros/humble/setup.bashsource install/setup.bashros2 run robot_qt_gui robot_qt_gui_node11.3 C 后端统一发布到 /backend_statuspublisher_ this-create_publisherstd_msgs::msg::String(backend_status, 10);msg.data C 后端数据更新当前计数 std::to_string(count_);这样 Qt 界面不用修改只要订阅 /backend_status就能显示 Python 或 C 后端发来的数据。12. VSCode 配置与头文件虚线处理12.1 推荐打开整个工作空间cd ~/Ros2Projectcode .不要只打开某个功能包目录否则 VSCode 可能无法正确识别 build、install、src 和 .vscode 配置。12.2 推荐插件插件用途C/CC 代码提示、跳转、调试CMake ToolsCMake 配置和构建支持CMakeCMakeLists.txt 语法支持Qt 插件辅助识别 Qt 工程和 Qt 路径PythonPython 节点开发ROS 插件ROS2 工程辅助12.3 settings.json 推荐配置{C_Cpp.default.compileCommands: ${workspaceFolder}/build/robot_qt_gui/compile_commands.json,C_Cpp.default.cppStandard: c17,C_Cpp.default.intelliSenseMode: linux-gcc-x64,cmake.configureOnOpen: false,python.terminal.activateEnvironment: false}12.4 处理 Qt/ROS2 头文件虚线如果 VSCode 中 QApplication、rclcpp.hpp、std_msgs/msg/string.hpp 等 include 出现虚线但 colcon build 可以成功通常是 IntelliSense 路径没有加载不是代码错误。cd ~/Ros2Projectsource /opt/ros/humble/setup.bashcolcon build --symlink-install --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDSONsource install/setup.bash执行后在 VSCode 中使用 Ctrl Shift P选择 Developer: Reload Window 重新加载窗口。