WWW-POSIM v0.6.16Simulator documentation
Documentation menu
WWW-POSIM / Simulator documentation

Workspace basics

Start a world from the opening screen, then learn the panels and controls.

Create and verify your account

  1. Open WWW-POSIM and select Create account.
  2. Enter your email and password. Open the email sent to you and select Verify email.
  3. Return to the website and sign in. If the email is missing, check spam or choose Send another verification email when signing in.

Email verification is required for the website and installed app. Back to main page and Sign out are on the first workspace entry screen.

Start a world near Busan

  1. For local simulation, Installation, sign in and select Start simulator. For server simulation, sign in on the website and open your personal workspace.
  2. Open Workspace. The installed app opens this window automatically.
  3. Select Pregenerated terrain to use a prepared field.
  4. In the terrain slider, select KMOU waterfront · 1 × 1 km to open Regional terrain → Vehicle. Prepared fields and completed maps appear together. For another location, generate a map and wait for it to become ready.
  5. Choose WAM-V, depth 0 m, and Autopilot. Keep the other settings at their defaults.
  6. Select Start world. Wait for the robot and live position data. The initial installed setup window closes only after the world is running.

Look around and view sensors

  1. Select Vehicle to follow the robot. Drag with the left button to move, drag with the right button to orbit, and scroll to zoom.
  2. Select World for a close oblique view of the scene. Select Map for a geographic map of the full region and live vehicle position, with north at the top; drag to pan and scroll to zoom.
  3. Open Sensors and choose a camera, LiDAR or IMU. Use Back to list to choose another sensor.
  4. Wait for the image or numbers to update. A sensor measures what the simulated robot sees or feels.

LiDAR measures distances around the robot. IMU measures motion and orientation. On a phone, open one panel at a time to keep the scene visible.

Find vehicle controls

Read the instruments

The bottom instrument shows the scene camera’s heading, simulation time and the measured realtime ratio. Its fixed arrow represents the camera’s forward direction; the compass letters rotate to locate true north. Map view keeps north at the top. 1.00× means simulation time advances at real time. The zoom buttons sit below Vehicle/World, beside the drag and scroll hints.

Use the interface

Control Action
Vehicle Follow the robot; drag to orbit, scroll to zoom
World Inspect the scene from a close oblique view
Map North-up geographic map and live vehicle position; drag to pan
Scene renderer Choose Browser or Gazebo for the world view
Focus Enlarge the scene while retaining the minimap and key status
Panels Hide/show side panels
− in a personal workspace Hide the panel; reopen through its panel/tab button
− / + in public LIVE Collapse/expand content while keeping the header

On a phone, open one panel at a time to leave room for the scene. The simulation continues while panels are hidden. Compass labels such as N, NE, E show direction. Check how recently the position data was received.

Inspect sensors

Expand the robot in Sensors, then choose a camera, LiDAR or IMU.

Digital zoom operates on the received image. Available sensors depend on the model.

Prepared terrain and demo worlds

Demo worlds

Inspect the demo targets

The WAM-V demo starts on Hong Kong harbour terrain with two round floating buoys: a coral buoy 16 m ahead and 5 m left, and a lime buoy 30 m ahead and 8 m right. Open the forward RGB camera and lidar scan to inspect both targets.

Download prepared terrain

The Mac app downloads terrain when you first select a demo or a prepared field. A progress indicator shows the transfer. The demo starts when its terrain is ready; other fields open Regional terrain → Vehicle. Downloaded fields stay available offline. Each field keeps its pinned content revision across app updates. If the download fails, check the connection and select the demo or field again.

A world contains the terrain, water and robot. A workspace is your place to create and run worlds. On the website, you may need to wait for an available server slot.

Read the workspace

