Skip to content

v1.14.2 - DetectionProcessor Header Independence (2025-12-11)

What Changed?

This release refactors the DetectionProcessor header file to be fully independent from cosmic_detector.h. The header now defines its own internal detection_result_t type, eliminating external dependencies while maintaining complete compatibility. This enables cleaner header includes and better separation of concerns for both current and next-generation (ENABLE_DEVICE_RESPONSE=1) firmware.

What's New

Main Feature: Header Independence

What it does: Eliminates the implicit dependency on cosmic_detector.h by moving the detection result type definition into detection_processor.h. The implementation (.cpp file) still uses the cosmic detector functions internally, but the header file has zero external dependencies beyond core types.

Why it matters:

  • Cleaner API: Users only include detection_processor.h for full detection functionality
  • Better encapsulation: Internal implementation details remain hidden
  • Flexible integration: Works seamlessly with both legacy (task dev:build, task prod:build) and next-generation (task next:build) firmware
  • Reduced coupling: Header dependencies are minimized to just config.h

Code example:

// Before (v1.14.1): Implicit dependency on cosmic_detector.h
#include "cosmic_detector.h"        // Required for cosmic_detection_t type
#include "detection_processor.h"    // Uses types from cosmic_detector

// After (v1.14.2): Completely self-contained
#include "detection_processor.h"    // Includes detection_result_t internally
// cosmic_detector.h not needed in header

Installation

Quick Start

# Get the release
git checkout v1.14.2

# 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

  • detection_result_t type - Internal detection result structure defined in detection_processor.h
  • Replaces implicit dependency on cosmic_detection_t from cosmic_detector.h
  • Identical structure but independent definition
  • Fully documented with JSDoc comments

🔧 Changed

  • detection_processor.h refactored - Reduced external dependencies
  • Removed implicit dependency on cosmic_detector.h
  • Now depends only on config.h and standard C types
  • Updated documentation to clarify independence
  • Added "Internal - abstracted from cosmic_detector.h" section

🐛 Fixed

  • Header coupling eliminated - No longer forces inclusion of unrelated headers

Architecture Improvements

Header Dependency Graph

Before (v1.14.1):

detection_processor.h
  └── cosmic_detector.h (implicit via implementation)
      └── Arduino.h
      └── config.h

After (v1.14.2):

detection_processor.h
  ├── config.h (minimal, required)
  └── (cosmic_detector.h only in .cpp implementation)

Clean Separation

The header file now clearly separates:

  1. Public API - DetectionProcessor class interface
  2. Internal Types - detection_result_t (implementation detail, marked @internal)
  3. Documentation - Design philosophy and usage patterns

Is It Safe to Upgrade?

Backward Compatible: ✅ Yes (100% compatible)

  • Zero behavior changes - All detection and processing logic identical
  • No API changes - Public interface unchanged
  • Header-only refactoring - Implementation unaffected
  • 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% (102,352 / 327,680 bytes) - identical to v1.14.1
  • ✅ Flash usage: 27.4% (359,061 / 1,310,720 bytes) - identical to v1.14.1
  • ✅ Header include verification (no unintended dependencies)
  • ✅ Pre-commit hooks: All checks passed
  • ✅ Type safety: detection_result_t correctly defined and used
  • ✅ Detection functionality: All features (ENABLE_TIMESTAMP, BME280, RTC, GNSS) working

Release Details

  • Date: 2025-12-11
  • Version: v1.14.2
  • Commits: 1 (header refactoring)
  • ea8af87 - refactor(detection): add detection_result_t type to detection_processor.h for independence
  • Files Changed: 1
  • MODIFIED: include/detection_processor.h (+27 lines, updated documentation)

Design Principles Applied

Single Responsibility Principle (SRP)

Each module handles one concern:

  • detection_processor.h: Detection API definition and internal types
  • cosmic_detector.h: GPIO-level cosmic ray detection
  • Implementation coupling kept minimal

Dependency Inversion

High-level modules (DetectionProcessor) don't depend on low-level details exposed in headers. Implementation details are hidden in .cpp files.

Minimalist Headers

Headers expose only what's necessary:

  • Public API (DetectionProcessor class)
  • Required types (internal detection_result_t)
  • Configuration (via config.h)

Code Organization

Header Structure (v1.14.2)

#ifndef DETECTION_PROCESSOR_H
#define DETECTION_PROCESSOR_H

#include <stdint.h>
#include <stdbool.h>
#include "config.h"        // ← Only external dependency

#if ENABLE_DEVICE_RESPONSE

// Detection data structures (internal, self-contained)
typedef struct { ... } detection_result_t;

// Public API
class DetectionProcessor { ... };

#endif  // ENABLE_DEVICE_RESPONSE
#endif  // DETECTION_PROCESSOR_H

Implementation Structure (unchanged)

// src/detection_processor.cpp
#include "cosmic_detector.h"  // ← Implementation detail
#include "bme280_sensor.h"
#include "stream_data.h"
// ... other implementation dependencies

Next Steps

  • v1.15.0 (planned): CommandParser class for unified command argument parsing
  • Future: Additional DetectionProcessor features (rate limiting, event filtering)
  • Next-gen roadmap: Full migration of legacy code to unified protocol (ENABLE_DEVICE_RESPONSE=1)