Skip to content

v1.16.2 - Timestamp Variable Naming Clarity (2025-12-12)

What Changed?

This release improves code readability through clearer variable naming in the timestamp tracking system. Two timestamp variables serving different purposes have been renamed to directly express their intent: g_deadtime_ms for deadtime enforcement and g_triggered_us for event trigger timing. This is a pure refactoring with zero functional changes.

What's New

Refactoring: Timestamp Variable Naming

What it does: Improves code clarity by renaming timestamp variables to express their architectural purpose directly. The two variables track independent timing systems at different layers:

  • g_deadtime_ms: Hardware-layer deadtime enforcement (prevents detector saturation)
  • g_triggered_us: Application-layer event trigger timestamps (for inter-event duration calculation)

Naming improvements:

// Before: Names were ambiguous and unclear
unsigned long last_detection_time = millis();    // ??? What does this track?
uint64_t g_last_event_time_us = micros();       // ??? Different from the one above?

// After: Names express purpose and layer directly
unsigned long g_deadtime_ms = millis();         // Reference timestamp for deadtime filtering
uint64_t g_triggered_us = micros();             // Trigger timestamp of detection event

Code locations:

  • include/detector.h:220 - g_deadtime_ms class member
  • src/detector.cpp:33,100,157 - g_deadtime_ms static member and usage
  • src/detection_processor.cpp:50,59,139-140 - g_triggered_us static variable and usage

Installation

Quick Start

# Get the release
git checkout v1.16.2

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from v1.16.1?

✅ Added

🔧 Changed

  • Renamed last_detection_time → g_deadtime_ms across detector module (4 files, 6 changed lines)
  • Renamed g_last_event_time_us → g_triggered_us across detection_processor module (3 files, 4 changed lines)
  • Updated documentation comments and variable documentation strings for clarity
  • Both variable names now explicitly convey their purpose and timestamp resolution (ms vs us)

🐛 Fixed

  • None (pure refactoring, no bug fixes)

Is It Safe to Upgrade?

Backward Compatible: Yes (internal refactoring only)

  • No API changes
  • No functional behavior changes
  • No protocol changes
  • No user-visible impact
  • Timestamp values and calculations remain identical

Technical Details

Timestamp Architecture Clarification

Why these variables exist:

Variable Purpose Layer Updated When
g_deadtime_ms Prevents detector saturation Hardware Detection passes deadtime check
g_triggered_us Inter-event duration calculation Application Event is queued for transmission

Key insight: These are intentionally independent and correctly decoupled by design:

  • Deadtime suppresses unwanted detections at the hardware layer
  • Trigger timestamp tracks the actual cosmic ray detection moment for user timing data
  • Both variables operate at different temporal scales (milliseconds vs microseconds)

Tests Passed

  • ✅ Builds without errors
  • ✅ All pre-commit hooks passed
  • ✅ RAM usage: 31.3% (102,496 / 327,680 bytes) - unchanged
  • ✅ Flash usage: 27.6% (361,221 / 1,310,720 bytes) - unchanged
  • ✅ No compilation warnings

Release Details

  • Date: 2025-12-12
  • Version: v1.16.2
  • Commit: 4df746f
  • Files Changed: 4 (include/detector.h, src/detector.cpp, src/detection_processor.cpp, docs/progress/entries/2025-12-12-timestamp-timing-analysis.md)
  • Type: Refactoring (semantic clarity, zero functional impact)

Next Steps

The next phase of work could focus on:

  1. Detector Event Patterns: Analyze cosmic ray event coincidence rates across channels
  2. Timing Correlation: Compare inter-event intervals across multiple detectors for synchronization
  3. Performance Metrics: Track detection efficiency and deadtime suppression effectiveness
  4. Documentation: Create user guide for timing-based analysis workflows

References

  • Analysis: See progress log for detailed timing sequence analysis and naming rationale
  • Commit: refactor(timestamp): improve variable naming clarity for deadtime and trigger tracking
  • Architecture: Timestamp systems are part of the unified device response protocol (v1.12.0+)