Control an installed workspace
Open the prepared ROS 2 example in VS Code, then run a short command in your local simulation.
Start a controllable world
- Follow Installation and install VS Code.
- Open WWW-POSIM, sign in with your verified account and select Start simulator. On Windows and Ubuntu, start Docker first.
- In Workspace, choose ready terrain and WAM-V, then select ROS 2 direct control.
- Start the world and wait for the vehicle and fresh position data. Keep the application and browser open.
The application runs the simulator. VS Code edits and runs your control program.
Open the prepared example in VS Code
Select Open in VS Code in the application. It opens your working directory and ros_vehicle_command.py. The initial directory is Documents/WWW-POSIM. Create Python project adds the examples and editor files while preserving existing files; opening VS Code also adds a missing vehicle example. Choose another folder in Local settings → Working directory. Open working directory opens that folder in the file manager.
If VS Code asks, trust your own project and allow the WWW-POSIM: ROS terminal automatic task. If you decline, run it with Terminal → Run Task → WWW-POSIM: ROS terminal. New integrated terminals use the WWW-POSIM ROS profile. Wait for ROS connected before running commands. Opening the example file does not run it.
On macOS, the terminal and Python debugger use the application’s bundled Python and prepared ROS environment. A separate Python virtual environment is unnecessary for this project. On Windows and Ubuntu, terminal commands run in the prepared controller container while VS Code edits the shared folder.
Install Microsoft’s Python and Python Debugger extensions for editing and debugging. On Windows and Ubuntu, also install Dev Containers and use Dev Containers: Reopen in Container for container debugging. Open ROS terminal opens an external prepared terminal in the same working directory.
Run the ROS 2 vehicle example
Select Enable ROS in the running world’s control panel. In the prepared VS Code terminal, inspect the options, then request a short WAM-V movement:
python ros_vehicle_command.py --help
python ros_vehicle_command.py --vehicle wamv --forward 0.3 --seconds 2
The example publishes ROS 2 commands regularly, then sends neutral commands when it finishes or you press Ctrl+C. It waits for a subscriber before sending movement commands. The example limits each run to 30 seconds, WAM-V commands to 1 m/s and 0.5 rad/s, and BlueROV2 thrust to 5 N per motor.
For BlueROV2, start with six neutral thrust values:
python ros_vehicle_command.py --vehicle bluerov2 --thrusters 0 0 0 0 0 0 --seconds 2
Check the selected vehicle and its motion before increasing input. Neutral commands do not remove inertia or wave forces.
Use the Python session interface
The same package also offers a Python session interface. Save this as controller.py and run python controller.py in the prepared terminal:
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"])
The program reads fresh position, requests 0.3 m/s forward motion for two seconds and releases control. Printed positions need not differ by an exact distance. Set yaw_rate=0.1 for a left turn. Use the browser’s stop control to interrupt vehicle control immediately.
BlueROV thrusters
The session interface accepts six BlueROV2 thrust values in native joint order, in newtons. WAM-V uses two values, left and right. Start with neutral input:
from www_posim_ros import Session
with Session.local(control=True) as sim:
sim.set_thrusters([0.0] * 6, duration=1.0)
| Interface limit | Value |
|---|---|
| WAM-V velocity | Forward ±1.5 m/s; yaw ±0.5 rad/s |
| WAM-V thrust | ±200 N per motor |
| BlueROV2 thrust | ±50 N per motor |
| Helper duration | Greater than 0, up to 300 seconds |
| Command watchdog | 0.75 seconds without a valid update |
These interface limits differ from the deliberately smaller limits in ros_vehicle_command.py. Helpers repeat commands at about 10 Hz and release control afterward. sim.stop() interrupts the current helper from another thread. A disconnect ends control; commands do not restart automatically after a network error.
When the server supports release confirmation, each helper waits for confirmation of neutral output and released authority before returning. controller_busy means another controller holds authority; stop that controller before starting a new one.
Normal scorer completion or the workspace Stop button can raise control_lease_ended. A command watchdog or unavailable simulator/sensor instead raises watchdog_timeout or simulation_or_sensor_unavailable and fails the run. Check simulator health and command timing, then start a new run explicitly.
During challenge evaluation, control_service_stalled means the server's native control callbacks stopped for more than 0.75 seconds. Propulsion stops safely and that course receives no valid score. Website submissions keep completed course records and retry the interrupted course automatically. In local practice, restart the run after checking simulator health.
Load an installed-app extension
An installed local workspace can load an owner-approved world/model ZIP extension. Hosted workspaces and assessment sessions do not execute extension code.
- In the workspace’s final review step, open User world/model extensions and Import extension ZIP. The archive contains
extension.json, its SDF entrypoint and the declared files with their hashes. Import validates and stores the archive without executing it. - Review Declared files and SDK, including the code, target, ZIP SHA-256 and SDK SHA-256. The target and SDK must match the running engine. Code runs with the local runtime’s file and network access.
- Choose Approve code and select, confirm only code you trust, then start the world. Approval belongs to the owner and exact ZIP/SDK pair; selection applies to the new session. Clear selected extension leaves the stored archive available.
An unknown SDK or target/hash mismatch disables selection. Use an extension built for the selected engine and approve its exact archive. General scripts without a registered navigation-provider entrypoint cannot run. The app owns the provider process for the session and stops it when the session ends.
WAM-V and BlueROV2 share one active ROS navigation provider. A selected user provider replaces the built-in provider’s output while retaining the raw GNSS receiver. Its common outputs are /vehicle/navigation/estimate (nav_msgs/Odometry) and /vehicle/navigation/status (std_msgs/String JSON). Pose uses navigation_map ENU; twist uses base_link body FLU. Matching simulation timestamps, finite covariance, session identity and a WGS 84 geographic origin are required.
In Autopilot mode, the common gateway checks those outputs before supplying external navigation to the FCU. Raw GNSS alone determines GPS fix status. Missing calibration, global alignment or valid sensor data must keep provider readiness false; importing or starting a provider does not establish navigation readiness. See GNSS & navigation for source selection and loss behaviour.
SDK updates
The Python SDK does not install updates automatically. Starting with SDK 0.4.2, connecting to a simulation checks the public stable release in the background. When a newer SDK is available, the terminal shows the installed and recommended versions and how to update. A failed update check does not stop your controller. Successful checks are cached for one hour; checking does not send your WWW-POSIM login details. Official scoring runs do not make this update request.
- App-prepared ROS terminal: use Check for updates in the WWW-POSIM launcher and install the app update. Start the updated simulator, then use Open ROS terminal or Open in VS Code in that launcher. Existing terminals keep their original environment.
- Existing Windows/Linux VS Code Dev Container: update the app, then set
imagein.devcontainer/devcontainer.jsonto the engine image printed in the SDK notice. Preserve your other project settings. Run Dev Containers: Rebuild and Reopen in Container, or Dev Containers: Rebuild Container when already connected. Reopening alone keeps the previous container. If the old SDK has no notice, use Create Python project in a new empty folder in the updated launcher and copy the generated container configuration'simagevalue. See VS Code's rebuild instructions. - Your own Python environment: stop your controller, then run the command printed by the notice. It uses that environment's Python executable and the official wheel for the recommended SDK. Restart Python afterward. Updating the app does not update a separately installed virtual environment.
You can check manually without signing in or running a world. In an app-prepared ROS terminal, run:
python -m www_posim_ros.updates
For the Website: prepare Python and VS Code, run the command from your project folder using its virtual environment.
Windows PowerShell
.\.venv\Scripts\python.exe -m www_posim_ros.updates
Mac / Linux
.venv/bin/python -m www_posim_ros.updates
SDK 0.4.1 and earlier do not contain the notifier or this command. Update those environments once using the SDK wheel installation command in the Website: prepare Python and VS Code, adding --upgrade after pip install. The notice describes an available update; it does not mean that installation has happened.
Troubleshooting
No module named www_posim_ros: use the project’s prepared Python interpreter.- No fresh telemetry: confirm that the world is running and the vehicle has appeared. A topic name alone does not confirm data reception.
- Direct-control mode required: start the world with ROS 2 direct control.
controller_busy: stop the other controller before retrying.- World or vehicle changed: restart the program to obtain the current connection profile.
- ROS tools fail: inspect
~/.www-posim-ros/domain-76/client.login the prepared environment, then close and reopen the tools if necessary.
Continue with ROS terminals & connections, Control a web workspace, RViz & Foxglove viewers or ROS troubleshooting.