Skip to content

v1.14.4 - LED Manager Module Extraction (2025-12-11)

What Changed?

This release extracts LED control functionality into a dedicated led_manager module, applying the Single Responsibility Principle to separate LED hardware control from cosmic ray detection logic. The LED manager module provides a clean, reusable interface for all LED operations while maintaining identical behavior. All detection processing and command handling continues to work without modification—this is a pure refactoring with zero behavior changes.

What's New

Main Feature: LED Manager Module

What it does: Provides a centralized LED control module (led_manager.h/cpp) that encapsulates all LED operations. This separates LED control from the cosmic detector module, improving modularity and making LED control available to any part of the system without depending on detection logic.

Module Structure: The LED manager provides three categories of LED control:

  1. Initialization: led_init() - Set up LED pins as outputs
  2. Detection-Based Feedback: led_feedback(hit1, hit2, hit3) and led_off() - Provide visual feedback on detection
  3. Direct LED Control: led_set(channel, state) and led_get_state(channel) - Manual LED control via commands

How to use it: The module is automatically initialized when cosmic_detector_init() is called, so no changes needed for existing code. For manual LED control:

// Turn on LED 1
led_set(1, HIGH);

// Turn off all LEDs
led_set(0, LOW);

// Get current state
uint8_t state = led_get_state(1);

For detection-based feedback (used internally by DetectionProcessor):

led_feedback(detection.hit1, detection.hit2, detection.hit3);
delay(50);
led_off();

Architecture diagram:

LED Manager Module Hierarchy:

LED Control Sources:
├── Detection feedback (from DetectionProcessor)
│   ├── led_feedback() - Turn on LEDs based on hit counts
│   └── led_off() - Turn off all LEDs
├── Command interface (from text/binary commands)
│   └── led_set() - Direct LED control
└── Query interface
    └── led_get_state() - Read current LED state

Physical Hardware:
├── LED Channel 1: GPIO14
├── LED Channel 2: GPIO26
└── LED Channel 3: GPIO33

Benefits:

  • Single Responsibility: LED control is completely isolated from detection logic
  • Separation of Concerns: Detection-based feedback vs. direct control are separate code paths
  • Improved Modularity: Other modules can use LED control independently
  • Cleaner cosmic_detector: Detection module now focuses only on GPIO signal sampling
  • Better Testability: LED functions can be tested independently
  • Reusability: DetectionProcessor, command handlers, and future modules all use the same LED interface

Installation

Quick Start

# Get the release
git checkout v1.14.4

# Build all variants
task build              # Development build
task prod:build         # Production build
task next:build         # Next-generation (ENABLE_DEVICE_RESPONSE=1)

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • LED Manager Module - New dedicated module for LED control
  • include/led_manager.h (138 lines) - Public API with complete JSDoc documentation
  • src/led_manager.cpp (76 lines) - Implementation of all LED control functions

🔧 Changed

  • cosmic_detector.cpp refactored (38 lines removed)
  • Removed LED pin configuration (31-47 lines deleted)
  • Removed cosmic_detector_led_off() call from initialization
  • Added call to led_init() for proper module initialization

  • Kept backward-compatible LED functions for now (deprecated but available)

  • detection_processor.cpp updated

  • Added #include "led_manager.h" header
  • Updated led_feedback() method to use ::led_feedback() from led_manager (uses :: namespace qualifier to avoid recursion)

  • Updated led_off() call to use ::led_off() from led_manager

  • main.cpp updated (legacy protocol path)

  • Added #include "led_manager.h" header
  • Updated LED calls from cosmic_detector_led_feedback() to ::led_feedback()

  • Updated LED calls from cosmic_detector_led_off() to ::led_off()

  • main_next.cpp updated (unified device response path)

  • Added #include "led_manager.h" header

  • LED initialization now happens via cosmic_detector_init() → led_init() chain

  • text_command_manager.cpp updated

  • Added #include "led_manager.h" header
  • Updated all cosmic_detector_led_set() calls to led_set()
  • Supports both ENABLE_DEVICE_RESPONSE=0 and ENABLE_DEVICE_RESPONSE=1 paths

🐛 Fixed

  • No bug fixes in this release (pure refactoring)

Architecture Improvements

Before (v1.14.3)

cosmic_detector.cpp
├── Detection pin configuration (GPIO12, GPIO19, GPIO27)
├── Detection signal sampling
├── LED pin configuration (GPIO14, GPIO26, GPIO33)
│   └── Initializes LED pins in cosmic_detector_init()
├── led_feedback() - LED control for detection events
├── led_off() - Turn off all LEDs
└── led_set() - Direct LED control (duplicate implementation)

(LED functionality mixed with detection logic)

After (v1.14.4)

cosmic_detector.cpp
├── Detection pin configuration (GPIO12, GPIO19, GPIO27)
├── Detection signal sampling
└── Calls led_init() to initialize LED manager
    ↓
led_manager.cpp (new module)
├── LED pin configuration (GPIO14, GPIO26, GPIO33)
│   └── Initializes LED pins in led_init()
├── led_feedback() - LED control for detection events
├── led_off() - Turn off all LEDs
└── led_set() - Direct LED control

(LED functionality separated from detection logic)

Module Responsibility Map

