[Documentation] [TitleIndex] [WordIndex

API review

Proposer: Bill Morris

Reviewers:

Overview

There is a growing need for a standard GPS message. This will allow for the development of inter-operable navigation algorithms and ground station control systems.

Status Basic

Proposed Basic Status

uint16 satellites_visible

uint16 STATUS_NO_FIX=0   # Unable to fix position
uint16 STATUS_FIX=1      # Normal fix
uint16 STATUS_DGPS_FIX=3 # Fixed with DGPS
uint16 STATUS_WAAS_FIX=5 # Fixed with WAAS
uint16 status

Status Advanced

UMD/gpsd

Header header

# Satellites used in solution
uint16 satellites_used # Number of satellites
int32[] satellite_used_prn # PRN identifiers\

# Satellites visible
uint16 satellites_visible
int32[] satellite_visible_prn # PRN identifiers
int32[] satellite_visible_z # Elevation of satellites
int32[] satellite_visible_azimuth # Azimuth of satellites
int32[] satellite_visible_snr # Signal-to-noise ratios (dB)


# Measurement status
uint16 STATUS_NO_FIX=0   # Unable to fix position
uint16 STATUS_FIX=1      # Normal fix
uint16 STATUS_DGPS_FIX=3 # Fixed with DGPS
uint16 STATUS_WAAS_FIX=5 # Fixed with WAAS
uint16 status
uint16 SOURCE_NONE=0 # No information is available
uint16 SOURCE_GPS=1 # Using standard GPS location [only valid for position_sourc
e]
uint16 SOURCE_POINTS=2 # Motion/orientation fix is derived from successive point
s
uint16 SOURCE_DOPPLER=4 # Motion is derived using the Doppler effect
uint16 SOURCE_ALTIMETER=8 # Using an altimeter
uint16 SOURCE_MAGNETIC=16 # Using magnetic sensors
uint16 SOURCE_GYRO=32 # Using gyroscopes
uint16 SOURCE_ACCEL=64 # Using accelerometers
uint16 motion_source # Source for speed, climb and track
uint16 orientation_source # Source for device orientation
uint16 position_source # Source for position

Position

The position returned by the GPS

UMD/gpsd

Header header

# Latitude (degrees). Positive is north of equator; negative is south.
float64 latitude

# Longitude (degrees). Positive is east of prime meridian, negative south.
float64 longitude

# Altitude (meters). Positive is above reference (e.g., sea level).
float64 altitude

# Direction (degrees from north)
float64 track

# Ground speed (meters/second)
float64 speed

# Vertical speed (meters/second)
float64 climb

# Device orientation (units in degrees)
float64 pitch
float64 roll
float64 dip

# GPS time
float64 time

# Total (positional-temporal) dilution of precision
float64 gdop

# Positional (3D) dilution of precision
float64 pdop

# Horizontal dilution of precision
float64 hdop

# Vertical dilution of precision
float64 vdop

# Temporal dilution of precision
float64 tdop

# Spherical position uncertainty (meters) [epe]
float64 err

# Horizontal position uncertainty (meters) [eph]
float64 err_horz

# Vertical position uncertainty (meters) [epv]
float64 err_vert

# Track uncertainty (degrees) [epd]
float64 err_track

# Ground speed uncertainty (meters/second) [eps]
float64 err_speed

# Vertical speed uncertainty (meters/second) [epc]
float64 err_climb

# Temporal uncertainty [ept]
float64 err_time

# Orientation uncertainty (degrees)
float64 err_pitch
float64 err_roll
float64 err_dip

Question / concerns / comments

Refocusing the discussion

GNSFix.msg

From my reading we have a consensus to have sensor_msgs/GNSFix.msg as below pending finalization of the uncertainty representation.

# Specified in WGS84
#
# If the covariance of the measurement is known, it should be filled in (if all you know is the variance of each measurement, e.g. from the GPS receiver, just put those along the diagonal)
# A covariance matrix of all zeros will be interpreted as "covariance unknown", and to use the data a covariance will have to be assumed or gotten from some other source

Header header

sensor_msgs/GNSStatus status

# Position information
# Latitude [degrees]. Positive is north of equator; negative is south.
float64 latitude

# Longitude [degrees]. Positive is east of prime meridian; negative is west.
float64 longitude

# Altitude [m]. Positive is above reference ellipsoid
float64 altitude

# Position covariance [m^2]
float64[9] position_covariance # Row major about latitude, longitude, altitude

GNSStatus.msg

This is the new version of GPSStatus globalized and adding service field as proposed by Mike.

# Note that you whether to output a DGPS fix is not only determined by both the fix type and the last time DGPS corrections were received. For example, if the last time a good set of corrections were received was more than, say, 15 seconds ago, you should fall back to a standard fix. A similar rule should apply for WAAS.
# A fix is valid if the status field is >= 0

int8 STATUS_NO_FIX = -1  # Unable to fix position
int8 STATUS_FIX = 0      # Normal fix
int8 STATUS_SBAS_FIX = 1 # Fixed with some sort of SBAS (e.g. WAAS)
int8 STATUS_DGPS_FIX = 2 # Fixed with DGPS
int8 status

# Defines the source of the GNSS signal(s) used by the receiver.
# BeiDou included in SERVICE_COMPASS
int8 SERVICE_GPS=1
int8 SERVICE_GLONASS=2
int8 SERVICE_COMPASS=4
int8 SERVICE_GALILEO=8
int8 service

Diagnostics

However it sounds like people would like an independently published GNSAdvancedStatus message of some form with things like the satellite information. How do these generalize to other GNS systems? I haven't seen a concrete proposal so I'm going to throw this down as a straw man. However we may consider holding off on this part until the next round since it gets more complicated and the above messages are much more important for compatibility.

I'm going to suggest should we have a advanced status message which is service specific such that there is a different one for GPS vs Galileo, vs Glonass. I think that if we try to keep things entirely generic it will end up being useless.

sensor_msgs/GPSSattelite.msg

int32 prn # PRN identifier
int32 z # elevation
int32 azimuth
int32 snr # signal-to-noise ratio (dB)

GPSAdvancedStatus

Header header
GNSStatus status  # put status here too since it's in a different channel than GNSFix
uint32 gps_weeks
Time gps_seconds
# Total (positional-temporal) dilution of precision
float64 gdop

# Positional (3D) dilution of precision
float64 pdop

# Horizontal dilution of precision
float64 hdop

# Vertical dilution of precision
float64 vdop

# Temporal dilution of precision
float64 tdop

# Spherical position uncertainty (meters) [epe]
float64 err

GPSSatellite gps_satellites_used
GPSSatellite gps_satellites_visible_but_unused

Review discussion

New points raised in review discussion e-mails.

uint8 COVARIANCE_TYPE_UNKNOWN = 0
uint8 COVARIANCE_TYPE_APPROXIMATED = 1
uint8 COVARIANCE_TYPE_DIAGONAL_KNOWN = 2
uint8 COVARIANCE_TYPE_KNOWN = 3
uint8 position_covariance_type

Meeting agenda

(Jack) We need final approvals by 22 October 2010 for inclusion in the common_msgs stack for Diamondback. Let's shoot for an initial approval vote Wednesday morning, 20 October. That leaves two days to resolve any final issues that remain.

(Jack, 20 October) I am starting to wrap up this review, polling the reviewers directly via e-mail.

(Jack, 22 October) As moderator, I declare this review closed and the new API approved.

Conclusion

Review conclusions (pending final approval):

Future releases:



2023-10-28 13:04