POSIM v1.0.1Platform for Ocean Simulation · Documentation
Documentation menu
POSIM / Plugin reference

Marine GNSS

The public posim_gz_gnss system simulates a satellite receiver at a model's antenna link. It converts the antenna's world position to geographic coordinates, adds configurable Gaussian position/velocity error, and publishes an atomic measurement with a timestamp and validity state. It models loss of reception under water, explicit obstruction, reacquisition and latency.

Build and mount a receiver

In terminal A prepared for your installation, including the Linux desktop reached through RDP on macOS:

cd "$POSIM_WS"
source /opt/ros/lyrical/setup.bash
colcon build --merge-install --packages-select posim_gz_gnss posim_robot_models
source install/setup.bash

Your model needs a physical antenna link, usually gnss_link, with its intended pose and attachment to the vehicle. The world needs WGS 84 spherical coordinates. Add the following plugin inside the model SDF, replacing the topic and link name as needed:

<plugin filename="libposim_gnss.so" name="posim::Gnss">
  <link_name>gnss_link</link_name>
  <topic>/model/my_robot/gnss</topic>
  <enabled>true</enabled>
  <water_level>0</water_level>
  <update_rate>5</update_rate>
  <latency>0.2</latency>
  <reacquire_seconds>3</reacquire_seconds>
  <dry_margin>0.05</dry_margin>
</plugin>

The receiver profiles provide mount poses relative to base_link: WAM-V at z = 1.8 m; BlueROV2 variants at 0.3 m; REXROV at 0.8 m. WAM-V and the three BlueROV2 profiles enable the receiver; REXROV disables it by default. These JSON profiles are data for model-building callers. Installing them does not insert a link or plugin into every robot. WAM-V also needs its external Wave Sim model.

BlueROV2, BlueROV2 Heavy and the sonar variant include the receiver and the marine_gnss_input adapter. With ArduSub enabled, the adapter sends MAVROS GPSINPUT messages to the autopilot instead of SITL's synthetic GPS. It converts ENU velocity to NED and WGS 84 ellipsoid altitude to EGM96 mean-sea-level altitude using the installed GeographicLib dataset. Submerged, blocked, invalid, future or more than 1 s old measurements produce no fix. Satellite count is unknown (255) for a valid fix; satellite geometry and dilution are not simulated. The demo receiver uses mean water level z = 0, independently of the visual waves.

Parameters

SDF parameter Unit / meaning Default
update_rate Samples per simulation second; >0 to 100 Hz 5
latency Fix delivery delay in simulation seconds; 0–10 s 0.2
reacquire_seconds Continuous dry acquisition time, s 3
dry_margin Clearance above water needed to acquire, m 0.05
horizontal_stddev Horizontal position standard deviation, m 0.7
vertical_stddev Vertical position standard deviation, m 1.2
velocity_stddev Velocity standard deviation, m/s 0.1
water_level Mean surface z when no wave topic is set, m 0
seed Receiver random seed 42
enabled Receiver enabled true
link_name Antenna link within the model gnss_link
topic Gazebo measurement topic /model/<model-name>/gnss
wave_topic Optional sampled-water-height topic Empty

Numeric receiver settings must be finite. Latency, acquisition time, dry margin and standard deviations must be nonnegative.

An empty wave_topic uses the mean-water plane. A nonempty topic requires fresh local height samples; missing or invalid data produces surface unavailable. The protocol uses gz.msgs.Double_V: schema 1, grid count, periodic X/Y size, wind speed/angle, steepness, simulation time and row-major heights. The grid count is an integer from 2 to 256, followed by a number of height values equal to the square of that count. Tile sizes must be finite and positive; the finite timestamp must be no more than 0.6 simulation seconds old and cannot be in the future. The receiver consumes this grid; configure a compatible publisher separately. Wind metadata does not control reception.

Read measurements and obstruction state

After starting your configured model, use the prepared terminal B to read its topic:

gz topic -e -t /model/my_robot/gnss

Each message contains 15 doubles. Indices are zero-based; retain the acquisition timestamp even when a fix arrives after the configured delay.

Index Field / unit
0–3 Schema 1, reset epoch, acquisition time in simulation seconds, state
4–6 Latitude degrees, longitude degrees, altitude meters
7–9 East, north and up velocity, m/s
10–12 Horizontal/vertical position variance in m², velocity variance in (m/s)²
13–14 Antenna world z and local water height, m

States are 0 disabled, 1 submerged, 2 acquiring, 3 fix, 4 blocked and 5 surface unavailable. Invalid measurements have NaN coordinates and velocities. Water contact or blockage clears queued fixes. Reacquisition needs continuous clearance above the dry margin. Reset clears the timer and delayed samples and advances the epoch.

Publish an obstruction input; use false to clear it:

gz topic -t /model/my_robot/gnss/blocked -m gz.msgs.Boolean -p 'data: true'

Interpretation and checks

Compare a stationary dry antenna, a submerged antenna, a blocked antenna and recovery. Check acquisition time, delay, epoch after reset and increasing measurement timestamps. Consumers must reject stale/future fixes and handle invalid states.

The supplied BlueROV2 adapter feeds ArduSub; other ROS NavSatFix consumers and custom autopilots still need an adapter.

The receiver is a simplified pose-based model. It does not compute satellite geometry, RF propagation, physical multipath or underwater acoustic positioning. Configurable accuracy values are simulation inputs, not a vendor accuracy guarantee. See the receiver implementation and package guide.