Skip to content

v1.6.9 - Uptime Tracking for Event Timestamps (2025-11-20)

What Changed?

This release adds uptime tracking (Phase 1) to enable researchers to correlate detection events temporally and verify sensor warm-up behavior. Board uptime in milliseconds is now optionally included in sensor event output and can be retrieved via the GET_UPTIME command. The feature is disabled by default in production builds and enabled in development builds, ensuring zero overhead when not needed.

What's New

Main Feature: Uptime Tracking (v1.6.9 Phase 1)

What it does: Captures and outputs board uptime (milliseconds since power-on) with each cosmic ray detection event. This enables temporal correlation of events and analysis of sensor initialization behavior. The feature is compile-time configurable via the ENABLE_TIMESTAMP flag.

How to use it:

  1. Build development firmware (with uptime enabled):
task dev:build && task dev:upload
task monitor
  1. View uptime for each detection:
100 85 92 2048 25.35 1013.25 45.67 5234

Last field 5234 = board uptime in milliseconds

  1. Query uptime anytime via text command:
UPTIME
UPTIME: 0 days 00:00:05.234 (5234 ms)

Code example:

// In src/main.cpp - Detection event output now includes uptime
#if ENABLE_TIMESTAMP
uint32_t current_uptime = millis();
Serial.print(" ");
Serial.print(current_uptime);
#endif
Serial.println();

Installation

Quick Start

# Get the release
git checkout v1.6.9

# Build development version (uptime enabled)
task dev:build && task dev:upload

# Or build production version (uptime disabled, minimal overhead)
task prod:build && task prod:upload

# Monitor output
task monitor

What's Different from the Last Version?

✅ Added

  • ENABLE_TIMESTAMP compile-time flag in include/config.h (default: disabled)
  • Uptime field in sensor event output - optional last field: uptime_ms
  • GET_UPTIME text command - displays board uptime in human-readable format
  • Build profile configuration - development profile automatically enables uptime
  • Comprehensive documentation - CLAUDE.md, docs/api.md, and config.h docstrings

🔧 Changed

  • src/main.cpp detection event handler now calculates and outputs uptime when enabled
  • platformio.ini esp32dev-dev profile includes -DENABLE_TIMESTAMP=1 build flag

Performance Impact

  • Production (ENABLE_TIMESTAMP=0): Zero overhead - code eliminated at compile-time
  • Development (ENABLE_TIMESTAMP=1): ~40 bytes Flash, minimal CPU impact
  • Flash overhead: 297,005 bytes (prod) → 302,117 bytes (dev) = ~5 KB difference

Is It Safe to Upgrade?

Backward Compatible: Yes ✅

  • When disabled (default in production), no behavior change
  • When enabled (development), adds optional final field to detection output
  • Existing tools can ignore the new field
  • GET_UPTIME command only available when enabled
  • All three build profiles (dev, release, debug) compile successfully

Tests Passed

  • ✅ Builds without errors (all three profiles: dev, release, debug)
  • ✅ Development build (ENABLE_TIMESTAMP=1) compiles successfully
  • ✅ Production build (ENABLE_TIMESTAMP=0) compiles with minimal overhead
  • ✅ Uptime values monotonically increase across detection events
  • ✅ GET_UPTIME command returns correct human-readable format
  • ✅ Sensor output format verified: signal1 signal2 signal3 adc temp pressure humidity [uptime_ms]
  • ✅ Flash memory overhead within specification (≤5 KB for full dev profile)

Release Details

  • Date: 2025-11-20
  • Version: v1.6.9
  • Files Changed: 11
  • Commits:
  • 0c8b39e - feat: implement uptime tracking infrastructure (Phase 1-3)
  • c82bdb7 - feat: complete uptime tracking implementation (Phase 1, 2, 3, 7)
  • bcaac69 - docs: update progress log task name in tasks.md
  • dfc5e45 - docs: mark T032 final serial verification as completed
  • 4bc7990 - docs: add comprehensive progress log for uptime tracking Phase 1

Next Steps

Upcoming (v1.7.1 and beyond)

  • Phase 2 (v1.7.1): Duration tracking - Calculate inter-event intervals
  • Add GET_LAST_EVENT_TIME command

  • Extend output format with duration field

  • Phase 3 (v1.8.0+): RTC absolute time support

  • Integration with real-time clock module
  • Unix timestamp or ISO 8601 format options
  • Time synchronization via SET_TIME command

See REFACTORING_ROADMAP.md for complete roadmap.