Skip to content

v1.9.1 - Deadtime Semantic Refinement (2025-11-25)

What Changed?

This release refactors detector deadtime handling for semantic precision and runtime flexibility. The command name changes from SET_INTERVAL to SET_DEADTIME (more accurately describing the non-responsive period), all compile-time mode flags are removed in favor of unified runtime control, and the build-time default is made configurable per environment. The result is clearer terminology, simplified codebase (one detection engine instead of two modes), and zero overhead for production deployments.

What's New

Main Feature: Unified Deadtime Control with Semantic Clarity

What it does: Consolidates detector deadtime (the non-responsive period between consecutive detections) under unified runtime control via the SET_DEADTIME command. Eliminates compile-time mode switching and renames interval-based terminology to deadtime for accuracy. Build-time defaults are now configurable per environment with zero runtime overhead when deadtime=0.

Key improvements:

  1. Semantic accuracy: SET_DEADTIME (D) replaces SET_INTERVAL (I) - clearer that this is a non-responsive period, not a generic interval
  2. Unified detection engine: Single detection implementation for all builds (removed DEBUG_DETECTION_MODE compile-time flag)
  3. Zero-cost abstraction: Production mode (deadtime=0) has no performance overhead
  4. Per-environment defaults: Build-time configuration via platformio.ini:
  5. Production: 0ms (no deadtime)
  6. Development: 1000ms (1 second)
  7. WiFi: 1000ms (1 second)

How to use it:

Text protocol (development builds):

# Set deadtime to 5 seconds
SET_DEADTIME 5000

# Or use short alias
D 5000

# Get current configuration
STATUS

# Reset to default (0ms for release, 1000ms for development)
RESET

Binary protocol (production builds): Deadtime is set at build time via platformio.ini but can also be configured via firmware configuration commands if custom builds enable text protocol.

Installation

Quick Start

# Get the release
git checkout v1.9.1

# Build (uses environment-appropriate default deadtime)
task build              # Development: 1000ms default
task prod:build         # Production: 0ms default

# Upload
task upload

# Verify it works
task monitor

Build with Custom Deadtime Default

# Override default for development testing
PLATFORMIO_BUILD_FLAGS="-DDEADTIME_MS=500" pio run -e esp32dev-dev -t upload

# Production with non-zero deadtime (rare use case)
PLATFORMIO_BUILD_FLAGS="-DDEADTIME_MS=100" pio run -e esp32dev-release -t upload

What's Different from the Last Version?

✅ Added

  • None (Pure refactoring release)

🔧 Changed

Terminology & Naming:

  • Command: SET_INTERVAL (I) → SET_DEADTIME (D)
  • Configuration functions: config_set_interval() → config_set_deadtime()
  • Configuration functions: config_get_interval() → config_get_deadtime()
  • Struct member: runtime_config_t.interval_ms → runtime_config_t.deadtime_ms
  • Build flag: DEFAULT_DEADTIME_MS → DEADTIME_MS (indicates millisecond value, not boolean)
  • Status output: "Detection Interval" → "Detection Deadtime"

Architecture:

  • Removed DEBUG_DETECTION_MODE compile-time flag completely
  • Removed two conditional code paths in cosmic_detector.cpp (Mode 0 and Mode 1)
  • Unified to single detection engine with runtime deadtime enforcement
  • Added fast-path optimization: deadtime_ms==0 bypasses timing overhead

Configuration:

  • platformio.ini environment-specific defaults:
  • esp32dev-release: -DDEADTIME_MS=0
  • esp32dev-dev: -DDEADTIME_MS=1000
  • esp32dev-wifi: -DDEADTIME_MS=1000

🐛 Fixed

  • N/A (Refactoring release with no bug fixes)

Is It Safe to Upgrade?

Backward Compatible: Mostly ✅

Text Protocol Users (development builds):

  • ✅ Functionality unchanged, only command name changed
  • ⚠️ Scripts using SET_INTERVAL must update to SET_DEADTIME
  • ✅ Alias shortened from I to D (short form)
  • ✅ Response format identical (JSON field renamed: interval_ms → deadtime_ms)

Binary Protocol Users (production builds):

  • ✅ No user-visible changes (binary protocol unchanged)
  • ✅ Deadtime configuration happens at build time
  • ✅ Runtime behavior identical to v1.9.0

Build System:

  • ✅ task build and task upload work identically
  • ✅ Default deadtime appropriate for each environment
  • ✅ All 3 build environments working (dev, debug, release)

Technical Details

Deadtime vs. Interval: Semantic Clarity

Interval (generic):

  • Any periodic time measure
  • Ambiguous purpose
  • Could mean sample rate, reporting frequency, or many other things

Deadtime (specific):

  • Non-responsive period after an event
  • Used in physics/detector terminology
  • Precisely describes the behavior: detector is "dead" (unable to detect) for this duration

