安装与构建 LAESim#

本页包含完整安装流程：先在 Windows 中构建 LAESim/UE 4.27 核心仿真器，再按需在 WSL2 中安装 ROS Noetic 和 ns-3。只使用 Windows Python API 时完成前半部分即可；需要 ROS 或自组织网络仿真时继续完成后半部分。

Visual Studio 工作负载、Unreal 基础环境和 AirSim 通用依赖可先参考 AirSim 官方 Windows 构建文档。

环境要求#

  • Windows 10/11
  • Unreal Engine 4.27
  • Visual Studio 2019 或 2022
  • 使用 C++ 的桌面开发工作负载
  • Windows 10 SDK，推荐 10.0.19041.0
  • Git 和 PowerShell

需要 ROS 或 ns-3 时，再准备 WSL2；它们不是 Windows 插件编译的前置条件。

获取源码#

$LaesimRoot = Join-Path $HOME "source\LAESim"
git clone --branch V1.4 https://github.com/SANIS-HITSZ/LAESim.git $LaesimRoot
Set-Location $LaesimRoot

若 PowerShell 禁止运行本地脚本，可仅为当前用户启用签名策略：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

可选：导出可移植源码#

需要把一份不含本机编译缓存的源码交付给其他开发者时，可以使用仓库提供的导出脚本：

$PortableRoot = Read-Host "请输入可移植源码输出目录"
powershell -ExecutionPolicy Bypass -File .\PreparePortableSource.ps1 `
  -DestinationRoot $PortableRoot

该流程用于制作干净源码副本，不替代 Git 分支、发布标签或正式构建验证。

编译 LAESim 插件#

推荐入口：

.\BuildAirSimRelease.bat

该脚本会查找 Visual Studio 开发环境，然后调用：

build.cmd --Release

也可以打开 Visual Studio 2019/2022 的 x64 Native Tools Command Prompt，在仓库根目录手动执行：

build.cmd --Release

两种入口生成相同的 Release 产物；BuildAirSimRelease.bat 额外负责定位 Visual Studio 并初始化 x64 编译环境。

构建结束后，LAESim 插件位于：

<LAESim 源码目录>\Unreal\Plugins\AirSim

UE 安装在非标准目录#

自动探测失败时指定 UE 根目录：

$env:UNREAL_ENGINE_ROOT = Read-Host "请输入 UE 4.27 安装目录"
.\BuildAirSimRelease.bat

Boat 模型资源#

Boat 的源码资产位于：

Unreal\Assets\Boat\Models\Boat

构建脚本会将其复制到：

Unreal\Plugins\AirSim\Content\Models\Boat

默认 Pawn 会加载 /AirSim/Models/Boat/Type_052B_Destroyer_Combined，因此普通使用者不需要在 settings.json 中配置模型路径。若资源没有复制成功，Boat 会回退到代码生成的简化外形。

Satellite 模型资源#

Satellite 源码资产位于 Unreal\Assets\Satellite\Models\Satellite。构建脚本会将其复制到 Unreal\Plugins\AirSim\Content\Models\Satellite，默认 Pawn 加载 /AirSim/Models/Satellite/10477_Satellite_v1_L3；资源缺失时会回退到代码生成的简化卫星外形。

接入自己的 UE 工程#

  1. 创建或打开一个 UE 4.27 C++ 项目。
  2. 将 Unreal\Plugins\AirSim 整体复制到目标项目的 Plugins\AirSim。
  3. 重新生成并编译目标项目的 Development Editor。
  4. 在关卡中配置 PlayerStart 和 AirSimGameMode。
  5. 将 LAESim 配置放到 %USERPROFILE%\Documents\AirSim\settings.json。
  6. 打开关卡并点击 Play。

只验证仓库自带 Blocks 场景时，可以额外运行：

.\Unreal\Environments\Blocks\BuildBlocksEditor.bat

该脚本只构建 Blocks 示例，不替代 LAESim 插件构建。

构建验证#

至少确认以下结果：

  • Unreal\Plugins\AirSim\Binaries 已生成插件二进制
  • UE 能加载 AirSim/LAESim 插件并进入 Play
  • settings.json 使用 AirGround 时能同时生成无人机、汽车、船和卫星
  • 本机端口 41451、41461、41471、41481、41491 按配置监听

常见 Windows 构建问题#

找不到 Eigen/Dense#

出现以下错误通常表示 Eigen 下载或解压中断，虽然 AirLib\deps\eigen3 目录存在，但实际头文件不完整：

error C1083: 无法打开包括文件: "Eigen/Dense"

先检查真正的头文件：

Test-Path .\AirLib\deps\eigen3\Eigen\Dense

返回 False 时清理残缺目录并重新构建：

Remove-Item -LiteralPath .\AirLib\deps\eigen3 -Recurse -Force
.\BuildAirSimRelease.bat

依赖压缩包下载中断#

Invoke-WebRequest 报意外 EOF、连接关闭或解压时报“找不到中央目录结尾记录”，通常表示代理或网络导致 zip 不完整。清理临时文件后重试：

Remove-Item -LiteralPath .\eigen3.zip -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath .\suv_download_tmp -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath .\AirLib\deps\eigen3 -Recurse -Force -ErrorAction SilentlyContinue
.\BuildAirSimRelease.bat

car_assets.zip 失败时通常会回退到默认车辆模型；Eigen 下载失败会阻止 AirLib 编译，应先解决网络或代理问题。

完成 Windows/UE 构建后，可以先阅读使用 LAESim。需要 ROS 或 ns-3 时继续完成下面的可选环境安装。

WSL2、ROS Noetic 与 ns-3#

本文说明如何在 Windows 中运行 LAESim/UE4，同时在 WSL2 中运行 ROS Noetic 和可选的 ns-3 网络仿真。所有路径均使用环境变量或通用占位符，不依赖某台电脑的用户名、盘符或目录结构。

1. 系统结构#

Windows 11
  UE 4.27 + LAESim
  %USERPROFILE%\Documents\AirSim\settings.json
                 | AirSim RPC
                 v
WSL2 自定义发行版
  Ubuntu 20.04 + ROS Noetic
  $HOME/LAESim/ros
  $HOME/opt/ns-3.48
  laesim_network_bridge
       | Backend=none -> 理想网络，消息立即到达
       ` Backend=ns3  -> ns-3 Wi-Fi ad hoc + OLSR/AODV

