Skip to content

v1.16.8 - EventQueue & GNSS Field Ordering (2025-12-12)

What Changed?

This release refactors the EventQueue implementation and GNSS field ordering for consistency and clarity. EventQueue now follows identical 3-layer architecture patterns as CommandQueue within the unified device response protocol. GNSS timestamp is prioritized as the first field in event data structures for improved multi-detector synchronization.

What's New

EventQueue Architecture Refactoring

What it does:

EventQueue now implements clean 3-layer architecture identical to CommandQueue:

  • Layer 1: Handlers populate event_response_t with typed fields
  • Layer 2: DeviceResponse::from_event() converts to transport struct (pure data copy)
  • Layer 3: DeviceResponse::send() serializes to JSON Lines (JSONL) format

Consistency achieved:

  • Both queues use FreeRTOS static allocation (no heap)
  • Both respect Command::getInstance().get_stream() for unified control
  • Both implement Phase 6 Payload Pointer Pattern (memory efficient)
  • Identical serialization path for all output

Code example:

// Layer 1: Create typed response
event_response_t response = event_response_ok(&event);
response.sent_at = device_get_timestamp();

// Queue for deferred processing
EventQueue::enqueue(&response);

// Layer 2-3: Handled in flush()
EventQueue::flush();  // Converts to device_response_t and sends JSON

GNSS Field Reordering

What it does:

Moves unix timestamp (gnss_time_us) to the first position in GNSS field group. This improves logical grouping and clarity for multi-detector time synchronization.

Updated field order:

gnss_time_us → latitude → longitude → altitude → satellites → fix_quality → hdop → fix_valid

Output example:

{"gnss_time_us":0, "gnss_latitude":0, "gnss_longitude":0, ...}

Installation

Quick Start

# Get the release
git checkout v1.16.8

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • EventQueue comprehensive documentation with 3-layer architecture explanation
  • GNSS field ordering consistency across all structures

🔧 Changed

  • GNSS field ordering: gnss_time_us moved to beginning of GNSS fields in all structures:
  • event_t (stream_data.h)
  • event_response_t (event_queue.h)
  • detection_processor.cpp field assignments
  • event_queue.cpp JSON payload building
  • JSON output: GNSS fields now appear in struct-definition order

🐛 Fixed

  • EventQueue JSON payload field ordering aligned with struct definitions
  • Consistency between struct member order and JSON serialization order

Is It Safe to Upgrade?

Backward Compatible: Yes (with minor JSON field ordering change)

Impact:

  • JSON output field ordering changed for GNSS data only
  • Functional behavior unchanged (all field values identical)
  • Clients using positional access (array indices) are unaffected
  • Clients parsing JSON objects by field name are unaffected
  • GNSS timestamp now appears first in JSON output (improves clarity)

Tests Passed

  • ✅ Builds without errors (esp32dev-dev, esp32dev-release, esp32dev-debug)
  • ✅ FreeRTOS queue operations verified
  • ✅ EventQueue enqueue/flush working correctly
  • ✅ JSON serialization produces valid JSONL output
  • ✅ GNSS field ordering consistent across all code paths
  • ✅ Pre-commit hooks passed (whitespace, file endings, merge conflicts, large files)

Release Details

  • Date: 2025-12-12
  • Version: v1.16.8
  • Files Changed: 6
  • docs/releases/v1.16.8.md (new)
  • include/event_queue.h (refactored)
  • src/event_queue.cpp (refactored)
  • include/stream_data.h (GNSS field reordering)
  • src/detection_processor.cpp (GNSS field reordering)

Next Steps

  1. Implement event_to_device_response() helper - Centralize event conversion in event_queue.cpp
  2. Add CommandQueue::reset() method - For symmetry with EventQueue::clear()
  3. Performance monitoring - Log overflow_count periodically via GET_STATUS

Architecture Notes

EventQueue and CommandQueue now demonstrate exemplary architectural symmetry:

  • Same 3-layer pattern (Domain → Transport → Serialization)
  • Same queue primitives (FreeRTOS static allocation)
  • Same stream control integration (Command::getInstance().get_stream())
  • Appropriate specialization (queue sizes, input/output paths based on domain requirements)

See progress log 2025-12-12-queue-architecture-review.md for comprehensive architecture analysis (9/10 symmetry rating with detailed justification).