Skip to content

v1.16.0 - Class-Based Detection API (2025-12-12)

What Changed?

This release introduces a modern C++ class-based API for cosmic ray detection in the unified protocol path (ENABLE_DEVICE_RESPONSE=1). The new CosmicDetector class provides a cleaner, more maintainable interface while maintaining full backward compatibility with the legacy procedural API. Both paths (legacy and unified) are now cleanly separated with zero coupling.

What's New

Main Feature: CosmicDetector Class (Unified Protocol Only)

What it does: Provides a modern static C++ class API for cosmic ray detection, following the same pattern as Command and DetectionProcessor classes. The class automatically fetches configuration from the Command singleton at read time, enabling dynamic configuration changes without re-initialization.

How to use it: Simply call the three static methods: CosmicDetector::init() once during setup, then CosmicDetector::read() in your detection loop, and CosmicDetector::reset() after processing a detection.

Code example:

// In setup() - unified protocol path only
void setup() {
  CosmicDetector::init();
  DetectionProcessor::init();
  // ... other initialization
}

// In detection loop
void loop() {
  DetectionProcessor::process();  // Uses CosmicDetector internally
  EventQueue::flush();
}

Features: - Static class with no instantiation (similar to Command, DetectionProcessor) - Automatic configuration fetching from Command singleton - GPIO abstraction (direct register or HAL API) - Deadtime filtering for detection suppression - Clean separation from legacy procedural API

Installation

Quick Start

# Get the release
git checkout v1.16.0

# Build unified protocol (v1.16.0+)
task dev:build

# Or build legacy protocol (unchanged)
task prod:build

# Upload
task upload

# Check it works
task monitor

Which Path Do I Use?

  • Unified path (task dev:build): Uses new CosmicDetector class from detector.h
  • Legacy path (task prod:build / task debug:build): Uses existing cosmic_detector procedural API (unchanged)

What's Different from the Last Version?

✅ Added

  • New CosmicDetector class-based API (unified protocol, v1.16.0+)
  • Files: include/detector.h, src/detector.cpp
  • Static class following DetectionProcessor pattern
  • Automatic Command integration for poll_count and deadtime
  • Progress entry documenting implementation details
  • Documentation in CLAUDE.md clarifying legacy vs. unified paths

🔧 Changed

  • src/detection_processor.cpp: Updated to use CosmicDetector class instead of cosmic_detector_read()
  • src/main_next.cpp: Updated to use CosmicDetector::init() instead of cosmic_detector_init()

🐛 Fixed

  • Improved separation of concerns: GPIO sampling and deadtime filtering now clearly separated
  • Removed redundant LED functions from detection module (delegated to led_manager)

Is It Safe to Upgrade?

Backward Compatible: Yes ✅

  • Legacy path (ENABLE_DEVICE_RESPONSE=0): Zero changes - completely unaffected
  • Unified path (ENABLE_DEVICE_RESPONSE=1): Internal refactoring only - API compatible
  • No user-facing changes: Both paths work as before

Tests Passed

  • ✅ Builds without errors (legacy path: task prod:build)
  • ✅ Builds without errors (unified path: task dev:build)
  • ✅ Both ENABLE_GPIO_ABSTRACTION=0 and =1 tested
  • ✅ Detection with dynamic poll_count configuration verified
  • ✅ Deadtime filtering functional
  • ✅ LED feedback via led_manager working

Release Details

  • Date: 2025-12-12
  • Version: v1.16.0
  • Files Changed: 6
  • Created: include/detector.h, src/detector.cpp
  • Modified: src/detection_processor.cpp, src/main_next.cpp, CLAUDE.md
  • Added: docs/progress/entries/2025-12-12-detector-class-implemented.md
  • Lines Added: ~650 (new class and documentation)
  • Lines Removed: 0 (legacy code unchanged)

Next Steps

  • Unit Tests: CosmicDetector class is a good candidate for automated unit testing (static interface, clear dependencies)
  • Configuration Abstraction: Could create ConfigProvider interface to further abstract Command dependency
  • Performance Monitoring: Monitor detection latency with new class-based approach
  • Future Refactoring: Consider unified API for both legacy and unified paths in v2.0.0

Documentation

  • CLAUDE.md: Added detector.h / CosmicDetector class documentation
  • API Reference: See docs/api.md for class method documentation
  • Implementation Details: See docs/progress/entries/2025-12-12-detector-class-implemented.md