WSL2 发行版可以安装到任意空间充足的非系统盘。Windows 项目目录、WSL 虚拟磁盘目录和 Linux 主目录彼此独立，不要求使用相同盘符。

2. 已验证的软件版本#

组件 版本
Windows Windows 11 + WSL2
Unreal Engine UE 4.27
Linux Ubuntu 20.04 (focal)
ROS ROS Noetic
ns-3 ns-3.48，提交 d2add90b452d600cfb4859baed8e9ea633519447
ns-3 编译器 GCC/G++ 11
LAESim ROS 编译器 GCC/G++ 8

ROS Noetic 与 Ubuntu 20.04 已离开标准支持周期。当前组合用于兼容 LAESim 的 ROS1 工程；在项目完成 ROS 2 迁移前，不要直接用其他 Ubuntu 或 ROS 版本替换。

3. 创建 LAESim WSL2 发行版#

3.1 定义本机参数#

在 LAESim 仓库根目录打开管理员 PowerShell。先定义本机使用的参数：

$DistroName = "LAESim"
$LinuxUser = "laesim"
$WslInstallRoot = Read-Host "请输入 WSL2 发行版存储目录，例如 D:\WSL\LAESim"
$RootfsPath = Read-Host "请输入 Ubuntu 20.04 rootfs tar 文件路径"
$RepoRoot = (Resolve-Path .).Path
  • $WslInstallRoot 决定 ext4.vhdx 的存放位置，应选择空间充足的磁盘。
  • $RootfsPath 指向 Ubuntu 20.04 的 WSL rootfs 归档。
  • $LinuxUser 可以改为符合 Linux 用户名规则的其他名称。

如果电脑中已有干净的 Ubuntu 20.04 WSL 发行版，可以导出为 rootfs：

$SourceDistro = Read-Host "请输入现有 Ubuntu 20.04 发行版名称"
wsl --export $SourceDistro $RootfsPath

也可以使用可信来源提供的 Ubuntu 20.04 WSL rootfs。使用下载文件时，应按发布方说明校验哈希，不要复用其他电脑生成的私有归档哈希。

3.2 导入发行版#

powershell -ExecutionPolicy Bypass -File .\NetworkSim\scripts\create_laesim_wsl.ps1 `
  -RootfsPath $RootfsPath `
  -InstallRoot $WslInstallRoot `
  -DistroName $DistroName `
  -DefaultUser $LinuxUser

脚本使用 wsl --import --version 2 导入发行版、创建默认用户，并启用 systemd。验证结果：

wsl -l -v
Get-Item (Join-Path $WslInstallRoot "ext4.vhdx")
wsl -d $DistroName -- id

wsl -l -v 中该发行版的 VERSION 应为 2，id 应显示 $LinuxUser 对应的非 root 用户。

4. 安装 ROS Noetic#

安装脚本位于 Windows 仓库中。先把 Windows 路径转换为当前 WSL 可识别的路径：

$RepoRootWsl = (wsl -d $DistroName -- wslpath -a $RepoRoot).Trim()

