mk2vsc 0.1.2__tar.gz

mk2vsc-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle Hart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mk2vsc-0.1.2/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: mk2vsc
+Version: 0.1.2
+Summary: Read, verify, edit and diff Victron VEConfigure .rvms configuration files without VEConfigure
+Author: Kyle Hart
+License: MIT
+Project-URL: Homepage, https://github.com/kylehart/mk2vsc
+Keywords: victron,veconfigure,rvms,rvsc,ve.bus,multiplus,quattro,ess
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# mk2vsc
+
+Read, validate, decode, diff, edit and qualify Victron VEConfigure `.rvms` configuration files
+without VEConfigure, on any operating system, from Python or the command line.
+
+## The problem
+
+Victron MultiPlus and Quattro inverter/chargers are configured with VEConfigure and VE.Bus System
+Configurator. Those tools run only on Windows. VictronConnect is replacing them but does not support
+assistants (ESS, AC PV and the rest), so anyone maintaining a real installation still needs a Windows
+machine or a virtual machine. The configuration itself travels as a small binary file: `.rvsc` for a
+single unit, `.rvms` for parallel and multi-phase systems, downloaded and uploaded through VRM's Remote
+VEConfigure. A Victron Community thread titled "RVSC File Format Specification" asked Victron to publish
+the format so people could write their own editors; it received no answer. As of September 2026 we
+found no open-source parser, specification or editor for these files anywhere.
+
+We operate four two-inverter systems and needed to change charge voltages and Virtual Switch
+thresholds on them remotely, repeatably, and with a record of what changed. This repository is what we
+built to do that, together with everything we learned about the file along the way.
+
+## What this is
+
+* A zero-dependency Python 3.9+ library and a CLI (`mk2vsc`) that:
+  * parses the file's section structure and verifies every integrity checksum,
+  * decodes the per-inverter settings array into labelled values with a confidence level per field,
+  * compares two files by inverter serial and tells you whether they differ only in bookkeeping,
+  * edits settings in place, self-verifies that nothing else changed, and never changes file length,
+  * qualifies a file against the values you intended before you upload and after you re-download,
+  * mines a library of archived downloads into a dated, per-inverter change log (`mk2vsc history`).
+* A corpus of 84 real device files with a manifest, and a test suite that checks every documented
+  claim against that corpus (468 tests).
+* A written account of the format as we understand it, and of what we do not understand.
+
+## What this is not
+
+* It does not upload anything. You upload through VRM, exactly as before.
+* It does not install assistants (ESS and others) as a supported operation. The experimental graft and
+  upload-form transform are included under `mk2vsc.experimental`, gated, and have never produced a running
+  system; docs/ESS_INJECTION.md is the complete record for anyone who wants to pick that up.
+* It does not touch grid codes or the dealer password that protects them.
+* It is not affiliated with or endorsed by Victron Energy.
+
+## Status and confidence
+
+| Capability | Status | Evidence |
+|---|---|---|
+| Section grammar and integrity checksum | Proven | Validates on every section of all 84 fixture files (107 counting archive duplicates); edited files accepted by the device on 4 systems |
+| Settings array = VE.Bus setting IDs at +0x59 + 2n | High | Reference IDs reproduce 120 V output, 50.0 A limit, 95 %/98 % SoC, grid-code flag on all 162 blocks of the 81 well-formed fixtures |
+| Field table (190 entries) | Partial | 4 CONFIRMED, 10 HIGH, 9 MEDIUM, 19 LOW, 20 UNKNOWN named; the rest unnamed |
+| Guarded writer (`mk2vsc set`) | Proven live | Absorption, float and Virtual Switch thresholds written and read back on 4 systems, July to August 2026 |
+| By-serial diff (`mk2vsc diff`) | Proven | Consecutive downloads, including a pair whose blocks swapped position, classify as bookkeeping only |
+| Qualifier (`mk2vsc qualify`) | Proven | Reproduces the incident that motivated it (a rollback that reverted a charge-voltage fix) |
+| Assistant area | Read only | Record structure and stub signature recognised; record bodies not understood |
+| Upload-form (GUI export) files | Read only | Detected and decoded; the writer refuses them |
+| ESS injection (`mk2vsc experimental`) | Experimental, never ran | Graft and device-to-upload-form transform reproduce the August 2026 files byte-for-byte; the device stored them, the system never started |
+
+The confidence vocabulary (CONFIRMED, HIGH, MEDIUM, LOW, UNKNOWN) is defined in `mk2vsc/fields.py` and
+docs/FIELDS.md. The writer edits CONFIRMED and HIGH fields; anything lower needs an explicit override.
+
+## Install
+
+```
+git clone <this repository>
+cd mk2vsc
+python3 -m venv .venv && .venv/bin/pip install -e ".[test]"
+.venv/bin/pytest          # 468 tests against the fixture corpus
+```
+
+Or run without installing: `PYTHONPATH=. python3 -m mk2vsc.cli ...`.
+
+## Quickstart
+
+```
+mk2vsc info fixtures/mango/mango_2026-07-24_download_bare_deviceform_1.rvms
+```
+```
+format 1.33  length 5055  checksums OK
+  HQ24149MY9U  fw 2729560  form=device  flag=f5  saved 2026-07-24T22:49:20+00:00  assistant: no assistant
+      flags0                          33268 bitmask [HIGH] (+0x059)
+      flags1                          19966 bitmask [HIGH] (+0x05b)
+      absorption_V                     56.8 V    [CONFIRMED] (+0x05d)
+      float_V                          54.0 V    [CONFIRMED] (+0x05f)
+      charge_current_A                   35 A    [HIGH] (+0x061)
+      ...
+```
+
+Two downloads of the same system a few minutes apart differ only in bookkeeping (pointer, save
+timestamp, checksum), even though the two inverter blocks may have swapped position in the file:
+
+```
+mk2vsc diff fixtures/mango/mango_2026-07-24_download_bare_deviceform_1.rvms \
+          fixtures/mango/mango_2026-07-24_download_bare_deviceform_2.rvms
+```
+```
+lengths 5055 -> 5055; prologue same; verdict: ONLY BOOKKEEPING (settings verbatim)
+  HQ2240FKJDE: len 482->482 form device->device bookkeeping=6B header=0B assistant=0B
+  HQ24149MY9U: len 482->482 form device->device bookkeeping=6B header=0B assistant=0B
+```
+
+Edit a setting on every inverter, then check the result against what you intended:
+
+```
+mk2vsc set fixtures/guava/guava_2026-07-20_download_bare_deviceform_1.rvms /tmp/prepared.rvms \
+         absorption_V=56.8 float_V=54.0
+mk2vsc qualify /tmp/prepared.rvms --intent examples/intent.example.json
+```
+```
+HQ2414U6FVN  absorption_V  56.0 -> 56.8 V  (+0x05d / file 0x1056)
+HQ2414AXENJ  absorption_V  57.6 -> 56.8 V  (+0x05d / file 0x123a)
+...
+wrote /tmp/prepared.rvms; verified: only the listed bytes and their section checksums changed
+/tmp/prepared.rvms: QUALIFIED
+  ok   all section checksums valid
+  ok   serials match the intended system
+  ok   absorption_V = 56.8 on all inverters
+  ok   float_V = 54.0 on all inverters
+```
+
+Every command: `info`, `validate`, `decode`, `diff`, `set`, `qualify`, `fix`, `fields`, `census`,
+`history`. `mk2vsc --help` and `mk2vsc <command> --help` describe the options.
+
+From Python:
+
+```python
+from mk2vsc import RvmsFile, units_by_serial, set_settings, diff_bytes
+
+data = open("download.rvms", "rb").read()
+print(units_by_serial(RvmsFile.parse(data))["HQ2414U6FVN"].setting(2) / 100)   # absorption, volts
+out, edits = set_settings(data, [(None, "absorption_V", 56.8)])                # None = every inverter
+assert not diff_bytes(data, out).only_bookkeeping                               # the setting changed
+open("prepared.rvms", "wb").write(out)
+```
+
+See examples/edit_and_verify.py for the full loop.
+
+## The change-control loop
+
+Uploading a file replaces the whole configuration of every inverter in the system. These five steps
+are how we make that safe; docs/CHANGE_CONTROL.md explains each one and the incident behind it.
+
+1. Download a fresh file from VRM (Remote VEConfigure) into `00_baseline/`. Never start from an
+   archived copy: the device rejects stale save timestamps, and old files carry old values.
+2. `mk2vsc set` the baseline into `01_prepared/`, then `mk2vsc qualify` it against an intent file that
+   lives outside the file under test.
+3. Upload `01_prepared/` through VRM.
+4. Download again into `02_downloaded/`.
+5. `mk2vsc diff` prepared against downloaded (expect "ONLY BOOKKEEPING") and `mk2vsc qualify` the
+   download. "Success" in the upload dialog is not the same as "the settings are right".
+
+## Corpus and tests
+
+The `fixtures/` directory holds 84 unique files from 4 split-phase MultiPlus systems (8 inverters,
+firmware 2729560, format version 1.33) collected between June and September 2026, including device
+downloads, GUI exports, files our tools produced, and three deliberately broken files kept as negative
+controls. `fixtures/manifest.json` records each file's hash, origin, state and inverters. The tests in
+`tests/` check structure, checksums, byte-exact round trips, every documented field claim, the writer,
+the diff, the qualifier and the CLI against that corpus. docs/QA.md describes how to verify the same
+things on your own system before trusting the tool with it.
+
+## Documentation
+
+| File | Contents |
+|---|---|
+| docs/FORMAT.md | The file format as we understand it: sections, checksum, unit block layout, device vs upload form, assistant area |
+| docs/FIELDS.md | The settings table: every field's offset, label, scale, confidence, presumed purpose and evidence |
+| docs/CHANGE_CONTROL.md | The baseline / prepared / downloaded pattern, the rules, and the incidents that produced them |
+| docs/WORKFLOW.md | Working with VRM Remote VEConfigure, and what still needs the Windows GUI |
+| docs/SAFETY.md | Responsible use, the proven-safe surface, recovery, first-use protocol |
+| docs/QA.md | How to decide whether to trust this: the test suite, the corpus, and a verify-it-yourself recipe |
+| docs/ASSISTANTS.md | What we know and do not know about ESS and other assistants in the file |
+| docs/ERRORS.md | What mk2vsc-36, mk2vsc-47, mk2vsc-49, Error 1303 and the VE.Bus errors mean |
+| docs/HISTORY.md | How this came to be, in order, including the things we got wrong |
+| docs/ESS_INJECTION.md | The ESS-by-file experiment in full: what a GUI install writes, every attempt, hypotheses, the next test |
+| docs/FIXTURES.md | What every file in the corpus is |
+| docs/PRACTICES.md | How the project is run: public record, evidence rules, safety rules, AI-assistance disclosure |
+
+## Limits and unknowns
+
+* We hold files from one firmware (2729560), one format version (1.33), one product family, one
+  topology (two inverters, split phase). Other hardware may differ; the tests will tell you.
+* We have no `.rvsc` single-unit files and no three-phase or three-plus-unit files.
+* About two thirds of the settings array is unnamed or named with low confidence. docs/FIELDS.md
+  lists what each value looks like even where we cannot say what it does.
+* The assistant record bodies, the 4001-byte BareSettingInfo section and parts of the block header
+  are not understood. docs/FORMAT.md keeps an explicit Observed / Inferred / Unknown list.
+* Installing an assistant by file has never produced a running system for us. docs/ASSISTANTS.md
+  records each attempt and its outcome so nobody has to repeat them on live hardware.
+
+## How to help
+
+The most useful contributions are files and controlled pairs, not code:
+
+* A download, one setting changed in VEConfigure, and a second download, plus a screenshot of the
+  VEConfigure tab showing the value. One such pair names a field for everyone.
+* Files from other hardware: Quattro, other firmware, three-phase, single-unit `.rvsc`.
+* Running the verify-it-yourself recipe in docs/QA.md on your system and reporting what happened.
+
+See CONTRIBUTING.md for how to add a fixture and what the privacy expectations are.
+
+## License and responsible use
+
+MIT, see LICENSE. This tool is for people who are already responsible for, and authorized to
+configure, the systems they apply it to. It produces files; the decision to upload one, and the
+consequences on a live battery system, remain yours. Read docs/SAFETY.md first.
+
+## How this project is run
+
+Every change goes through a public pull request, every open question is a labelled issue, and every
+format claim is tied to a test on real files. The project is developed with AI assistance, disclosed
+in commits and in docs/PRACTICES.md.
+
+## Acknowledgements
+
+* github.com/xcellsior/ve-bus-programming documented the VE.Bus setting IDs and scales over the MK2/MK3
+  protocol; that table is what let us name most of the settings array.
+* The Victron Community threads on `.rvsc`/`.rvms` files, Remote VEConfigure and the "switch as group"
+  error saved us time and confirmed the demand for this work.