Module Responsibility Functions
cosmic_detector GPIO signal sampling cosmic_detector_read(), cosmic_detector_reset(), initialization
detection_processor Event processing workflow process(), sensor orchestration, LED feedback delegation
led_manager LED hardware control led_init(), led_feedback(), led_off(), led_set(), led_get_state()

Key Design: Each module has one reason to change:

  • cosmic_detector changes if GPIO polling logic changes
  • detection_processor changes if detection workflow changes
  • led_manager changes if LED control logic changes

Code Organization

Header Structure (v1.14.4)

include/led_manager.h:
├── INITIALIZATION
│   └── led_init()
├── DETECTION-BASED FEEDBACK
│   ├── led_feedback()
│   └── led_off()
├── DIRECT LED CONTROL
│   └── led_set()
└── QUERY INTERFACE
    └── led_get_state()

Include Dependency (v1.14.4)

main.cpp / main_next.cpp
├── #include "cosmic_detector.h"
│   └── cosmic_detector_init()
│       └── led_init() (called internally)
└── #include "led_manager.h"
    └── led_feedback(), led_set(), etc.

detection_processor.cpp
├── #include "cosmic_detector.h"
│   └── GPIO reading
└── #include "led_manager.h"
    └── LED feedback delegation

Is It Safe to Upgrade?

Backward Compatible: ✅ Yes (100% compatible)

  • Zero behavior changes - All LED operations work identically
  • No API changes for users - LED output format unchanged
  • Same performance - No performance impact (pure refactoring)
  • Same memory usage - RAM: 31.2% (next), 8.8% (dev), 8.1% (prod) - identical to v1.14.3
  • All build variants supported:
  • ✅ task build (development)
  • ✅ task prod:build (production)
  • ✅ task debug:build (debug symbols)
  • ✅ task next:build (next-generation, ENABLE_DEVICE_RESPONSE=1)

Existing users can upgrade without any code changes.

Tests Passed

  • ✅ Builds without errors (all 4 build variants)
  • esp32dev-dev (development)
  • esp32dev-release (production)
  • esp32dev-debug (debug)
  • esp32dev-next (next-generation)
  • ✅ RAM usage: 31.2% (next), 8.8% (dev), 8.1% (prod) - identical to v1.14.3
  • ✅ Flash usage: 27.4% (next), 26.6% (dev), 26.2% (prod) - identical to v1.14.3
  • ✅ LED feedback: Detection-based LED control verified
  • ✅ LED commands: Manual LED control (TEST_LED) verified
  • ✅ DetectionProcessor integration: LED feedback delegation works correctly
  • ✅ All command handlers: LED commands in text_command_manager verified
  • ✅ Pre-commit hooks: All checks passed

Release Details

  • Date: 2025-12-11
  • Version: v1.14.4
  • Commits: 1 (LED manager extraction)
  • XXXXXXX - refactor(led): extract LED control into dedicated led_manager module
  • Files Changed: 7
  • NEW: include/led_manager.h (+138 lines)
  • NEW: src/led_manager.cpp (+76 lines)
  • MODIFIED: src/cosmic_detector.cpp (-31 lines, +6 lines net -25 lines)
  • MODIFIED: src/detection_processor.cpp (+2 lines for led_manager include and namespace qualification)
  • MODIFIED: src/main.cpp (+1 line for led_manager include)
  • MODIFIED: src/main_next.cpp (+1 line for led_manager include)
  • MODIFIED: src/text_command_manager.cpp (+1 line for led_manager include, -3 lines for function name changes)

Design Principles Applied

Single Responsibility Principle (SRP)

Each module has one reason to change:

  • cosmic_detector: Only if GPIO sampling or detection logic changes
  • detection_processor: Only if detection workflow or sensor orchestration changes
  • led_manager: Only if LED control logic or pin mappings change

Before: cosmic_detector mixed detection logic with LED control After: Separate concerns - each module has single responsibility

Separation of Concerns

LED operations are now completely isolated:

  • Detection-based feedback (via DetectionProcessor) is separate from direct control (via commands)
  • LED hardware control is separate from detection logic
  • Command handlers can use LED control without depending on cosmic_detector

High-Level Orchestration

Initialization is now clean:

cosmic_detector_init()  // Initializes detection pins + calls led_init()
  └── led_init()        // Initializes LED pins and sets to OFF

This ensures:

  • Detection pins are ready for GPIO sampling
  • LED pins are configured before any detection processing
  • Clear initialization sequence with no hidden dependencies

Backward Compatibility

Deprecated Functions (Still Available)

The cosmic_detector.h still provides these functions for backward compatibility:

  • cosmic_detector_led_feedback()
  • cosmic_detector_led_off()
  • cosmic_detector_led_set()

These are now implemented in terms of the led_manager functions, providing a compatibility layer. However, new code should use led_manager.h functions directly.

Migration Path (Optional)

For code currently using cosmic_detector_led_*() functions:

  • Option 1 (Recommended): Update includes and function calls to use led_manager.h
// Old: #include "cosmic_detector.h"
// New:
#include "led_manager.h"
led_feedback(hit1, hit2, hit3);  // Instead of cosmic_detector_led_feedback()
  • Option 2: Keep existing code, it continues to work via compatibility layer

Next Steps

  • v1.15.0 (planned): CommandParser class for unified command argument parsing and validation
  • Future: Additional LED manager features (PWM brightness control, blink patterns, etc.)
  • Ongoing: Monitor for opportunities to apply SRP to other monolithic functions