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

GNSS & navigation

WAM-V and BlueROV2 application sessions enable the simulated POSIM satellite GNSS receiver by default. BlueROV2 settings can explicitly disable it. Both vehicles use the same sensor contract, antenna link and topics. GNSS measurement state and FCU position estimates remain distinct.

Implementation catalogue

Stage Implemented technology Parameter / output
Antenna kinematics Native Gazebo posim::Gnss observes the actual antenna link, including body rotation and lever arm. link_name, model mounting pose; geographic position and finite-difference antenna velocity.
Measurement error Independent seeded Gaussian position and velocity perturbations. horizontal_stddev, vertical_stddev, velocity_stddev, seed; diagonal measurement covariance.
Availability Wave-sampled antenna wet/dry test, hysteresis, continuous reacquisition and explicit obstruction input. water_level, wave_topic, dry_margin, reacquire_seconds, enabled; fix/acquiring/submerged/blocked/unavailable state.
Timing Simulation-time acquisition cadence and delayed-measurement queue. update_rate, latency; original acquisition stamp retained after delivery.
ROS / flight controller Adapter validates epoch/stamp/finiteness, publishes sensor fix/status and converts accepted measurements to MAVLink GPS_INPUT. Sensor aliases, raw FCU GPS and fused estimates remain separately identifiable.
Display / mission Freshness and EKF state drive readiness and mission guards. A fusion indicator is a status interpretation, not access to every filter innovation.

Receiver implementation and profiles define the sensor. WWW-POSIM adds ROS conversion, controller-source selection and mission integration. The following sections give the parameter values, reference frames and failure behaviour. Sensor models & parameters.

Measurements and estimates

Output Meaning
/model/{robot}/gnss/fix Sensor NavSatFix; antenna position with configured measurement noise
/model/{robot}/gnss/status Receiver state and original measurement time; JSON in std_msgs/String
/vehicle/gnss/fix, /vehicle/gnss/status Common active-vehicle ROS aliases of those same sensor messages; not a second GPS injector
/mavros/global_position/raw/fix ArduPilot's received GPS, after MAVROS conversion
/mavros/global_position/global Fused FCU position estimate
/mavros/local_position/pose Fused local FCU pose; ENU
/model/{robot}/odometry Simulator reference for 3D rendering, terrain safety and validation; not the map latitude/longitude source

The receiver creates measurements in the native Gazebo process. Its ROS adapter converts accepted fixes to MAVLink GPS_INPUT, receiver ID 0. The ArduPilot profile selects the MAV receiver, disables the second receiver and SITL's synthetic GPS, and selects GPS horizontal position/velocity with compass yaw. Ground-truth vision pose/velocity is not injected into the FCU, including when GNSS is disabled. A single antenna supplies no stationary heading measurement; GPS course while moving is also distinct from body heading.

The GNSS profile sets the horizontal velocity-noise floor EK3_VELNE_M_NSE from receiver.velocity_stddev, clamped to the documented 0.05–5 m/s range (default 0.1 m/s). Reported receiver speed accuracy can raise the effective floor. This configures EKF weighting; the simulated measurement noise stays unchanged.

WAM-V's Gazebo IMU supplies acceleration and angular velocity through the ArduPilot JSON interface. Its compass uses the SITL magnetic-field model. This heading path is an idealized simulation dependency; it does not derive stationary heading from the GNSS antenna.

Waypoint targets use the FCU geographic EKF origin. GNSS missions use the estimated position for arrival decisions. Simulator truth remains available for trajectory evaluation and terrain safety checks. It does not align away the receiver's horizontal error. A fresh fix alone does not establish a healthy navigation filter: the UI reports EKF validity separately. The fusion indicator combines the configured source, fresh sensor state and EKF flags; it is not a per-observation innovation log.

After arming, missions with GNSS configured require two continuous wall-clock seconds of fresh local pose and observed sensor fusion, from GNSS or accepted external navigation, before requesting GUIDED. Loss restarts this interval. The mission stops if navigation does not settle within 35 seconds. Receiver reacquisition uses a separate simulation-time timer.