Running WAM-V workspace with scene tools on the left, ArduPilot and vehicle instruments on the right, and ground control below
WAM-V running in the KMOU waterfront terrain. Select a screenshot to read it at full size.
Area Contents and purpose
Top bar Robot/terrain identity, Live status, Workspace, language, Focus and Panels. Session also appears when account usage is enabled.
Centre scene A view of the running world. Vehicle, World and Map change the viewpoint.
Left: Scene and Sensors Scene controls the environment and display. Sensors opens robot measurements. ROS topics inspects published messages.
Right: ArduPilot or ROS2 The selected control path. ArduPilot exposes arming, flight modes, joystick input, missions and parameters. ROS2 exposes direct-control enable/stop.
Right: Vehicle panel Attitude instrument, selectable time-series graph, simulation speed, position/orientation and connection details.
Lower left: Ground control Geographic robot position, map waypoints and route commands. Its header expands or collapses the map.
Scene instruments Camera compass, simulation time and measured realtime ratio. These help distinguish the scene camera's direction from the vehicle's heading.

− / + collapses or expands a panel; the header remains available. Open a section's + to see its settings. On a small screen, the dock may compact another section to make room. Panels hides or shows the side panels; Focus enlarges the scene. Hiding a panel does not stop the simulation.

Start Workspace

Start Workspace dialog with Demo worlds, Pregenerated terrain, Practice arena and Custom world tabs
The four tabs choose a workspace entry path. The bright lime tab is selected.
Tab or control What it does
Demo worlds Starts WAM-V or BlueROV2; other robot previews show their availability.
Pregenerated terrain Lists ready or downloadable fields and saved ready terrain. Selecting a field opens its vehicle setup after any required download.
Practice arena Prepares the challenge-practice setup when available.
Custom world Opens Regional terrain, robot editing, RViz tools and storage.
Location → Vehicle → Review Select or generate terrain, choose the robot and starting pose, then review and start the world.
Control mode in Vehicle setup Chooses Autopilot or ROS 2 direct control for the world being started.
Start world Submits the selected world and robot configuration. Watch the progress/error area and wait for live position data.

Complete the coordinates and depth within their field limits before continuing to Review. A custom practice seed must be a whole number from 0 to 1,000,000; an empty seed selects an automatic layout. Free exploration and administrator baseline runs ignore custom practice seeds.

A world’s control type is chosen before Start world. To change between Autopilot and ROS 2 direct control, start a world with the other control type. A flight-mode change inside ArduPilot is a separate action.

Change the view

Button or gesture Effect
Vehicle Follows the robot; use orbit and zoom to inspect it.
World Shows a local oblique overview of the scene.
Map Opens the north-up geographic view when the world has a geographic reference.
Drag / right-drag / scroll Pan, orbit or zoom as indicated by the current view's hints. Map dragging pans the map.
Clear track Clears the displayed planned route and recent trail; recording continues from the current position. It does not cancel a mission.
Focus / Exit focus Enlarges the scene and returns to the normal layout. Ground-control information remains accessible.

Under Scene → Scene renderer, Browser and Gazebo choose how the main scene is drawn. Gazebo still computes physics and sensor data when the Browser scene is selected. Scene-camera and renderer choices do not change the ArduPilot flight mode.

Scene and environment panel

Scene panel with renderer, environment and display settings
Expand the section you need. A setting's availability follows the running world.
Section Controls and interpretation
Waves Choose a sea-state preset, or open advanced wind settings; Apply waves sends the selected values. Check the confirmation/status beneath the button.
Ocean current With a current-capable runtime, turn on Enable current and choose Uniform or Depth profile. Edit speed and direction; in Depth profile, drag nodes horizontally to change speed or edit/add depth nodes in the table. Select Apply current and check for Confirmed by the current solver. Stop mission/direct ROS control before changing currents.
Marine traffic Enables AIS-synchronised visual vessels. Custom worlds use the locally supplied AISStream key. Availability depends on coverage and simulation speed.
Scene renderer Select Browser/Gazebo and, where available, expand Underwater appearance for texture, haze, absorption, lighting and measurement-line settings.
Display Toggles seafloor, sea surface, reference grid and robot axes. These are display choices, not extra measurements.
Natural lighting / Day/night Changes the scene's lighting presentation.
Water opacity / Map overlay / Map opacity Adjusts visibility and map presentation where supported by the current renderer/view.
Graphics performance Shows measured browser rendering statistics.