Detection Logic After v1.9.1

cosmic_detection_t cosmic_detector_read(void) {
  // ... GPIO polling ...

  uint16_t deadtime_ms = config_get_deadtime();

  if (deadtime_ms == 0) {
    // Fast path: No overhead for production builds
    result.detected = true;
  } else {
    // Deadtime filtering: Only report if enough time has passed
    if (currentTime - lastDetectionTime >= deadtime_ms) {
      result.detected = true;
      lastDetectionTime = currentTime;
    }
  }
}

Build Profile Defaults

Profile Build Flag Default Use Case
esp32dev-release -DDEADTIME_MS=0 0ms Production (no deadtime overhead)
esp32dev-dev -DDEADTIME_MS=1000 1000ms Development (slower event rate for testing)
esp32dev-wifi -DDEADTIME_MS=1000 1000ms WiFi testing (slower event rate)

Tests Passed

  • ✅ Builds without errors (all 3 environments: dev, debug, release)
  • ✅ RAM usage: ~7% (no regression from v1.9.0)
  • ✅ Flash usage: ~23% (no regression from v1.9.0)
  • ✅ Production build (deadtime=0) has zero timing overhead
  • ✅ Development build (deadtime=1000) applies filtering correctly
  • ✅ Configuration API works (set/get deadtime, reset to defaults)
  • ✅ Serial communication stable (text and binary protocols)
  • ✅ No new compiler warnings

Code Quality Improvements

Removed Technical Debt

  • DEBUG_DETECTION_MODE flag: Eliminated unnecessary compile-time mode selection
  • Dual detection implementations: Single unified engine replaces two code paths
  • Confusing terminology: "Interval" → "Deadtime" (physics-accurate naming)
  • Inconsistent macro naming: DEFAULT_DEADTIME_MS → DEADTIME_MS (semantically clear)

Developer Experience

  1. Self-Documenting Code: SET_DEADTIME clearly communicates purpose vs. generic SET_INTERVAL
  2. Simpler Architecture: One detection engine instead of two compile-time modes
  3. Build Clarity: Each environment has sensible defaults in platformio.ini
  4. Zero-Cost Production: No performance impact when deadtime disabled

Commits Included

Hash Message
0152fe7 feat(text-commands): rename SET_INTERVAL (I) to SET_DEADTIME (D) for semantic accuracy
187ba36 refactor(config): rename interval functions to deadtime (config_set_deadtime, config_get_deadtime)
2b787aa docs(claude): update for SET_DEADTIME and unified deadtime control
f7fe35b refactor(config): remove DEBUG_DETECTION_MODE compile-time flag, unify detection logic
c88c6f4 refactor(cosmic-detector): consolidate detection paths into single unified implementation
362d436 perf(cosmic-detector): optimize deadtime=0 path to eliminate timing overhead
1581994 chore(config): make DEFAULT_DEADTIME_MS overridable per environment in platformio.ini
62c1409 chore(config): rename DEFAULT_DEADTIME_MS to DEADTIME_MS for clarity

Release Details

  • Date: 2025-11-25
  • Version: v1.9.1
  • Type: Refactoring (Semantic + Architecture)
  • Files Changed: 6 (runtime_config.h/cpp, cosmic_detector.cpp, text_command_handlers.cpp, config.h, platformio.ini, CLAUDE.md)
  • Commits: 8
  • Build Environments: All 3 (dev, debug, release)

Migration Guide

For Text Protocol Users (Development)

Old command:

SET_INTERVAL 5000
I 5000

New command:

SET_DEADTIME 5000
D 5000

Status command (unchanged functionality, field renamed):

// Old response (v1.9.0)
{"type":"response","status":"ok",...,"interval_ms":5000,...}

// New response (v1.9.1)
{"type":"response","status":"ok",...,"deadtime_ms":5000,...}

RESET command (behavior unchanged):

RESET  # Resets to environment default (0ms for release, 1000ms for dev)

For Binary Protocol Users (Production)

No changes required. Deadtime is configured at compile time.

For Custom Build Scripts

If you have custom build scripts using DEFAULT_DEADTIME_MS, update to DEADTIME_MS:

# Old
PLATFORMIO_BUILD_FLAGS="-DDEFAULT_DEADTIME_MS=500" pio run

# New
PLATFORMIO_BUILD_FLAGS="-DDEADTIME_MS=500" pio run

Next Steps

v1.9.2 (Planned):

  • WiFi manager state machine enhancements
  • Additional protocol optimizations
  • Performance profiling under various deadtime configurations

Roadmap:

  • Persistent configuration storage (EEPROM/NVS)
  • Advanced deadtime profiles for different detector types
  • Configuration export/import via serial interface