Skip to content

v1.13.6 - EventQueue Implementation (2025-12-09)

What Changed?

This release implements EventQueue - a detector-triggered event buffering system that establishes symmetric architecture with the 2A CommandQueue. All cosmic ray detection events now flow through a 200-item FreeRTOS queue, enabling efficient high-frequency event handling (10-50 Hz bursts). The release maintains complete backward compatibility with existing production builds (ENABLE_DEVICE_RESPONSE=0).

What's New

Main Feature: EventQueue - Unified Event Buffering

What it does: EventQueue is a FreeRTOS-based event buffering system that queues all cosmic ray detection events for deferred transmission. Instead of sending events immediately, detection data is converted to the unified device_response_t format, queued in a 200-item buffer, and transmitted in batches during the main loop. This enables efficient handling of burst detection (10-50 Hz) without blocking the detection hardware.

How to use it: EventQueue is automatically integrated into the detection loop when ENABLE_DEVICE_RESPONSE=1 is set. No configuration needed - detection events are automatically queued and transmitted. Use the SET_STREAM command to control event output (same as before).

Architecture:

Detection Hardware → event_t → event_to_device_response() → device_response_t
                                                               ↓
                                                    EventQueue::enqueue()
                                                               ↓
                                           Main Loop: EventQueue::flush()
                                                               ↓
                                         send_event_response() → JSON Serial

Code example:

// In detection_process() - detection events are now queued
device_response_t event_response = event_to_device_response((const event_t*)&data);
EventQueue::enqueue(&event_response);

// In main loop() - queued events are transmitted in batches
EventQueue::flush();  // Non-blocking, <5ms per event

Installation

Quick Start

# Get the release
git checkout v1.13.6

# Build development (with EventQueue enabled)
task next:build

# Or build production (legacy behavior, ENABLE_DEVICE_RESPONSE=0)
task prod:build

# Upload to ESP32
task upload

# Check it works
task monitor

Build Profiles

  • task next:build (NEW): EventQueue enabled (ENABLE_DEVICE_RESPONSE=1) - Phase 4 next-gen protocol
  • task prod:build: Production (ENABLE_DEVICE_RESPONSE=0) - Unchanged, backward compatible
  • task dev:build: Development with text commands (ENABLE_DEVICE_RESPONSE=0) - Unchanged

What's Different from the Last Version?

✅ Added

  • EventQueue class (include/event_queue.h, src/event_queue.cpp): FreeRTOS-based event buffering with 200-item queue capacity
  • Event response functions (include/event_response.h, src/event_response.cpp): Unified serialization for detection events
  • EventQueue initialization: Automatic queue setup in setup() when ENABLE_DEVICE_RESPONSE=1
  • EventQueue transmission: Integrated into main loop with EventQueue::flush() for non-blocking event draining
  • Architecture documentation: Comprehensive queue file mapping and design analysis
  • Build profile: New esp32dev-next environment for Phase 4 next-gen protocol testing

🔧 Changed

  • Detection loop: Now uses EventQueue path when ENABLE_DEVICE_RESPONSE=1 (previously immediate transmission)
  • Serial protocol module: Removed unnecessary 58-line wrapper (serial_protocol.h/cpp), inlined Serial.begin() directly in main.cpp
  • Event transmission timing: Deferred to main loop batch processing instead of event-driven immediate sends
  • Build filters: Added serial_protocol.cpp exclusion from esp32dev-next build

🐛 Fixed

  • Removed dead code in serial_protocol.cpp (unused serial_discard() function)
  • Improved build modularity by eliminating thin wrapper modules

Is It Safe to Upgrade?

Backward Compatible: ✅ Yes

  • Production users (using task prod:build): No impact. EventQueue code is completely conditional and not compiled when ENABLE_DEVICE_RESPONSE=0
  • Development users (using task dev:build): No impact. Unchanged behavior with text commands
  • Experimental users (using task next:build): New feature, EventQueue replaces immediate event transmission with batch processing
  • Legacy detection buffer: Still available for ENABLE_DEVICE_RESPONSE=0 builds

Zero Overhead When Disabled: EventQueue code is 100% conditional - production builds have identical binary size and performance.

Tests Passed

  • ✅ task prod:build - SUCCESS (ENABLE_DEVICE_RESPONSE=0, unchanged)
  • ✅ task dev:build - SUCCESS (ENABLE_DEVICE_RESPONSE=0, text commands)
  • ✅ task next:build - SUCCESS (ENABLE_DEVICE_RESPONSE=1, EventQueue enabled)
  • ✅ All includes and dependencies resolved
  • ✅ Pre-commit hooks passed
  • ✅ File modifications verified

Release Details

  • Date: 2025-12-09
  • Version: v1.13.6
  • Files Changed: 12
  • Created: 5 files (event_queue.h/cpp, event_response.h/cpp, 1 architecture doc)
  • Deleted: 2 files (serial_protocol.h/cpp)
  • Modified: 3 files (main.cpp, platformio.ini, Taskfile.yml)
  • Other: 2 files (uv.lock, progress doc)
  • Lines Added: +2172
  • Lines Removed: -290
  • Commits: 6 since v1.13.5

Next Steps

Phase 4.1 (Planned)

  • Extend event_response.cpp to populate full payload fields in device_response_t during conversion (currently populated at serialization time)
  • Add comprehensive testing and validation of EventQueue serialization format
  • Document EventQueue API in main API reference

Phase 5 (Roadmap)

  • CommandParser class for unified argument parsing across all command handlers
  • Complete transition from legacy protocol to unified device response protocol (make ENABLE_DEVICE_RESPONSE=1 the default)
  • Remove legacy serial protocol modules when no longer needed