WWW-POSIM v0.6.16仿真器文档
文档菜单
WWW-POSIM / 仿真器文档

安装

选择适合操作系统的安装方式。表格中的链接会跳转到本页对应的操作步骤。

选择安装包

操作系统 安装方式 仿真引擎
Apple Silicon · macOS 27及以上 通过DMG安装 · 通过Homebrew安装 原生ROS 2、Gazebo · Metal
Ubuntu 26.04 · x86-64 APT软件源 · 通过DEB安装 Docker中的Linux引擎
Windows · x86-64 在Windows上安装 Docker Desktop · WSL2

SHA-256校验和

在Windows上安装

配置WSL2

如果尚未安装WSL,从开始菜单以管理员身份打开终端或PowerShell,执行:

wsl --install --no-distribution

按提示重启电脑,再打开一个新终端执行:

wsl --update
wsl --set-default-version 2
wsl --status

确认默认版本为2。如果出现虚拟化错误,请检查固件中的硬件虚拟化设置,并参阅Microsoft的WSL安装指南。Docker Desktop使用自己的WSL2环境,因此应用不需要单独安装Ubuntu发行版。只有准备独立的ROS环境时才需要另行安装。

安装Docker Desktop和应用

  1. 安装Docker Desktop,配置WSL2后端,并按要求重启。
  2. 打开Docker Desktop,等待引擎运行。
  3. 下载Windows安装程序,按提示安装。如果出现Windows已保护你的电脑,对官方WWW-POSIM下载选择更多信息 → 仍要运行。当前安装包没有Authenticode签名,可使用公开的SHA-256校验和确认文件。
  4. 从开始菜单打开WWW-POSIM。如果再次出现相同警告,再次确认。登录后选择启动仿真器。
  5. 浏览器会打开本地仿真器。继续阅读熟悉工作区。

使用期间请保持Docker Desktop运行。应用会自动下载与自身版本匹配的镜像。

通过DMG安装

需要搭载Apple Silicon的Mac,系统为macOS 27或更新版本。可在苹果菜单 → 关于本机中确认。

  1. 下载Mac版DMG。
  2. 打开DMG,将WWW-POSIM拖入应用程序。
  3. 尝试打开应用。该应用使用临时签名,未经过Apple公证。
  4. 如果首次启动被阻止,打开系统设置 → 隐私与安全性 → 安全性,点击WWW-POSIM旁的仍要打开。在确认窗口中选择打开,并按要求完成身份验证。参阅Apple说明。
  5. 登录并选择启动仿真器。首次启动会下载、验证并解压引擎文件,窗口中会显示进度。
  6. 浏览器打开后,继续阅读熟悉工作区。

下载支持断点续传,文件按512 MiB分块。每个安装程序和分块文件均小于2 GiB。ROS环境和准备好的引擎缓存在应用目录之外,供后续启动复用。原生引擎通过Metal使用GPU。

如果启动受阻,参阅恢复Mac应用启动。

通过Homebrew安装

如果尚未安装Homebrew,先按照其官方安装说明完成安装。然后执行以下命令安装同一应用:

brew tap ioes-lab/www-posim
brew trust --cask ioes-lab/www-posim/www-posim
brew install --cask ioes-lab/www-posim/www-posim

brew trust --cask允许加载指定仓库中该应用的Cask。参阅Tap Trust。

如果Homebrew请求packages.arm64_dunno.jws.json时收到HTTP 404,说明其系统版本表尚未识别macOS 27。可以绕过软件包API更新Homebrew,再安装应用:

HOMEBREW_NO_INSTALL_FROM_API=1 brew update
HOMEBREW_NO_AUTO_UPDATE=1 brew tap ioes-lab/www-posim
HOMEBREW_NO_AUTO_UPDATE=1 brew trust --cask ioes-lab/www-posim/www-posim
HOMEBREW_NO_AUTO_UPDATE=1 brew install --cask ioes-lab/www-posim/www-posim

