Skip to content

Victron: add Multi RS battery template (per-inverter minimum SoC) - #36407

Open
ChrisKoh83 wants to merge 2 commits into
evcc-io:masterfrom
ChrisKoh83:victron-multi-rs
Open

ChrisKoh83 wants to merge 2 commits into
evcc-io:masterfrom
ChrisKoh83:victron-multi-rs

Conversation

@ChrisKoh83

Copy link
Copy Markdown

Follow-up to #35802

#35802 was closed by the stale bot, not by a reviewer. The branch already contains @andig's fix from #35802 ("Templates: explicit modbus id", b6f8dd9), so this PR is the same change including that adjustment.


Branch: victron-multi-rs
File: templates/definition/meter/victron-multi-rs.yaml (new)
Related issue: #34550


Problem

On a Victron Multi RS installation the ESS is managed by the inverters, not by the GX.
/Settings/CGwacs/BatteryLife/MinimumSocLimit (register 2901), which the victron-energy
template writes for BatteryHold, therefore has no effect: the operative minimum SoC lives in
each com.victronenergy.multi service (/Settings/Ess/MinimumSocLimit, register 4614) and is
mirrored read-only as com.victronenergy.acsystem /Ess/ActiveSocLimit (register 4925).

Result: the discharge lock ("Entladung der Hausbatterie im Schnell-Modus und bei geplantem Laden
verhindern") does not hold the battery; it keeps discharging during fast charging (measured up to
4.8 kW while the car charged at 11 kW).

Change

New template victron-multi-rs (class meter, usage battery) that

  • reads power and SoC from the GX system service (register 842/843, unit 100) as before,
  • writes the minimum SoC to every configured Multi RS via
    /Settings/Ess/MinimumSocLimit (register 4614, writesingle, one unit id per inverter),
    implemented as a Modbus sequence inside limitsoc,

so the existing battery-control logic in meter/usage_battery.go (normal → minSoc,
hold → max(SoC, minSoc), charge → maxSoc) works on Multi RS systems without a custom device.

New parameter units – comma separated Modbus unit ids of the Multi RS units (GX device list).

meters:
  - name: battery
    type: template
    template: victron-multi-rs
    usage: battery
    modbus: tcpip
    host: 192.168.0.80
    port: 502
    units: 0,1,2
    capacity: 10
    minsoc: 10
    maxsoc: 100

Tested on real hardware

Installation: Ekrano/Cerbo GX + 3 × Multi RS 48/6000/100 (3-phase), Pytes 10 kWh,
evcc 0.318.2. Template loaded with evcc meter --template … --template-type meter:

Power:          3504W                 27ms
Soc:            71%                   1ms
Capacity:       10.0kWh
Min soc:        10%
Max soc:        100%
Controllable:   true
Battery modes:  [normal hold charge]

Battery mode normal with minsoc: 17 produced exactly three writes (trace):

[pytes] TRACE modbus: send 00 01 00 00 00 06 00 06 12 06 00 11   # unit 0, FC06, 0x1206 = 4614, 17
[pytes] TRACE modbus: send 00 02 00 00 00 06 01 06 12 06 00 11   # unit 1
[pytes] TRACE modbus: send 00 03 00 00 00 06 02 06 12 06 00 11   # unit 2

Read-back: 4614 = 17/17/17, acsystem /Ess/ActiveSocLimit (4925) = 17 (follows within ~20 s).
Setting normal with minsoc: 10 wrote 0x000a to all three and restored 4614 = 10/10/10,
4925 = 10 — i.e. the hold/release semantics of evcc map 1:1 onto the registers the inverter obeys.

Notes / limitations

  • The template only covers usage: battery; grid/PV keep using victron-energy.
  • Multi RS unit ids must be configured; they are not auto-discovered (the GX device list shows them).
  • acsystem has no writable minimum SoC, hence the per-unit writes.
  • Tested with 3 units; a single-unit installation works with units: 0.

Why a separate template

victron-energy intentionally targets the GX/Hub-4 world (2901) and works for VE.Bus systems.
A device-family detection inside that template would silently change behaviour for existing
installations, so a separate template keeps both worlds intact (see also issue discussion where
this was classified as a device-specific enhancement).