mk2vsc-0.1.2/README.md

@@ -0,0 +1,217 @@
+# mk2vsc
+
+Read, validate, decode, diff, edit and qualify Victron VEConfigure `.rvms` configuration files
+without VEConfigure, on any operating system, from Python or the command line.
+
+## The problem
+
+Victron MultiPlus and Quattro inverter/chargers are configured with VEConfigure and VE.Bus System
+Configurator. Those tools run only on Windows. VictronConnect is replacing them but does not support
+assistants (ESS, AC PV and the rest), so anyone maintaining a real installation still needs a Windows
+machine or a virtual machine. The configuration itself travels as a small binary file: `.rvsc` for a
+single unit, `.rvms` for parallel and multi-phase systems, downloaded and uploaded through VRM's Remote
+VEConfigure. A Victron Community thread titled "RVSC File Format Specification" asked Victron to publish
+the format so people could write their own editors; it received no answer. As of September 2026 we
+found no open-source parser, specification or editor for these files anywhere.
+
+We operate four two-inverter systems and needed to change charge voltages and Virtual Switch
+thresholds on them remotely, repeatably, and with a record of what changed. This repository is what we
+built to do that, together with everything we learned about the file along the way.
+
+## What this is
+
+* A zero-dependency Python 3.9+ library and a CLI (`mk2vsc`) that:
+  * parses the file's section structure and verifies every integrity checksum,
+  * decodes the per-inverter settings array into labelled values with a confidence level per field,
+  * compares two files by inverter serial and tells you whether they differ only in bookkeeping,
+  * edits settings in place, self-verifies that nothing else changed, and never changes file length,
+  * qualifies a file against the values you intended before you upload and after you re-download,
+  * mines a library of archived downloads into a dated, per-inverter change log (`mk2vsc history`).
+* A corpus of 84 real device files with a manifest, and a test suite that checks every documented
+  claim against that corpus (468 tests).
+* A written account of the format as we understand it, and of what we do not understand.
+
+## What this is not
+
+* It does not upload anything. You upload through VRM, exactly as before.
+* It does not install assistants (ESS and others) as a supported operation. The experimental graft and
+  upload-form transform are included under `mk2vsc.experimental`, gated, and have never produced a running
+  system; docs/ESS_INJECTION.md is the complete record for anyone who wants to pick that up.
+* It does not touch grid codes or the dealer password that protects them.
+* It is not affiliated with or endorsed by Victron Energy.
+
+## Status and confidence
+
+| Capability | Status | Evidence |
+|---|---|---|
+| Section grammar and integrity checksum | Proven | Validates on every section of all 84 fixture files (107 counting archive duplicates); edited files accepted by the device on 4 systems |
+| Settings array = VE.Bus setting IDs at +0x59 + 2n | High | Reference IDs reproduce 120 V output, 50.0 A limit, 95 %/98 % SoC, grid-code flag on all 162 blocks of the 81 well-formed fixtures |
+| Field table (190 entries) | Partial | 4 CONFIRMED, 10 HIGH, 9 MEDIUM, 19 LOW, 20 UNKNOWN named; the rest unnamed |
+| Guarded writer (`mk2vsc set`) | Proven live | Absorption, float and Virtual Switch thresholds written and read back on 4 systems, July to August 2026 |
+| By-serial diff (`mk2vsc diff`) | Proven | Consecutive downloads, including a pair whose blocks swapped position, classify as bookkeeping only |
+| Qualifier (`mk2vsc qualify`) | Proven | Reproduces the incident that motivated it (a rollback that reverted a charge-voltage fix) |
+| Assistant area | Read only | Record structure and stub signature recognised; record bodies not understood |
+| Upload-form (GUI export) files | Read only | Detected and decoded; the writer refuses them |
+| ESS injection (`mk2vsc experimental`) | Experimental, never ran | Graft and device-to-upload-form transform reproduce the August 2026 files byte-for-byte; the device stored them, the system never started |
+
+The confidence vocabulary (CONFIRMED, HIGH, MEDIUM, LOW, UNKNOWN) is defined in `mk2vsc/fields.py` and
+docs/FIELDS.md. The writer edits CONFIRMED and HIGH fields; anything lower needs an explicit override.
+
+## Install
+
+```
+git clone <this repository>
+cd mk2vsc
+python3 -m venv .venv && .venv/bin/pip install -e ".[test]"
+.venv/bin/pytest          # 468 tests against the fixture corpus
+```
+
+Or run without installing: `PYTHONPATH=. python3 -m mk2vsc.cli ...`.
+
+## Quickstart
+
+```
+mk2vsc info fixtures/mango/mango_2026-07-24_download_bare_deviceform_1.rvms
+```
+```
+format 1.33  length 5055  checksums OK
+  HQ24149MY9U  fw 2729560  form=device  flag=f5  saved 2026-07-24T22:49:20+00:00  assistant: no assistant
+      flags0                          33268 bitmask [HIGH] (+0x059)
+      flags1                          19966 bitmask [HIGH] (+0x05b)
+      absorption_V                     56.8 V    [CONFIRMED] (+0x05d)
+      float_V                          54.0 V    [CONFIRMED] (+0x05f)
+      charge_current_A                   35 A    [HIGH] (+0x061)
+      ...
+```
+
+Two downloads of the same system a few minutes apart differ only in bookkeeping (pointer, save
+timestamp, checksum), even though the two inverter blocks may have swapped position in the file:
+
+```
+mk2vsc diff fixtures/mango/mango_2026-07-24_download_bare_deviceform_1.rvms \
+          fixtures/mango/mango_2026-07-24_download_bare_deviceform_2.rvms
+```
+```
+lengths 5055 -> 5055; prologue same; verdict: ONLY BOOKKEEPING (settings verbatim)
+  HQ2240FKJDE: len 482->482 form device->device bookkeeping=6B header=0B assistant=0B
+  HQ24149MY9U: len 482->482 form device->device bookkeeping=6B header=0B assistant=0B
+```
+
+Edit a setting on every inverter, then check the result against what you intended:
+
+```
+mk2vsc set fixtures/guava/guava_2026-07-20_download_bare_deviceform_1.rvms /tmp/prepared.rvms \
+         absorption_V=56.8 float_V=54.0
+mk2vsc qualify /tmp/prepared.rvms --intent examples/intent.example.json
+```
+```
+HQ2414U6FVN  absorption_V  56.0 -> 56.8 V  (+0x05d / file 0x1056)
+HQ2414AXENJ  absorption_V  57.6 -> 56.8 V  (+0x05d / file 0x123a)
+...
+wrote /tmp/prepared.rvms; verified: only the listed bytes and their section checksums changed
+/tmp/prepared.rvms: QUALIFIED
+  ok   all section checksums valid
+  ok   serials match the intended system
+  ok   absorption_V = 56.8 on all inverters
+  ok   float_V = 54.0 on all inverters
+```
+
+Every command: `info`, `validate`, `decode`, `diff`, `set`, `qualify`, `fix`, `fields`, `census`,
+`history`. `mk2vsc --help` and `mk2vsc <command> --help` describe the options.
+
+From Python:
+
+```python
+from mk2vsc import RvmsFile, units_by_serial, set_settings, diff_bytes
+
+data = open("download.rvms", "rb").read()
+print(units_by_serial(RvmsFile.parse(data))["HQ2414U6FVN"].setting(2) / 100)   # absorption, volts
+out, edits = set_settings(data, [(None, "absorption_V", 56.8)])                # None = every inverter
+assert not diff_bytes(data, out).only_bookkeeping                               # the setting changed
+open("prepared.rvms", "wb").write(out)
+```
+
+See examples/edit_and_verify.py for the full loop.
+
+## The change-control loop
+
+Uploading a file replaces the whole configuration of every inverter in the system. These five steps
+are how we make that safe; docs/CHANGE_CONTROL.md explains each one and the incident behind it.
+
+1. Download a fresh file from VRM (Remote VEConfigure) into `00_baseline/`. Never start from an
+   archived copy: the device rejects stale save timestamps, and old files carry old values.
+2. `mk2vsc set` the baseline into `01_prepared/`, then `mk2vsc qualify` it against an intent file that
+   lives outside the file under test.
+3. Upload `01_prepared/` through VRM.
+4. Download again into `02_downloaded/`.
+5. `mk2vsc diff` prepared against downloaded (expect "ONLY BOOKKEEPING") and `mk2vsc qualify` the
+   download. "Success" in the upload dialog is not the same as "the settings are right".
+
+## Corpus and tests
+
+The `fixtures/` directory holds 84 unique files from 4 split-phase MultiPlus systems (8 inverters,
+firmware 2729560, format version 1.33) collected between June and September 2026, including device
+downloads, GUI exports, files our tools produced, and three deliberately broken files kept as negative
+controls. `fixtures/manifest.json` records each file's hash, origin, state and inverters. The tests in
+`tests/` check structure, checksums, byte-exact round trips, every documented field claim, the writer,
+the diff, the qualifier and the CLI against that corpus. docs/QA.md describes how to verify the same
+things on your own system before trusting the tool with it.
+
+## Documentation
+
+| File | Contents |
+|---|---|
+| docs/FORMAT.md | The file format as we understand it: sections, checksum, unit block layout, device vs upload form, assistant area |
+| docs/FIELDS.md | The settings table: every field's offset, label, scale, confidence, presumed purpose and evidence |
+| docs/CHANGE_CONTROL.md | The baseline / prepared / downloaded pattern, the rules, and the incidents that produced them |
+| docs/WORKFLOW.md | Working with VRM Remote VEConfigure, and what still needs the Windows GUI |
+| docs/SAFETY.md | Responsible use, the proven-safe surface, recovery, first-use protocol |
+| docs/QA.md | How to decide whether to trust this: the test suite, the corpus, and a verify-it-yourself recipe |
+| docs/ASSISTANTS.md | What we know and do not know about ESS and other assistants in the file |
+| docs/ERRORS.md | What mk2vsc-36, mk2vsc-47, mk2vsc-49, Error 1303 and the VE.Bus errors mean |
+| docs/HISTORY.md | How this came to be, in order, including the things we got wrong |
+| docs/ESS_INJECTION.md | The ESS-by-file experiment in full: what a GUI install writes, every attempt, hypotheses, the next test |
+| docs/FIXTURES.md | What every file in the corpus is |
+| docs/PRACTICES.md | How the project is run: public record, evidence rules, safety rules, AI-assistance disclosure |
+
+## Limits and unknowns
+
+* We hold files from one firmware (2729560), one format version (1.33), one product family, one
+  topology (two inverters, split phase). Other hardware may differ; the tests will tell you.
+* We have no `.rvsc` single-unit files and no three-phase or three-plus-unit files.
+* About two thirds of the settings array is unnamed or named with low confidence. docs/FIELDS.md
+  lists what each value looks like even where we cannot say what it does.
+* The assistant record bodies, the 4001-byte BareSettingInfo section and parts of the block header
+  are not understood. docs/FORMAT.md keeps an explicit Observed / Inferred / Unknown list.
+* Installing an assistant by file has never produced a running system for us. docs/ASSISTANTS.md
+  records each attempt and its outcome so nobody has to repeat them on live hardware.
+
+## How to help
+
+The most useful contributions are files and controlled pairs, not code:
+
+* A download, one setting changed in VEConfigure, and a second download, plus a screenshot of the
+  VEConfigure tab showing the value. One such pair names a field for everyone.
+* Files from other hardware: Quattro, other firmware, three-phase, single-unit `.rvsc`.
+* Running the verify-it-yourself recipe in docs/QA.md on your system and reporting what happened.
+
+See CONTRIBUTING.md for how to add a fixture and what the privacy expectations are.
+
+## License and responsible use
+
+MIT, see LICENSE. This tool is for people who are already responsible for, and authorized to
+configure, the systems they apply it to. It produces files; the decision to upload one, and the
+consequences on a live battery system, remain yours. Read docs/SAFETY.md first.
+
+## How this project is run
+
+Every change goes through a public pull request, every open question is a labelled issue, and every
+format claim is tied to a test on real files. The project is developed with AI assistance, disclosed
+in commits and in docs/PRACTICES.md.
+
+## Acknowledgements
+
+* github.com/xcellsior/ve-bus-programming documented the VE.Bus setting IDs and scales over the MK2/MK3
+  protocol; that table is what let us name most of the settings array.
+* The Victron Community threads on `.rvsc`/`.rvms` files, Remote VEConfigure and the "switch as group"
+  error saved us time and confirmed the demand for this work.

