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 (475 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

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

pip install mk2vsc

Or from source, with the fixture corpus and tests:

git clone https://github.com/kylehart/mk2vsc.git && cd mk2vsc
python3 -m venv .venv && .venv/bin/pip install -e ".[test]"
.venv/bin/pytest          # 475 tests against the fixture corpus

Quickstart: one download, one change

Download the file from VRM (Device list, Remote VEConfigure, Download). Then:

mk2vsc show download.rvms

download.rvms: 5055 bytes, 2 inverter(s), form=device, checksums OK
  HQ2414AXENJ: firmware 2729560, saved 2026-07-20T18:41:22+00:00, assistant: no assistant
  HQ2414U6FVN: firmware 2729560, saved 2026-07-20T18:41:28+00:00, assistant: no assistant
  Charger
    absorption_V        Absorption voltage       57.6 V    56 V   <- inverters differ
    float_V             Float voltage            55.2 V    54 V   <- inverters differ
    charge_current_A    Charge current             35 A    35 A
    ...

Change what needs changing. The output is written next to the input; the input is never touched:

mk2vsc edit download.rvms absorption=56.8 float=54.0

  HQ2414AXENJ  absorption_V   57.6 -> 56.8 V
  HQ2414U6FVN  absorption_V   56.0 -> 56.8 V
  HQ2414AXENJ  float_V        55.2 -> 54.0 V
  HQ2414U6FVN  float_V        54.0 -> 54.0 V (unchanged)

wrote download.edited.rvms
verified: only those bytes and their section checksums changed; the input file is untouched.

Next:
  1. VRM > Device list > Remote VEConfigure > Upload: download.edited.rvms
  2. Download again from the same page.
  3. mk2vsc verify download.edited.rvms <the new download>

After the upload, prove the device took exactly your change and nothing else, and that the values are what you intended on both inverters:

mk2vsc verify download.edited.rvms redownload.rvms
mk2vsc check  redownload.rvms --expect absorption=56.8 float=54.0

That is the whole loop. show, edit, verify, check; plus diff for any two files, history for a folder of old downloads, validate, fields, and experimental (read docs/ESS_INJECTION.md first). Field names take aliases (absorption, float, charge_current, ac_limit, low_shutdown, vs_entry, vs_return, capacity), full names from mk2vsc fields, or VE.Bus setting IDs.

From Python, the same loop:

import mk2vsc

cfg = mk2vsc.load("download.rvms")
print(cfg["HQ2414U6FVN"]["absorption"])        # 56.0
cfg.set("absorption", 56.8)                      # every inverter
cfg.set("float", 54.0)
path = cfg.save()                                # download.edited.rvms
# upload through VRM, download again, then:
ok, report = mk2vsc.verify(path, "redownload.rvms")
ok, results = mk2vsc.load("redownload.rvms").check(absorption=56.8, float=54.0)

When you run a fleet: 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 edit the baseline into 01_prepared/, then mk2vsc check it against the values you intend (on the command line, or an intent file that lives outside the file under test).
3. Upload 01_prepared/ through VRM.
4. Download again into 02_downloaded/.
5. mk2vsc verify prepared against downloaded and mk2vsc check 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

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.