Skip to content

v1.13.1 - CommandQueue & Legacy Protocol Integration (2025-12-09)

What Changed?

This release integrates the CommandQueue Phase 2A system with legacy text/binary protocol support, using compile-time conditional selection. When ENABLE_DEVICE_RESPONSE=1, the firmware uses the new unified CommandQueue system; when disabled, it falls back to the legacy text or binary command protocol. Both systems can now coexist without conflicts through careful header guards and build filtering.

What's New

Main Feature: Unified Protocol System Separation

What it does: Separates CommandQueue (Phase 2A, new) from legacy text/binary protocol systems using compile-time guards and build filtering. This prevents type definition conflicts and circular dependencies while maintaining backward compatibility.

How to use it:

Build CommandQueue mode (unified protocol):

task dev:build  # Uses ENABLE_DEVICE_RESPONSE=1

Build legacy mode (text protocol):

PLATFORMIO_BUILD_FLAGS="-DENABLE_DEVICE_RESPONSE=0" pio run -e esp32dev-release

Implementation details:

Serial protocol header now checks ENABLE_DEVICE_RESPONSE flag:

#if ENABLE_DEVICE_RESPONSE == 0
#if ENABLE_TEXT_COMMAND
#include "text_command.h"    // Legacy text protocol
#else
#include "binary_command.h"  // Legacy binary protocol
#endif
#endif

PlatformIO build filter excludes legacy files in CommandQueue mode:

[env:esp32dev-dev]
build_src_filter =
    +<*>
    -<text_command.cpp>
    -<text_command_manager.cpp>

Installation

Quick Start

# Get the release
git checkout v1.13.1

# Build development environment
task dev:build

# Upload
task dev:upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • Compile-time header guards for protocol selection (serial_protocol.h)
  • PlatformIO build_src_filter configuration for legacy protocol exclusion

🔧 Changed

  • serial_protocol.h: Added ENABLE_DEVICE_RESPONSE == 0 check before including protocol headers
  • serial_protocol.cpp: Protected legacy protocol queue initialization with ENABLE_DEVICE_RESPONSE == 0 guard
  • main.cpp: Protected process_protocol_commands() definition with ENABLE_DEVICE_RESPONSE == 0 guard
  • platformio.ini: Expanded build_src_filter to exclude both text_command.cpp and text_command_manager.cpp

🐛 Fixed

  • Resolved circular dependency between CommandQueue and legacy text protocol systems
  • Fixed type definition conflicts when ENABLE_DEVICE_RESPONSE=1

Is It Safe to Upgrade?

Backward Compatible: Yes

  • No changes to public API or command syntax
  • Legacy text protocol mode (ENABLE_DEVICE_RESPONSE=0) fully functional with all existing code
  • CommandQueue mode (ENABLE_DEVICE_RESPONSE=1) is opt-in via build configuration
  • Production release build uses legacy mode by default (zero impact on existing deployments)

Tests Passed

  • ✅ Production build (esp32dev-release) compiles successfully - ENABLE_DEVICE_RESPONSE=0
  • ✅ Legacy text protocol mode isolated from CommandQueue system
  • ✅ Header includes properly guarded based on ENABLE_DEVICE_RESPONSE flag
  • ✅ Build filtering excludes legacy files in CommandQueue mode

Release Details

  • Date: 2025-12-09
  • Version: v1.13.1
  • Files Changed: 4 (platformio.ini, serial_protocol.h, serial_protocol.cpp, main.cpp)

Next Steps

Phase 2A CommandQueue implementation is now properly isolated from legacy systems. Next release (v1.14.0) will focus on completing the CommandQueue implementation by adding missing static method implementations (receive_line, parse, dispatch) to command_queue.cpp.