mk2vsc-0.1.2/mk2vsc/__init__.py

@@ -0,0 +1,35 @@
+"""
+rvms -- read, verify, edit and diff Victron VEConfigure ``.rvms`` configuration files without VEConfigure.
+
+Zero dependencies. Python 3.9+.
+
+Quick tour::
+
+    from mk2vsc import RvmsFile, units_by_serial, decode_file, set_settings, diff_files
+
+    f = RvmsFile.load("system.rvms")
+    f.all_checksums_ok                      # every section's integrity trailer validates
+    units_by_serial(f)["HQ2414U6FVN"].setting(2) / 100   # absorption voltage
+
+Safety model in one paragraph: this library produces *files*.  It never talks to an inverter.  A valid
+file is necessary, not sufficient: editing the right offset is on you (see ``fields.py`` confidence
+levels), and the only proven-safe edits are length-preserving value changes to the settings array.
+Adding, removing or transplanting an assistant (ESS etc.) by file has never worked for us and has
+disrupted live systems.  Read docs/SAFETY.md before uploading anything.
+"""
+from .sections import RvmsFile, Section, RvmsParseError, sum32_le, scan_unit_blocks
+from .units import UnitBlock, unit_blocks, units_by_serial
+from .fields import FIELDS, BY_ID, BY_NAME, lookup, Field
+from .decode import decode_file, decode_bytes
+from .writer import set_settings, WriteRefused
+from .diff import diff_files, diff_bytes
+from .qualify import qualify_file, Intent
+
+__version__ = "0.1.2"
+__all__ = [
+    "RvmsFile", "Section", "RvmsParseError", "sum32_le", "scan_unit_blocks",
+    "UnitBlock", "unit_blocks", "units_by_serial",
+    "FIELDS", "BY_ID", "BY_NAME", "lookup", "Field",
+    "decode_file", "decode_bytes", "set_settings", "WriteRefused", "diff_files", "diff_bytes",
+    "qualify_file", "Intent",
+]

