Skip to content

v1.8.3 - Serial Protocol Reliability Refactoring (2025-11-23)

What Changed?

This release refactors the serial command reception from custom byte-by-byte reading to Arduino's Serial.readBytesUntil() API. The new implementation is simpler (64% code reduction), more reliable (500ms timeout), and safer (buffer overflow protection). All user-facing behavior remains unchanged—complete backward compatibility with existing commands.

What's New

Main Feature: Improved Serial Command Reception

What it does:

Replaces custom serial line-reading logic with Arduino's built-in Serial.readBytesUntil() API for more robust command reception. The new implementation:

  • Uses standard Arduino API instead of custom byte loops
  • Implements reliable 500ms timeout for incomplete commands
  • Protects against buffer overflow (63-byte limit)
  • Supports cross-platform line endings (Unix \n, Windows \r\n, Mac \r)

How to use it:

No changes required! Send commands exactly as before:

  1. Open Serial Monitor at 115200 baud
  2. Select "NL" (newline) line ending
  3. Type commands: STATUS, SET_POLL_COUNT 150, etc.
  4. Commands process identically to previous versions

Code example:

// Before: ~55 lines of custom byte-by-byte logic
// After: ~20 lines using Serial.readBytesUntil()

Serial.setTimeout(SERIAL_READ_TIMEOUT_MS);
size_t bytes_read = Serial.readBytesUntil('\n', buffer, CMD_MAX_LENGTH);

// Overflow detection: if 63 bytes without newline, flush and reject
if (bytes_read == CMD_MAX_LENGTH) {
  while (Serial.available()) Serial.read();  // Flush remaining
  return false;  // Reject command
}

Installation

Quick Start

# Get the release
git checkout v1.8.3

# Build
task dev:build

# Upload
task dev:upload

# Test
task monitor

What's Different from the Last Version?

✅ Added

  • SERIAL_READ_TIMEOUT_MS constant (500ms timeout for line reception)
  • CMD_BUFFER_SIZE and CMD_MAX_LENGTH constants for buffer management
  • serial_command_t data structure for command representation
  • Comprehensive docstrings and inline comments explaining timeout/overflow behavior
  • Full quickstart testing guide with 8 test procedures

🔧 Changed

  • serial_read_text_command(): Replaced custom loop with Serial.readBytesUntil() (55 → 20 lines)
  • Timeout handling: Now uses Serial.setTimeout() instead of manual timing
  • Buffer overflow: Automatic flush on 63-byte overflow detection
  • Line ending support: Unified trim logic handles \n, \r\n, and \r

🐛 Fixed

  • Improved reliability of incomplete command detection
  • Eliminated edge cases in custom byte-reading logic
  • Better handling of slow data arrival (incremental reception)
  • Safe recovery from buffer overflow without command corruption

Is It Safe to Upgrade

Backward Compatible: ✅ Yes (100% compatible)

  • No breaking API changes
  • Function signature unchanged: bool serial_read_text_command(char* buffer, int buffer_size)
  • All commands work identically
  • Response format unchanged (JSON still sent via serial)
  • No changes to command syntax or behavior

Impact on existing users

  • Zero impact - Commands behave exactly as before
  • No new configuration required
  • No changes to serial monitor settings needed
  • All existing firmware features work unchanged

Tests Passed

  • ✅ Builds without errors (SUCCESS at 6.30s)
  • ✅ Test 1: Complete command reception (STATUS → JSON response)
  • ✅ Test 2: Command with arguments (SET_POLL_COUNT 150 → confirmation)
  • ✅ Test 3: Partial command timeout (no response after 500ms)
  • ✅ Test 4: Buffer overflow rejection (70 bytes safely rejected)
  • ✅ Test 5: Cross-platform line endings (NL, CR+LF, CR all work)
  • ✅ Test 6: Empty command rejection (silent, no error)
  • ✅ Test 7: Rapid command queue (FIFO order preserved)
  • ✅ Test 8: Case insensitivity (lowercase/mixed case work)
  • ✅ Flash usage: 23.9% (no significant increase)
  • ✅ RAM usage: 7.3% (optimal)

Release Details

  • Date: 2025-11-23
  • Version: v1.8.3
  • Files Changed: 3 (config.h, serial_protocol.h, serial_protocol.cpp)
  • Commits: e794517, 9887b74, 2655837, 9cae7a4, afa546a
  • Lines Changed: ~55 → ~20 in serial_read_text_command() (64% reduction)

Next Steps

  • v1.9.0: RTC (Real-Time Clock) feature for event timestamping
  • Future: Additional serial protocol enhancements based on user feedback
  • Roadmap: See REFACTORING_ROADMAP.md