Skip to content

v1.16.5 - Microsecond-Precision RTC Timestamps (2025-12-12)

What Changed?

This release adds microsecond-precision timestamp support to the RTC (Real-Time Clock) system. The detected_at field now captures detection events with ~4 microsecond precision instead of 1-second granularity, enabling high-precision event correlation across multiple detectors. Three new commands provide access to timestamps at different precisions (seconds, milliseconds, microseconds).

What's New

Main Feature: Microsecond-Precision RTC Timestamps

What it does:

  • detected_at field upgraded from uint32_t (seconds) to uint64_t (microseconds)
  • Three new command levels for timestamp queries: GET_RTC_TIME (seconds), GET_RTC_TIME_MS (milliseconds), GET_RTC_TIME_US (microseconds)
  • High-precision timestamp capture for detection event correlation

How to use it:

  1. Query current RTC timestamp in microseconds: 

    # Via serial command interface
GET_RTC_TIME_US

# Response:
{"type":"response","status":"ok","rtc_time_us":1732046789123456}

  2. Alternative precisions:

GET_RTC_TIME       # Seconds (uint32_t)
GET_RTC_TIME_MS    # Milliseconds (uint64_t)
GET_RTC_TIME_US    # Microseconds (uint64_t)

Code example:

// In detection_processor.cpp - capture event with microsecond precision
void DetectionProcessor::add_rtc_data(event_t* event) {
#if ENABLE_RTC
  event->detected_at = rtc_get_time_us();  // ~4µs precision
#endif
}

// In stream_formatter output - detected_at now in microseconds
#if ENABLE_RTC
  Serial.print(delimiter);
  Serial.print(data->detected_at);  // uint64_t microseconds
#endif

Installation

Quick Start

# Get the release
git checkout v1.16.5

# Build with RTC support
PLATFORMIO_BUILD_FLAGS="-DENABLE_RTC=1" task build

# Upload
task upload

# Test RTC commands
task monitor

Then send: GET_RTC_TIME_US to verify microsecond-precision timestamps.

What's Different from the Last Version?

✅ Added

  • rtc_get_time_ms() - Millisecond-precision RTC time getter
  • rtc_get_time_us() - Microsecond-precision RTC time getter
  • Command::get_rtc_time_ms() and Command::get_rtc_time_us() methods
  • GET_RTC_TIME_MS and GET_RTC_TIME_US command handlers
  • hit_type field output to JSONL format (stream_formatter)

🔧 Changed

  • detected_at field type: uint32_t → uint64_t (seconds → microseconds)
  • RTC timestamp capture uses rtc_get_time_us() for high precision
  • stream_data_t.detected_at documentation updated to reflect microsecond units
  • JSONL output now includes hit_type field when ENABLE_HITTYPE=1

🐛 Fixed

  • JSONL format was missing hit_type field (now included)
  • RTC timestamp precision limited to seconds (now microseconds)

Is It Safe to Upgrade?

Backward Compatible: Mostly Yes (with notes)

  • Breaking change: detected_at field type changed from uint32_t to uint64_t
  • If you parse detected_at in client code expecting 32-bit values, update your parsers
  • JSON serialization handles this transparently

  • Serial text output works without changes

  • New commands are additive (no breaking changes)

  • JSONL hit_type field is optional (only when ENABLE_RTC=1 + ENABLE_HITTYPE=1)

Tests Passed

  • ✅ Builds without errors (esp32dev-release profile)
  • ✅ RTC manager functions compile and link correctly
  • ✅ Command dispatch table updated with new handlers
  • ✅ Pre-commit hooks passed (trailing whitespace, formatting)
  • ✅ stream_formatter JSONL output includes all fields

Release Details

  • Date: 2025-12-12
  • Version: v1.16.5
  • Files Changed: 13
  • include/rtc_manager.h - Added function signatures
  • src/rtc_manager.cpp - Implemented rtc_get_time_ms(), rtc_get_time_us()
  • include/command.h - Added Command class methods
  • src/command.cpp - Implemented methods
  • src/command/rtc.cpp - Added handlers for GET_RTC_TIME_MS, GET_RTC_TIME_US
  • src/command_manager.cpp - Registered commands
  • include/stream_data.h - Updated detected_at type and docs
  • src/stream_formatter.cpp - Added JSONL hit_type output
  • src/main.cpp - Updated to use rtc_get_time_us()
  • src/detection_processor.cpp - Updated to use rtc_get_time_us()

Next Steps

  • Phase 7: GNSS timestamp integration with microsecond precision
  • Consider 1PPS (1 Pulse Per Second) signal synchronization for multi-detector coordination
  • Timestamp field documentation and migration guide for client libraries