# ROS 2 机器人开发环境配置清单

> 郎学科技 · 开源资料 / v2026.10
> 适用：Ubuntu 24.04 + ROS 2 Jazzy；Ubuntu 22.04 + ROS 2 Humble 同样适用，替换版本号即可。
> 许可：CC BY-NC-SA 4.0。转载请注明来源，禁止直接用于商业课程售卖。

## 0. 先确认三件事

- [ ] 你的电脑是 x86_64，内存 ≥ 16 GB，磁盘剩余 ≥ 80 GB。
- [ ] 你有一台可以安装 Ubuntu 的机器，或愿意使用 Docker / WSL2。
- [ ] 你清楚自己要接的硬件：底盘、机械臂、相机、雷达分别用什么接口。

> 不建议在 Windows 原生环境里做 ROS 2 真机开发。WSL2 可以跑通大部分仿真，但 USB 设备直通和实时性会遇到额外问题。

## 1. 系统与基础工具

```bash
sudo apt update && sudo apt upgrade -y
sudo apt install -y \
  build-essential cmake git curl wget vim \
  python3-pip python3-venv python3-colcon-common-extensions \
  net-tools htop tree
```

检查：

```bash
lsb_release -a
uname -m
python3 --version
```

## 2. 安装 ROS 2（Jazzy 示例）

```bash
# 启用 universe
sudo add-apt-repository universe -y

# 添加 ROS 2 apt 源
sudo apt install -y software-properties-common curl
export ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F\" '{print $4}')
curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo $VERSION_CODENAME)_all.deb"
sudo dpkg -i /tmp/ros2-apt-source.deb

# 安装桌面版
sudo apt update
sudo apt install -y ros-jazzy-desktop ros-dev-tools
```

把环境变量写进 shell：

```bash
echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc
source ~/.bashrc
```

验证：

```bash
ros2 --help
ros2 run demo_nodes_cpp talker
# 另开终端
ros2 run demo_nodes_py listener
```

能互相收发 `Hello World`，说明 DDS 通信正常。

## 3. 常用开发包

```bash
sudo apt install -y \
  ros-jazzy-nav2-bringup \
  ros-jazzy-slam-toolbox \
  ros-jazzy-robot-state-publisher \
  ros-jazzy-joint-state-publisher-gui \
  ros-jazzy-xacro \
  ros-jazzy-rviz2 \
  ros-jazzy-teleop-twist-keyboard \
  ros-jazzy-realsense2-camera \
  ros-jazzy-ros2-control \
  ros-jazzy-ros2-controllers \
  ros-jazzy-moveit
```

> 不要一次性把所有包都装上。先装当前阶段必须用的，出问题更容易定位。

## 4. 建工作空间

```bash
mkdir -p ~/robot_ws/src
cd ~/robot_ws
colcon build --symlink-install
source install/setup.bash
```

创建自己的包：

```bash
cd ~/robot_ws/src
ros2 pkg create --build-type ament_cmake lx_bringup --dependencies rclcpp launch
ros2 pkg create --build-type ament_python lx_perception --dependencies rclpy
```

## 5. micro-ROS / ESP32 链路

- [ ] 安装 Arduino IDE 或 PlatformIO。
- [ ] ESP32 开发板包：`https://espressif.github.io/arduino-esp32/package_esp32_index.json`
- [ ] 安装 `micro_ros_arduino` 库（注意与 ROS 2 版本匹配）。
- [ ] 确认串口权限：`sudo usermod -aG dialout $USER`，重新登录。
- [ ] 先用串口跑通传感器读数，再接 ROS 2。
- [ ] 用 `ros2 topic hz` 看频率，不要只看 `/echo` 是否有一条数据。

## 6. 网络与 DDS

同一局域网内多机通信，先确认：

```bash
ip addr
ping <另一台机器IP>
```

需要时设置：

```bash
export ROS_DOMAIN_ID=42
export ROS_LOCALHOST_ONLY=0
```

- [ ] 所有机器使用同一个 `ROS_DOMAIN_ID`。
- [ ] 防火墙放行 DDS 所需端口，或先临时关闭防火墙验证。
- [ ] Wi-Fi 不稳定时，优先用有线网络；真机调试不要依赖公共 Wi-Fi。
- [ ] 大带宽图像话题考虑压缩或使用零拷贝 / 共享内存方案。

## 7. 相机与标定

- [ ] `v4l2-ctl --list-devices` 能看到设备。
- [ ] `ros2 run usb_cam usb_cam_node_exe` 能出图。
- [ ] `rqt_image_view` 能看到画面。
- [ ] 用棋盘格完成内参标定，保存 YAML。
- [ ] 手眼标定单独安排时间，不要和机械臂调试混在一起。

## 8. 仿真环境

```bash
# 以 TurtleBot3 为例
sudo apt install -y ros-jazzy-turtlebot3 ros-jazzy-turtlebot3-simulations
export TURTLEBOT3_MODEL=burger
ros2 launch turtlebot3_gazebo turtlebot3_world.launch.py
```

另一个终端：

```bash
ros2 launch turtlebot3_navigation2 navigation2.launch.py use_sim_time:=true
```

- [ ] Gazebo 能启动，`/clock` 有数据。
- [ ] RViz 能看到 TF 树完整。
- [ ] 能给定目标点并完成导航。
- [ ] 记录一次 rosbag，确认可以回放。

## 9. 每日开工检查

```bash
# 1. 环境
printenv | grep ROS

# 2. 节点与话题
ros2 node list
ros2 topic list
ros2 topic hz /scan

# 3. TF
ros2 run tf2_tools view_frames

# 4. 录制与回放
ros2 bag record -o demo_bag /scan /odom /tf /tf_static
ros2 bag play demo_bag
```

## 10. 常见问题速查

| 现象 | 优先检查 |
| --- | --- |
| `ros2 topic list` 为空 | 环境变量、`ROS_DOMAIN_ID`、网络、防火墙 |
| TF 树断开 | `robot_state_publisher`、URDF、`joint_states` 是否发布 |
| RViz 无图像 | 话题名、QoS、相机驱动、带宽 |
| Nav2 原地打转 | 代价地图、footprint、控制器参数、定位漂移 |
| 机械臂不动 | `ros2_control` 控制器状态、急停、使能、CAN 链路 |
| 仿真时间不走 | `use_sim_time` 与 `/clock` |
| 编译内存不足 | 减少并行：`colcon build --parallel-workers 2` |

## 11. 版本记录建议

每次改环境，记录：

- Ubuntu / ROS 2 版本
- 内核版本与显卡驱动
- 关键包版本（`ros2 pkg xml <pkg>`）
- 硬件型号、固件版本
- 改过的网络与 udev 规则

> 环境问题最贵的成本不是解决它，而是三天后忘了当时怎么解决的。

---

来源：郎学科技工程团队整理 · 2026.10