GPS Receiver Guide

RemoteRF supports USB GPS / GNSS satellite navigation receiver modules operating at the GPS L1 band (1575.42 MHz). Connected to a RemoteRF host, the receiver provides live UTC satellite time, 3D geodetic coordinates (latitude, longitude, altitude, and ground speed), tracked satellite counts, and raw NMEA 0183 sentences ($GPGGA, $GPRMC, $GPGSV, $GPGSA). This guide covers how to initialize, query position fixes, and read NMEA sentences with a reserved GPS receiver through RemoteRF using Python.

A USB GPS / GNSS satellite navigation receiver module.
A USB GPS / GNSS satellite navigation receiver module.

Device Initialization

To interface with a GPS receiver through RemoteRF, call ensure_driver to make sure the local driver is up to date, import GpsModule from remoterf.drivers.gps, and initialize a gps object with either your reserved device handle (e.g., "GPS_Receiver@ucla" while logged in with remoterf --login) or the reservation token issued by resdev:

from remoterf.drivers import ensure_driver
ensure_driver(token="GPS_Receiver@ucla")

from remoterf.drivers.gps import GpsModule
gps = GpsModule(token="GPS_Receiver@ucla") # device handle or reservation token

Once initialized, the gps object provides access to parsed position dictionaries, satellite lock status, UTC timestamps, and raw NMEA sentence streams.

Example Script

The Python script below demonstrates how to query satellite lock status, geodetic position fixes, and raw NMEA 0183 sentences from a GPS receiver via the RemoteRF platform. In this example, the script checks the receiver connection, waits for a satellite fix, prints the parsed latitude, longitude, altitude, and UTC time, and reads a batch of raw NMEA sentences.

Note that the device initialization lines described above have already been included in the code below. You should not need to change any of the code below except for the device handle or token for your reservation.

from remoterf.drivers import ensure_driver

# -------------------------------------------------------
# 1. Connect to Reserved GPS Receiver
# -------------------------------------------------------
TOKEN = "GPS_Receiver@ucla"
ensure_driver(token=TOKEN)

from remoterf.drivers.gps import GpsModule

gps = GpsModule(token=TOKEN)

# -------------------------------------------------------
# 2. Check Receiver Status & Wait for Satellite Fix
# -------------------------------------------------------
print(f"Connected  : {gps.connected}")
print(f"Serial Port: {gps.port}")

gps.wait_for_fix(timeout=5)
print(f"Has Fix    : {gps.has_fix}")
print(f"Satellites : {gps.satellites}")
print(f"UTC Time   : {gps.utc_time}")

# -------------------------------------------------------
# 3. Query Parsed Geodetic Position & Satellite Telemetry
# -------------------------------------------------------
pos = gps.get_position()
print("\nPosition Snapshot:")
print(f"  Latitude    : {pos.get('latitude')}")
print(f"  Longitude   : {pos.get('longitude')}")
print(f"  Altitude    : {pos.get('altitude')} {pos.get('altitude_units', 'M')}")
print(f"  Speed       : {pos.get('speed_kmh')} km/h")
print(f"  Fix Quality : {pos.get('fix_quality')} (HDOP: {pos.get('hdop')})")
print(f"  UTC Datetime: {pos.get('datetime_utc')}")

print("\nSatellites in View:")
for sat in gps.get_satellites_in_view()[:8]:
    print(
        f"  PRN {sat['prn']:2d} | Elev: {str(sat['elevation_deg']):>5} deg | "
        f"Azim: {str(sat['azimuth_deg']):>5} deg | SNR: {sat['snr_db']} dB-Hz"
    )

gps.close()

Properties and Methods

Properties

The properties below report live receiver connectivity, 3D coordinates, dilution of precision, satellite lock, and UTC clock status on GpsModule.

Property Type Access Description & Range
connected bool R/O True if the serial NMEA stream to the physical GNSS receiver module is open and active.
port str R/O Host serial device path bound to the GPS receiver (e.g., '/dev/ttyACM0' or '/dev/ttyUSB0').
has_fix bool R/O True when the receiver currently holds a valid 2D/3D satellite navigation fix.
fix_quality int R/O GPS fix quality indicator (0 = No fix, 1 = GPS fix, 2 = DGPS fix).
latitude float or None R/O Current latitude in decimal degrees, or None if no valid fix.
longitude float or None R/O Current longitude in decimal degrees, or None if no valid fix.
lat_long tuple[float, float] or None R/O Current (latitude, longitude) tuple in decimal degrees, or None if no valid fix.
altitude float or None R/O Altitude in meters above mean sea level.
speed float R/O Ground speed in km/h.
satellites int R/O Number of GNSS satellites currently tracked / in view.
hdop / pdop / vdop float or None R/O Horizontal, Position (3D), and Vertical Dilution of Precision parsed from $GPGSA.
utc_time str or None R/O Latest satellite-derived UTC datetime string (YYYY-MM-DD HH:MM:SS).

Methods

The methods below poll parsed navigation fixes, per-satellite sky-plot telemetry, and raw NMEA 0183 sentences from the receiver.

Method Returns Description
get_position() dict Returns the latest parsed navigation state containing latitude, longitude, altitude, altitude_units ('M'), speed_kmh, satellites, has_fix, fix_quality, hdop, pdop, vdop, datetime_utc, and last_update_ts.
get_lat_long() tuple[float, float] or None Returns (latitude, longitude) in decimal degrees, or None if no valid fix is present.
get_satellites_in_view() list[dict] Returns parsed per-satellite telemetry from $GPGSV sentences, where each dict contains prn, elevation_deg, azimuth_deg, and snr_db (C/N0 in dB-Hz).
wait_for_fix(timeout=30.0) bool Blocks up to timeout seconds waiting for the receiver to acquire a valid satellite fix, returning True if a fix is present.
read_raw(count=5) list[str] Returns the most recent count raw ASCII NMEA 0183 sentences from the receiver buffer for diagnostic inspection.
reset() bool Clears cached coordinates, satellite state, and sentence buffers.
close() None Closes the client RPC session.

Tips and Tricks

1. Indoor vs. Rooftop Antenna Placement

Even when an indoor GPS antenna has partial sky visibility, gps.utc_time and gps.get_satellites_in_view() can often be read with 1–3 satellites before a full 4-satellite 3D position fix (has_fix == True) is achieved. Always check pos["has_fix"] before using latitude and longitude in geospatial calculations.

2. Dilution of Precision (DOP) and Sky Plots

You do not need to parse raw NMEA sentences to inspect constellation geometry or signal quality:

  • Check gps.hdop, gps.pdop, and gps.vdop (or the corresponding keys in gps.get_position()) to evaluate geometric dilution of precision (< 2.0 is excellent; > 5.0 indicates poor satellite geometry).
  • Call gps.get_satellites_in_view() to get each satellite’s PRN, elevation (0–90 deg), azimuth (0–359 deg), and carrier-to-noise ratio (snr_db in dB-Hz) directly as Python dictionaries for polar sky plots.