Current's Flow direction uses 0° East and 90° North. Its angle convention differs from the camera compass. For current-profile ranges and interpolation, sea-state ranges, terrain coverage and optical settings, see Workspace basics and Generate terrain for your site.

Sensors and ROS topics

Sensors panel showing an actual robot camera feed and its stream controls
Select a sensor to open its measurement view. Back to list returns to the available sensors.
Control Effect
Sensors → sensor name Opens the selected camera, scan or numerical measurement. Available sensors come from the robot model.
Start stream / Stop stream Starts or stops that image stream. The simulation continues.
Enlarge Opens a larger camera-image dialog.
Save frame Saves the received personal image or a snapshot of the demo video.
Sensor rate Requests the supported image delivery rate; the measured rate reports actual reception.
Digital zoom / Reset Digitally enlarges the received image or restores its zoom.
ROS topics → search/topic Finds a topic and opens its message view.
Subscribe / Unsubscribe Starts or stops receiving the selected topic in the viewer.
Field / Plot / Raw / Draw Selects a numeric field, inspects values, or draws supported spatial messages. The available options depend on message type and frame.

The main Vehicle/World camera is an observer view. A sensor-camera panel shows the robot's own simulated camera. The two views can point in different directions. Control an installed workspace explain external visualisation and controller connections.

When the image has not appeared yet

After Start stream, Connecting or Waiting means the sensor and transport are preparing. Also check the reception time of images and numeric samples. A retained image marked Stale or Reconnecting is not a fresh measurement. First check whether the world is ready and the intended sensor is selected.

The public Hong Kong demo RGB camera uses shared H.264 video and waits for its initial buffer. Personal camera panels request JPEG frames; ROS compressed images have a separate delivery path. Save frame saves the displayed video snapshot in the demo and the received image file in a personal panel. Sensor Hz, video FPS and physical RTF are different measurements. See Video and sensor transport.

ArduPilot: arm and change flight mode

WAM-V ArduPilot panel reporting Disarmed and HOLD after applying a mode change
WAM-V uses the ArduRover boat controller.
BlueROV2 ArduPilot panel reporting ALT_HOLD after applying a mode change
BlueROV2 uses ArduSub. Its flight-mode choices differ from WAM-V.
  1. Expand the ArduPilot header. Check that telemetry is connected and read the current armed state and reported mode.
  2. Centre/release manual inputs. Finish or Abort an active mission before making a manual mode change.
  3. Choose a value in Flight mode, then select Apply.
  4. Check Flight mode · … beneath the controls and the mode in the header. The dropdown is a request; the reported value confirms the controller's state.

Arm enables the controller's propulsion path after readiness checks. Disarm disables it and cancels an active mission. A mode selection alone does not arm the vehicle. If a command is rejected, read the error and Connection details. Terrain holds and active missions can block a mode change; a camera image alone does not establish control readiness.

WAM-V flight modes

Mode shown in the menu Meaning
MANUAL Pilot throttle and steering commands control the outputs directly.
HOLD Commands stopped/neutral propulsion. Inertia, waves and current may still move a boat; this is not geographic station keeping.
STEERING Uses feedback-assisted speed and turning control for pilot inputs. It does not run a waypoint route by itself.

See ArduPilot's Manual, Hold and Steering descriptions for the controller behaviour.

BlueROV2 flight modes

Mode shown in the menu Meaning
MANUAL Direct pilot control without automatic attitude or depth stabilisation.
STABILIZE Stabilises attitude; the pilot still controls depth.
ALT_HOLD Adds automatic depth control to stabilisation. With neutral vertical input it maintains the depth target; it does not hold horizontal position.

These are the modes exposed by the WWW-POSIM menu, rather than the full upstream mode list. See the official ArduSub mode reference.

Missions and GUIDED