ChrisKoh83 and others added 2 commits November 4, 2026 17:15
On Multi RS installations the ESS is managed by the inverters, so writing /Settings/CGwacs/BatteryLife/MinimumSocLimit (register 2901) on the GX has no effect. Write /Settings/Ess/MinimumSocLimit (register 4614) on every com.victronenergy.multi unit instead, keeping evcc's existing battery control modes (normal/hold/charge) working on these systems.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 5 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="templates/definition/meter/victron-multi-rs.yaml" line_range="59-67" />
<code_context>
+    set:
+      source: sequence
+      set:
+      {{- range splitList "," (.units | unquote) }}
+      - source: modbus
+        {{- include "modbus-connection" $ | indent 6 }}
+        id: {{ . | trim }}
+        register:
+          address: 4614 # /Settings/Ess/MinimumSocLimit
+          type: writesingle
+          decode: uint16
+      {{- end }}
+  {{- include "battery-params" . }}
+  {{- end }}
</code_context>
<issue_to_address>
**Minimum SoC diverges across units**

When a Modbus write fails partway through the configured unit list, `sequencePlugin.IntSetter` stops at the first failed write, leaving earlier units updated and later units unchanged. The inverters end up with inconsistent minimum SoC limits, and battery control leaves the change partially applied.

Make the sequence attempt every configured unit and report failures after processing the list.
</issue_to_address>

### Comment 2
<location path="templates/definition/meter/victron-multi-rs.yaml" line_range="23" />
<code_context>
+  - name: modbus
+    choice: ["tcpip"]
+    id: 1
+  - name: units
+    required: true
+    example: 0,1,2
</code_context>
<issue_to_address>
**Invalid unit IDs reach Modbus**

When the comma-separated `units` value contains an empty, nonnumeric, or out-of-range ID, the template renders unit IDs without validating them: an empty field becomes `id:` and can decode as unit 0, while other invalid values produce a bad config or target an unintended unit. Users do not get a clear error for the invalid `units` value.

Validate each unit ID and reject empty, nonnumeric, or out-of-range values with a clear configuration error.

Also at `templates/definition/meter/victron-multi-rs.yaml:24`, `templates/definition/meter/victron-multi-rs.yaml:59-62`.
</issue_to_address>

### Comment 3
<location path="templates/definition/meter/victron-multi-rs.yaml" line_range="59-67" />
<code_context>
+    set:
+      source: sequence
+      set:
+      {{- range splitList "," (.units | unquote) }}
+      - source: modbus
+        {{- include "modbus-connection" $ | indent 6 }}
+        id: {{ . | trim }}
+        register:
+          address: 4614 # /Settings/Ess/MinimumSocLimit
+          type: writesingle
+          decode: uint16
+      {{- end }}
+  {{- include "battery-params" . }}
+  {{- end }}
</code_context>
<issue_to_address>
**Single numeric unit ID fails rendering**

When the single-unit ID is configured as the unquoted YAML scalar `0`, `splitList` receives the result of `unquote`, which expects a string; a YAML configuration containing the documented single-unit form `units: 0` parses as an integer and template execution fails instead of loading the meter. Convert the parameter to a string before applying string functions.

Coerce `units` to a string before applying `unquote` and `splitList`, or declare and enforce a string parameter type.
</issue_to_address>

### Comment 4
<location path="templates/definition/meter/victron-multi-rs.yaml" line_range="1" />
<code_context>
+template: victron-multi-rs
+products:
+  - brand: Victron
</code_context>
<issue_to_address>
**Template docs omit Multi RS**

When the new template is added without regenerating and including its documentation, the generated template documentation has no Multi RS entry, so users browsing it cannot find this template's parameters or setup guidance.

Run `make docs` and include the generated documentation for the new template.
</issue_to_address>

### Comment 5
<location path="templates/definition/meter/victron-multi-rs.yaml" line_range="50" />
<code_context>
+    {{- include "modbus-connection" . | indent 2 }}
+    id: 100 # com.victronenergy.system
+    register:
+      address: 843 # Soc
+      type: input
+      decode: uint16
</code_context>
<issue_to_address>
**SoC acronym is misspelled**

The register comment spells the acronym as `Soc` instead of `SoC`, breaking the repository's capitalization convention in the new template.

Change the comment to `# SoC`.
</issue_to_address>

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment on lines +59 to +67
{{- range splitList "," (.units | unquote) }}
- source: modbus
{{- include "modbus-connection" $ | indent 6 }}
id: {{ . | trim }}
register:
address: 4614 # /Settings/Ess/MinimumSocLimit
type: writesingle
decode: uint16
{{- end }}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 High · Minimum SoC diverges across units

When a Modbus write fails partway through the configured unit list, sequencePlugin.IntSetter stops at the first failed write, leaving earlier units updated and later units unchanged. The inverters end up with inconsistent minimum SoC limits, and battery control leaves the change partially applied.

