Cosys-AirSim (UE5) + ROS 2 联合仿真环境部署全踩坑指南

前言

最近在折腾 Cosys-AirSim 的联合仿真，目标是实现 Windows (运行 UE5 仿真) 与 Ubuntu (运行 ROS 2 算法) 的跨机通信。

虽然官方文档提供了基础流程，但在国内网络环境和实际部署中，坑非常多！本文总结了从 ROS 2 安装、UE5 项目编译，到 TCP 连接死活通不过的完整排坑流程，希望能帮大家节省时间。

🛠️ 目录结构预览 (Ubuntu)

为了避免路径混乱，建议在 Ubuntu 端保持以下目录结构。这对于后续修改 CMakeLists.txt 至关重要。

/home/你的用户名/
├── Cosys-AirSim/             <-- [核心源码库]
│   ├── AirLib/               <-- 核心物理引擎库 (必须编译成功)
│   ├── ros2/                 <-- 原始 ROS 代码
│   ├── setup.sh              <-- 依赖安装脚本
│   └── build.sh              <-- 编译脚本
│
└── airsim_ros2_ws/           <-- [ROS 2 工作空间]
    ├── src/
    │   ├── airsim_ros_pkgs/  <-- 从 Cosys-AirSim/ros2/src 复制过来的
    │   │   ├── launch/       <-- 修改 IP 的地方
    │   │   └── CMakeLists.txt <-- 修改 AIRSIM_ROOT 路径的地方
    │   └── airsim_interfaces/
    └── build/                <-- 编译生成文件

---

一、前期准备：环境安装

1. Windows 端：部署 UE5 与 Cosys-AirSim

Cosys-AirSim 是以插件形式运行在 Unreal Engine 中的。

• 步骤 1: 安装 Visual Studio 2022
  • 下载并安装 VS2022。
  • 关键点：安装时必须勾选 “使用 C++ 的桌面开发” 和 “使用 C++ 的游戏开发” (包含 Unreal Engine 安装程序)。
• 步骤 2: 安装 Unreal Engine 5
  • 打开 Epic Games Launcher，安装 UE 5.X (我用的5.5.4) 版本。
• 步骤 3: 编译 Cosys-AirSim 插件
  • 打开 “VS2022 开发人员命令提示符” (Developer Command Prompt)。
  • 克隆仓库并编译：

    git clone https://github.com/Cosys-Lab/Cosys-AirSim.git D:\Cosys-AirSim
    cd D:\Cosys-AirSim
    build.cmd
    

  • 注：这一步会下载大量依赖，请保持网络通畅。
• 步骤 4: 启动测试项目 (Blocks)
  • 编译完成后，进入 Unreal\Environments\Blocks 目录。
  • 双击 Blocks.uproject。如果是第一次运行，它会询问是否重新编译，点击 “Yes”。
  • 配置 文档/Airsim/setting.json (下面会写)
  • 打开 UE5 编辑器后，点击上方的绿色 Play 按钮，如果能看到无人机，说明仿真端就绪。

2. Ubuntu 端：一键安装 ROS 2 (鱼香 ROS)

在 Ubuntu 虚拟机或实体机上，使用国内最方便的“鱼香 ROS”一键脚本安装，自动解决换源和 GPG 密钥问题。

• 步骤 1: 运行脚本

  wget http://fishros.com/install -O fishros && . fishros
  

• 步骤 2: 选择菜单
  • 输入 1：安装 ROS。
  • 输入 1：更换源并清理第三方源（推荐）。
  • 选择版本：
    • Ubuntu 22.04 请选择 Humble 或 Iron。
    • Ubuntu 20.04 请选择 Foxy (不推荐，已停止维护)。
  • 选择安装方式：选择 Desktop (桌面版，包含 Rviz 等工具)。
• 步骤 3: 验证
  安装完成后，新开终端输入 ros2，有输出即为成功。
  

---

第一部分：Windows 端配置 (仿真器)

Windows 端主要负责开启 TCP 服务端口等待连接。

1. 修改 settings.json (关键!)

AirSim 默认只监听本机，导致虚拟机无法连接。建议使用以下配置：

• 文件位置: 文档\AirSim\settings.json
• 修改重点:
  1. LocalHostIp: 填写真实的局域网 IP（推荐）或 0.0.0.0。
  2. SimMode: 设置为 Multirotor (无人机模式)，避开缺少车辆模型的报错。