然后安装 ROS 和编译依赖：

wsl -d $DistroName -u root -- env TARGET_USER=$LinuxUser `
  bash "$RepoRootWsl/NetworkSim/scripts/bootstrap_wsl_ros.sh"

脚本默认使用中科大 ROS 镜像。需要使用 ROS 官方软件源时执行：

wsl -d $DistroName -u root -- env TARGET_USER=$LinuxUser `
  ROS_APT_MIRROR=https://packages.ros.org/ros/ubuntu `
  bash "$RepoRootWsl/NetworkSim/scripts/bootstrap_wsl_ros.sh"

TARGET_USER 必须是将来运行 LAESim 和 ROS 的非 root Linux 用户。

5. 在 WSL 中编译 LAESim ROS#

建议将用于 Linux 编译的源码克隆到 WSL 的 ext4 文件系统中。不要直接在 /mnt/c、/mnt/d 等 Windows 挂载目录中编译大量 Linux 小文件。

在 PowerShell 中进入刚创建的发行版：

wsl -d $DistroName

进入 WSL 后执行：

export LAESIM_HOME="${HOME}/LAESim"
git clone --branch V1.4 https://github.com/SANIS-HITSZ/LAESim.git "${LAESIM_HOME}"
cd "${LAESIM_HOME}"
./setup.sh

cd ros
source /opt/ros/noetic/setup.bash
catkin_make \
  -DCMAKE_C_COMPILER=/usr/bin/gcc-8 \
  -DCMAKE_CXX_COMPILER=/usr/bin/g++-8
source devel/setup.bash

如果发行版名称不是 LAESim，把第一条命令中的名称替换为创建时设置的 $DistroName。如果目录已经克隆，使用 git pull --ff-only 更新，不要再次执行 git clone。

编译前应确认以下依赖目录存在：

$HOME/LAESim/AirLib/deps/eigen3
$HOME/LAESim/external/rpclib

6. 验证 Windows LAESim 与 WSL ROS#

6.1 启动 Windows 仿真端#

  1. 将多机配置保存为 %USERPROFILE%\Documents\AirSim\settings.json。
  2. 使用 UE 4.27 打开 LAESim 环境。
  3. 点击 Play，等待场景和 AirSim RPC 服务启动。
  4. 根据 settings.json 中配置的 RPC 端口检查监听状态。

例如，默认 RPC 端口可通过 PowerShell 检查：

Test-NetConnection 127.0.0.1 -Port 41451

6.2 启动 WSL ROS#

WSL2 使用 NAT 网络时，Windows 仿真端通常不能通过 WSL 内的 localhost 访问。应从 WSL 默认路由动态获取 Windows 主机地址，不要把某次运行得到的 IP 写死：

export LAESIM_HOME="${HOME}/LAESim"
export ROS_WORKSPACE="${LAESIM_HOME}/ros"
export WINDOWS_HOST="$(ip route show default | awk '{print $3}')"

source /opt/ros/noetic/setup.bash
source "${ROS_WORKSPACE}/devel/setup.bash"
roscore

另开一个 WSL 终端：

export ROS_WORKSPACE="${HOME}/LAESim/ros"
export WINDOWS_HOST="$(ip route show default | awk '{print $3}')"

source /opt/ros/noetic/setup.bash
source "${ROS_WORKSPACE}/devel/setup.bash"
roslaunch airsim_ros_pkgs airsim_node.launch host:="${WINDOWS_HOST}"

验证 ROS 主题：

rostopic list | grep /airsim_node
rostopic hz /airsim_node/Car/odom_local_ned

主题名称取决于 settings.json 中的载具名称。能够持续收到配置中各载具的位姿、GPS 或传感器主题，即说明 Windows 与 WSL ROS 已连通。TF_REPEATED_DATA 表示重复时间戳，不等同于 RPC 连接失败。

7. 安装与构建 ns-3#

在 WSL 内执行仓库脚本：

export LAESIM_HOME="${HOME}/LAESim"
bash "${LAESIM_HOME}/NetworkSim/scripts/bootstrap_ns3.sh"
bash "${LAESIM_HOME}/NetworkSim/scripts/build_ns3_runner.sh"

默认目录如下，均相对于当前 Linux 用户的主目录：

$HOME/opt/ns-3.48
$HOME/opt/ns-3.48/build/scratch/ns3.48-laesim-ns3-runner

需要改用其他目录时，在运行两个脚本前设置同一个 NS3_ROOT：

export NS3_ROOT="${HOME}/simulators/ns-3.48"

运行后端冒烟测试：

source /opt/ros/noetic/setup.bash
python3 "${HOME}/LAESim/NetworkSim/tests/smoke_backend.py"

