Eclipse openMobility

第一部分：Eclipse SUMO 部署

一、前置准备

硬件建议：SUMO 可在普通笔记本上运行小型路网，但城市级仿真建议 4 核 CPU、8GB 内存以上。

操作系统：Windows、Linux（推荐 Ubuntu 22.04+）、macOS 均可。

二、Windows 安装

方式一：预编译安装包（最简单）

从 SUMO 官方下载页面获取 Windows 64 位安装包（如 sumo-win64-1.27.1.msi）。双击安装，默认路径为 C:\Program Files (x86)\Eclipse\Sumo。安装完成后，bin 目录下有 sumo.exe（命令行）和 sumo-gui.exe（图形界面）。

方式二：winget 安装

Windows 10/11 用户可使用 winget 快速安装：

winget install EclipseFoundation.SUMO

验证安装：打开命令提示符，输入：

sumo --version

应输出 SUMO 版本信息。

三、Linux 安装（Ubuntu/Debian，推荐）

方式一：APT 仓库安装（最简单）

sudo add-apt-repository ppa:sumo/stable
sudo apt-get update
sudo apt-get install sumo sumo-tools sumo-doc

方式二：发行版仓库安装

sudo apt-get install sumo sumo-tools sumo-doc

方式三：从源码编译（需要自定义或最新版）

安装依赖：

sudo apt-get install cmake python g++ libxerces-c-dev libfox-1.6-dev \
  libgdal-dev libproj-dev libgl2ps-dev swig

克隆源码并编译：

git clone --recursive https://github.com/eclipse-sumo/sumo
cd sumo
export SUMO_HOME="$PWD"
mkdir build/cmake-build && cd build/cmake-build
cmake ../..
make -j$(nproc)

注意：不要在 Anaconda 环境中编译，库版本冲突会导致构建失败-18。

四、macOS 安装

方式一：Homebrew

brew tap dlr-ts/sumo
brew install sumo

方式二：MacPorts

sudo port install sumo

使用 GUI 前需安装 XQuartz：brew install --cask xquartz。

五、设置环境变量（MOSAIC 需要）

Linux/macOS：在 ~/.bashrc 或 ~/.zshrc 中添加：

export SUMO_HOME=/usr/share/sumo

或指向源码编译路径（如 /home/user/sumo）。

Windows：在“系统属性 → 环境变量”中添加 SUMO_HOME，值为 SUMO 安装路径（如 C:\Program Files (x86)\Eclipse\Sumo）。

验证：

echo $SUMO_HOME   # Linux/macOS
echo %SUMO_HOME%  # Windows

六、运行第一个仿真

SUMO 自带教程和示例。进入 docs/tutorial/quickstart/data 目录：

sumo-gui -c quickstart.sumocfg

或命令行运行：

sumo -c quickstart.sumocfg --netstate-dump quickstart.dump

核心文件说明：

• .net.xml：路网文件（节点、边）
• .rou.xml：路由文件（车辆类型、路线、车辆）
• .sumocfg：仿真配置文件（引用路网和路由文件）

第二部分：Eclipse MOSAIC 部署

一、前置准备

Java 环境：MOSAIC 基于 Java 开发，需要 Java 17 或 21（推荐 Eclipse Temurin OpenJDK）。Java 16 及以下不支持，Java 22 及以上未测试。

验证：

java -version

SUMO 版本要求：MOSAIC 25.2 官方测试的 SUMO 版本为 1.0.1 – 1.25.0，推荐 1.25.0。1.25.0 以上版本未测试，0.32.0 及以下不支持。

可选通信仿真器：如需详细通信仿真，可安装 ns-3（推荐 3.36.1）或 OMNeT++（推荐 6.1 + INET 4.5.4）。预置场景不需要这些。

二、下载 MOSAIC

从 Eclipse MOSAIC 下载页面获取最新发行版（当前为 eclipse-mosaic-25.2.zip）。

解压到任意路径，该路径称为 <mosaic-root>。解压后的目录结构包含：

• scenarios/：仿真场景目录
• etc/：配置文件（runtime.json 配置 Ambassador）
• mosaic.sh / mosaic.bat：启动脚本
• lib/：Java 库文件
• logs/：日志目录

三、运行第一个仿真（Bundle 版）

进入 MOSAIC 根目录，终端执行：

Linux/macOS：

./mosaic.sh -s Barnim -v

Windows：

mosaic.bat -s Barnim -v

-s Barnim 指定运行 Barnim 场景，-v 打开 2D 可视化（在默认浏览器中显示）。仿真中车辆会沿道路行驶并交换 V2X 消息。

降低仿真速度以便观察：

./mosaic.sh -s Barnim -v -b 5

-b 5 表示将仿真速度降低到实时因子的 1/5。

关闭 watchdog（调试时）：-w 0。

四、SUMO 与 MOSAIC 的配置对接

MOSAIC 运行 SUMO 场景时，需要以下文件：

<scenario_name>/sumo/
├── <scenarioName>.net.xml     # SUMO 路网文件（必需）
├── <scenarioName>.sumocfg     # SUMO 配置文件
└── sumo_config.json           # Ambassador 配置文件

注意：MOSAIC 场景中通常不需要单独的 .rou.xml 路由文件，因为车辆定义和路线通常通过 Mapping 配置文件和应用数据库管理。

启用 SUMO GUI：在 sumo/sumo_config.json 中设置 "visualizer": true。

启用 LibSumo 加速（大规模场景推荐）：

1. 确认 SUMO_HOME 已正确设置
2. 检查 SUMO 安装目录是否有 libsumojni.dll（Windows）或 liblibsumojni.so（Linux）
3. 如无，需安装 SUMO “extras” 发行版或从源码编译并启用 libsumo

五、从源码构建 MOSAIC（开发者）

如需修改 MOSAIC 源码，额外需要 Maven 3.1+。

git clone https://github.com/eclipse-mosaic/mosaic.git
cd mosaic
mvn clean install

构建产物在 bundle/target/ 目录下，解压后即可运行。

IntelliJ IDEA 用户：仓库已包含预定义的运行配置，导入项目后可直接运行。

第三部分：常见问题排查

SUMO 报错“no route file specified”：检查 .sumocfg 中 <route-files> 路径是否正确，文件是否存在。

MOSAIC 启动后立即退出：检查 Java 版本（需 17/21）、SUMO_HOME 环境变量、MOSAIC 日志中的具体错误。

SUMO GUI 在 macOS 无法启动：需先安装 XQuartz。

LibSumo 不可用：确认 SUMO 安装中包含 libsumojni 文件，如无则需安装 extras 版本或从源码编译。

MOSAIC 找不到场景：确认场景位于 <mosaic-root>/scenarios/ 下，或使用 -c 参数指定完整配置路径。