Skip to content

v1.7.3 - Module Naming Refactor for SRP Compliance (2025-11-22)

What Changed?

This release improves code clarity and maintainability by refactoring module names to accurately reflect their responsibilities (Single Responsibility Principle). The refactoring renames serial_communication to serial_protocol, splits sensor_output into separate data structure and formatting modules, and updates the build configuration flag name from ENABLE_TEXT_COMMANDS to ENABLE_TEXT_PROTOCOL. All changes are mechanical refactoring—no new features or behavior changes. Existing firmware functionality is completely preserved.

What's New

Module Organization: Clearer Responsibility Boundaries

What it does: Refactored the codebase to improve modularity and code readability. Each module now has a single, clearly-defined responsibility that can be understood directly from its name.

Changes:

  1. serial_communication → serial_protocol
  2. More accurately reflects that this module handles protocol selection (binary 3-byte vs. human-readable text)

  3. Name now describes the responsibility: managing different communication protocols

  4. sensor_output split into two focused modules

  5. sensor_data.h: Contains only the sensor_data_t structure definition
  6. sensor_formatter.h: Contains all output formatting functions (SSV/TSV/CSV/JSONL)

  7. Separation of concerns: data definition is separate from formatting logic

  8. Build flag: ENABLE_TEXT_COMMANDS → ENABLE_TEXT_PROTOCOL

  9. More accurate terminology: describes what's being selected (protocol type)
  10. Consistent with module naming improvements

How to use it:

If you have custom build scripts or CI/CD pipelines:

# OLD way (v1.7.2 and earlier)
PLATFORMIO_BUILD_FLAGS="-DENABLE_TEXT_COMMANDS=0" pio run -e esp32dev-release

# NEW way (v1.7.3+)
PLATFORMIO_BUILD_FLAGS="-DENABLE_TEXT_PROTOCOL=0" pio run -e esp32dev-release

All three build profiles (production, debug, development) already use the new flag names in platformio.ini.

Installation

Quick Start

# Get the release
git checkout v1.7.3

# Build (development profile, recommended)
task build

# Upload to device
task upload

# Monitor output
task monitor

Using Different Build Profiles

# Production release (optimized, no text commands)
task prod:build && task prod:upload

# Debug build (with symbols, no text commands)
task debug:build && task debug:upload

# Development (text commands enabled for testing)
task build && task upload

What's Different from the Last Version?

✅ Added

  • None (pure refactoring)

🔧 Changed

  • Renamed serial_communication.h/cpp → serial_protocol.h/cpp for clarity
  • Split sensor_output.h/cpp into sensor_data.h/cpp + sensor_formatter.h/cpp
  • Renamed build flag ENABLE_TEXT_COMMANDS → ENABLE_TEXT_PROTOCOL in platformio.ini
  • Updated all preprocessor directives (#if blocks) to use new flag name
  • Updated CLAUDE.md documentation to reflect module naming changes

🐛 Fixed

  • None (no bugs in this release)

Is It Safe to Upgrade?

Backward Compatible: ⚠️ PARTIALLY

  • Firmware functionality: 100% compatible - behavior is completely unchanged
  • Build configuration: Requires update if you use custom build scripts
  • Update -DENABLE_TEXT_COMMANDS= to -DENABLE_TEXT_PROTOCOL= in your build commands
  • Update #include "serial_communication.h" to #include "serial_protocol.h"
  • Update #include "sensor_output.h" to separate #include "sensor_data.h" and #include "sensor_formatter.h"

Impact on existing users:

  • If you upload pre-built binaries: No changes needed, just upload as usual
  • If you compile from source: No changes needed, all three build profiles work unchanged
  • If you have CI/CD or custom build scripts: Update the flag name -DENABLE_TEXT_COMMANDS → -DENABLE_TEXT_PROTOCOL
  • If you include these modules directly in custom code: Update include paths as noted above

Tests Passed

  • ✅ Production Release build compiles (291 KB binary)
  • ✅ Debug build compiles (292 KB binary)
  • ✅ Development build compiles with all features (306 KB binary)
  • ✅ All builds complete with zero errors and zero warnings
  • ✅ No circular dependencies in split modules
  • ✅ All include paths verified
  • ✅ All preprocessor directives updated and consistent

Release Details

  • Date: 2025-11-22
  • Version: v1.7.3
  • Type: Refactoring (mechanical code organization improvement)
  • Files Changed: 13 files
  • New files: 6 (serial_protocol.h/cpp, sensor_data.h/cpp, sensor_formatter.h/cpp)
  • Modified files: 3 (main.cpp, platformio.ini, CLAUDE.md)
  • Deleted files: 4 (old serial_communication.h/cpp, sensor_output.h/cpp)
  • Documentation: 2 (tasks.md, progress log)

Commits in this release: 8 focused, atomic commits

  1. feat(refactor): add new module files with clearer names and split responsibilities
  2. refactor(main): update includes for renamed and split modules
  3. refactor(config): rename ENABLE_TEXT_COMMANDS to ENABLE_TEXT_PROTOCOL
  4. docs: update CLAUDE.md to reflect module renaming and flag changes
  5. refactor: remove old module files (replaced with renamed/split versions)
  6. refactor: update main.cpp to use ENABLE_TEXT_PROTOCOL flag
  7. docs(tasks): mark all 14 implementation tasks as complete
  8. docs(progress): add Phase I module naming refactor completion log

Next Steps

Phase II Refactoring (v1.8.0+):

  • Rename ENABLE_TEXT_COMMANDS usage in other projects/tools
  • Consider additional module reorganization if new protocols are added
  • Evaluate directory structure refactoring (e.g., src/protocols/, src/formatters/)

Current Roadmap:

  • See REFACTORING_ROADMAP.md for Phase J and beyond

Migration Guide (If You Have Custom Code)

For Custom Builds Using Build Flags

# If you previously used this in your scripts:
-DENABLE_TEXT_COMMANDS=1

# Update to:
-DENABLE_TEXT_PROTOCOL=1

For Code Including These Modules

// OLD (v1.7.2 and earlier)
#include "serial_communication.h"
#include "sensor_output.h"

// NEW (v1.7.3+)
#include "serial_protocol.h"
#include "sensor_data.h"
#include "sensor_formatter.h"

For Preprocessor Conditionals

// OLD
#if ENABLE_TEXT_COMMANDS
  process_text_commands();
#endif

// NEW
#if ENABLE_TEXT_PROTOCOL
  process_text_commands();
#endif

Thank You

This refactoring improves code maintainability and follows best practices (Single Responsibility Principle). The clear module naming makes the codebase more beginner-friendly and easier to extend in the future.

Questions or issues? Open an issue on the GitLab repository.