{
  "SettingsVersion": 1.2,
  "SimMode": "Multirotor",
  "ClockSpeed": 1,
  "LocalHostIp": "192.168.31.144",
  "ApiServerPort": 41451,
  "Vehicles": {
    "Drone1": {
      "VehicleType": "SimpleFlight",
      "X": 0, "Y": 0, "Z": -2,
      "Sensors": {
        "Lidar1": { "SensorType": 1, "Enabled": true, "DrawDebugPoints": true },
        "Imu": { "SensorType": 2, "Enabled": true },
        "Gps": { "SensorType": 3, "Enabled": true }
      },
      "Cameras": {
        "front_center": {
          "CaptureSettings": [
            { "ImageType": 0, "Width": 640, "Height": 480, "FOV_Degrees": 90 }
          ],
          "X": 0.5, "Y": 0, "Z": 0
        }
      }
    }
  }
}

2. 配置防火墙 (必做!)

• 打开 高级安全 Windows Defender 防火墙。
• 新建 入站规则 -> 选择 端口 -> TCP -> 特定本地端口 41451。
• 允许连接 -> 全选 -> 命名为 AirSim RPC。

---

第二部分：Ubuntu 端配置 (ROS 2)

1. 解决依赖 (rosdepc)

# 安装 rosdepc
sudo pip3 install http://dep.fishros.com/code/rosdepc/rosdepc-1.0.8.tar.gz
sudo rosdepc init
rosdepc update

# 安装基础工具
sudo apt install python3-colcon-common-extensions git netcat

2. 编译 AirLib (核心库)

步骤 1: 克隆代码

git clone https://github.com/Cosys-Lab/Cosys-AirSim.git ~/Cosys-AirSim

步骤 2: 修改 setup.sh (避坑核心)
打开 ~/Cosys-AirSim/setup.sh，做以下修改：

1. 添加镜像: 将所有 https://github.com/ 替换为 https://mirror.ghproxy.com/https://github.com/。
2. 跳过 PPA: 注释掉 sudo add-apt-repository ppa:ubuntu-toolchain-r/test。
3. 降级依赖: 将 libstdc++-13-dev 改为 libstdc++-12-dev。

步骤 3: 编译

cd ~/Cosys-AirSim
./setup.sh --no-full-poly-car
./build.sh

3. 搭建 ROS 2 工作空间

步骤 1: 复制源码

mkdir -p ~/airsim_ros2_ws/src
# 将 ROS 2 部分的源码复制出来
cp -r ~/Cosys-AirSim/ros2/src/* ~/airsim_ros2_ws/src/

步骤 2: 修复 CMakeLists.txt
打开 ~/airsim_ros2_ws/src/airsim_ros_pkgs/CMakeLists.txt，手动指定 AirLib 的真实位置：

# 修改前
# set(AIRSIM_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../../../")

# 修改后 (请填入你的实际路径)
set(AIRSIM_ROOT "/home/你的用户名/Cosys-AirSim")

步骤 3: 安装依赖并编译

cd ~/airsim_ros2_ws
# 安装缺少的 ROS 依赖 (注意替换 humble/iron/foxy)
sudo apt install ros-$ROS_DISTRO-geographic-msgs ros-$ROS_DISTRO-mavros-msgs ros-$ROS_DISTRO-tf2-sensor-msgs ros-$ROS_DISTRO-tf2-geometry-msgs

# 编译
colcon build --symlink-install

---

第三部分：终极避坑 (Launch 文件修复)

原因: 官方 Launch 文件的参数名定义有误 (host_ip vs host)。

解决方案: 修改 ~/airsim_ros2_ws/src/airsim_ros_pkgs/launch/airsim_node.launch.py，直接把 IP 硬编码进去。

    # 找到 host_ip 定义处，修改 default_value
    host_ip = DeclareLaunchArgument(
        "host_ip",
        default_value='192.168.31.144') # 改成你 Windows 的 IP

修改后执行 colcon build 重新编译。

---

第四部分：启动与验证

1. 启动

1. Windows: 启动 UE5 工程，点击 Play。
2. Ubuntu:

   cd ~/airsim_ros2_ws
   source install/setup.bash
   ros2 launch airsim_ros_pkgs airsim_node.launch.py
   

2. 验证

终端出现 [INFO] [airsim_ros_wrapper]: AirSimROSWrapper: Connected! 即为成功。

3. 可视化 (Rviz2)

rviz2

• Fixed Frame: world_ned
• Add: PointCloud2 (Lidar) 和 Image (Scene)

---

希望这篇文档能帮到正在踩坑的你！🚀