Skip to content

Centralize portable settings persistence - #549

Open
BanjoR wants to merge 3 commits into
DCC-EX:masterfrom
BanjoR:codex/commandstation-portable-settings
Open

BanjoR wants to merge 3 commits into
DCC-EX:masterfrom
BanjoR:codex/commandstation-portable-settings

Conversation

@BanjoR

@BanjoR BanjoR commented Aug 16, 2026

Copy link
Copy Markdown

Summary

This PR defines a platform-neutral persistence boundary for the existing settings store. It is scoped to the persistence access layer and preserves existing settings compatibility.

Related issues:

Superseded fork-only PR: BanjoR/CommandStation-EX#4, now closed in favor of this upstream-targeted PR.

Bounded scope

  • Route existing settings reads, writes, and capacity queries through EEStore::read, EEStore::write, and EEStore::capacity.
  • Permit a board-specific backend to provide EESTORE_READ, EESTORE_WRITE, and EESTORE_CAPACITY hooks while retaining Arduino EEPROM behavior by default.
  • Preserve the legacy EEStoreData byte layout: DCC++1 identifier plus the three 16-bit object counts.
  • Exclude settings migration, a new settings protocol, EEPROM record-stream redesign, automatic data erasure, WiFi credential policy, EXRAIL storage, and any unrelated protocol/traction/integration code.

Validation

Pass:

  • tests/host_eestore_format.ps1 — passed: EEStore host format test passed.

  • python -m platformio run -e mega2560 using isolated task-local PlatformIO directories — passed; firmware linked and produced HEX, RAM 1357/8192 (16.6%), Flash 58190/253952 (22.9%).

  • git diff --check upstream/master...HEAD — passed.

  • Final checkout cleanliness/path audit — passed: clean worktree; only the ten bounded files in the diff; no generated .pio, work, or config.h files; no forbidden/unrelated paths.

  • Direct EEPROM access audit — passed: production call sites use the EEStore boundary; the only remaining EEPROM.* references are the documented default hook definitions.

  • PASS - Exact default python -m platformio run in a clean task checkout with an isolated PlatformIO core completed for all five configured environments: mega2560, ESP32, Nucleo-F411RE, Nucleo-F446RE, and Nucleo-F429ZI.

Exact-head fork CI: PASS - CI run 31951891358 completed successfully for head 0a50786. The upstream PR has no firmware check attached because the main workflow is push-triggered. The C++ host test source contains compile-time layout assertions, but a native host C++ compiler is not installed in this environment; the AVR PlatformIO build validates the shared production format header instead.

Hardware validation

Not run—no hardware available.

Maintainer bench criteria: build with the intended board configuration; flash a Mega2560 or equivalent EEPROM-backed target; load at least one turnout, sensor, and output; issue <E>; power-cycle; verify the same counts and definitions reload; issue <e> and verify a subsequent reboot loads an empty store. For a non-EEPROM target, define the board backend hooks and repeat the same round-trip and clear tests, including capacity reporting and preservation of an existing legacy DCC++1 header.

@BanjoR BanjoR changed the title Add portable persistent settings boundary Centralize portable settings persistence Aug 16, 2026
@BanjoR
BanjoR marked this pull request as ready for review August 17, 2026 09:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant