Skip to content

v1.13.2 - CommandQueue Implementation Completion (2025-12-09)

What Changed?

This release completes Phase 1 of CommandQueue integration by fixing C++ linker errors and refactoring the main loop structure. The CommandQueue system can now be compiled successfully (dev:build) while maintaining full backward compatibility with the legacy protocol mode (prod:build). Detection processing is now properly decoupled from protocol selection.

What's New

Main Fix: CommandQueue Static Method Scope Resolution

What it does: Resolves C++ linker errors caused by scope mismatch between class method declarations and file-scoped implementations. All four private static methods in CommandQueue now properly use class scope (CommandQueue::method_name) instead of file-scoped static declarations.

How to use it: No user-visible changes. Both dev:build (CommandQueue mode) and prod:build (legacy mode) now compile successfully.

Technical details:

The problem was a fundamental C++ scope mismatch:

// ❌ Before: .h declares class method, .cpp implements as file function
// command_queue.h
class CommandQueue {
 private:
  static bool receive_line(char* buffer, size_t buffer_size);  // Class scope
};

// command_queue.cpp
static bool receive_line(char* buffer, size_t buffer_size) {   // File scope
  // Linker error: symbols don't match!
}

// ✅ After: .cpp implementation uses class scope
bool CommandQueue::receive_line(char* buffer, size_t buffer_size) {
  // Now the linker can match the declaration
}

Secondary Improvement: Detection Process Decoupling

What it does: Refactored detection_process() to run unconditionally in the main loop, with internal output format selection based on protocol mode. This separates hardware detection logic (sensor reads, LED feedback) from protocol-specific output serialization.

Design rationale:

  • Detection is core hardware responsibility, independent of protocol system
  • Output serialization is handled by internal guards (lines 206-213)
  • ENABLE_DEVICE_RESPONSE=1: Uses DeviceResponseBuilder::from_event()
  • ENABLE_DEVICE_RESPONSE=0: Uses legacy send_event()
  • This prevents duplication and maintains clear separation of concerns

Installation

Quick Start

# Get the release
git checkout v1.13.2

# Build development (CommandQueue mode)
task build

# Or build production (legacy protocol mode)
task prod:build

# Upload to ESP32
task upload

# Monitor serial output
task monitor

What's Different from the Last Version?

✅ Added

  • (None - Phase 1 completion, no new user-facing features)

🔧 Changed

  • Linker fix: CommandQueue static methods now use proper class scope (CommandQueue::method_name)
  • Loop structure: detection_process() is now unconditional; output format selection is internal
  • Comments: Updated loop comments to clarify protocol selection and detection decoupling

🐛 Fixed

  • Fixed undefined reference linker errors in dev:build (4 symbols)
  • Fixed scope mismatch between .h declarations and .cpp implementations

Is It Safe to Upgrade?

Backward Compatible: Yes

  • prod:build (legacy mode): Fully backward compatible, no changes to detection or output behavior
  • dev:build (CommandQueue mode): Now compiles successfully for the first time
  • Detection behavior unchanged; only internal scope corrections and output format organization

Tests Passed

  • ✅ dev:build compiles successfully (322KB Flash, 27.8KB RAM)
  • ✅ prod:build compiles successfully (307KB Flash, 22.7KB RAM)
  • ✅ No linker errors in either configuration
  • ✅ Both ENABLE_DEVICE_RESPONSE modes build without warnings

Release Details

  • Date: 2025-12-09
  • Version: v1.13.2
  • Files Changed: 2 (src/command_queue.cpp, src/main.cpp)
  • Commits: 2
  • fix(command-queue): Convert static methods to CommandQueue:: scope
  • refactor(main): Make detection_process() unconditional in loop

Next Steps

Phase 2 roadmap (v1.14.0):

  • Create unified process_commands() helper function to simplify loop interface
  • Optimize detection_process() output formatting (avoid event_t→device_response_t conversion)
  • Reorganize setup() initialization sections with clear comments
  • Consider implementing full test coverage for CommandQueue message dispatch