ROS 2 学习笔记与配套代码：自语言基础起，至自制两轮差速机器人（
szcbot）的实车导航。
内容覆盖：Python / C++ 语言基础，话题、服务、参数与 Launch，TF 与可视化工具， URDF 建模与 Gazebo 仿真，SLAM 建图与 Nav2 导航，pluginlib 与 Nav2 自定义插件， ESP32 + micro-ROS 实体机器人，以及 QoS、执行器、生命周期节点、组件与 DDS 调优。
| 位置 | 说明 | |
|---|---|---|
| 笔记 | ROS2/ |
97 篇 Markdown，逐节对应源码，见 笔记索引 |
| 代码 | 111/ ~ 999/、10/ |
各章配套工作空间，见 环境与依赖 |
| 附件 | _resources/ |
图片与 PDF，已内嵌于笔记正文 |
git clone https://github.com/Vince-0906/ROS.git
cd ROS笔记按阅读顺序编为一条链路，起点为 2.5.2 C++新特性，每篇末尾链至下一节； 亦可自 笔记索引 按章检索。笔记正文中的链接均为标准 Markdown 相对链接，图片以标准语法内嵌，不依赖特定编辑器的扩展。
编译代码前请先核对 环境与依赖 中的版本要求， 并按「各章工作空间」一节定位对应目录。
共 97 篇笔记。其中 90 篇编入一条阅读链路，首篇为 2.5.2 C++新特性，末篇为 10.6.4 使用DDS共享内存；每篇正文顶部标注上一节与该节对应的源码路径，底部标注下一节。余下 7 篇为速查与参考，不入链路。
「配套代码」一列指向该节对应的源码文件，悬停可查看完整路径。
全部笔记均带 ROS2 标签，并按主题细分：
| 标签 | 篇数 | 含义 |
|---|---|---|
ROS2 |
97 | 全部笔记 |
实战 |
24 | 实体机器人与进阶专题（第 9–10 章） |
工具和仿真 |
22 | TF / RViz / bag / URDF / Gazebo（第 5–6 章） |
cpp |
17 | C++ 实现 |
python |
15 | Python 实现 |
导航 |
15 | Nav2 导航与插件（第 7–8 章） |
Linux |
2 | Linux 与命令行 |
以下笔记不在阅读链路内，供随时检索。
| 笔记 | 内容 | 配套代码 |
|---|---|---|
| ROS2基础 | Topic / Service / Parameter / Action 四种通信方式，Gazebo、Nav2、MoveIt 2 三大框架 | — |
| ROS2相关命令 | 功能包创建、构建、ros2 node/topic/service/param 命令速查 |
— |
| ROS2 版本 | 各发行版发布 / EOL 时间表与 LTS 选型建议 | — |
| Linux命令 | 安装 ROS 2 与常用文件操作命令 | — |
| C++速成 | 指针、命名空间、智能指针、STL、Lambda、模板等 12 个主题速查 | src/ |
| C++速成EZ版 | 同上内容的生活化比喻版，面向初学者 | src/ |
| CODE_EXPLANATION | turtle_control.cpp 与 patrol_client.cpp 逐行详解 + ROS 2 代码模板 |
turtle_control.cpp · patrol_client.cpp · Patrol.srv |
配套代码目录：222/
| # | 笔记 | 内容 | 配套代码 |
|---|---|---|---|
| 1 | 2.5.2 C++新特性 | auto、智能指针、Lambda、函数包装器 |
learn_auto.cpp · learn_shared_ptr.cpp · learn_lambda.cpp · learn_functional.cpp |
| 2 | 2.5.3.1 多线程 | Python threading 与并发下载 |
learn_thread.py |
配套代码目录：333/
| # | 笔记 | 内容 | 配套代码 |
|---|---|---|---|
| 3 | 3.2.1 通过Topic创建小说 | 发布者与发布频率验证 | novel_pub_node.py |
| 4 | 3.2.2 订阅小说并合成语音 | 订阅者 + TTS 语音合成 | novel_sub_node.py · novel1.txt |
| 5 | 3.3.1 发布速度控制海龟画圆 | C++ 发布者、隐式转换陷阱 | turtle_circle.cpp |
| 6 | 3.3.2 订阅pose实现闭环控制 | P 控制闭环 | turtle_control.cpp |
| 7 | 3.4.2 自定义通信接口 | .msg 定义、rosidl 生成、CMake 与 package.xml 配置 |
SystemStatus.msg · sys_status_pub.py |
| 8 | 3.4.4 在功能包中使用QT | Qt 接入 ament_cmake | hello_qt.cpp · CMakeLists.txt |
| 9 | 3.4.5 订阅数据并用Qt显示 | 系统状态可视化面板 | sys_status_display.cpp |
配套代码目录：444/ws
| # | 笔记 | 内容 | 配套代码 |
|---|---|---|---|
| 10 | 4.2.2 人脸检测 | OpenCV 人脸检测基础 | learn_face_detect.py |
| 11 | 4.2.3 人脸检测服务实现 | Python 服务端 | FaceDetector.srv · face_detect_node.py |
| 12 | 4.2.4 人脸检测客户端的实现 | 客户端与 executor 嵌套踩坑记录 | face_detect_client_node.py |
| 13 | 4.3.2 服务端代码实现 | C++ 服务端 | Patrol.srv · turtle_control.cpp |
| 14 | 4.3.3 客户端代码实现 | async_send_request 异步调用 |
patrol_client.cpp |
| 15 | 4.4.1 参数声明设置 | Python 参数声明与读写 | face_detect_node.py |
| 16 | 4.4.2 订阅参数更新 | 参数回调 | face_detect_node.py |
| 17 | 4.4.3 客户端代码实现 | Python 参数客户端 | face_detect_client_node.py |
| 18 | 4.5.1 参数声明与设置 | C++ 参数声明与读写 | turtle_control.cpp |
| 19 | 4.5.2 接收参数事件 | 参数事件回调 | turtle_control.cpp |
| 20 | 4.5.3 修改其他节点的参数 | 跨节点参数修改 | patrol_client.cpp |
| 21 | 4.6.1 使用Launch启动多个节点 | launch 文件与安装配置 | demo.launch.py |
| 22 | 4.6.2 使用launch传递参数 | launch 里声明与获取参数 | demo.launch.py |
| 23 | 4.6.3 launch使用进阶 | 动作、条件、替换三大组件 | actions.launch.py |
配套代码目录：555/ws
| # | 笔记 | 内容 | 配套代码 |
|---|---|---|---|
| 24 | 5.1.1 通过命令行使用TF | tf2_tools、TF 树导出（含 PDF 附件） |
— |
| 25 | 5.2.1 从机械臂底座到相机的静态TF发布 | Python 静态 TF 广播 | static_tf_broadcast.py |
| 26 | 5.2.2 通过Python发布动态TF | Python 动态 TF 广播 | dynamic_tf_broadcaster.py |
| 27 | 5.2.3 通过Python查询TF关系 | Duration 超时与四元数转换坑 |
tf_listener.py |
| 28 | 5.3.1 通过C++发布静态TF | C++ 静态 TF 广播 | static_tf_broadcaster.cpp |
| 29 | 5.3.2 通过C++发布动态TF | C++ 动态 TF 广播 | dynamic_tf_broadcaster.cpp |
| 30 | 5.3.3 通过C++查询TF关系 | C++ lookupTransform |
tf_listener.cpp |
| 31 | 5.4.2 数据化可视工具Rviz | 启动方式与配置文件 | display_robot_model.rviz |
| 32 | 5.5 数据记录工具ros2 bag | 录制与回放 | — |
| 33 | 5.6 Git进阶 | 撤销修改、分支管理 | — |
配套代码目录：666/ws
配套代码目录：777/ws
| # | 笔记 | 内容 | 配套代码 |
|---|---|---|---|
| 52 | 7.2.2 将地图保存为文件 | map_saver 与 room.yaml |
room.yaml |
| 53 | 7.3.3 编写launch并启动导航 | nav2_params.yaml 与导航 launch |
navigation2.launch.py · nav2_params.yaml |
| 54 | 7.3.4 进行单点与路点导航 | RViz 中下发目标 | navigation2.launch.py |
| 55 | 7.3.7 优化导航速度和膨胀半径以及到点精度 | 速度、膨胀系数、到点容差调参 | nav2_params.yaml |
| 56 | 7.4.1 使用话题初始化机器人位姿 | /initialpose |
init_robot_pose.py |
| 57 | 7.4.2 使用TF获取机器人实时位置 | Python 与 C++ 两版实现 | get_robot_pose.py · get_robot_pose_cpp.cpp |
| 58 | 7.4.3 调用接口进行单点导航 | NavigateToPose action |
nav_to_pose.py |
| 59 | 7.4.4 使用接口完成路点导航 | FollowWaypoints action |
waypoint_follower.py |
| 60 | 7.5.2 编写巡检控制节点 | 自动巡检节点与 YAML 配置 | partol_node.py · partol_config.yaml · autopatrol.launch.py |
| 61 | 7.5.3 添加语音播报功能 | 自定义 SpeechText.srv + espeak 服务端 |
SpeechText.srv · speaker.py · partol_node.py |
| 62 | 7.5.4 订阅图像并记录 | 巡检抓图落盘与话题桥接补充 | partol_node.py · bridge.yaml |
配套代码目录：888/
| # | 笔记 | 内容 | 配套代码 |
|---|---|---|---|
| 63 | 8.1.3 创建插件 | pluginlib 基类与三个运动控制器实现 | motion_control_interface.hpp · linear_motion_controller.cpp · spin_motion_controller.cpp · zshaped_motion_controller.cpp |
| 64 | 8.1.4 编写插件测试程序 | 插件加载测试与动态库检查 | test_plugin.cpp · CMakeLists.txt |
| 65 | 8.2 配置自定义导航并测试 | 自定义 Nav2 全局规划器（含 Jazzy 接口变更） | nav2_custom_planner.cpp · nav2_custom_planner.hpp · custom_planner_plugin.xml · nav2_params.yaml |
| 66 | 8.3 配置自定义导航控制器并测试 | 自定义 Nav2 局部控制器 | custom_controller.cpp · custom_controller.hpp · nav2_custom_controller.xml · nav2_params.yaml |
配套代码目录：999/
| # | 笔记 | 内容 | 配套代码 |
|---|---|---|---|
| 67 | 9.1 主要配置 | WiFi / UDP 配置、micro-ROS Agent 与雷达驱动 Docker | udpserver.py |
| 68 | 9.2 硬件 | 电机参数、ESP32 与 PlatformIO 工程流程 | platformio.ini · main.cpp |
| 69 | 9.3 PID控制，运动学正逆解，里程计计算 | PidController 与 Kinematics 实现 |
PidController.cpp · Kinematics.cpp · main.cpp |
| 70 | 9.4.1 microROS初始化和节点 | Agent 启动与固件端节点 | platformio.ini · main.cpp |
| 71 | 9.4.2 订阅话题控制机器人 | 固件端订阅 cmd_vel |
main.cpp |
| 72 | 9.4.3 发布机器人里程计话题 | 固件端发布 odom |
main.cpp |
| 73 | 9.5.1 驱动并显示雷达点云 | YDLidar 驱动与串口转发配置 | tcpserver.py |
| 74 | 9.5.3 准备机器人URDF | 实车 URDF 与 urdf2tf.launch.py |
szcbot.urdf · urdf2tf.launch.py |
| 75 | 9.5.4 发布里程计TF | odom2tf.cpp |
odom2tf.cpp |
| 76 | 9.5.5 完成机器人建图并保存地图 | slam_toolbox 建图与雷达 QoS 匹配 | bringup.launch.py · slam_toolbox.yaml |
| 77 | 9.5.6 完成导航 | 实车 Nav2 上线 | navigation2.launch.py · nav2_params.yaml |
配套代码目录：10/
| # | 笔记 | 内容 | 配套代码 |
|---|---|---|---|
| 78 | 10.1.1 QoS策略 | History / Reliability / Durability / Deadline / Lifespan / Liveliness | — |
| 79 | 10.1.2 QoS的兼容性 | 发布端与订阅端策略兼容矩阵 | — |
| 80 | 10.1.3 QoS的兼容性测试 | Python 与 C++ 可靠性测试节点 | reliability_test.cpp · reliability_test.py |
| 81 | 10.2.1 执行器与回调组 | 单线程 / 多线程执行器与互斥、可重入回调组 | learn_executor.cpp · learn_executor.py |
| 82 | 10.3.1 生命周期节点 | 状态机、ros2 lifecycle 命令与两版实现 |
learn_lifecyclenode.cpp · learn_lifecyclenode.py |
| 83 | 10.4.1 使用执行器组织多个节点 | 进程内通信（intra-process） | talker.cpp · listener.cpp · intra_process_pubsub.cpp |
| 84 | 10.4.2 使用组件运行组合节点 | ros2 component 加载 / 卸载 |
learn_compose/ |
| 85 | 10.4.3 编写组件 | RCLCPP_COMPONENTS_REGISTER_NODE 与 CMake 导出 |
talker.cpp · listener.cpp · CMakeLists.txt |
| 86 | 10.5.1 同步传感器数据 | message_filters 时间同步（双语言实现） |
timesync.cpp · timesync.py · rosbag2_message_filter/ |
| 87 | 10.6.1 使用不同的DDS进行通信 | Fast DDS / CycloneDDS / Zenoh 切换 | — |
| 88 | 10.6.2 配置局域网通信 | ROS_DOMAIN_ID 与本机通信限制 |
— |
| 89 | 10.6.3 调整DDS配置 | XML profile 限制订阅 | topic_sub_limit.xml |
| 90 | 10.6.4 使用DDS共享内存 | 共享内存传输与 loaned message | shm.xml · shm_pub.cpp |
.
├── ROS2/ # 全部笔记（Markdown）
│ ├── ROS2基础.md # 通信方式与应用框架概览
│ ├── ROS2相关命令.md # ros2 命令行速查
│ ├── ROS2 版本.md # 各发行版与 EOL 时间表
│ ├── Linux命令.md # 常用 Linux / 安装命令
│ ├── python/ # 第 2–5 章 Python 实现
│ ├── C++/ # 第 2–5 章 C++ 实现，含 C++ 速成
│ ├── 工具和仿真/ # 第 5–6 章 TF、RViz、bag、URDF、Gazebo
│ ├── 导航/ # 第 7–8 章 Nav2 导航与自定义插件
│ └── 实战/ # 第 9–10 章 实体机器人与进阶专题
│
├── _resources/ # 笔记附件，按笔记标题分子目录
│ └── <笔记标题>/<md5>_MD5.jpg|pdf
│
├── 111/ 222/ ... 999/ 10/ # 第 1–10 章配套代码，详见「环境与依赖」
├── LICENSE # Apache-2.0
└── .gitignore # 已忽略 build/ install/ log/ .pio/ 等构建产物
代码目录以重复数字标识章号：111 为第 1 章，222 为第 2 章，依此类推至 999 为第 9 章，
第 10 章为 10。同名功能包（szcbot_description、szcbot_navigation2、autopartol_robot）
在多个章节目录下各存一份，为该章当时的快照，请按章号取用。
笔记基于下列环境编写，其他版本的差异在正文中另行标注。
| 项目 | 版本 / 型号 |
|---|---|
| 操作系统 | Ubuntu 24.04.4 LTS（Noble Numbat） |
| ROS 2 | Jazzy Jalisco |
| 仿真器 | Gazebo Sim（Harmonic / Ionic，需 ros_gz 桥接） |
| 导航 | Nav2 + slam_toolbox |
| 控制框架 | ros2_control + gz_ros2_control |
| 单片机 | ESP32（PlatformIO + Arduino framework） |
| 嵌入式通信 | micro-ROS（UDP，micro-ROS Agent 运行于 Docker） |
| 雷达 | YDLidar |
| 电机 | 12V 370 减速电机，130 rpm，编码器一圈 1974 脉冲，轮径 65 mm |
Note
自 Humble（Gazebo Classic）迁移至 Jazzy（Gazebo Sim）的差异，见
Gazebo版本迁移指南.md。
Jazzy 引入的 API 变更（如 Nav2 插件的 cancel_checker、异常头文件拆分）在 8.2、8.3 中有标注。
工作空间路径按章而异，编译前请对照下表，勿统一套用 <章号>/ws。
| 章 | 工作空间 | 内容 |
|---|---|---|
| 第 1 章 | 111/ |
裸 CMake / Python 示例，无 colcon 工作空间 |
| 第 2 章 | 222/ws |
demo_cpp_pkg、demo_py_pkg |
| 第 3 章 | 333/topic_ws · 333/topic_practice_ws |
话题示例与系统监控实践 |
| 第 4 章 | 444/ws |
服务、参数、Launch |
| 第 5 章 | 555/ws |
demo_cpp_tf、demo_py_tf |
| 第 6 章 | 666/ws |
szcbot_description（URDF + Gazebo + ros2_control） |
| 第 7 章 | 777/ws |
szcbot_navigation2、autopartol_robot |
| 第 8 章 | 888/learn_pluginlib · 888/ws |
pluginlib 示例与 Nav2 自定义插件 |
| 第 9 章 · 上位机 | 999/ws |
bringup、雷达驱动、串口转发 |
| 第 9 章 · 固件 | 999/example_led · 999/example_motor · 999/example_imu · 999/example_project |
ESP32（PlatformIO） |
| 第 10 章 | 10/ws |
QoS、执行器、生命周期节点、组件、DDS |
cd 666/ws # 替换为上表中对应的工作空间
colcon build
source install/setup.bash
ros2 run szcbot_description <可执行文件名>第 9 章的 ESP32 固件以 PlatformIO 构建：
cd 999/example_led # 替换为上表中对应的固件工程
pio run -t uploadNote
build/、install/、log/、.pio/ 等构建产物已在 .gitignore 中忽略，克隆后需自行编译。
本仓库以 Apache License 2.0 发布。