Victron VRM Portal
Brings a Victron Energy GX device — Cerbo GX, Ekrano GX, Venus GX, or any Venus OS installation — into GEM through the VRM Portal cloud API. The driver polls the installation's live values and surfaces the headline energy metrics as zone attributes: battery state of charge, PV (solar) power, AC load/consumption, generator power, and battery current. Those feed dashboards, the energy widgets, and automation triggers (e.g. "if state_of_charge < 30 % then shed loads").
This is a cloud integration authenticated with a Personal Access Token — no username/password is stored in GEM, and the token can be revoked independently in VRM. It is monitoring-only: the driver reads telemetry and does not push control setpoints to the GX device.
Prefer a local integration? Victron GX devices also speak Modbus TCP and MQTT on the LAN. Those are lower-latency and cloud-independent but require the register/topic map; this VRM driver is the fastest path to visibility and works anywhere the GX reports to VRM.
Prerequisites
- A GX device that is online in the VRM Portal — sign in at vrm.victronenergy.com and confirm the installation is reporting.
- A VRM Personal Access Token:
- In VRM, open Preferences → Integrations → Access tokens.
- Click Add, give it a name (e.g. "GEM"), and copy the token immediately — VRM shows it only once.
Setup steps
- In GEM, Devices → Add Device and choose the Victron VRM Portal driver.
- Paste the VRM Access Token.
- Save, then run get_installations — it lists every installation the token can see with its
idSiteand name. - If the token owns more than one installation, set Installation ID (idSite) to the one you want. For a single-installation account you can leave it blank; the driver auto-selects the first installation.
- Create one zone to receive the telemetry. Set its Address to the
idSite(or simplysite).
Authentication header
VRM personal access tokens use a distinctive header — note it is the literal word Token, not Bearer, with a single space:
X-Authorization: Token <your-token>
The driver sends this on every request. Getting Bearer vs Token (or the spacing) wrong is the most common cause of a 401.
How telemetry is resolved
The diagnostics endpoint returns the same "advanced live values" you see in the VRM dashboard — one record per data point, each with a short code, a human description, a formattedValue (e.g. "85 %"), and a numeric rawValue.
Attribute reference
Device attributes
| Attribute | Required | Default | Description |
|---|---|---|---|
token | yes | — | VRM Personal Access Token. Stored encrypted. |
site_id | no | (auto) | VRM installation id (idSite). Blank = auto-select the first installation. |
poll_interval | no | 120000 | Poll period in milliseconds. Keep ≥ 60000 to respect VRM rate limits. Blank, 0, negative or unreadable values use 120000; values under 1000 are raised to 1000. |
Zone attributes (runtime, set by the driver)
Mapped from these verified VRM diagnostics codes:
| Zone attribute | VRM code | Meaning |
|---|---|---|
state_of_charge | SOC | Battery state of charge (%). |
battery_current | I | Battery current (A). |
pv_power | Pdc | PV / solar power (W). |
consumption_power | o1 | AC load / consumption power (W). |
generator_power | gs1 | Generator power (W). |
state | (derived) | charging / discharging / idle, derived from battery current sign. |
Every other live value (individual phase powers, tank levels, temperatures, per-device stats, etc.) is not mapped to a named attribute but is available in full via the get_diagnostics command — read the raw records and pull whatever code you need.
Zone address format
The zone Address is the VRM installation id (idSite) shown by get_installations, or simply site for a single-installation device. All zones on the device receive the same installation's telemetry, so one zone per device is the normal setup.
Connection and polling
- Connected means the driver resolved an installation and the latest diagnostics poll returned live values. A
401from VRM (token wrong or revoked) marks the device disconnected; a rate limit (429) or a VRM server error leaves the state as it was, and a network failure marks it disconnected. - VRM unreachable at startup. If the installation cannot be resolved when the device starts (no internet, VRM down, the GX not yet registered), the driver retries after 30 s, doubling the wait up to 5 minutes, and starts polling as soon as it succeeds. A rejected token (
401/403) is not retried — paste a new token and the device reloads. - Back-off. After three failed polls in a row the wait between polls doubles each time, up to 5 minutes (or your
poll_intervalif that is longer). The first good poll returns to the normal interval. The failure is logged once rather than on every poll. - A reply that is not VRM data (for example a captive-portal or maintenance web page) is treated as a failed poll: zone attributes are not touched.
| Command | Args | Effect |
|---|---|---|
get_installations | — | List installations the token can access (id = idSite, plus name). |
get_diagnostics | count | Return the raw live-value records for the installation. Blank, 0, negative or non-numeric count uses 1000. |
get_stats | type, interval, start, end | Aggregated stats passthrough. start/end are epoch seconds for historical ranges. Values are trimmed and blank ones omitted; an unfilled [...] placeholder is refused rather than sent. |
refresh | — | Force an immediate telemetry poll. |
Known limitations
- Monitoring only. This driver reads VRM; it does not write ESS setpoints, relay states, or operating modes. Control belongs on a local Modbus/MQTT integration where round-trip latency and cloud availability aren't in the loop.
- Only headline codes are named. SOC, battery current, PV, load, and generator power get friendly attributes; anything else must be pulled from
get_diagnostics. This is deliberate — VRM exposes dozens of codes per site and blindly mirroring all of them would spam attribute history. - Battery state is inferred from the sign of battery current (Victron convention: positive current = charging into the battery). Sites without a battery monitor won't report
I, sostatestaysidle. - Cloud dependency + rate limits. If VRM is unreachable or the GX device stops reporting, telemetry goes stale. Keep
poll_interval≥ 60 s.
Troubleshooting
| Symptom | Cause / check |
|---|---|
| 401 unauthorized | Token wrong, revoked, or sent as Bearer. Regenerate under VRM → Preferences → Integrations → Access tokens. |
| No installation resolved | The token owns no installations, or VRM couldn't return the user. Run get_installations to confirm the token sees the site. |
| No telemetry attributes appear | The GX device may be offline in VRM, or the metrics use codes outside the mapped set — run get_diagnostics and inspect the code values. |
| http 429 | Rate limited. Increase poll_interval (60000 ms or more). |
state never leaves idle | No battery-current (I) record — the installation has no battery monitor, or current is within the ±0.5 A idle band. |