mk2vsc-0.1.2/mk2vsc/assistants.py

@@ -0,0 +1,105 @@
+"""
+READ-ONLY parsing of the assistant area that follows the settings array in a unit block.
+
+What we can say with evidence (docs/ASSISTANTS.md has the full story):
+
+* Bare block (no assistant): the area is the 9 bytes ``ff ff ff ff 00 00 ff 00 0b`` (device form) --
+  i.e. an empty record header (``ff ff`` marker, ``ff ff`` subtype, length ``00 00``) plus 3 trailer bytes.
+* Block with the ESS assistant installed by the GUI: one or more records framed
+  ``f5 ff <subtype u16> <len u16> <body>``; body lengths 704 and 1152 in every working install we hold
+  (one per inverter of the pair; the two bodies differ from each other, and are byte-identical across
+  systems except for a single primary/secondary flag byte).  The device pads records with ``0xff`` runs
+  and appends trailer bytes; the GUI's upload form writes the same records compact.
+* Stub: after VEConfigure accepted one of our transplanted files it wrote a 64-byte empty container
+  ``40 00 a7 fe 00 00 57 01`` + ``0xff`` filler + ``c0 0a`` on both inverters and discarded our payload.
+  Its presence in a download is the signature of a failed by-file assistant install.
+
+We do NOT understand the record body.  It looks like a compiled program (entropy ~6.2 bits/byte,
+recurring 2-3 byte opcodes, embedded parameter values such as 48.00 V and 10 %).  This module reports
+structure; it does not author it.
+"""
+from __future__ import annotations
+
+import struct
+from typing import Dict, List
+
+from .units import UnitBlock
+
+RECORD_MARK = b"\xf5\xff"
+EMPTY_MARK = b"\xff\xff"
+CONTAINER_SIG = b"\xa7\xfe\x00\x00\x57\x01"
+STUB_MAGIC = b"\x40\x00" + CONTAINER_SIG     # len 64 + signature, as it appears after the ff ff ff ff header
+
+
+def parse_records(area: bytes):
+    """Walk ``marker(2) subtype(2) len(2) body`` records from the start of the area.
+
+    Returns (records, tail_offset).  Walking stops at the first byte pair that is not a known marker.
+    """
+    records: List[Dict] = []
+    pos = 0
+    while pos + 6 <= len(area) and area[pos: pos + 2] in (EMPTY_MARK, RECORD_MARK):
+        marker = area[pos: pos + 2]
+        subtype, length = struct.unpack_from("<HH", area, pos + 2)
+        body = area[pos + 6: pos + 6 + length]
+        records.append({"offset": pos, "marker": marker.hex(), "subtype": f"{subtype:04x}", "length": length,
+                        "body_sha8": _sha8(body) if length else "", "nonpad_bytes": sum(1 for b in body if b != 0xFF),
+                        "container_signature": body.startswith(CONTAINER_SIG),
+                        "truncated": len(body) < length})
+        pos += 6 + length
+    return records, pos
+
+
+def parse_assistant_area(u: UnitBlock) -> Dict:
+    """Describe the assistant area of a unit block.
+
+    Uniform model (every block in the corpus fits it)::
+
+        area := record* tail
+        record := marker(2) subtype(2) len(2) body[len]
+        marker  ff ff  -> empty slot / container.  Bare blocks: len 0.  Two June-2026 files from an older
+                          tool build: len 6, body a7 fe 00 00 57 01.  Stub written by VEConfigure after it
+                          discarded a transplanted assistant: len 64, same signature + 0xff filler.
+                f5 ff  -> assistant record.  GUI-installed ESS: one 704-byte and one 1152-byte record per
+                          system (one on each inverter), subtype 0101 / 0001.
+        tail   := padding(0xff)* | ff | u16 free
+                  On bare, legacy and stub blocks free == 2816 - bytes used; see docs/FORMAT.md for ESS.
+
+    A ``f5 ff`` header with len 0 where ``ff ff`` is expected is residue seen on downloads taken after a
+    rejected or rolled-back assistant upload; functionally bare.
+    """
+    area = u.assistant_area
+    records, tail_off = parse_records(area)
+    tail = area[tail_off:]
+    out: Dict = {"bytes": len(area), "records": records, "tail_bytes": len(tail), "tail_hex": tail[-8:].hex(" "),
+                 "stub": False, "kind": "unknown", "summary": ""}
+    if len(tail) >= 3 and tail[-3] == 0xFF:
+        out["free"] = struct.unpack_from("<H", tail, len(tail) - 2)[0]
+        out["used"] = tail_off
+        out["free_plus_used"] = out["free"] + tail_off
+    if any(r["truncated"] for r in records):
+        out["kind"] = "malformed"
+        out["summary"] = "record length exceeds the area (malformed)"
+        return out
+    real = [r for r in records if r["marker"] == "f5ff" and r["length"] > 0]
+    containers = [r for r in records if r["marker"] == "ffff" and r["length"] > 0]
+    if any(r["length"] >= 64 and r["container_signature"] for r in containers):
+        out["kind"], out["stub"] = "stub", True
+        out["summary"] = "EMPTY STUB container (signature of a failed by-file install)"
+    elif real:
+        out["kind"] = "records"
+        out["summary"] = "assistant records: " + ", ".join(f"{r['length']}B/{r['subtype']}" for r in real)
+    elif containers:
+        out["kind"] = "container"
+        out["summary"] = f"empty {containers[0]['length']}-byte container (no program)"
+    elif records:
+        out["kind"] = "none"
+        out["summary"] = "no assistant" + (" (empty record residue)" if records[0]["marker"] == "f5ff" else "")
+    else:
+        out["summary"] = f"{len(area)} unrecognised bytes"
+    return out
+
+
+def _sha8(b: bytes) -> str:
+    import hashlib
+    return hashlib.sha256(b).hexdigest()[:8]