ROS terminals & connections
The www_posim_ros package connects your ROS environment to a running WWW-POSIM workspace. Its connector receives authenticated telemetry and publishes standard ROS 2 messages in your local ROS domain. Keep it running while using ROS tools.
Gazebo sensors→ HTTPS / WebSocket →www_posim_ros
connector→ local ROS 2 →ros2 topic · RViz
your Python program
Installed app terminal
Start a world, then select Open ROS terminal in the installed app. It opens your working directory, initially Documents/WWW-POSIM, and prepares the app’s ROS environment. Several app terminals share one local connector.
If startup fails on Windows, the app-opened terminal keeps the error message visible until you press Enter. For a live-telemetry timeout, start your world in the browser, then reopen the ROS terminal.
On macOS, the terminal shows a WWW-POSIM header, preparation status and an elapsed connection indicator. Wait for ROS connected and the ROS, Python and connector versions before entering commands. The colored WWW-POSIM prompt identifies this prepared environment.
Open in VS Code opens the same directory with a prepared ROS terminal and ros_vehicle_command.py. Follow Control an installed workspace to run a controller. Open RViz opens the installed viewer.
In Autopilot mode, ROS tools provide telemetry only. ros_vehicle_command.py requires ROS 2 direct control. To change modes, disarm the vehicle, reuse a prepared terrain in workspace setup, select ROS 2 direct control and start the world again. Restarting resets the simulation. A saved vehicle keeps its control mode; use a built-in vehicle or edit a copy of the saved vehicle to change it.
The installed workbench's ROS 2 direct control panel also offers Open ROS terminal and Open in VS Code. Both use the app's selected working directory. On the website, or when the local launcher is unavailable, use ROS terminal and VS Code guide. The guide opens in a separate window.
Connect your ROS environment to a web workspace
Start your personal world on the website. Prepare ROS 2 Lyrical and standard message packages using the ROS installation guide. In an Ubuntu or WSL terminal, load ROS and install the connector:
source /opt/ros/lyrical/setup.bash
sudo apt install ros-lyrical-rmw-cyclonedds-cpp
python3 -m venv --system-site-packages .venv-ros
source .venv-ros/bin/activate
python -m pip install https://github.com/IOES-Lab/homebrew-www-posim/releases/download/v0.6.16/www_posim_ros-0.4.3-py3-none-any.whl
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
export ROS_DOMAIN_ID=76
export ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST
www-posim-connect --server https://www-posim.vercel.app/api --email YOU@example.com
Enter your password when prompted. Leave this terminal open. In a second terminal, source the same ROS setup and virtual environment and set the same three environment variables. A Python virtual environment alone does not provide ROS or rclpy.
For the Mac app’s bundled environment, replace the ROS setup command with:
eval "$(/Applications/WWW-POSIM.app/Contents/MacOS/WWW-POSIM --ros-env)"
Connect your ROS environment to an installed workspace
Start the installed app and your world. In your prepared ROS environment, use this command instead of the website connector:
www-posim-connect --local --server http://127.0.0.1:3300/api
It uses the app’s active session without asking for website credentials. Use one connector per ROS domain; do not also start an app-managed connector in that domain. If a separate WSL distribution cannot reach the Windows app’s loopback address, use Open ROS terminal in the app.
Verify topics and live data
Once the connector reports ready, run these commands in the prepared terminal:
ros2 topic list
ros2 topic echo /model/wamv/odometry
Check that messages continue arriving and their timestamps advance. Press Ctrl+C to stop the echo. For BlueROV2, choose its odometry topic from the list. A topic name appearing in the list does not by itself confirm a live stream.
If there is no data, check that the world is running and both terminals use the same ROS environment and domain. Continue with ROS troubleshooting, Control a web workspace or Control an installed workspace.