Starting a checked waypoint route or preset mission makes the application request GUIDED and arm the controller as part of its start sequence. GUIDED is managed by the mission runner; it is not a manual option in this dropdown.

Stop in Ground control pauses an active mission around its hold target. Continue resumes it. Abort cancels and disarms. These mission actions are separate from choosing ArduRover HOLD or stopping joystick input.

Joystick and gamepad input

Joystick input panel with control pads, input source and gain controls
Joystick input reveals the manual-input panel in an Autopilot world.

Enable Joystick input in ArduPilot, then choose Mouse / touch or Gamepad. Read the axis labels: WAM-V exposes throttle/steering, while an underwater robot also has lateral and vertical control. Input gain scales manual input. Begin with centred inputs and a low gain.

For mouse or touch input, Stop input cancels the current press. Release and press a pad again to resume. Losing focus, disarming, switching input source or a rejected command also ends that press.

For a gamepad, hold LB/L1 while issuing stick commands. Releasing it or selecting Stop input sends neutral input; this does not disarm or guarantee that a moving robot stops immediately. BlueROV2's Y/Triangle shortcut requests ALT_HOLD; A/Cross requests STABILIZE. Read back the resulting mode in ArduPilot. Full mappings and controller-profile selection are in Use manual controls.

Ground control and missions

Complete each waypoint coordinate and depth before checking the route. Empty fields remain empty while editing. A new underwater waypoint starts at 2 m. The standard range is 0–10 m; use the current Mission depth limits shown by the server for supported inspection scenes.

Ground-control map with editable waypoints and route-check, run, stop, continue and abort controls
Map waypoints and mission controls share one panel. Check route and Run route stay available when the map is collapsed.
Control Effect
Click / right-click a waypoint Adds a point / removes the selected nearby point. Drag and wheel/pinch pan and zoom the map.
Waypoint list Edits coordinates and underwater depth. Surface waypoints use 0 m depth. Map waypoints wait for 1 second.
Return to start / Clear Adds return behaviour / clears the editable waypoint selection.
Check route Builds a terrain-checked preview. Check the drawn path and any reported clearance or blocker.
Run route Starts the checked route and arms the robot after readiness checks.
Arm / Disarm Controls arming; disarm also cancels the mission.
Stop / Continue / Abort Pauses around a hold target / resumes / cancels and disarms.

After a route starts, check it again before another run; the robot may have moved since the previous preview.

Under ArduPilot → Preset scenario missions, choose a preset and its depth/size, then Check route. Its action becomes Arm & run mission after a successful preview. Map waypoints take priority when present; clear them to use the preset again. Route checking evaluates terrain and hull clearance; it does not provide complete moving-vessel avoidance or COLREG compliance.

Vehicle panel

Vehicle is the right-hand panel below ArduPilot or ROS2. Select its + / − button to expand or collapse it. On a phone, select Vehicle in the mobile switcher first. The panel scrolls when its contents exceed the available height; expand Simulation speed, Position & orientation and Connection details individually to reveal their contents.

Vehicle instruments, depth graph, simulation speed and expandable position and connection sections
The Vehicle panel shows live readings from a disarmed WAM-V. Expand each detail section to inspect timing, position and connection status.

Attitude instrument and graph

The blue fixed marker represents the robot. The moving horizon and angle marks show its roll and pitch. The numeric readings beside it describe the vehicle's orientation:

Reading Meaning
Heading Vehicle compass bearing: 0° North, 90° East, 180° South, 270° West. The letter is the nearest compass direction. The bottom scene compass follows the camera separately.
Roll Side-to-side bank in degrees.
Pitch Nose-up/nose-down angle in degrees, using the instrument's display convention.
Depth Signed depth from the world's zero sea level: −Z in metres. Positive values are below that level; negative values are above it. This differs from clearance above the seabed.

