v1.8.6 - Protocol Architecture Symmetry (2025-11-24)¶

What Changed?¶

This release achieves complete architectural symmetry between binary and text protocol implementations. Three major improvements streamline protocol handling: removing 3 unused serial wrapper functions (cleaner API), renaming serial_flush() to serial_discard() (better naming clarity), and moving text protocol queue management to Layer 2 (better architecture). The result is a maintainable, symmetric protocol layer ready for future protocol extensions.

What's New¶

Main Feature: Symmetric Protocol Architecture¶

What it does: Unifies binary and text protocol function naming and structure using a consistent [protocol]_[stage]() pattern. Both protocols now have identical 3-layer architecture with queue management at Layer 2 (protocol layer), not Layer 3 (handler layer).

Design Pattern:

Binary Protocol (binary_*):

binary_receive() - Read and queue incoming commands
binary_queue(), binary_queued(), binary_dequeue() - FIFO queue management
binary_execute() - Process queued commands

Text Protocol (text_*):

text_receive() - Read and queue incoming commands
text_queue(), text_queued(), text_dequeue() - FIFO queue management
text_execute() - Process queued commands

Shared Utilities (serial_*):

serial_init() - Initialize serial communication
serial_discard() - Safely clear input buffer (replaces confusing serial_flush())

Before v1.8.6 (Asymmetric):

binary_protocol:  Queue in Layer 2 ✓
text_protocol:    Queue in Layer 3 ✗ (inconsistent)
Function naming:  Mixed patterns
Unused functions: serial_available(), serial_send_response(), serial_send_text_response()

After v1.8.6 (Symmetric):

binary_protocol:  Queue in Layer 2 ✓
text_protocol:    Queue in Layer 2 ✓ (moved from Layer 3)
Function naming:  Unified [protocol]_[stage]() pattern
Unused functions: Removed (cleaner API)

Installation¶

Quick Start¶

# Get the release
git checkout v1.8.6

# Build
task build

# Upload
task upload

# Verify it works
task monitor

What's Different from the Last Version?¶

✅ Added¶

Comprehensive protocol naming convention documentation (see docs/protocol-naming-convention.md)
Queue management API at Layer 2 for text protocol: text_queue(), text_queued(), text_dequeue()

🔧 Changed¶

Removed unused functions (3 functions):
serial_available() - Unused wrapper (replaced with direct Serial.available())
serial_send_response() - Unused wrapper (replaced with direct Serial.println())
serial_send_text_response() - Unused wrapper (replaced with direct Serial.print())
Renamed function for clarity:
serial_flush() → serial_discard()
Distinction: Serial.flush() (output buffer sync) vs serial_discard() (input buffer cleanup)
Updated across 3 call sites: binary_protocol.cpp (2x), text_protocol.cpp (1x)
Moved text protocol queue management:
From: text_protocol_handler.cpp (Layer 3)
To: text_protocol.cpp (Layer 2)
Achieves architectural parity with binary protocol

🐛 Fixed¶

N/A (Refactoring release with no bug fixes)

Architecture Achievement¶

3-Layer Protocol Architecture (Now Symmetric)¶

Layer	Responsibility	Binary	Text
Layer 1	Shared serial I/O	`serial_init()`, `serial_discard()`
Layer 2	Reception + Queue	`binary_receive()`, `binary_queue()`	`text_receive()`, `text_queue()` ✅
Layer 3	Validation + Dispatch	`binary_validate()`, `binary_response_*()`	`text_dispatch()`, `text_response_*()`

Function Naming Convention¶

All protocol functions follow [protocol]_[stage]() pattern:

[protocol]: binary, text, or serial
[stage]: receive, queue, queued, dequeue, execute, validate, dispatch, response_ok, response_error, parse, etc.

Example: text_queue(), binary_execute(), serial_discard()

Is It Safe to Upgrade?¶

Backward Compatible: Mostly ✅

Text protocol users: No changes to functionality, only internal architecture improvements
Binary protocol users: No changes to functionality
Build system: task build and task upload work identically
Serial output: Unchanged format
Note: Internal function names changed; only relevant if you have custom code calling these functions

Tests Passed¶

✅ Builds without errors (all 3 environments: dev, debug, release)
✅ RAM usage: 7.3% (23,912 bytes) - No regression
✅ Flash usage: 24.0% (314,201 bytes) - No regression
✅ No new compiler warnings or errors
✅ Serial communication stable (text and binary protocols tested)

Code Quality Improvements¶

Removed Technical Debt¶

3 unused wrapper functions eliminated
Clearer function naming reduces confusion between Arduino API and local utilities
Symmetric architecture simplifies code review and onboarding

Developer Experience¶

Self-Documenting Code: Function names (text_queue(), binary_execute()) clearly communicate purpose
Consistent Patterns: New protocol implementations follow proven [protocol]_[stage]() template
Easier Search: Find all protocol functions with prefix search (e.g., text_*)
Clear API Surface: Only essential functions exposed; wrapper clutter removed

Commits Included¶

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

Release Details¶

Date: 2025-11-24
Version: v1.8.6
Type: Refactoring (Internal Architecture)
Files Changed: 8 (header + implementation files)
Commits: 5
Build Environments: All 3 (dev, debug, release)

Next Steps¶

v1.8.7 (Planned):

Complete remaining naming convention updates for Stage 1-2 functions
Consider shared queue abstraction if patterns prove reusable across protocols
Evaluate additional protocol implementations using new symmetric pattern

Long-term Roadmap:

Phase 4: Update main.cpp to use final unified function names
Phase 5: WiFi protocol integration following same [protocol]_[stage]() pattern
Phase 6: Code generation tooling for new protocol implementations