这些环境变量仅对紧随其后的命令有效,详见Homebrew环境选项。如果仍然失败,请使用通过DMG安装。

打开WWW-POSIM,使用与网站相同的账号登录。应用会自动连接账号服务器。首次启动会验证文件并将引擎解压到Library中,显示已解压大小、百分比、预计剩余时间和服务启动状态。Gazebo、ROS 2和Autopilot均在Mac上运行。更新提示不会中断正在运行的仿真。

要在已有终端中加载随应用提供的环境,执行:

eval "$(/Applications/WWW-POSIM.app/Contents/MacOS/WWW-POSIM --ros-env)"

应用已包含连接器、标准ROS消息和RViz2。打开ROS终端和打开RViz会使用该环境。算法所需的其他依赖请安装到兼容环境中。参阅ROS 终端与连接和控制桌面版工作区。

在Ubuntu上准备Docker

安装Docker和curl。将账号加入Docker用户组后,退出Ubuntu会话并重新登录。

sudo apt update
sudo apt install -y docker.io curl
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

APT软件源

先完成在Ubuntu上准备Docker,再添加签名APT软件源并安装应用:

SERVER=https://www-posim.vercel.app
curl -fSL "$SERVER/guide/packages/apt/www-posim-archive-keyring.gpg" | \
  sudo tee /usr/share/keyrings/www-posim-archive-keyring.gpg >/dev/null
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/www-posim-archive-keyring.gpg] $SERVER/guide/packages/apt stable main" | \
  sudo tee /etc/apt/sources.list.d/www-posim.list
sudo apt update
sudo apt install www-posim
www-posim

应用会按自身版本选择引擎镜像。当前账号必须能够访问Docker。GPU渲染还需要兼容的驱动和容器运行环境。

通过DEB安装

此安装包面向x86-64架构的Ubuntu 26.04。按Ctrl+Alt+T打开终端并执行:

sudo apt update
sudo apt install -y docker.io curl
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
mkdir -p ~/Downloads
cd ~/Downloads
curl -fL -o www-posim.deb https://www-posim.vercel.app/guide/packages/latest/linux-amd64.deb
sudo apt install ./www-posim.deb
  1. sudo提示时输入电脑密码,输入过程中不会显示字符。
  2. 退出Ubuntu会话并重新登录,使Docker访问权限生效。
  3. 从应用菜单打开WWW-POSIM,或运行www-posim。
  4. 登录,选择启动仿真器,再阅读熟悉工作区。

使用Docker也必须是Ubuntu 26.04吗?

Docker Engine也支持Ubuntu 24.04和22.04。容器内的Ubuntu与ROS版本不必与宿主机一致。不过,WWW-POSIM发布的DEB和安装脚本面向Ubuntu 26.04,启动程序本身也依赖宿主机的系统库。因此,此DEB的支持环境是26.04。旧版宿主机能够运行Docker,并不能证明WWW-POSIM安装程序也兼容。参阅Docker支持的Ubuntu版本。

验证账号并开始使用

在安装注册账号,打开验证邮件并选择验证邮箱。如果没有收到,请检查垃圾邮件。验证成功并登录后,应用可以将密码保存在操作系统的凭据存储中。

登录和定期更新使用权限需要互联网连接。请为引擎、地形和模型预留磁盘空间。账号存储配额与电脑的可用空间是两回事。参阅账号与使用时长。

创建Python项目会向已保存的工作目录添加示例,初始目录为Documents/WWW-POSIM。打开ROS终端、打开工作目录和在VS Code中打开均使用该目录。VS Code会打开ros_vehicle_command.py。继续阅读控制桌面版工作区。

选择图形设备

本地设置中的图形 → 自动(推荐)会在引擎容器内实际检测EGL图形设备。Windows的NVIDIA环境使用WSL D3D12。如果没有可用的硬件渲染器,应用会改用CPU并说明原因。

