MojoScale Studio Docs
API Reference

gps

UART GNSS receiver module.

All modules Open Studio
Studio Docs Sensors & I/O

import gps

The gps module reads standard NMEA sentences from GPS and multi-constellation GNSS receivers over UART. It validates checksums in native code and keeps the latest complete navigation fix.

Quick example

import gps
import system

receiver = gps.GPS(uart=1, rx=16, tx=17)
receiver.begin()

def show_location():
    fix = receiver.read(timeout_ms=1000)
    if fix == None:
        print("Waiting for GPS fix")
        return
    print(fix["latitude"], fix["longitude"])

system.schedule("gps", 1000, 0, -1, show_location)

import gps
import mojoscale_messaging

receiver = gps.GPS(uart=1, rx=16)
location_channel = mojoscale_messaging.channel("location")

def send_location(fix):
    location_channel.send({
        "latitude": fix["latitude"],
        "longitude": fix["longitude"],
        "speed_kmph": fix["speed_kmph"],
    })

receiver.begin()
receiver.on_fix(send_location)

importgps

UART GNSS receiver module.

The gps module reads standard NMEA sentences from GPS and multi-constellation GNSS receivers over UART. It validates checksums in native code and keeps the latest complete navigation fix.

API 22 available

gps.GPS(rx: int, uart: int = None, tx: int = None, baud: int = None, update_rate_hz: int = None, buffer_size: int = None) -> gps_receiver

Create a UART GNSS receiver object.

Creating the object does not start the UART receiver. Call ``begin()`` before reading location data. The module accepts standard NMEA output from common u-blox, ATGM, Quectel, MediaTek, and similar GNSS receivers.

Parameters
Name Type Pass as Required Description
rx int positional or keyword Yes Required GPIO receiving data from the GNSS module TX pin.
uart int positional or keyword No Optional UART port number. Defaults to 1.
tx int positional or keyword No Optional GPIO transmitting data to the GNSS module RX pin.
baud int positional or keyword No Optional UART baud rate. Defaults to 9600.
update_rate_hz int positional or keyword No Optional expected navigation update rate. Defaults to 1.
buffer_size int positional or keyword No Optional native receive-buffer size. Defaults to 1024.
Returns

gps_receiver gps_receiver object.

gps.GPS().begin() -> bool

Start the UART receiver and NMEA parser.

gps.GPS().stop() -> bool

Stop parsing and release the UART driver owned by this receiver.

gps.GPS().is_running() -> bool

Return whether the receiver task is active.

gps.GPS().read(timeout_ms=0) -> dict

Return the newest fresh fix, or None when no fix is available before the timeout.

Parameters
Name Type Pass as Required Description
timeout_ms int positional or keyword No Optional value. Defaults to 0.

gps.GPS().latest() -> dict

Return the latest parsed fix, even if stale, or None if no fix has ever been received.

gps.GPS().has_fix(max_age_ms=3000) -> bool

Return whether a valid recent location fix is available.

Parameters
Name Type Pass as Required Description
max_age_ms int positional or keyword No Optional value. Defaults to 3000.

gps.GPS().fix_age_ms() -> int

Return milliseconds since the latest valid fix, or None before the first fix.

gps.GPS().latitude() -> float

Return signed decimal latitude, or None when no recent fix is available.

gps.GPS().longitude() -> float

Return signed decimal longitude, or None when no recent fix is available.

gps.GPS().location() -> dict

Return latitude, longitude, and age_ms, or None when no recent fix is available.

gps.GPS().altitude_m() -> float

Return altitude above mean sea level in meters, or None when unavailable.

gps.GPS().speed_kmph() -> float

Return ground speed in kilometers per hour, or None when unavailable.

gps.GPS().speed_mps() -> float

Return ground speed in meters per second, or None when unavailable.

gps.GPS().course_deg() -> float

Return course over ground in degrees, or None when unavailable.

gps.GPS().satellites() -> int

Return the number of satellites used in the current fix, or None when unavailable.

gps.GPS().hdop() -> float

Return horizontal dilution of precision, or None when unavailable.

gps.GPS().utc() -> dict

Return UTC date/time fields, or None before GNSS time is available.

gps.GPS().stats() -> dict

Return bytes_received, sentences_received, sentences_valid, checksum_errors, malformed_sentences, overflow_errors, fixes_received, last_sentence_age_ms, and running.

gps.GPS().configure(stale_after_ms=3000, minimum_satellites=0, maximum_hdop=0.0) -> bool

Set freshness and fix-quality filters.

Parameters
Name Type Pass as Required Description
stale_after_ms int positional or keyword No Optional value. Defaults to 3000.
minimum_satellites int positional or keyword No Optional value. Defaults to 0.
maximum_hdop float positional or keyword No Optional value. Defaults to 0.0.

gps.GPS().on_fix(callback) -> bool

Register a callback receiving the same fix dict returned by read(). Pass None to clear it.

Parameters
Name Type Pass as Required Description
callback callback positional or keyword Yes Required value.

gps.GPS().on_fix_lost(callback) -> bool

Register a callback called once when the latest fix becomes stale. Pass None to clear it.

Parameters
Name Type Pass as Required Description
callback callback positional or keyword Yes Required value.