Skip to content

v1.11.0 - GNSS Integration Complete (2025-12-06)

What Changed?

This release adds complete GNSS (Global Navigation Satellite System) integration to OSECHI, enabling real-time satellite positioning and time synchronization. The GT502MGG GNSS receiver connects via UART2 and provides latitude, longitude, altitude, satellite count, and unix timestamps that are automatically included in all cosmic ray detection events. All new GNSS features are accessible via text commands and maintain full backward compatibility with existing features.

What's New

Main Feature: GNSS Module with Automatic Geotagging

What it does: The new GNSS manager module handles GT502MGG GNSS receiver communication via UART2. It parses NMEA sentences, maintains a state machine (INITIALIZING → SEARCHING → FIXED), and automatically includes location data and unix timestamps in every cosmic ray detection event. The module runs non-blocking with ~100ms polling intervals to ensure detection responsiveness.

How to use it: Simply enable GNSS in the build flags (-DENABLE_GNSS=1), and the module initializes automatically. Use text commands to monitor status: - GET_GNSS_STATUS - Query current satellite count and fix quality - GET_GNSS_POSITION - Get current latitude, longitude, altitude - GET_GNSS_TIME - Query device time synchronized from GPS - SYNC_TIME <unix_timestamp> - Manually set device time

Code example:

// GNSS is automatically integrated in main loop
void gnss_update() {
  // Non-blocking UART read and NMEA parsing
  while (Serial2.available()) {
    char c = Serial2.read();
    if (gps.encode(c)) {
      // Valid NMEA sentence received
      g_gnss_data.latitude = gps.location.lat();
      g_gnss_data.longitude = gps.location.lng();
    }
  }
}

// Detection events automatically include GNSS data
event_t event = {
  .hit1 = 85, .hit2 = 92, .hit3 = 78,
  .latitude = 35.6892,
  .longitude = 139.6917,
  .altitude = 45.3f,
  .satellites = 12,
  .unix_timestamp = 1733561234
};

Secondary Feature: Time Synchronization

What it does: The GNSS time synchronization feature enables your detector to maintain accurate unix timestamps (seconds since 1970-01-01 UTC) by syncing with GPS satellites. This is essential for correlating cosmic ray events across multiple detectors or with external data sources (weather, seismic, etc.). Timestamps persist across power cycles using ESP32's internal RTC backup domain.

How to use it: When GPS fix is acquired with valid time, the device automatically updates its internal clock. Or manually set time with: 

SET_TIME 1733561234

Installation

Quick Start

# Get the release
git checkout 1.11.0

# Build (requires ENABLE_RTC=1 and ENABLE_GNSS=1)
task build

# Upload
task upload

# Check it works
task monitor

Build Requirements:

  • ENABLE_RTC=1 - Real-time clock for unix timestamp persistence
  • ENABLE_GNSS=1 - GNSS module support for positioning and time synchronization

Both flags are enabled by default in the esp32dev-dev and esp32dev-wifi build profiles.

Hardware Setup

Connect GT502MGG GNSS receiver to ESP32:

  • RX (GNSS) → GPIO16 (ESP32)
  • TX (GNSS) → GPIO17 (ESP32)
  • GND → GND
  • VCC → 5V (with LDO regulator to 3.3V if needed)

What's Different from the Last Version?

✅ Added

  • Complete GNSS module with state machine (INITIALIZING → SEARCHING → FIXED → ERROR)
  • Automatic geotagging of detection events (latitude, longitude, altitude)
  • Satellite count and fix quality in output
  • GNSS text commands: GET_GNSS_STATUS, GET_GNSS_POSITION, GET_GNSS_TIME, SYNC_TIME
  • TinyGPS++ library integration for NMEA parsing
  • Unix timestamp synchronization via GPS
  • GNSS data in all stream formats (SSV, TSV, CSV, JSONL)
  • Comprehensive GNSS specification documentation (1,494 lines)
  • Non-blocking GNSS polling (~100ms) to preserve detection responsiveness

🔧 Changed

  • Updated stream_data_t to include GNSS fields (latitude, longitude, altitude, satellites)
  • Updated all stream formatters to output GNSS data
  • Added GNSS configuration to config.h (pins, baud rate, timeouts)

🐛 Fixed

  • Fixed TinyGPS++ library reference in platformio.ini (mikalhart/TinyGPSPlus instead of TinyGPS++)
  • Replaced non-portable timegm() with mktime() + setenv("TZ", "UTC0") for macOS ARM64 compatibility
  • Enabled GNSS in development build profile

Is It Safe to Upgrade?

Backward Compatible: Yes ✅

  • GNSS module is optional and disabled by default in production builds
  • When ENABLE_GNSS=0 (production), all GNSS code is compile-time excluded (zero overhead)
  • Stream data format remains compatible - GNSS fields only appear when enabled
  • All existing text commands work unchanged
  • No breaking changes to API or configuration

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)
  • ✅ RAM usage: 8.8% (28,764 / 327,680 bytes)
  • ✅ Flash usage: 26.5% (347,325 / 1,310,720 bytes)
  • ✅ GNSS UART2 communication at 9600 baud verified
  • ✅ NMEA sentence parsing with TinyGPS++ confirmed

Release Details

  • Date: 2025-12-06
  • Version: 1.11.0
  • Files Changed: 67 files (3,496 insertions, 633 deletions)
  • Commits: 36 commits since v1.10.8
  • Build Profiles: 3 (esp32dev-release, esp32dev-dev, esp32dev-wifi)

Next Steps

Phase 8: GNSS Advanced Features

  • Multi-detector GNSS synchronization protocol
  • GNSS event logging to SD card
  • Kalman filtering for position smoothing
  • GNSS almanac pre-loading for faster initial fix
  • Integration with WiFi AP interface for remote location monitoring

See REFACTORING_ROADMAP.md for detailed implementation plan.