C API

Updated on Apr 8, 2026

Include <jimmypaputto/GnssHat.h>. All functions are prefixed with jp_gnss_hat_ (lifecycle/navigation) or jp_gnss_ (config helpers, string converters).

Lifecycle

jp_gnss_hat_t* hat = jp_gnss_hat_create();
// ... use hat ...
jp_gnss_hat_destroy(hat);

Function	Return	Description
`jp_gnss_hat_create(void)`	`jp_gnss_hat_t*`	Create GNSS HAT instance. Auto-detects HAT variant
`jp_gnss_hat_destroy(jp_gnss_hat_t* hat)`	`void`	Destroy instance and free resources
`jp_gnss_hat_name(jp_gnss_hat_t* hat)`	`const char*`	Get detected HAT name
`jp_gnss_hat_start(jp_gnss_hat_t* hat, const jp_gnss_gnss_config_t* config)`	`bool`	Configure module and start acquisition

Function	Return	Description
`jp_gnss_hat_wait_and_get_fresh_navigation(hat, nav)`	`bool`	Block until new data, write to `nav`. Returns `false` on error
`jp_gnss_hat_get_navigation(hat, nav)`	`bool`	Get last known data immediately (non-blocking)

Reset

Function	Return	Description
`jp_gnss_hat_hard_reset_cold_start(hat)`	`void`	Full cold reset
`jp_gnss_hat_soft_reset_hot_start(hat)`	`void`	Soft reset preserving almanac/ephemeris

Timepulse

Function	Return	Description
`jp_gnss_hat_enable_timepulse(hat)`	`bool`	Enable timepulse on GPIO 5
`jp_gnss_hat_disable_timepulse(hat)`	`void`	Disable timepulse
`jp_gnss_hat_timepulse(hat)`	`void`	Block until next timepulse

GPSD Forwarding

Function	Return	Description
`jp_gnss_hat_start_forward_for_gpsd(hat)`	`bool`	Start NMEA forwarding to virtual TTY
`jp_gnss_hat_stop_forward_for_gpsd(hat)`	`void`	Stop forwarding
`jp_gnss_hat_join_forward_for_gpsd(hat)`	`void`	Block until forwarder exits
`jp_gnss_hat_get_gpsd_device_path(hat)`	`const char*`	Virtual serial port path

Time Mark

Function	Return	Description
`jp_gnss_hat_get_time_mark(hat, tm)`	`bool`	Get last time mark (non-blocking)
`jp_gnss_hat_wait_and_get_fresh_time_mark(hat, tm)`	`bool`	Block until new time mark event
`jp_gnss_hat_enable_time_mark_trigger(hat)`	`bool`	Enable EXTINT as output
`jp_gnss_hat_disable_time_mark_trigger(hat)`	`void`	Disable EXTINT trigger
`jp_gnss_hat_trigger_time_mark(hat, edge)`	`void`	Toggle/raise/lower EXTINT

Configuration

Function	Return	Description
`jp_gnss_gnss_config_init(config)`	`void`	Initialize config struct with defaults
`jp_gnss_gnss_config_add_geofence(config, geofence)`	`bool`	Add a geofence (max 4). Returns `false` if full

RTK

Function	Return	Description
`jp_gnss_rtk_get_full_corrections(hat)`	`jp_gnss_rtk_corrections_t*`	Full RTCM3 correction set (M7M)
`jp_gnss_rtk_get_tiny_corrections(hat)`	`jp_gnss_rtk_corrections_t*`	Compact RTCM3 correction set (M4M)
`jp_gnss_rtk_get_rtcm3_frame(hat, id)`	`jp_gnss_rtcm3_frame_t*`	Specific RTCM3 message by ID
`jp_gnss_rtk_apply_corrections(hat, frames, count)`	`bool`	Send corrections to rover
`jp_gnss_rtk_corrections_free(corrections)`	`void`	Free corrections memory
`jp_gnss_rtcm3_frame_free(frame)`	`void`	Free single frame memory

Note
Memory Management — RTK correction functions allocate memory. Always free with jp_gnss_rtk_corrections_free() or jp_gnss_rtcm3_frame_free() after use.

String Converters

All return const char* — static strings, do not free.

Function	Input Type
`jp_gnss_fix_quality_to_string`	`jp_gnss_fix_quality_t`
`jp_gnss_fix_status_to_string`	`jp_gnss_fix_status_t`
`jp_gnss_fix_type_to_string`	`jp_gnss_fix_type_t`
`jp_gnss_jamming_state_to_string`	`jp_gnss_jamming_state_t`
`jp_gnss_antenna_status_to_string`	`jp_gnss_antenna_status_t`
`jp_gnss_antenna_power_to_string`	`jp_gnss_antenna_power_t`
`jp_gnss_rf_band_to_string`	`jp_gnss_rf_band_t`
`jp_gnss_geofencing_status_to_string`	`jp_gnss_geofencing_status_t`
`jp_gnss_geofence_status_to_string`	`jp_gnss_geofence_status_t`
`jp_gnss_gnss_id_to_string`	`jp_gnss_gnss_id_t`
`jp_gnss_sv_quality_to_string`	`jp_gnss_sv_quality_t`
`jp_gnss_time_mark_mode_to_string`	`jp_gnss_time_mark_mode_t`
`jp_gnss_time_mark_run_to_string`	`jp_gnss_time_mark_run_t`
`jp_gnss_time_mark_time_base_to_string`	`jp_gnss_time_mark_time_base_t`
`jp_gnss_utc_time_iso8601`	`const jp_gnss_position_velocity_time_t*`

Key Structs

jp_gnss_navigation_t

Field	Type
`pvt`	`jp_gnss_position_velocity_time_t`
`dop`	`jp_gnss_dilution_over_precision_t`
`geofencing`	`jp_gnss_geofencing_t`
`rf_blocks[UBLOX_MAX_RF_BLOCKS]`	`jp_gnss_rf_block_t`
`rf_block_count`	`uint8_t`
`satellites[UBLOX_MAX_SATELLITES]`	`jp_gnss_satellite_info_t`
`satellite_count`	`uint8_t`

See Navigation Data for detailed field documentation.

Constants

Constant	Value	Description
`UBLOX_MAX_GEOFENCES`	4	Maximum geofence zones
`UBLOX_MAX_RF_BLOCKS`	2	Maximum RF blocks (bands)
`UBLOX_MAX_SATELLITES`	64	Maximum tracked satellites
`UBLOX_SPECTRUM_BINS`	256	Spectrum data bins per RF block