Web and installed workspaces request FCU EKF status, system status and heartbeat messages at 5 Hz of simulation time after the flight controller connects. This keeps status updates frequent when physics runs below real time. Status older than three wall-clock seconds is rejected. While the receiver has a clock-validated fix, the GNSS adapter repeats its validity status every 0.2 wall-clock seconds with the original measurement timestamp. Each GPS input and sensor fix comes from a new accepted receiver measurement. A stopped clock or stale measurement invalidates the receiver.

Common configuration and frames

POSIM's posim_gz_gnss/config/profiles.json defines receiver settings and per-model mounting transforms. Model SDFs contain base_link → gnss_link → gnss. The existing pose publisher exposes the actual link/sensor hierarchy through TF. WAM-V places the antenna 1.8 m above base_link; BlueROV2's mount is 0.3 m above it. The model link contributes 0.001 kg.

Simulator truth uses map and the model's link frames. GNSS sessions give MAVROS local poses a separate fcu_map frame and publish map → fcu_map → fcu_base_link for the estimate. The first transform uses the reported EKF geographic origin projected into the terrain datum; it is never fitted against truth. Its vertical translation assumes zero, preserving the local barometric zero approximation rather than claiming survey altitude. Sensor mounting TF belongs to the truth hierarchy; a surveying consumer must apply the same mount extrinsics to the estimated body pose and preserve measurement times.

Quantity Default and interpretation
Coordinates WGS 84 latitude/longitude in degrees; world spherical coordinates define the datum
Local axes ENU: east, north, up; world heading 0°
Body axes FLU; ArduPilot antenna offset converts to FRD: x, −y, −z
Velocity Antenna displacement over the measurement interval, rotated into ENU; GPS_INPUT is north, east, down
Antenna lever arm Applied geometrically before measuring; supplied to ArduPilot as the same body offset
Position standard deviation East/north 0.7 m each; vertical 1.2 m
Velocity standard deviation 0.1 m/s per axis
Covariance ENU diagonal 0.49, 0.49, 1.44 m²; known diagonal
Measurement rate / latency 5 Hz / 0.2 s, simulation time
Validity limits Reject duplicate, reversed, nonfinite, future or over-0.6-second-old measurements; 0.8 s wall watchdog for simulation clock progress
Time Acquisition stamp is retained through delay; deterministic GPS week 2296 + elapsed simulation time
Quality placeholders 12 satellites, HDOP 1.0, VDOP 1.5; no satellite constellation calculation
Randomness Seed 42; independent Gaussian position and velocity errors

The default world uses sea-level elevation 0 m and a synthetic zero geoid separation. Sensor altitude and GPS_INPUT MSL altitude coincide under this assumption. MAVROS raw GPS messages apply their installed EGM96 geoid conversion when reporting ellipsoid altitude, so their altitude can differ from the sensor topic. Absolute vertical geodesy is not survey qualified. Depth remains referenced to the local water surface. A future GNSS+IMU+depth multibeam pipeline must preserve these frames, acquisition times and vertical datum assumptions.

Water, loss and recovery

The receiver compares the world-space antenna height, including vehicle rotation, with the local water surface. Application worlds use the physical wave solver's sampled local heightfield, with bilinear interpolation. A surface sample older than 0.6 simulation seconds makes the receiver unavailable. Standalone POSIM models use the configured mean water plane unless a wave topic is supplied.

The application relays measured local wave cells with their original timestamps, selecting samples 0.2–0.5 simulation seconds old. Missing cells remain invalid; the receiver still requires finite local samples and checks antenna immersion.

Immersion at or below the surface immediately invalidates the fix and clears delayed measurements. Acquisition starts only above a 0.05 m dry margin and requires 3 continuous simulation seconds. A locked receiver remains valid within the dry margin until it reaches the wet boundary. This hysteresis and acquisition timer prevent rapid fix/no-fix switching near waves.

No-fix messages contain NaN coordinates. The adapter sends an explicit no-fix GPS_INPUT without valid position fields. It never republishes a last valid coordinate with a new acquisition time. A reset clears pending measurements and acquisition state, advances the receiver epoch and restarts clock validation.

An underwater receiver can lose fix while manual attitude, depth and thrust controls remain available for surfacing. Absolute-position missions require a fresh, valid sensor-fed FCU navigation estimate. WAM-V startup uses a fresh GNSS fix or a qualified, accepted external source, together with the other arming checks.