测试应分别覆盖有效通信距离内成功送达，以及超出通信距离后丢包的情况。

8. 配置可选网络后端#

在 Windows 的 %USERPROFILE%\Documents\AirSim\settings.json 顶层加入：

"NetworkSimulation": {
  "Backend": "none",
  "StepMs": 20,
  "Routing": "olsr",
  "MaxRangeMeters": 250.0,
  "TxPowerDbm": 16.0,
  "WarmupSeconds": 3.0,
  "PacketTimeoutSeconds": 5.0,
  "RunnerPath": "~/opt/ns-3.48/build/scratch/ns3.48-laesim-ns3-runner"
}
Backend 行为
none 保持理想通信，ROS 消息立即转发，不计算网络时延、丢包和路由
ns3 消息经过 ns-3 Wi-Fi ad hoc 网络，节点位置由配置出生偏移与 LAESim 局部 odometry 合成

当前 runner 支持 olsr 和 aodv。MaxRangeMeters 是当前实现使用的硬通信范围，PacketTimeoutSeconds 到期后未送达的包会被记录为 DROP。

9. 启动网络桥接器#

默认情况下，启动脚本会根据 Windows 的 %USERPROFILE% 自动定位 Documents\AirSim\settings.json：

export LAESIM_HOME="${HOME}/LAESim"
export ROS_WORKSPACE="${LAESIM_HOME}/ros"
export BACKEND=none  # 可改为 ns3；该变量会覆盖 settings.json
bash "${LAESIM_HOME}/NetworkSim/scripts/run_ros_network_bridge.sh"

不设置 BACKEND 时使用 settings.json 中的配置。如果配置文件放在自定义位置，先把 Windows 路径转换为 WSL 路径并显式设置 SETTINGS：

export SETTINGS="$(wslpath -u 'D:\path\to\settings.json')"

上面的 D:\path\to\settings.json 只是格式示例，应替换为实际文件路径。

10. ROS 消息接口与端到端测试#

发送端向 /network_sim/tx 发布 std_msgs/String，内容为 JSON：

{
  "packet_id": "frame-0001",
  "src": "UAV",
  "dst": "Car",
  "size_bytes": 1024,
  "payload": "application-data"
}

接收端订阅 /network_sim/rx/<载具名>。输出会增加 ns-3 的 simulation_time_ns：

{
  "packet_id": "frame-0001",
  "src": "UAV",
  "dst": "Car",
  "size_bytes": 1024,
  "simulation_time_ns": 19787694150,
  "payload": "application-data"
}

端到端测试：

source /opt/ros/noetic/setup.bash
source "${HOME}/LAESim/ros/devel/setup.bash"
python3 "${HOME}/LAESim/NetworkSim/tests/ros_roundtrip_test.py"

应分别用 none 和 ns3 后端测试。none 模式的网络仿真时间为 0；ns3 模式应返回非零仿真时间，链路不可达时应输出丢包结果。

11. 图像传输与网络栈边界#

ns-3 可以模拟承载图像的字节流，但不会替代 UE 生成画面，也不会自动把 sensor_msgs/Image 转换成真实操作系统 socket 流量。当前集成采用消息级网络仿真：

  • UE/LAESim 生成仿真画面。
  • 应用压缩并分片图像，再按分片实际字节数提交给 /network_sim/tx。
  • ns-3 决定分片何时到达或是否丢失。
  • 接收应用根据数据包和分片序号重组并解码图像。

当前单个 ns-3 包上限为 60000 字节，大图像必须分片。这种方式适合研究自组织网络对感知和协同算法的影响，并可统计时延、吞吐量、丢包率和路由变化。

如果必须让未经修改的 ROS/TCP/UDP 程序直接经过网络仿真，需要进一步接入 TAP/EMU 或 DCE。这会增加 Linux 网络接口、权限和时钟同步要求，不属于当前集成范围。

12. 当前限制#

  • runner 当前使用 IEEE 802.11g ad hoc、固定发送功率、RangePropagationLoss 和 OLSR/AODV。
  • ROS 时钟与 ns-3 离散事件时钟使用固定 StepMs 软同步。
  • 自动出生偏移当前读取 Vehicles.<name>.X/Y/Z；使用 StartOnSceneMap 时应同时提供等价的 X/Y/Z 供网络桥接器定位。
  • 指标尚未发布为 ROS 指标主题或持久化为 CSV。
  • 路由变化尚未导出到 ROS。
  • 视频传输仍需补充编码、分片、重传和接收缓冲策略。
  • WSL 发行版的 ext4.vhdx 可以放在非系统盘，但 Windows 自身的 WSL 组件仍可能占用少量系统盘空间。

13. 官方参考#