痛点 1：语言割裂与目录混乱#

有人为了统一，强行全部用 C++ 写，结果陷入了 1600 行状态机屎山；有人为了简单全部用 Python 写，结果串口解包延迟高、丢帧严重；还有人把 C++ 驱动和 Python 决策拆成两个毫不相关的独立项目，中间靠手动跑一堆终端命令启动，联调时乱成一锅粥。

痛点 2：改了一行 Python，结果车走的还是老代码#

这是 ROS 2 最恶心新手的深坑之一：你在 my_decision.py 里把坐标从 x = 2.0 改成了 x = 3.5，按了保存，满怀期待在终端里启动节点。
结果机器人依然直奔 2.0 撞了上去！
你抓狂地以为是自己代码有 bug，查了半小时才发现：ROS 2 默认把源码物理复制了一份到 install/ 目录下，你改的是源码，节点跑的却是旧副本！

痛点 3：没有开发机环境就寸步难行#

很多队员在宿舍用的是 Windows 笔记本甚至 Mac，手头没有装好 ROS 2 的 Ubuntu 主机。传统观念认为“没装 ROS 2 就别想写上位机决策”，导致队员在机械还没造好、工控机还没到位的空窗期，完全处于摆烂状态。

本章的目标，就是通过一套现代 ROS 2 混合工作空间体系，把这三个问题全部彻底根除。

1. 发行版选择：认准长期支持版（LTS）#

开发工业/竞赛机器人，绝对不要追求最新潮的版本，稳定性压倒一切。请严格遵守以下对应关系：

提示：目前最推荐的还是22.04版本，24.04太新了，之前也说过这个问题。 警告：千万不要去装 Iron（短命版）或 Rolling（滚动开发版），更不要在队内不同成员的电脑上混用不同发行版。接口微小的版本差异在赛前联调时会让你痛不欲生。

2. 国内环境安装#

在境内安装 ROS 2，经常会遭遇 GitHub GPG 密钥下载失败、apt 官方源超时等问题。最成熟、省时的安装方式是鱼香ROS的自动化脚本：

1
# 运行一键配置脚本（支持自动测速换源、一键安装 ROS 2 Humble/Jazzy）
2
wget http://fishros.com/install -O fishros && . fishros

在交互菜单中选择安装 ROS 2，版本选择 Humble（或根据你的 Ubuntu 版本选择 Jazzy），安装类型选择 Desktop 版（包含常用的可视化与工具包）。

3. 环境激活的规范做法#

安装完成后，很多教程会让你把 source /opt/ros/humble/setup.bash 写进 ~/.bashrc。这没有错，但在整车混合开发中，建议在 ~/.bashrc 底部加上常用的快捷别名（Aliases），大幅提升赛场调试效率：

1
# 打开你的 bashrc
2
nano ~/.bashrc
3

4
# 在末尾加入以下便捷配置：
5
source /opt/ros/humble/setup.bash
6

7
# 便捷别名（可选）
8
alias cb='colcon build --symlink-install'
9
alias sdev='source install/setup.bash'
10
alias killros='killall -9 ros2 __node'

修改后执行 source ~/.bashrc 立即生效。

1. C++ 底座：ament_cmake 构建模型#

打开 robot_serial 的工程定义文件：

• package.xml：声明构建工具为 ament_cmake，并列出依赖项：

  1
  <buildtool_depend>ament_cmake</buildtool_depend>
  2
  <depend>rclcpp</depend>
  3
  <depend>std_msgs</depend>
  4
  <depend>geometry_msgs</depend>
  5
  <depend>nav_msgs</depend>

• CMakeLists.txt：标准的现代 CMake 组织方式。它不仅要编译 serial_driver_node.cpp 可执行文件，还需要编译自定义接口（如 Command.msg 与 Ack.msg）：

  1
  cmake_minimum_required(VERSION 3.8)
  2
  project(robot_serial)
  3
  
  4
  find_package(ament_cmake REQUIRED)
  5
  find_package(rclcpp REQUIRED)
  6
  find_package(rosidl_default_generators REQUIRED)
  7
  
  8
  # 1. 编译自定义 ROS 2 消息
  9
  rosidl_generate_interfaces(${PROJECT_NAME}
  10
    "msg/Command.msg"
  11
    "msg/Ack.msg"
  12
  )
  13
  
  14
  # 2. 编译 C++ 驱动节点
  15
  add_executable(serial_driver_node src/serial_driver_node.cpp src/crc.cpp)
  16
  ament_target_dependencies(serial_driver_node rclcpp nav_msgs)
  17
  rosidl_get_typesupport_target(cpp_typesupport_target ${PROJECT_NAME} "rosidl_typesupport_cpp")
  18
  target_link_libraries(serial_driver_node "${cpp_typesupport_target}")
  19
  
  20
  install(TARGETS serial_driver_node DESTINATION lib/${PROJECT_NAME})
  21
  ament_package()

  显示更多显示更少

2. Python 大脑：ament_python 构建模型#

在同一个 src/ 目录下，robocon_fsm 采用完全不同的构建体系：

