Python API

from jimmypaputto import gnsshat

GnssHat Class

hat = gnsshat.GnssHat()
# or as context manager:
with gnsshat.GnssHat() as hat:
    ...

The context manager automatically stops GPSD forwarding and disables timepulse on exit.

Methods

Method	Return	Description
`start(config)`	`bool`	Configure and start the GNSS module
`wait_and_get_fresh_navigation()`	`Navigation`	Block until new data arrives. Releases GIL
`get_navigation()`	`Navigation`	Get current data (non-blocking)
`name()`	`str`	Detected HAT name
`soft_reset_hot_start()`	`None`	Soft reset — preserves almanac/ephemeris
`hard_reset_cold_start()`	`None`	Full cold reset
`enable_timepulse()`	`None`	Enable 1PPS output on GPIO 5
`disable_timepulse()`	`None`	Disable 1PPS output
`timepulse()`	`None`	Block until next PPS. Releases GIL
`start_forward_for_gpsd()`	`None`	Start NMEA forwarding to virtual TTY
`stop_forward_for_gpsd()`	`None`	Stop NMEA forwarding
`join_forward_for_gpsd()`	`None`	Block until forwarding thread exits. Releases GIL
`get_gpsd_device_path()`	`str` or `None`	Virtual TTY path, or `None` if not active
`get_time_mark()`	`TimeMark` or `None`	Get last time mark (non-blocking)
`wait_and_get_fresh_time_mark()`	`TimeMark`	Block until new time mark. Releases GIL
`enable_time_mark_trigger()`	`None`	Enable EXTINT pin as output
`disable_time_mark_trigger()`	`None`	Disable EXTINT trigger
`trigger_time_mark(edge=TOGGLE)`	`None`	Trigger a time mark event
`rtk_get_full_corrections()`	`list[bytes]`	Full RTCM3 corrections from base
`rtk_get_tiny_corrections()`	`list[bytes]`	Compact RTCM3 corrections from base
`rtk_get_rtcm3_frame(msg_id)`	`bytes`	Specific RTCM3 frame by ID
`rtk_apply_corrections(frames)`	`None`	Send RTCM3 corrections to rover

Configuration Dict

The start() method accepts a Python dict. Required fields: measurement_rate_hz, dynamic_model, timepulse_pin_config.

config = {
    'measurement_rate_hz': 10,
    'dynamic_model': gnsshat.DynamicModel.AUTOMOTIVE,
    'timepulse_pin_config': {
        'active': True,
        'fixed_pulse': {'frequency': 1, 'pulse_width': 0.1},
        'pulse_when_no_fix': {'frequency': 1, 'pulse_width': 0.5},
        'polarity': gnsshat.TimepulsePolarity.RISING_EDGE
    },
    'geofencing': {
        'confidence_level': 3,
        'pin_polarity': gnsshat.PioPinPolarity.LOW_MEANS_INSIDE,
        'geofences': [
            {'lat': 52.2297, 'lon': 21.0122, 'radius': 100.0},
        ]
    },
    'rtk': {
        'mode': gnsshat.RtkMode.BASE,
        'base': {
            'base_mode': gnsshat.BaseMode.SURVEY_IN,
            'survey_in': {
                'minimum_observation_time_s': 60,
                'required_position_accuracy_m': 2.0
            }
        }
    },
    'timing': {
        'enable_time_mark': True,
        'time_base': {
            'base_mode': gnsshat.BaseMode.SURVEY_IN,
            'survey_in': {
                'minimum_observation_time_s': 60,
                'required_position_accuracy_m': 5.0
            }
        }
    }
}

Module Functions

Function	Return	Description
`gnsshat.version()`	`str`	Library version (e.g. `'1.0.0'`)
`gnsshat.utc_time_iso8601(nav)`	`str`	Convert Navigation or PVT to ISO 8601 string

Constants

Constant	Value
`gnsshat.MAX_GEOFENCES`	4
`gnsshat.MAX_RF_BLOCKS`	2
`gnsshat.MAX_SATELLITES`	64

Enums

All enums are IntEnum types: gnsshat.<EnumName>.<MEMBER>.

Enum	Members
`DynamicModel`	`PORTABLE`, `STATIONARY`, `PEDESTRIAN`, `AUTOMOTIVE`, `SEA`, `AIRBORNE_1G/2G/4G`, `WRIST`, `BIKE`, `MOWER`, `ESCOOTER`
`TimepulsePolarity`	`FALLING_EDGE`, `RISING_EDGE`
`PioPinPolarity`	`LOW_MEANS_INSIDE`, `LOW_MEANS_OUTSIDE`
`FixQuality`	`INVALID`, `GPS_FIX_2D_3D`, `DGNSS`, `PPS_FIX`, `FIXED_RTK`, `FLOAT_RTK`, `DEAD_RECKONING`
`FixStatus`	`VOID`, `ACTIVE`
`FixType`	`NO_FIX`, `DEAD_RECKONING_ONLY`, `FIX_2D`, `FIX_3D`, `GNSS_WITH_DEAD_RECKONING`, `TIME_ONLY_FIX`
`GeofenceStatus`	`UNKNOWN`, `INSIDE`, `OUTSIDE`
`GeofencingStatus`	`NOT_AVAILABLE`, `ACTIVE`
`RfBand`	`L1`, `L2_OR_L5`
`JammingState`	`UNKNOWN`, `OK_NO_SIGNIFICANT_JAMMING`, `WARNING_...`, `CRITICAL_...`
`AntennaStatus`	`INIT`, `DONT_KNOW`, `OK`, `SHORT`, `OPEN`
`AntennaPower`	`OFF`, `ON`, `DONT_KNOW`
`RtkMode`	`BASE`, `ROVER`
`BaseMode`	`SURVEY_IN`, `FIXED_POSITION`
`FixedPositionType`	`ECEF`, `LLA`
`GnssId`	`GPS`, `SBAS`, `GALILEO`, `BEIDOU`, `IMES`, `QZSS`, `GLONASS`
`SvQuality`	`NO_SIGNAL` through `CODE_AND_CARRIER_LOCKED_3`
`TimeMarkMode`	`SINGLE`, `RUNNING`
`TimeMarkRun`	`ARMED`, `STOPPED`
`TimeMarkTimeBase`	`RECEIVER`, `GNSS`, `UTC`
`TimeMarkTriggerEdge`	`RISING`, `FALLING`, `TOGGLE`

nav = hat.wait_and_get_fresh_navigation()

# Position
nav.pvt.latitude        # float, degrees
nav.pvt.longitude       # float, degrees
nav.pvt.altitude        # float, meters (WGS84)
nav.pvt.altitude_msl    # float, meters (MSL)

# Fix info
nav.pvt.fix_quality     # int (FixQuality enum)
nav.pvt.fix_type        # int (FixType enum)
nav.pvt.visible_satellites  # int

# Accuracy
nav.pvt.horizontal_accuracy  # float, meters
nav.pvt.vertical_accuracy    # float, meters

# Time
nav.pvt.utc_time.hours       # int
nav.pvt.utc_time.minutes     # int
nav.pvt.utc_time.seconds     # int

# Satellites
for sat in nav.satellites:
    sat.gnss_id, sat.sv_id, sat.cno, sat.used_in_fix

# RF blocks
for rf in nav.rf_blocks:
    rf.jamming_state, rf.antenna_status