Skip to content

v1.15.2 - GNSS State Monitoring (2025-12-12)

What Changed?

This release adds comprehensive GNSS module state monitoring capabilities. A new GET_GNSS_STATE command returns the current operational state (INITIALIZING, SEARCHING, FIXING, FIXED, or ERROR), and the existing GET_GNSS command now includes state information in its response. This enables client applications to accurately track GNSS receiver status and make state-dependent decisions.

What's New

New Command: GET_GNSS_STATE

What it does: Returns the current operational state of the GNSS receiver module as a single numeric value (0-4). Allows applications to determine the current phase of GNSS acquisition and fix operation.

How to use it: Send the command GET_GNSS_STATE (no arguments) via serial text protocol:

GET_GNSS_STATE

State Values:

  • 0 = INITIALIZING - Module booting, parser initializing (0-2 seconds)
  • 1 = SEARCHING - Actively acquiring satellites, no valid fix yet
  • 2 = FIXING - Valid position acquired, refining accuracy
  • 3 = FIXED - Valid 3D fix with ≥4 satellites, reliable position/time
  • 4 = ERROR - UART timeout, checksum failure, or communication error

Response Example:

{"type":"response","status":"ok","sent_at":1732046789,"state":3}

Enhanced Command: GET_GNSS

What changed: The GET_GNSS command now includes the GNSS module state in its comprehensive response. Previously returned: position, time, satellite count, quality, validity, and HDOP. Now also includes the current operational state for complete status visibility in a single query.

Response Example (now includes state):

{
  "type":"response",
  "status":"ok",
  "sent_at":1732046789,
  "latitude":35.1234,
  "longitude":137.5678,
  "altitude":100.5,
  "gnss_time":1732046789,
  "satellites":12,
  "quality":1,
  "valid":true,
  "hdop":2.5,
  "state":3
}

Installation

Quick Start

# Get the release
git checkout vX.Y.Z

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • GET_GNSS_STATE command - Query GNSS module operational state (0-4)
  • state field in GET_GNSS response - Complete status in single query
  • get_gnss_state() method in Command class - Access state from application code

🔧 Changed

  • GET_GNSS response format now includes state field (backward compatible JSON addition)

Is It Safe to Upgrade?

Backward Compatible: Yes

  • Existing GET_GNSS responses remain valid - new state field is additive
  • No breaking changes to command behavior or existing response fields
  • New GET_GNSS_STATE command is purely additive, no impact on existing code
  • Works with ENABLE_GNSS=1 and ENABLE_DEVICE_RESPONSE=1 (standard development build)

Tests Passed

  • ✅ Builds without errors (RAM 8.8%, Flash 26.6%)
  • ✅ All pre-commit hooks passed
  • ✅ GET_GNSS_STATE command registration verified
  • ✅ GET_GNSS response payload includes state field

Release Details

  • Date: 2025-12-12
  • Version: v1.15.2
  • Files Changed: 6
  • include/command.h (added get_gnss_state() method declaration)
  • src/command.cpp (implemented get_gnss_state() method)
  • src/command/gnss.cpp (added handle_get_gnss_state() handler, updated GET_GNSS)
  • src/command_manager.cpp (registered GET_GNSS_STATE in dispatch table)
  • docs/releases/v1.15.2.md (release notes)
  • uv.lock (dependency updates)

Next Steps

Future enhancements may include:

  • State change notifications/callbacks for real-time state monitoring
  • Historical state tracking for troubleshooting
  • Integration with WiFi and cloud logging for remote GNSS diagnostics
  • Extended state enumerations for fine-grained troubleshooting