An explicit Gazebo Boolean /model/{robot}/gnss/blocked input represents an imposed reception obstruction. Wind speed is not a GNSS-off switch. Wind can move the vehicle, change its attitude and contribute to waves that immerse the antenna. Satellite geometry, buildings, multipath, atmospheric propagation, RF interference and antenna radiation patterns are not physically simulated. The Gaussian errors, obstruction switch and immersion rule are simplified test models, not measured RF performance.

BlueROV2 equipment

The selectable satellite receiver is a simulation payload. It does not describe the equipment supplied with a physical BlueROV2 or a manufacturer GNSS integration kit. Check the official BlueROV2 catalogue for the hardware configuration.

Water Linked Underwater GPS integration combines a topside geographic reference with underwater acoustic positioning. Water Linked also describes combining UGPS with DVL. These are separate devices and measurement paths. Acoustic UGPS is not implemented by this satellite receiver.

GPS.gov explains how geometry, blockage, multipath and receiver design affect real accuracy. The simulated standard deviations are application settings, not a GPS service guarantee. External pages are references; product imagery, manuals and vendor code are not bundled by this receiver.

Sensor-based map position

Ground Control uses a fresh GNSS antenna measurement or a valid external estimate accepted by the FCU gateway. It never substitutes simulator coordinates. The map shows green GPS fixed, red GPS lost, and distinct unknown, stale or invalid states. GPS fix and navigation readiness are independent.

With GPS fixed, only the GPS badge appears. With GPS lost and a fresh, validated estimate, the map also shows Position estimation ON. If an underwater estimate is required but unavailable, it shows Estimate unavailable. The info button beside ON opens the estimation method and a documentation link; use click, touch or the keyboard, and Escape to dismiss. Coordinate numbers are hidden. Expand Navigation details below the map for support, initial-reference and sensor-initialization states.

The IMU/DVL estimator consumes raw angular velocity, specific force and valid bottom-relative velocity. It retains sensor timestamps, mounting transforms and covariance; it does not consume Gazebo orientation. Local odometry alone does not establish geographic position or heading.

The built-in BlueROV2 · KMOU uses a scenario-declared initial coordinate and measured magnetometer heading with configured declination. This initial reference is labelled separately from GPS. A temporary simulation support holds the vehicle while cameras warm and the stationary sensor window initializes. After normal ALT_HOLD arming and accepted navigation, the support is released and actual joint removal is confirmed. The initial coordinate is not continuously updated from simulator truth.

This known-stationary profile is limited to that built-in demo. It is not enabled automatically for saved vehicles or arbitrary worlds. General GNSS-motion alignment remains unqualified for geographic output. Raw local filter diagnostics keep navigation_ready=false; the common gateway independently marks an accepted geographic estimate ready only with fresh data, valid origin/covariance, acknowledged source selection and FCU EKF/global telemetry.

DVL loss, stale inputs, a reset or a new segment invalidates the estimate. Ground Control removes the estimated coordinate and shows the failure. Restoring DVL delivery does not reuse the initial anchor: restart the simulation. A fresh GNSS fix after surfacing can supply map position again without silently restarting the underwater estimator.

ArduPilot, QGC and replaceable providers

Fresh GNSS feeds GPS_INPUT and EKF source 1. Accepted external position and velocity feed MAVROS vision pose/speed interfaces and EKF source 2. WAM-V's default GNSS-only session does not enable an unused visual-odometry input. An explicitly selected external provider enables the same guarded path for either vehicle.

QGC receives raw GPS validity through GPS_RAW_INT and the fused position through GLOBAL_POSITION_INT. Its GPS indicator can therefore report no fix while a valid FCU position estimate remains available. An external estimate never changes the raw GPS fix flag. Follow the Control with QGC; handing control over requires disarming, which can let an underwater vehicle rise under buoyancy.

Installed-app extensions can select an approved, hash-bound ROS provider declared in SDF. /vehicle/navigation/estimate carries ENU pose and body-FLU velocity in nav_msgs/Odometry; /vehicle/navigation/status carries the matching session, timestamp, origin, readiness metadata and source identity. The gateway rejects stale, mismatched or duplicate publishers. GNSS validity remains owned by the receiver. See Control an installed workspace for extension scope and trust requirements. A loaded provider alone does not qualify geographic accuracy or mission readiness.

Search documentation