Skip to content

v1.16.4 - GNSS Timestamp Integration (2025-12-12)

What Changed?

This release adds high-precision GNSS timestamp (gnss_time_us) to all detection events. The new field contains microsecond-precision unix timestamps from the GNSS receiver, enabling accurate temporal correlation of cosmic ray detections with absolute time references. The feature is fully backward compatible with ENABLE_GNSS=0.

What's New

Main Feature: GNSS Timestamp in Detection Events

What it does: Adds gnss_time_us field to all cosmic ray detection events when ENABLE_GNSS=1. The field contains a unix timestamp (seconds since 1970-01-01 UTC) with microsecond precision derived from GNSS 1PPS signal or NMEA centisecond data, providing absolute temporal reference for event correlation across multiple detectors.

How to use it: The gnss_time_us field is automatically included in all detection event outputs in all supported formats (SSV, TSV, CSV, JSONL) when ENABLE_GNSS is enabled. No configuration changes required—the field appears first in the GNSS section of each event record.

Output example (JSONL):

{"hit1":95,"hit2":87,"hit3":91,"adc":2048,"gnss_time_us":1732046789000000,"gnss_latitude":37.3874,"gnss_longitude":121.9724,"gnss_altitude":45.9,"gnss_satellites":12,"gnss_fix_quality":1,"gnss_hdop":1.23,"gnss_fix_valid":1}

Output order (all formats): - SSV/TSV/CSV: hit1 hit2 hit3 adc ... detected_at gnss_time_us gnss_latitude gnss_longitude ... - JSONL: gnss_time_us appears first in GNSS section

Installation

Quick Start

# Get the release
git checkout v1.16.4

# Build
task dev:build

# Upload
task dev:upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • gnss_time_us field (uint64_t) to stream_data_t structure for GNSS timestamp storage
  • GNSS timestamp population in detection_process() via gnss_get_time_us()
  • gnss_time_us output in all stream formats (SSV, TSV, CSV, JSONL)

🔧 Changed

  • GNSS section field ordering: gnss_time_us now appears first before position fields
  • Output format updated to include gnss_time_us at start of GNSS data section

🐛 Fixed

  • Struct initializer order in main.cpp to match stream_data_t field declaration

Is It Safe to Upgrade?

Backward Compatible: Yes

  • Existing detection output remains unchanged when ENABLE_GNSS=0
  • When ENABLE_GNSS=1: New gnss_time_us field added to output; client parsers should skip or handle unknown fields gracefully
  • No changes to core detection logic, threshold control, or LED feedback
  • Fully tested with ENABLE_GNSS enabled and disabled

Tests Passed

  • ✅ Development build (esp32dev-dev) compiles without errors
  • ✅ Pre-commit hooks pass (trailing whitespace, file endings, merge conflicts)
  • ✅ RAM usage: 8.8% (28,948 / 327,680 bytes)
  • ✅ Flash usage: 26.6% (348,953 / 1,310,720 bytes)
  • ✅ All output formats (SSV/TSV/CSV/JSONL) include gnss_time_us when ENABLE_GNSS=1

Release Details

  • Date: 2025-12-12
  • Version: v1.16.4
  • Files Changed: 3 (stream_data.h, main.cpp, stream_formatter.cpp)
  • Commits: 3
  • feat(gnss): add gnss_time timestamp to detection event output
  • refactor(gnss): reorder gnss_time_us field to beginning of GNSS section
  • fix(gnss): correct struct initializer order in detection_process

Next Steps

  • Multi-detector event synchronization using gnss_time_us as common timeline
  • Extended GNSS data output (velocity, bearing, satellite details)
  • Time-series analysis tools for correlating cosmic ray events with GNSS signal quality
  • Integration with data pipeline systems that require absolute timestamps