Skip to content

v1.15.0 - RTC Timestamp Field Rename (2025-12-12)

What Changed?

This release renames the RTC timestamp field from unix_timestamp to detected_at for improved semantic clarity. The timestamp now represents the exact moment of cosmic ray detection, captured immediately after GPIO detection with minimal timing overhead. Both Legacy and Unified protocol paths are synchronized with this change.

What's New

Field Rename: detected_at RTC Timestamp

What it does: The RTC timestamp field that captures the absolute time of cosmic ray detection has been renamed from unix_timestamp to detected_at. This improves code readability and semantic clarity - the field name now accurately reflects its purpose: marking the exact moment of detection.

Timing improvement: The RTC capture now happens immediately after GPIO detection in both protocol paths: - Legacy protocol: RTC captured before sensor reads - Unified protocol: New add_rtc_data() helper captures RTC first

This ensures the timestamp represents the true detection moment with minimal delay (<5 microseconds).

Example output:

{"type":"event","status":"ok","hit1":100,"hit2":85,"hit3":92,"adc":2048,"detected_at":1702300000,"temp_c":25.35,"atm_pa":101325.0,"hmd_pct":45.67}

Installation

Quick Start

# Get the release
git checkout v1.15.0

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • New add_rtc_data() helper method in DetectionProcessor for unified RTC handling
  • RTC timestamp field documentation updated in CLAUDE.md

🔧 Changed

  • BREAKING: RTC timestamp field renamed from unix_timestamp to detected_at in all data structures
  • RTC capture timing moved to immediately after GPIO detection (both protocol paths)
  • JSON field name in all outputs: unix_timestamp → detected_at
  • Output examples in documentation updated with new field name

🐛 Fixed

  • Unified protocol bug fix: RTC timestamp was not being captured in detection_processor.cpp (now implemented)

Is It Safe to Upgrade?

Backward Compatible: ⚠️ BREAKING CHANGE

⚠️ Important for Data Consumers: - JSON field name changed from unix_timestamp to detected_at - All data pipelines, parsers, and clients that expect unix_timestamp field will break - Action required: Update field name references in: - JSON parsers - Data pipeline scripts - Analysis tools - Logging/storage systems

Firmware compatibility: - All existing features remain functional - Conditional compilation ensures zero overhead when ENABLE_RTC=0 - Both protocol paths (Legacy and Unified) are synchronized

Tests Passed

  • ✅ Default build (RTC disabled): SUCCESS
  • ✅ RTC enabled build: PLATFORMIO_BUILD_FLAGS="-DENABLE_RTC=1" pio run -e esp32dev-release SUCCESS
  • ✅ Unified protocol with RTC: PLATFORMIO_BUILD_FLAGS="-DENABLE_DEVICE_RESPONSE=1 -DENABLE_RTC=1" pio run -e esp32dev-next SUCCESS
  • ✅ Pre-commit hooks pass (commitizen, trailing whitespace, file endings)

Release Details

  • Date: 2025-12-12
  • Version: v1.15.0
  • Files Changed: 10 (include/, src/, CLAUDE.md)
  • Commit: 343433d (feat(rtc): rename unix_timestamp to detected_at and improve capture timing)

Files Changed

Headers

  • include/event_queue.h - Field rename
  • include/stream_data.h - Field rename
  • include/detection_processor.h - New add_rtc_data() declaration

Implementation

  • src/detection_processor.cpp - New add_rtc_data() helper, RTC capture in read_sensors()
  • src/main.cpp - Move RTC capture to immediately after detection
  • src/event_queue.cpp - JSON field serialization update
  • src/stream_formatter.cpp - SSV/TSV/CSV/JSONL output updates
  • src/detection_buffer.cpp - Detection buffer output update

Documentation

  • CLAUDE.md - Phase 3 RTC section update with field rename and examples

Next Steps

Roadmap considerations:

  • Monitor for any client-side integration issues with field name change
  • Plan migration guide for users with existing data pipelines
  • Consider version bump strategy for semantic versioning (minor bump for breaking change in data format)