Skip to content

v1.8.10 - Text Protocol Module Refactoring (2025-11-24)

What Changed?

This release consolidates the text protocol layer from 4 files into a unified text_command module with improved encapsulation and reduced dependencies. The refactoring maintains all existing functionality while simplifying the architecture and improving code maintainability. This is an internal architectural improvement with no user-facing changes.

What's New

Module Consolidation: Unified text_command Module

What it does: Consolidates text protocol implementation from 4 files (2 headers, 2 implementations) into a single cohesive text_command module. The new structure uses 1 unified header with 2 implementation files, following a "hybrid consolidation" pattern that balances file size and code organization.

Architecture improvements:

  1. Single Unified Header (include/text_command.h)
  2. All type definitions (text_command_t, command_response_t, command_handler_t, command_entry_t, command_alias_t)
  3. All function declarations

  4. Consistent 8-section organization

  5. Dual Implementation Files

  6. src/text_command.cpp: Protocol layer (serial I/O, queueing, parsing, dispatching) - ~400 lines

  7. src/text_command_handlers.cpp: Command handlers and dispatch tables - ~750 lines

  8. Improved Encapsulation

  9. Removed serial_protocol.h dependency from text_command.cpp
  10. Implemented local text_discard() helper matching binary_command pattern
  11. Command and alias tables exported for inter-file access

Code example (Before and After):

Before (4 files):

include/text_protocol.h + text_protocol_handler.h
src/text_protocol.cpp + text_protocol_handler.cpp

After (3 files):

include/text_command.h
src/text_command.cpp + text_command_handlers.cpp

Installation

Quick Start

# Get the release
git checkout vX.Y.Z

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • Unified text_command.h header consolidating all type definitions and declarations
  • Local text_discard() helper function in text_command.cpp for buffer cleanup
  • File-level documentation notes explaining conditional compilation

🔧 Changed

  • Renamed text_protocol.h/cpp → text_command.h/cpp for consistency with binary_command naming
  • Renamed text_protocol_handler.cpp → text_command_handlers.cpp
  • Consolidated type definitions into single header (previously scattered across 2 headers)
  • Removed serial_protocol.h dependency from text_command.cpp
  • Simplified conditional compilation by relying on PlatformIO build configuration

🐛 Fixed

  • N/A (this is an architectural refactoring with no bug fixes)

Is It Safe to Upgrade?

Backward Compatible: Yes

  • This release is purely an internal architectural refactoring
  • All functionality remains unchanged (100% feature parity with v1.8.9)
  • Both development (text protocol) and production (binary protocol) builds fully supported
  • No changes to serial protocol communication or command interface

Tests Passed

  • ✅ Development build (ENABLE_TEXT_PROTOCOL=1): SUCCESS
  • ✅ Production build (ENABLE_TEXT_PROTOCOL=0): SUCCESS
  • ✅ All 3 commits build cleanly without warnings (except deprecation notices from ArduinoJson library)
  • ✅ Text protocol command interface functional
  • ✅ Binary protocol communication unaffected

Release Details

  • Date: 2025-11-24
  • Version: v1.8.10
  • Files Changed: 7 files (3 created, 4 deleted, 2 modified)
  • Lines Added: 443 | Lines Deleted: 383 (net +60 from reorganization)
  • Commits:
  • e3e772e refactor(text-command): consolidate protocol layer into unified text_command module
  • 46fef0a refactor(text-command): remove serial_protocol.h dependency
  • e35cda2 refactor(text-command): remove compile-time guards from implementation files

Next Steps

Future Improvements

  1. Binary Command Module Optimization: Consider similar encapsulation improvements for binary_command module
  2. Documentation: Update architectural diagrams to reflect unified text_command module structure
  3. Build System: Investigate further optimization of conditional compilation via PlatformIO src_filter

See docs/progress/entries/2025-11-24-text-command-refactoring.md for detailed design and implementation notes.