Version 2 release

[JoshuaDodds]

Release Summary

This PR brings new features other than Modbus mirroring to a production-oriented Maxem/Victron integration layer with replay tooling, tests, and operational docs.

Diff vs origin/main:

• 26 files changed
• 4,214 insertions / 77 deletions

What Changed

• Added a new lib/ core module layout and moved rewrite/mapping logic into reusable modules.
• Extended main.py with a Cerbo MQTT read-only pipeline and integrated rewrite flow.
• Reworked Maxem rewrite behavior to target instantaneous_values (0x5B00 block) while mirroring all other ABB words verbatim.
• Implemented configurable phase-power rewrite modes via CERBO_PHASE_POWER_SOURCE (activein, acout, abb).
• Added signed/net import handling and non-negative phase clamping behavior (CERBO_FORCE_NONNEGATIVE_PHASE_POWER).
• Added coherent 3-phase frame handling and skew guards for MQTT snapshots (CERBO_COHERENT_PHASE_FRAMES, CERBO_COHERENT_PHASE_FRAME_MAX_SKEW_SECONDS).
• Added virtual PV slave emulation (default slave 001) sourced from summed Cerbo PV topics:
  • N/48e7da878d35/solarcharger/283/Pv/0/P
  • N/48e7da878d35/solarcharger/282/Pv/0/P
  • N/48e7da878d35/solarcharger/282/Pv/1/P
• Added PV rewrite for slave 001 instantaneous words (total/phase watts and derived currents) while preserving full register mirroring elsewhere.
• Added dry-run and trace diagnostics for safe live validation (--dry-run-maxem-home, --trace-instantaneous-payload).
• Added timing-safe observability controls:
  • periodic heartbeat logging (STATUS_LOG_INTERVAL_SECONDS)
  • optional suppression of known 1-byte RTU noise log lines (SUPPRESS_SHORT_RTU_REQUEST_LOGS)
  • MQTT protocol/snapshot debug gates.
• Added clean single-Ctrl-C shutdown behavior.
• Added tooling for capture/replay/inspection:
  • tools/dump_register_block.py
  • tools/replay_maxem_preview.py
  • tools/inspect_instantaneous_payload.py
• Added comprehensive test suite and pytest config (29 tests passing).
• Added/updated docs and runbooks for current behavior and validation workflow:
  • README.md
  • docs/decisions/project-conventions.md
  • docs/runbooks/maxem-live-validation.md
  • docs/policies/documentation-and-memory-hygiene.md
  • installation screenshots/manual assets.
• Updated dependencies:
  • added paho-mqtt
  • added dev dependency pytest.
• Updated .gitignore to track lib/ and include repo hygiene patterns.

Validation

• python3 -m pytest -q → 29 passed
• python3 -m py_compile main.py lib/maxem_home_usage.py tests/10_test_maxem_home_usage.py → success
• Dry-run runtime confirms home rewrite lines and PV slave preview lines.

Operational Impact

• Maxem integration now supports:
  • home/grid rewrite semantics from Cerbo Ac/ActiveIn + Ac/Out
  • optional PV meter emulation on slave 001 for Maxem solar discovery/config flows.
• Runtime behavior is feature-flagged and documented in .env and runbooks.

[JoshuaDodds]

##Note

After merging this - make a new v2.0.0-stable release cut from main branch