控制桌面版工作区
在 VS Code 中打开已准备好的 ROS 2 示例,再向本地仿真发送一条短时指令。
启动可控制的世界
- 按安装准备应用,并安装 VS Code。
- 打开 WWW-POSIM,用已验证的账号登录并选择启动仿真器。Windows 和 Ubuntu 需先启动 Docker。
- 在工作区选择已就绪地形、WAM-V 和 ROS 2直接控制。
- 启动世界,等待载具和新的位置数据出现。保持应用与浏览器打开。
应用运行仿真,VS Code 用于编辑和执行控制程序。
在 VS Code 中打开准备好的示例
在 VS Code 中打开会同时打开工作目录和 ros_vehicle_command.py。初始目录为 Documents/WWW-POSIM。创建 Python 项目会保留已有文件并添加示例和编辑器设置。打开 VS Code 时,如果缺少载具示例,也会补充该文件。可在本地设置 → 工作目录中选择其他目录。打开工作目录会在文件管理器中显示该目录。
如果 VS Code 询问,请信任自己的项目,并允许自动任务 WWW-POSIM: ROS terminal。如果未允许,可通过终端 → 运行任务 → WWW-POSIM: ROS terminal启动。新集成终端使用 WWW-POSIM ROS 配置。请等待 ROS connected;打开文件本身不会执行示例。
macOS 的终端和调试器使用应用自带的 Python 与已准备的 ROS 环境,无需为此项目另建虚拟环境。Windows 和 Ubuntu 中,命令在准备好的控制容器中执行,VS Code 编辑主机上的共享目录。
安装 Microsoft 的 Python 和 Python Debugger 扩展。Windows 和 Ubuntu 还需 Dev Containers,通过 Dev Containers: Reopen in Container进行容器内调试。打开 ROS 终端会在同一工作目录启动外部 ROS 终端。
运行 ROS 2 载具示例
在世界控制面板选择启用ROS。在准备好的终端查看选项,再请求 WAM-V 短距离移动:
python ros_vehicle_command.py --help
python ros_vehicle_command.py --vehicle wamv --forward 0.3 --seconds 2
示例会定期发布指令,并在结束或按下 Ctrl+C 时发送中立指令。开始运动前会等待订阅者连接。每次运行最长 30 秒;WAM-V 限制为 1 m/s 和 0.5 rad/s,BlueROV2 限制为每个推进器 5 N。
BlueROV2 应从六个中立值开始:
python ros_vehicle_command.py --vehicle bluerov2 --thrusters 0 0 0 0 0 0 --seconds 2
增大输入前请检查所选载具及其响应。中立指令不会消除惯性或波浪力。
使用 Python 会话接口
同一软件包也提供 Python 会话接口。将以下代码保存为 controller.py,在准备好的终端运行 python controller.py:
from www_posim_ros import Session
with Session.local(control=True) as sim:
topic = next(name for name, kind in sim.topics.items()
if kind == "nav_msgs/msg/Odometry")
print("Before:", sim.latest(topic)["pose"]["pose"]["position"])
sim.set_velocity(forward=0.3, yaw_rate=0.0, duration=2.0)
print("After:", sim.latest(topic)["pose"]["pose"]["position"])
程序读取新的位置,以 0.3 m/s 请求前进两秒,然后释放控制。打印的两个位置不一定相差某个精确距离。设置 yaw_rate=0.1 可左转。浏览器的停止控件可立即中断控制。
控制 BlueROV 推力
会话接口按模型原生关节顺序接收 BlueROV2 的六个推力值,单位为牛顿。WAM-V 使用左、右两个值。先发送中立输入:
from www_posim_ros import Session
with Session.local(control=True) as sim:
sim.set_thrusters([0.0] * 6, duration=1.0)
| 接口限制 | 数值 |
|---|---|
| WAM-V 速度 | 前进 ±1.5 m/s,偏航 ±0.5 rad/s |
| WAM-V 推力 | 每个推进器 ±200 N |
| BlueROV2 推力 | 每个推进器 ±50 N |
| 辅助函数持续时间 | 大于 0,最长 300 秒 |
| 指令看门狗 | 0.75 秒没有有效更新 |
这些接口上限不同于 ros_vehicle_command.py 中刻意设置的较小示例上限。辅助函数约以 10 Hz 重复指令,结束后释放控制。其他线程可调用 sim.stop() 中断当前辅助函数。断线会结束控制;网络错误后不会自动恢复指令。
如果服务器支持释放确认,每个辅助函数都会等待推力归零并释放控制权。出现 controller_busy 时,请先停止另一个控制器。评测正常结束或手动停止时,可能会收到 control_lease_ended。watchdog_timeout 和 simulation_or_sensor_unavailable 表示运行失败。
挑战评测期间,control_service_stalled 表示服务器的原生控制回调停止超过0.75秒。推进器会安全停止,该次运行不获得有效分数。网站提交会保留已完成的评测记录,并自动重试中断的评测。本地练习时,请检查模拟器后重新开始运行。
加载安装版应用扩展
安装版应用的本地工作空间可以加载所有者批准的 world/model ZIP 扩展。托管工作空间和评测会话不执行扩展代码。
- 在工作空间最后的检查步骤中打开 User world/model extensions → Import extension ZIP。ZIP 包含
extension.json、SDF 入口和带哈希的已声明文件。导入只检查并保存文件,不执行代码。 - 在 Declared files and SDK 中检查代码、目标平台、ZIP SHA-256 和 SDK SHA-256。目标和 SDK 必须与正在运行的引擎一致。代码以本地运行环境的权限访问文件和网络。
- 仅对可信代码选择 Approve code and select 并确认,然后启动世界。批准绑定所有者和准确的 ZIP/SDK 组合,选择应用于新会话。Clear selected extension 不会删除已保存的 ZIP。
SDK 无法确认,或目标、哈希不匹配时,无法选择扩展。请使用为所选引擎构建的扩展,并批准其准确的 ZIP。没有已注册导航提供程序入口的普通脚本不能运行。应用管理提供程序进程,并在会话结束时停止它。
WAM-V 和 BlueROV2 共用一个只有单个活动 ROS 导航提供程序的接口。所选用户提供程序替代内置提供程序的输出,同时保留原始 GNSS 接收机。公共输出为 /vehicle/navigation/estimate 上的 nav_msgs/Odometry 和 /vehicle/navigation/status 上的 std_msgs/String JSON。位姿使用 navigation_map ENU 坐标,速度使用 base_link 机体 FLU 坐标。必须提供匹配的仿真时间戳、有限协方差、会话标识和 WGS 84 地理原点。
在 Autopilot 模式下,公共网关先检查输出,再向 FCU 提供外部导航。GPS 定位状态仅由原始 GNSS 决定。缺少标定、全局对齐或有效传感器数据时,提供程序必须保持未就绪状态。导入或启动进程不代表导航已就绪。输入源选择和信号丢失行为见GNSS 与导航。
更新 SDK
自 0.4.2 起,Python SDK 会在连接时于后台检查稳定版本,并在终端显示安装方法。正式评测会跳过此检查。如使用应用自带的 SDK,请更新应用并重新打开 ROS 终端。如使用现有的 VS Code 开发容器,请在 .devcontainer/devcontainer.json 中设置提示所示的镜像并重新构建容器。如使用独立的 Python 环境,请运行提示中的命令,再重启 Python。可以运行 python -m www_posim_ros.updates 手动检查。
排查问题
No module named www_posim_ros:使用项目准备好的 Python 解释器。- 没有新遥测:确认世界运行且载具已出现。话题名存在不代表接收到数据。
- 提示需要直接控制:以 ROS 2 直接控制模式启动世界。
controller_busy:停止其他控制程序后再试。- 更换了世界或载具:重启程序以取得当前连接配置。
- ROS 工具失败:查看准备好的环境中的
~/.www-posim-ros/domain-76/client.log,必要时关闭并重新打开工具。