必须使用GPU会在GPU检测失败时停止启动。软件(CPU)选择CPU渲染。Linux的NVIDIA环境需要兼容的驱动和NVIDIA Container Toolkit。Windows用户应在Windows侧安装NVIDIA驱动,引擎使用WSL2后端。Mac原生引擎使用Metal。

应用中的ROS终端和RViz已经配置好环境。只有按照ROS 终端与连接手动搭建独立环境时,才需要额外安装Ubuntu和ROS。

本地场景由Gazebo Ogre2渲染。拖动可绕场景旋转观察相机,滚轮用于缩放。没有收到画面或画面停止更新时,视图会显示等待状态。

更新

红色提示条会显示已安装版本和可用版本。立即更新在仿真器中打开安装说明,在启动程序中开始经过验证的下载。点击×可在当前标签页隐藏提示,直到出现更新版本。

请先结束仿真,再选择一种方式更新:

Mac更新程序会在替换应用前验证下载和签名。如果现有引擎已匹配,只下载应用文件。保存在应用目录之外的项目、模型和地形缓存会保留。

对于另一台ROS工作站,请下载连接器安装包,并按ROS 终端与连接准备兼容的ROS环境。

引擎镜像

应用会自动从Docker Hub下载匹配版本的引擎和工作空间镜像。这些镜像公开可用,无需登录镜像仓库或手动输入镜像地址。Mac原生安装包使用经过验证的分块发布文件,不使用Docker镜像。

docker.io/ioeslab/www-posim-engine:0.6.15-amd64
docker.io/ioeslab/www-posim-web:0.6.15-amd64

也可以提前下载:

docker pull docker.io/ioeslab/www-posim-engine:0.6.15-amd64
docker pull docker.io/ioeslab/www-posim-web:0.6.15-amd64

恢复Mac应用启动

此发行版未经Apple公证,因此下载或替换应用后可能再次出现警告。请先尝试仍要打开。如果按钮无响应,或应用停留在Dock中却没有窗口,可能需要重启macOS的应用验证服务。

先退出WWW-POSIM。只有启动程序无响应且没有仿真运行时,才使用苹果菜单 → 强制退出。重启Mac后重新打开应用是最简单的恢复方法。

如果希望不重启电脑,请先确认DMG来自官方下载,且与公布的SHA-256校验和一致。执行shasum -a 256并在后面加上DMG路径。临时签名只能验证文件完整性,不能证明发布者身份。

将Mac启动恢复工具保存到下载目录,然后执行:

bash "$HOME/Downloads/recover_macos_launch.command"

默认检查会验证应用身份和签名,并报告下载隔离属性。要修复启动阻止,执行:

bash "$HOME/Downloads/recover_macos_launch.command" --repair --restart-validation

阅读提示后,输入TRUST WWW-POSIM,表示允许该应用在Apple警告下运行。工具只移除所选应用的隔离属性,重启验证服务并请求打开应用。sudo要求时,请在本机终端输入Mac密码。Gatekeeper仍保持启用。请确认应用窗口确实出现;发出打开请求本身不代表启动成功。

如果仍要打开正常响应,无需重启验证服务,则只使用--repair。Dev版应用需添加--app "/Applications/WWW-POSIM Dev.app"。DMG的README旁也包含同一工具,可将其路径传给bash执行。

若手动执行同样的恢复,请先退出应用并验证官方DMG的校验和。只有下面的完整性检查成功、且你信任该应用时,才继续:

codesign --verify --deep --strict "/Applications/WWW-POSIM.app"
xattr -dr com.apple.quarantine "/Applications/WWW-POSIM.app"
sudo /usr/bin/killall -TERM syspolicyd
open -a "/Applications/WWW-POSIM.app"

重启验证服务会影响其他应用尚未完成的安全检查,可能需要重新打开这些应用。如果恢复失败,请重启Mac。如果签名验证失败,请重新下载官方安装程序。

搜索文档