• package.xml：构建工具声明为 ament_python：

  1
  <buildtool_depend>ament_python</buildtool_depend>
  2
  <exec_depend>rclpy</exec_depend>
  3
  <exec_depend>robot_serial</exec_depend> <!-- 依赖下层的 C++ 消息接口 -->

• setup.py：基于 Python 标准的 setuptools：

  1
  from setuptools import setup, find_packages
  2
  
  3
  package_name = 'robocon_fsm'
  4
  
  5
  setup(
  6
      name=package_name,
  7
      version='1.0.0',
  8
      packages=find_packages(),
  9
      data_files=[
  10
          ('share/ament_index/resource_index/packages', ['resource/' + package_name]),
  11
          ('share/' + package_name, ['package.xml']),
  12
      ],
  13
      install_requires=['setuptools'],
  14
      zip_safe=True,
  15
  )

  显示更多显示更少

3. 构建依赖的拓扑排序#

当你敲下 colcon build 时，colcon 会自动解析所有子包的 package.xml：

1. 它发现 robocon_fsm 依赖 robot_serial 提供的消息定义；
2. 于是它自动优先编译 robot_serial，生成 C++ 动态库并产出 Python 类型支持绑定（Type Support）；
3. 紧接着再安装 robocon_fsm，让 Python 可以直接 from robot_serial.msg import Command, Ack。

整个过程全自动流水线化，开发者完全无需手动干预编译顺序。

1. 默认构建 vs 符号链接构建#

我们来看看普通构建和符号链接构建的物理差异：

1
【普通构建：colcon build】
2
src/robocon_fsm/my_decision.py  ──(物理全量复制)──>  install/robocon_fsm/.../my_decision.py
3
* 致命后果：你在 src/ 下改了坐标，install/ 下依然是旧副本。必须重新 colcon build 才能生效！
4

5
【符号链接构建：colcon build --symlink-install】
6
src/robocon_fsm/my_decision.py  <──(建立软链接指向)── install/robocon_fsm/.../my_decision.py
7
* 优势：install/ 目录下的文件只是一个快捷方式指针！你在 src/ 下保存文件的一瞬间，install/ 读到的就是最新内容！

2. 实战开发铁律#

从今天起，请在你的大脑里把普通的 colcon build 彻底删除，只需要使用带符号链接的构建命令：

1
# 推荐的标准构建命令
2
colcon build --symlink-install

使用 --symlink-install 之后：

• Python 逻辑代码（.py）：修改后无需重新编译，直接启动节点即是最新逻辑；
• 配置文件与战术点位（.yaml）：修改后无需重新编译，保存即生效；
• 启动脚本（.launch.py）：修改后无需重新编译；
• C++ 代码（.cpp / .hpp）：因为需要生成新的机器码，所以修改后仍然需要编译。

增量编译小技巧：
当你只修改了 C++ 串口驱动，不想把整个工作空间都扫一遍时，可以使用指定包构建：

1
colcon build --symlink-install --packages-select robot_serial

耗时往往可以缩短很多。

模式 A：个人电脑轻量仿真模式（无需 ROS 2 / 无需 Linux）#

在你的日常 Windows / Mac / 办公轻薄本上，你只需要有 Python 3.8+：

1
# 1. 任意电脑克隆仓库（可以自己fork一份而不用git我的仓库）
2
git clone https://github.com/lumivers/robocon-fsm.git
3
cd robocon-fsm
4

5
# 2. 安装基础依赖（实际上核心库纯原生无额外依赖）
6
pip install -r requirements.txt
7

8
# 3. 本地直接跑全场离线仿真测试
9
python examples/02_mock_robot_mission/test_mission.py

终端会打印出全场导航、抓取、避障重试的完整日志！在没有出车的时候，你在宿舍就能把全场流程写得滴水不漏。

模式 B：工控机整车部署模式（真车 ROS 2 环境）#

当 5 月份机械和电控终于把车装配好、移交给上位机时：

1
# 在工控机的 ROS 2 工作空间下
2
cd ~/ros2_ws
3
colcon build --symlink-install
4
source install/setup.bash
5

6
# 启动整车 C++ 驱动与 Python 决策
7
ros2 launch templates/standard_robot/launch/robot.launch.py

同一套战术代码，无缝切入真车运行。

1. 准备工作空间#

1
mkdir -p ~/rc_ws/src
2
cd ~/rc_ws/src

2. 获取框架源码#

1
git clone https://github.com/lumivers/robocon-fsm.git .

3. 一键编译与环境加载#

1
cd ~/rc_ws
2
colcon build --symlink-install
3
source install/setup.bash

如果终端输出如下，说明 C++ 串口驱动与 Python 状态机已全部正确构建：

1
Summary: 2 packages finished [1.82s]

4. 运行框架原生单元测试#

在将整车开动前，执行框架自带的原语测试套件，验证底层事件流转机制：

1
python tests/run_all_tests.py

当屏幕打出一排绿色的 [PASS]，证明你的工控机系统与 Python 异步运行时环境已处于 100% 完美状态。