Skip to content

Progress Log: Protocol Architecture Symmetry (v1.8.6)

Task Description

Implement v1.8.6 refactoring to achieve complete architectural symmetry between binary_protocol and text_protocol layers. This involves:

  1. Phase 1: Removing unused serial wrapper functions (serial_available(), serial_send_response(), serial_send_text_response())
  2. Phase 2: Renaming serial_flush() to serial_discard() for clarity (distinguish from Arduino's Serial.flush())
  3. Phase 3: Moving text protocol queue management from text_protocol_handler.cpp to text_protocol.cpp to match binary_protocol structure
  4. Documentation: Updating REFACTORING_ROADMAP.md and protocol-naming-convention.md

Goal: Both protocols should have identical structure at Layer 2 (Protocol Implementation) with queue management integrated.

Outcome

✅ All phases completed successfully

Phase 1: Unused Function Removal

  • ✅ Deleted serial_available() from serial_protocol.h/cpp (unused wrapper)
  • ✅ Deleted serial_send_response() from serial_protocol.h/cpp (main.cpp usage → Serial.println())
  • ✅ Deleted serial_send_text_response() from text_protocol.h/cpp (text_protocol.cpp usage → Serial.print()/println())

Phase 2: Function Naming Clarity

  • ✅ Renamed serial_flush() → serial_discard() across all call sites:
  • binary_protocol.cpp (2 occurrences)
  • text_protocol.cpp (1 occurrence)
  • ✅ Enhanced docstring: "Discard remaining data in serial input buffer (safe with size limit)"
  • ✅ Clear distinction from Serial.flush() (output buffer synchronization vs input discard)

Phase 3: Text Protocol Queue Integration

  • ✅ Moved text_queue(), text_queued(), text_dequeue() from text_protocol_handler.cpp to text_protocol.cpp
  • ✅ Added declarations to text_protocol.h (in new QUEUE MANAGEMENT section)
  • ✅ Removed declarations from text_protocol_handler.h
  • ✅ Updated text_command_handler_init() to empty function (API compatibility maintained)
  • ✅ Implementation uses same FIFO pattern as binary_protocol (circular buffer with head/tail/count)

Build Verification

  • ✅ task build (esp32dev-dev) compilation success
  • ✅ RAM usage: 7.3% (23912 bytes)
  • ✅ Flash usage: 24.0% (314201 bytes)
  • ✅ No new warnings or errors introduced

Documentation Updates

  • ✅ REFACTORING_ROADMAP.md:
  • Updated v1.8.6 status from "計画中" to "実装中"
  • Added detailed Phase 1-3 completion documentation
  • Added architecture comparison table showing complete symmetry
  • Updated version history with 2025-11-24 entry
  • ✅ docs/protocol-naming-convention.md:
  • Updated Shared Utilities section
  • Enhanced Historical Context with v1.8.6 improvements

Git Commits

  1. a288363 - refactor(serial-protocol): rename serial_flush to serial_discard for clarity
  2. 40e2ddf - docs(binary-protocol, text-protocol): improve reception logic documentation
  3. 91b5c64 - refactor(text-protocol): move queue management from handler to protocol layer
  4. f7d67c8 - docs(refactoring-roadmap): update v1.8.6 progress with architecture improvements
  5. e471d76 - docs(protocol-naming-convention): update for v1.8.6 improvements

Architecture Achievement

Before v1.8.6

binary_protocol vs text_protocol were asymmetric:

  • binary: Queue in serial_protocol.cpp (Layer 2)
  • text: Queue in text_protocol_handler.cpp (Layer 3)
  • Different function naming patterns
  • Unused wrapper functions cluttering API

After v1.8.6

Complete Symmetry Achieved:

Function binary_protocol text_protocol
Reception binary_receive() text_receive()
Line Read binary_receive_line() text_receive_line()
Queue Ops binary_queue() text_queue() ✅
Queue Check binary_queued() text_queued() ✅
Dequeue Exec binary_dequeue() text_dequeue() ✅
Main Loop binary_execute() text_execute()

Layer Structure (Now Symmetric):

  • Layer 1: serial_protocol (shared utilities: serial_init(), serial_discard())
  • Layer 2: binary_protocol/text_protocol (reception + queue management)
  • Layer 3: binary_protocol_handler/text_protocol_handler (validation + execution)

Learnings

Design Insights

  1. Architectural Symmetry: Identical function naming and structure across protocols improves:
  2. Code discoverability (search for binary_* or text_* finds all protocol functions)
  3. Developer onboarding (new developers understand pattern immediately)

  4. Maintenance (adding new protocols follows proven template)

  5. API Surface Reduction: Removing 3 unused wrapper functions:

  6. Reduces cognitive load (fewer functions to understand)
  7. Simplifies API (only essential functions exposed)

  8. Encourages direct Arduino API use where appropriate

  9. Naming Clarity: serial_flush() → serial_discard() distinction:

  10. Arduino Serial.flush() = wait for output buffer transmission (blocking)
  11. Our serial_discard() = discard input buffer data (non-blocking, safe)
  12. Prevents confusion and implementation bugs

Implementation Notes

  • Queue management naturally belongs in Layer 2 (protocol implementation) not Layer 3 (handlers)
  • Both protocols use identical FIFO implementation (circular buffer, 10-item capacity)
  • text_command_handler_init() kept as empty function for API stability (no callers, but avoids link errors)

Next Steps

v1.8.7 (Planned): Continue with remaining naming convention updates

  • Implement [protocol]_[stage]() naming consistently for remaining functions
  • Rename Stage 1-2 functions to complete unified naming scheme
  • Consider creating shared queue abstraction if patterns prove reusable

Long-term: Phase 4 (main.cpp integration) - Update main loop to use final unified function names:

#if ENABLE_TEXT_PROTOCOL
  text_receive();        // Receive and queue
  text_execute();        // Execute queued
#else
  binary_receive();      // Receive and queue
  binary_execute();      // Execute queued
#endif

Summary

v1.8.6 successfully establishes complete architectural symmetry between binary and text protocols through:

  • 3 unused functions removed (cleaner API)
  • 1 function renamed for clarity (better semantics)
  • Queue management unified at Layer 2 (better architecture)
  • Full documentation updated (consistent knowledge)

Result: Maintainable, symmetric protocol layer ready for future extensions.