Make the sequence attempt every configured unit and report failures after processing the list.

Prompt for AI agents
In `templates/definition/meter/victron-multi-rs.yaml` at lines 59-67:

**Minimum SoC diverges across units**

When a Modbus write fails partway through the configured unit list, `sequencePlugin.IntSetter` stops at the first failed write, leaving earlier units updated and later units unchanged. The inverters end up with inconsistent minimum SoC limits, and battery control leaves the change partially applied.

Make the sequence attempt every configured unit and report failures after processing the list.

- name: modbus
choice: ["tcpip"]
id: 1
- name: units

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Invalid unit IDs reach Modbus

When the comma-separated units value contains an empty, nonnumeric, or out-of-range ID, the template renders unit IDs without validating them: an empty field becomes id: and can decode as unit 0, while other invalid values produce a bad config or target an unintended unit. Users do not get a clear error for the invalid units value.

Validate each unit ID and reject empty, nonnumeric, or out-of-range values with a clear configuration error.

Also at templates/definition/meter/victron-multi-rs.yaml:24, templates/definition/meter/victron-multi-rs.yaml:59-62.

Prompt for AI agents
In `templates/definition/meter/victron-multi-rs.yaml` at line 23:

**Invalid unit IDs reach Modbus**

When the comma-separated `units` value contains an empty, nonnumeric, or out-of-range ID, the template renders unit IDs without validating them: an empty field becomes `id:` and can decode as unit 0, while other invalid values produce a bad config or target an unintended unit. Users do not get a clear error for the invalid `units` value.

Validate each unit ID and reject empty, nonnumeric, or out-of-range values with a clear configuration error.

Also at `templates/definition/meter/victron-multi-rs.yaml:24`, `templates/definition/meter/victron-multi-rs.yaml:59-62`.

From AGENTS.md L293:

- Provide clear validation and error messages for invalid configurations

Comment on lines +59 to +67
{{- range splitList "," (.units | unquote) }}
- source: modbus
{{- include "modbus-connection" $ | indent 6 }}
id: {{ . | trim }}
register:
address: 4614 # /Settings/Ess/MinimumSocLimit
type: writesingle
decode: uint16
{{- end }}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Single numeric unit ID fails rendering

When the single-unit ID is configured as the unquoted YAML scalar 0, splitList receives the result of unquote, which expects a string; a YAML configuration containing the documented single-unit form units: 0 parses as an integer and template execution fails instead of loading the meter. Convert the parameter to a string before applying string functions.

Coerce units to a string before applying unquote and splitList, or declare and enforce a string parameter type.

Prompt for AI agents
In `templates/definition/meter/victron-multi-rs.yaml` at lines 59-67:

**Single numeric unit ID fails rendering**

When the single-unit ID is configured as the unquoted YAML scalar `0`, `splitList` receives the result of `unquote`, which expects a string; a YAML configuration containing the documented single-unit form `units: 0` parses as an integer and template execution fails instead of loading the meter. Convert the parameter to a string before applying string functions.

Coerce `units` to a string before applying `unquote` and `splitList`, or declare and enforce a string parameter type.

@@ -0,0 +1,69 @@
template: victron-multi-rs

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ Low · Template docs omit Multi RS

When the new template is added without regenerating and including its documentation, the generated template documentation has no Multi RS entry, so users browsing it cannot find this template's parameters or setup guidance.

Run make docs and include the generated documentation for the new template.

Prompt for AI agents
In `templates/definition/meter/victron-multi-rs.yaml` at line 1:

**Template docs omit Multi RS**

When the new template is added without regenerating and including its documentation, the generated template documentation has no Multi RS entry, so users browsing it cannot find this template's parameters or setup guidance.

Run `make docs` and include the generated documentation for the new template.

From AGENTS.md L287:

- Update docs after template changes: `make docs`

{{- include "modbus-connection" . | indent 2 }}
id: 100 # com.victronenergy.system
register:
address: 843 # Soc

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ Low · SoC acronym is misspelled

The register comment spells the acronym as Soc instead of SoC, breaking the repository's capitalization convention in the new template.

Change the comment to # SoC.

Prompt for AI agents
In `templates/definition/meter/victron-multi-rs.yaml` at line 50:

**SoC acronym is misspelled**

The register comment spells the acronym as `Soc` instead of `SoC`, breaking the repository's capitalization convention in the new template.

Change the comment to `# SoC`.

From AGENTS.md L106:

- Acronyms uppercase in prose: OCPP, MQTT, HEMS, SoC

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

devices Specific device support

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants