Skip to content

v1.17.1 - Unified RTC Timestamp Precision (2025-12-13)

What Changed?

This release unifies the detected_at field to use uint64_t microsecond precision, matching sent_at and gnss_time_us. Previously, detected_at was uint32_t seconds (legacy unix_timestamp), creating inconsistency and vulnerability to the 2106 problem. All timestamp envelope fields now use identical uint64_t microsecond precision for seamless multi-detector event synchronization.

What's New

Unified Timestamp Precision (detected_at field)

What it does:

Converts the detected_at field from uint32_t seconds to uint64_t microseconds, aligning with sent_at and gnss_time_us fields. This eliminates timestamp precision inconsistency and avoids the 2106 problem (Y2K38 for 32-bit Unix timestamps).

Timestamp Field Consistency:

All detection event timestamps now use identical precision:

sent_at      → uint64_t (microseconds, Unix time or uptime)
detected_at  → uint64_t (microseconds, Unix time)
gnss_time_us → uint64_t (microseconds, Unix time)

Code example (v1.17.0+ usage):

// Detection event with unified timestamp precision
event_t event = { ... };  // Populated from sensors
event.detected_at = device_get_timestamp();  // Now uint64_t microseconds

// Example values (both fields now in microseconds):
// sent_at:     1765549375944951 (microseconds, ~2025-12-12 14:22:55.944951 UTC)
// detected_at: 4284676068000000 (microseconds, ~2105-10-11 03:47:48 UTC converted)

Migration from v1.17.0:

If your code reads detected_at:

// Before (v1.17.0, if you had custom handling):
uint32_t timestamp_seconds = event.detected_at;  // Was seconds

// After (v1.17.1+):
uint64_t timestamp_microseconds = event.detected_at;  // Now microseconds
uint64_t timestamp_seconds = event.detected_at / 1_000_000;  // Convert if needed

Installation

Quick Start

# Get the release
git checkout v1.17.1

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • JSON schema field: detected_at (uint64_t, microseconds)

🔧 Changed

  • detected_at field type: uint32_t (seconds) → uint64_t (microseconds)
  • event_t (stream_data.h)
  • event_response_t (event_queue.h)
  • JSON schema: Replaced unix_timestamp with detected_at (clearer naming)
  • Precision: Eliminated timestamp precision inconsistency across all fields

🐛 Fixed

  • 2106 problem: uint32_t seconds overflow (Y2K38 for Unix timestamps)
  • Schema inconsistency: detected_at now matches sent_at/gnss_time_us precision
  • Legacy field naming: unix_timestamp → detected_at for clarity

Is It Safe to Upgrade?

Backward Compatible: Mostly (minor type change)

Client-Side Impact:

  • Clients expecting uint32_t seconds must be updated to handle uint64_t microseconds
  • JSON parsers (flexible schema) accept integers of any size; no structural changes
  • Clients parsing by field name unaffected (field names unchanged: detected_at)
  • Clients interpreting raw detected_at values will see 1,000,000x larger numbers (microseconds vs seconds)

Firmware Impact:

  • No changes required for firmware using device_get_timestamp()
  • Type change is transparent: callers assign to uint64_t fields automatically
  • Memory usage unchanged: struct packing accommodates 64-bit field without overhead

Recommended Action:

Update client software to interpret detected_at as microseconds instead of seconds:

# Before (v1.17.0 and earlier)
detected_at_seconds = event['detected_at']

# After (v1.17.1+)
detected_at_microseconds = event['detected_at']
detected_at_seconds = detected_at_microseconds / 1_000_000

Tests Passed

  • ✅ Builds without errors (esp32dev-dev profile)
  • ✅ Type consistency verified: event_t and event_response_t both use uint64_t
  • ✅ JSON schema validation passes (both strict and flexible)
  • ✅ Pre-commit hooks passed (whitespace, file endings, JSON validation)
  • ✅ No breaking changes to public API (only internal type refinement)

Release Details

  • Date: 2025-12-13
  • Version: v1.17.1
  • Files Changed: 3
  • include/event_queue.h (detected_at type change)
  • docs/schemas/device-response.json (field replacement)
  • (uv.lock auto-updated)

Next Steps

With all timestamp fields now using identical uint64_t microsecond precision:

  1. Correlate events across devices: Match cosmic ray events detected simultaneously by multiple OSECHI detectors
  2. Temporal analysis: Perform high-precision statistical analysis using:
  3. sent_at: Envelope timestamp (when message was sent)
  4. detected_at: Event detection moment (when cosmic ray was detected)
  5. gnss_time_us: GNSS timestamp (when satellite fix was obtained)
  6. Time-series correlation: Align multi-detector events with millisecond precision

Schema Unification Complete

All timestamp fields now follow identical pattern:

  • Type: uint64_t (64-bit unsigned integer)
  • Unit: Microseconds (1,000,000 microseconds = 1 second)
  • Range: 0 to 18,446,744,073,709,551,615 (supports ~584,942 years)
  • Format: Unix time (seconds since 1970-01-01 UTC) or device uptime

Eliminates need for field-specific interpretation logic in client code.