Skip to content

v1.17.2 - v1/v2 Codebase Separation (2025-12-15)

What Changed?

This release introduces infrastructure for managing parallel v1 (legacy protocol) and v2 (unified protocol) implementations. All v1-specific files are now prefixed with v1_ and v2-specific files with v2_ to enable clear separation and independent maintenance. This is a pure refactoring with zero functionality changes—all existing behavior remains identical.

What's New

Codebase Organization: v1/v2 Prefix Separation

What it does:

  • v1 files (legacy text/binary protocol): prefixed with v1_ (e.g., v1_main.cpp, v1_cosmic_detector.h)
  • v2 files (unified device response protocol): prefixed with v2_ (e.g., v2_main.cpp, v2_device_response.h)
  • Shared files (adc_sensor, bme280_sensor, etc.): no prefix, used by both versions
  • Build system automatically excludes the unused version via platformio.ini filters

How to use it:

No changes to user-facing behavior. Build commands remain the same:

  • task prod:build — Production release (v1)
  • task dev:build — Development with debug output (v1)
  • task next:build — Unified protocol testing (v2)
  • task wifi:build — WiFi AP mode (v1)

Code example:

; platformio.ini build filters (automatic)
[env:esp32dev-release]     ; v1 build
build_src_filter = +<*> -<v2_*> -<command/*>

[env:esp32dev-next]        ; v2 build
build_src_filter = +<*> -<v1_*>

Installation

Quick Start

# Get the release
git checkout v1.17.2

# Build (same as before)
task prod:build
task next:build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • v1/v2 prefix-based file organization for codebase separation
  • Clear namespace separation enabling parallel maintenance of legacy and unified protocols
  • Documentation structure for tracking v1 and v2 development paths independently

🔧 Changed

  • Internal: All v1 files renamed with v1_ prefix (main.cpp → v1_main.cpp, etc.)
  • Internal: All v2 files renamed with v2_ prefix (main_next.cpp → v2_main.cpp, etc.)
  • Internal: All #include directives updated to reference v1_/v2_ headers
  • Internal: platformio.ini build_src_filter updated to use glob patterns (-<v1_*>, -<v2_*>)

🐛 Fixed

  • None (pure refactoring)

Is It Safe to Upgrade?

Backward Compatible: Yes ✅

  • All build commands remain identical
  • All user-visible functionality unchanged
  • Binary output identical to v1.17.1
  • No hardware or protocol changes

Tests Passed

  • ✅ task prod:build — v1 production release (RAM 8.1%, Flash 26.2%)
  • ✅ task dev:build — v1 development (RAM 8.8%, Flash 26.6%)
  • ✅ task next:build — v2 unified protocol (RAM 31.3%, Flash 27.7%)
  • ✅ task wifi:build — v1 WiFi AP mode (RAM 14.5%, Flash 60.6%)
  • ✅ All pre-commit hooks pass (formatting, trailing whitespace, YAML/JSON)

Release Details

  • Date: 2025-12-15
  • Version: v1.17.2
  • Files Changed: 53 (35 renames, 18 modifications to #include statements)
  • Lines Changed: +131, -151 (net reduction due to simplified build filters)
  • Commit: 9fecd5c — refactor: split v1/v2 codebase with prefix-based file organization

Next Steps

  1. v1 Maintenance Track: Continue bug fixes and incremental improvements to production protocol
  2. v2 Development Track: Stabilize unified device response protocol for v2.0 release
  3. Documentation: Add v1/v2 section to CLAUDE.md explaining the separation
  4. Progress Logs: Create entries in docs/progress/v2/ tracking the unified protocol roadmap

Migration Guide for Developers

If you're working on the codebase:

To modify v1 (legacy protocol):

  • Edit files with v1_ prefix: src/v1_main.cpp, src/v1_text_command_manager.cpp, etc.
  • Include headers with v1_ prefix: #include "v1_cosmic_detector.h"
  • Build with: task prod:build or task dev:build

To modify v2 (unified protocol):

  • Edit files with v2_ prefix: src/v2_main.cpp, src/v2_device_response.cpp, etc.
  • Include headers with v2_ prefix: #include "v2_device_response.h"
  • Build with: task next:build

Shared modules (both v1 and v2):

  • No prefix: src/adc_sensor.cpp, src/bme280_sensor.cpp, etc.
  • Used by both versions without modification