Skip to content

v1.14.1 - DetectionProcessor Class Refactoring (2025-12-11)

What Changed?

This release refactors the detection_process() function into a class-based DetectionProcessor to provide better code organization and encapsulation. The unified device response protocol now has a complete architectural pattern: CommandQueue for commands, EventQueue for events, and DetectionProcessor for detection processing. All functionality remains identical—this is a pure refactoring with zero behavior changes.

What's New

Main Feature: DetectionProcessor Class

What it does: Encapsulates all cosmic ray detection event processing into a static class following the EventQueue and CommandQueue architectural patterns. This provides clean separation of concerns between detection logic, event buffering, and transmission.

How to use it: The API is simple and mirrors EventQueue:

void setup() {
  DetectionProcessor::init();      // Initialize (once, in setup)
  EventQueue::init();
}

void loop() {
  DetectionProcessor::process();   // Process detections (every loop)
  EventQueue::flush();             // Transmit queued events
}

Code example:

// Before (v1.14.0)
void detection_process(void) {
  cosmic_detection_t detection = cosmic_detector_read();
  if (detection.detected) {
    // 40+ lines of sensor reading and event building
    // ... BME280, ADC, RTC, GNSS reading ...
    // ... event_t construction ...
    // ... EventQueue::enqueue() ...
  }
  cosmic_detector_reset();
}

// After (v1.14.1)
DetectionProcessor::process();  // Single line in main loop

Installation

Quick Start

# Get the release
git checkout v1.14.1

# Build
task build              # Development build
# or
task prod:build         # Production build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • DetectionProcessor class - New static class for encapsulated detection processing
  • DetectionProcessor::init() - Initialize timestamp tracking
  • DetectionProcessor::process() - Process detection and queue events
  • Comprehensive JSDoc documentation - Full API documentation in include/detection_processor.h

🔧 Changed

  • main_next.cpp refactored - Removed 40+ lines of detection processing code
  • Removed detection_process() function
  • Removed global last_event_time_us variable
  • Single DetectionProcessor::process() call in loop
  • Cleaner, more readable main loop structure

🐛 Fixed

  • Added missing #include "device_response.h" in detection_processor.cpp for device_get_timestamp() declaration

Architecture Improvements

Before (v1.14.0)

main_next.cpp loop
├── 40+ lines of detection processing
├── Sensor reading logic mixed with event building
├── Global timestamp state management
└── EventQueue queueing at end

After (v1.14.1)

main_next.cpp loop
├── CommandQueue::receive()
├── CommandQueue::execute()
├── EventQueue::flush()
└── DetectionProcessor::process()  ← Single line, fully encapsulated
    ├── Read sensors internally
    ├── Build event_t
    ├── Queue to EventQueue
    └── Manage timestamp state

Is It Safe to Upgrade?

Backward Compatible: ✅ Yes (100% compatible)

  • Zero behavior changes - All detection, sensor reading, and event queueing logic remains identical
  • No API changes for users - Detection output format unchanged
  • Same performance - No performance impact (refactoring only)
  • Conditional compilation - All ENABLE_* flags work identically (ENABLE_TIMESTAMP, ENABLE_BME280, ENABLE_GNSS, etc.)

Existing users can upgrade without any code or configuration changes.

Tests Passed

  • ✅ Builds without errors (esp32dev-next environment)
  • ✅ RAM usage: 31.2% (102,352 / 327,680 bytes) - same as before
  • ✅ Flash usage: 27.4% (359,061 / 1,310,720 bytes) - same as before
  • ✅ Pre-commit hooks: All checks passed
  • ✅ Timestamp tracking (ENABLE_TIMESTAMP) verified
  • ✅ Sensor integration (BME280, ADC, RTC, GNSS) unchanged
  • ✅ EventQueue integration verified

Release Details

  • Date: 2025-12-11
  • Version: v1.14.1
  • Commits: 2 (refactoring + build fix)
  • 6c82624 - refactor(detection): convert detection_process function to DetectionProcessor class
  • 60987d0 - fix(detection): add missing device_response.h include
  • Files Changed: 3
  • NEW: include/detection_processor.h (179 lines)
  • NEW: src/detection_processor.cpp (150 lines)
  • MODIFIED: src/main_next.cpp (cleaner, 40 fewer lines)

Architectural Design Pattern

This release completes the "3-queue" unified protocol architecture:

  1. CommandQueue - Handles text commands from serial input
  2. EventQueue - Buffers detection events for transmission
  3. DetectionProcessor - Processes cosmic ray detection and builds events

All three follow the same static class pattern with init() and processing methods, providing architectural consistency across the firmware.

Code Examples

Detection with all optional fields enabled

// ENABLE_TIMESTAMP=1, ENABLE_BME280=1, ENABLE_RTC=1, ENABLE_GNSS=1
// Everything happens inside DetectionProcessor::process()

DetectionProcessor::process();  // Handles:
  // ✓ Read cosmic detection (GPIO polling)
  // ✓ Calculate inter-event timing (timedelta_us)
  // ✓ Read BME280 (temperature, pressure, humidity)
  // ✓ Read ADC and convert to millivolts
  // ✓ Read RTC (absolute unix timestamp)
  // ✓ Read GNSS (position, altitude, satellites)
  // ✓ Build 8-bit hit type bitmask
  // ✓ Create event_t with all fields
  // ✓ Build JsonDocument payload
  // ✓ Queue to EventQueue
  // ✓ LED feedback

Stream control

// Stream can be toggled at runtime
Command::getInstance().set_stream(false);  // Disable output
DetectionProcessor::process();              // Still processes, but won't queue

Command::getInstance().set_stream(true);   // Enable output
DetectionProcessor::process();              // Processes and queues

Next Steps

  • v1.15.0 (planned): CommandParser class for unified command argument parsing and validation
  • Future: Additional DetectionProcessor features like detection rate limiting or event filtering