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. |
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.
Commands
| 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 (default 1000). |
get_stats | type, interval, start, end | Aggregated stats passthrough. start/end are epoch seconds for historical ranges. |
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. |