Use the dropdown above the small graph to choose Depth, Heading, Pitch, Roll, Velocity or Thruster input. The bold number shows the selected value and its unit; the line shows the last 100 received pose samples. Changing this selection changes the graph. Check the workspace's live status and message age before interpreting a retained trace. Missing or stale attitude readings appear muted or as —.

Depth and attitude share the same odometry sample and acquisition time. Surface heave can cross zero in the depth graph. The demo aligns these samples to buffered video playback.

The small label beside the selector identifies the source. Depth, attitude and velocity use Gazebo simulator values. Velocity plots body-frame X (forward), Y (left) and Z (up) together in m/s. Thruster input plots each propulsion command in newtons with its own legend. These commands are requested thrust, rather than measured force. Missing or stale command samples create gaps.

Simulation speed

Open Simulation speed to reveal two selectors. A selection is submitted immediately; wait for the setting to finish applying and read the result beneath it.

Control or readout How to use it
Simulation speed selector Requests 0.25×, 0.5×, 1×, 2× or 4×. For example, 2× requests two seconds of simulation per second of real time.
Physics step selector Chooses the simulation integration interval: 5, 10 or 20 ms. A world already using 30 ms also shows its current 30 ms setting.
Actual and the value in the section header Measured simulation time divided by real time. This can be lower than the requested factor when the computer cannot keep up. The line below the selectors also shows the applied physics step.

These controls become available when timing is ready, the vehicle is disarmed, mission/manual/ROS control streams are inactive and terrain is ready. Read any applying or error message. At accelerated targets above 1×, AIS traffic is unavailable; return to a supported speed to use it. See Custom worlds for the timing trade-offs.

Position & orientation

Open Position & orientation to see the local position, geographic position when available, and raw orientation. The frame name identifies the local coordinate system.

Field Meaning
N / E / D, metres North, East and Down relative to the displayed local frame's origin. Positive D points down.
World coordinates Latitude followed by longitude in degrees, when the session has a geographic reference.
R / P / Y, degrees, under Attitude · ENU Raw roll, pitch and yaw in the east/north/up frame. Yaw 0° points East and 90° points North.

The attitude instrument converts these raw angles for its display: its pitch is −P, and its compass heading is (90 − Y + 360) % 360. For example, raw yaw 0° corresponds to Heading 90° East. Read the coordinate labels when comparing the panel with ROS tools. Waiting or stale position data is marked in this section.

Connection details and RViz

Open the Vehicle panel's Connection details to read #sequence, message age in seconds and the frame with its ENU convention. An increasing sequence and fresh age help confirm that new pose messages are arriving. These are pose diagnostics; the ArduPilot or ROS2 panel's own connection details describe its controller link.

Open at RViz in the Vehicle header opens the session's supported ROS visualisation workflow. The installed app provides native RViz2; a web workspace opens the browser viewer. The action requires a ready world, and the installed app also needs its local RViz service ready. Hover a disabled button to read its reason. See Control an installed workspace.

Controller tuning is under ArduPilot → ArduPilot parameters. Read/search/export parameters there, preview edits and apply allowed changes while disarmed, then verify the readback. See Autopilot parameters.

ROS 2 direct-control mode

ROS2 direct-control panel with Enable and Stop controls and connection diagnostics
A world started with ROS 2 direct control replaces the ArduPilot controls with this panel.

Enable ROS permits your connected controller to send bounded commands to the current session. Stop ROS latches neutral output until enabled again. Connection details show the reason, applied sequence/ACK and thrust values. The controller connection has a watchdog that returns output to neutral when commands stop arriving.

ArduPilot arming, flight-mode selection and the built-in guided missions belong to Autopilot worlds. In a ROS 2 direct-control world, follow Control an installed workspace for the connection and program workflow.

Manage saved terrain and vehicles

Open Workspace → Custom world → Storage to inspect model revisions, terrain, caches and free disk space. On hosts with account storage enabled, Archive hides an item from selection and Restore makes it selectable again in the same screen. Archiving retains its files and does not reclaim space. Wait for queued, starting, running or closing sessions that use an item to finish before archiving it.

