Skip to content

v1.11.1 - GNSS Debug Output & Status Enhancements (2025-12-06)

What Changed?

This patch release improves GNSS debugging and monitoring capabilities. The GNSS receiver status is now included in the GET_STATUS command, and debug output always shows GNSS fields even during satellite acquisition, making it easier to troubleshoot receiver initialization.

What's New

Enhancement: GNSS Feature Status in GET_STATUS

What it does: The GET_STATUS response now includes a gnss feature flag indicating whether GNSS compilation is enabled in the current build. This allows tools and scripts to detect GNSS capability at runtime.

Example response: 

{
  "type": "response",
  "status": "ok",
  "system": {
    "version": "1.11.1",
    "uptime_ms": 17571,
    "adc_channel": 1
  },
  "detection": {
    "poll_count": 100,
    "deadtime_ms": 0,
    "threshold1": 0,
    "threshold2": 0,
    "threshold3": 0
  },
  "features": {
    "bme280": 1,
    "gnss": 1,
    "rtc": 1,
    "timestamp": 1,
    "wifi": 0,
    "queue": 1,
    "gpio_abstraction": 1,
    "adcmv": 1
  }
}

Improvement: Always-On GNSS Debug Output

What it does: Previously, GNSS fields (latitude, longitude, altitude, satellites, fix_quality, hdop) were only output when a valid satellite fix was acquired. This created ambiguity during receiver initialization — developers couldn't tell if the module was working but searching for satellites, or if it was broken.

Now, GNSS fields are always output in sensor data streams, with a gnss_fix_valid flag indicating receiver status: - gnss_fix_valid=0: Receiver is initializing or searching for satellites (normal during cold start) - gnss_fix_valid=1: Receiver has acquired a valid satellite fix

Output format (SSV example): 

100 100 100 2048 25.35 1013.25 45.67 12345 9876 0.000000 0.000000 0.000000 0 0 0.0 0

Where the last 7 fields are (in order): 1. latitude (decimal degrees) 2. longitude (decimal degrees) 3. altitude (meters) 4. satellites (count in use) 5. fix_quality (0-3, quality indicator) 6. hdop (horizontal dilution of precision) 7. gnss_fix_valid (0=searching, 1=fixed)

This consistent field count makes it easier to parse data and understand receiver state at any point in the initialization timeline.

Why This Matters for Development

Problem: When testing GNSS receiver initialization, developers would see no GNSS fields in the output if the receiver hadn't acquired satellites yet. This made it impossible to distinguish between: - Receiver working but still acquiring satellites (takes 30-60 seconds on cold start) - Receiver broken or not communicating

Solution: By always outputting GNSS fields with gnss_fix_valid=0 during initialization, developers can now: 1. See that the GNSS module is operational and processing data 2. Monitor the exact moment satellites are acquired (when gnss_fix_valid transitions 0→1) 3. Verify UART communication and NMEA parsing is working 4. Diagnose hardware issues more easily

Installation

Quick Start

# Get the release
git checkout 1.11.1

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from v1.11.0?

✅ Added

  • gnss feature flag in GET_STATUS response indicating GNSS compilation status
  • gnss_fix_valid flag in all sensor data outputs (0=searching, 1=fixed) for debugging receiver state

🔧 Changed

  • GNSS data is now always output regardless of fix validity (previously gated by gnss_fix_valid check)
  • All GNSS fields maintain consistent column positions in SSV/TSV/CSV output for easier parsing

🐛 Fixed

  • GNSS debug output now visible during receiver initialization phase (cold start)
  • GET_STATUS response now accurately reflects GNSS feature compilation status

Is It Safe to Upgrade?

Backward Compatible: Yes ✅

  • Output format change is backward compatible: GNSS fields were previously output when fix was valid, now they're always output (with validity flag)
  • GET_STATUS response adds new gnss feature flag (additive, no breaking changes)
  • All existing commands and functionality remain unchanged
  • No changes to stream format configuration or build profiles

Tests Passed

  • ✅ Builds without errors on esp32dev-release, esp32dev-dev, esp32dev-wifi
  • ✅ Builds without errors on macOS ARM64 architecture
  • ✅ Pre-commit hooks pass (trailing whitespace, YAML, JSON validation)
  • ✅ GET_STATUS response includes gnss feature flag
  • ✅ SSV output shows all GNSS fields + gnss_fix_valid during cold start
  • ✅ GNSS state machine transitions (SEARCHING→FIXED) confirmed visible in output

Release Details

  • Date: 2025-12-06
  • Version: 1.11.1
  • Files Changed: 3 files (88 insertions, 14 deletions)
  • Commits: 3 commits since v1.11.0
  • Build Profiles: 3 (esp32dev-release, esp32dev-dev, esp32dev-wifi)
  • Patch Type: Bug fixes + debugging enhancements (no new features affecting production use)

Development Notes

Changes Made

  1. text_command_manager.cpp: Added "gnss": ENABLE_GNSS to GET_STATUS features dictionary
  2. stream_formatter.cpp: Removed conditional guard on GNSS field output; now always outputs all fields
  3. docs/progress/: Added progress entry documenting GNSS debug output changes

For Developers Using GNSS

  • Monitor the gnss_fix_valid field in your output parser to detect when satellites are acquired
  • Cold start (first power-on): Expect 30-60 seconds of gnss_fix_valid=0 before first fix
  • Hot start (power-on after recent use): Expect 5-10 seconds with cached almanac
  • Check GET_STATUS response to confirm GNSS is compiled in: "gnss": 1

Next Steps

Phase 8: GNSS Advanced Features

  • Kalman filtering for position smoothing (reduce jitter during fix)
  • GNSS event logging to SD card for post-processing
  • GNSS almanac pre-loading for faster hot-start
  • Multi-detector GNSS synchronization protocol
  • Integration with WiFi AP interface for remote location monitoring

See REFACTORING_ROADMAP.md for detailed implementation plan.