Use the vehicle builder's Export ZIP / Import vehicle to transfer a configuration to another computer. Edit a copy creates a new revision. See Prepare your vehicle.

Small screens and common questions

Desktop view in the public Hong Kong demo on a phone scales the desktop arrangement into the visible browser area in landscape; portrait shows a prompt to rotate. Use Return to mobile view to restore the panel layout. Fullscreen depends on browser support and a user action. If the address or tab bars remain visible, the workspace fits the available area below them.

Continue with Workspace basics, Control an installed workspace or Generate terrain for your site.

Choose the scene renderer

Choose a sea state

Apply ocean current

Open Scene → Ocean current below Waves when a current-capable runtime is connected. Enable the current, choose Uniform or Depth profile, and select Apply current. Stop mission or direct ROS control before changing it. Challenge currents follow their assigned conditions.

Edit a depth profile

Current changes the water-relative velocity used for vehicle drag and damping. Wind-driven waves continue to provide wave-aware buoyancy and loading through their own model. Current does not modify the wave spectrum, wavelength or propagation. Confirmed by the current solver means fresh physical readback matches the applied profile.

Set the physics time step

Windows and Linux installed apps start with a 20 ms physics step. The Mac native app uses 10 ms. In the vehicle panel’s simulation-speed settings, select 5 or 10 ms for finer time resolution while the vehicle is disarmed. Challenge profiles retain their required 10 ms step. The real-time ratio shows measured progress rather than the requested speed.

Scene views and sensor feeds

Both views use the same running simulation. Gazebo computes physics and sensor data. Cameras and GPU LiDAR use Gazebo rendering; IMU and position data come from the simulation. You can view these sensor feeds while using Browser for the world scene.

Underwater appearance

Expand Scene → Scene renderer → Underwater appearance in a running workspace. Each switch applies live to the Gazebo scene and camera color feeds, including RGBD color. The controls show confirmed renderer settings. Depth measurements and collision geometry retain their numeric values.

Effect defaults and saved settings

Understand camera visibility

See Camera clipping and visibility for the built-in BlueROV2 forward camera’s geometric clipping distance. Underwater haze, attenuation and occlusion reduce useful visibility. Vehicle scene tracks are 5 mm wide and are excluded from sensor images.

Read and clear route tracks

Yellow shows the planned mission route and teal shows the actual track in both scene renderers. The teal Gazebo trail clears when a new guided mission starts. Use Clear track beside the zoom buttons to erase both the planned route and the recorded trail from the view. Recording continues from the current position; the mission report is retained. The display keeps up to 1,024 segments, replacing the oldest as the vehicle moves.

Rendering assumptions

Choose Gazebo to inspect the optical effects. The Browser preview shares sand-detail and seabed-line settings. The effects use a flat mean sea level and PBR surfaces; sky rays use the same water-path attenuation, while custom water shaders and unlit materials have their own appearance. Sunlight patterns and suspended specks are visual approximations. See Generate terrain for your site for the sand source.

AISStream key

Demo worlds enable marine traffic automatically using the server’s configured AISStream credential. Installed demos use the Open Waters public AIS feed when no server key is configured. The traffic panel shows the provider and connection status. Vessel visibility depends on fresh reports received for the area.

Custom worlds require your own key: open Scene → Marine traffic, enter an AISStream API key and select Save key locally. The key is stored in this browser and sent to the selected simulator server. Remove local key clears it. Enable Marine traffic to connect. Reported AIS positions determine which ships appear.

Control with QGC

For an Autopilot vehicle, select Open QGC in the ArduPilot panel. Keep the installed app and signed-in workspace open. The connection dialog prepares the vehicle and hands control to QGroundControl. See Control with QGC for installation, connection and release of control.

BlueROV2 front lights

Use Front lights in the joystick controls to switch both BlueROV2 lamps ON/OFF. The readback confirms the actual lamp state; a failed or unavailable command is not shown as success. This changes vehicle illumination, separately from scene day/night and camera selection.

Search documentation