Victron
Introduction
Victron Energy devices are a core component of the GCXONE Tower Monitoring ecosystem, delivering real-time power and energy monitoring for remote tower sites. They track solar charging performance, battery health, and overall DC system voltage — ensuring the energy system operates within safe thresholds and providing early warning of battery or solar irregularities.
This guide outlines the steps required to onboard a Victron Energy device into GCXONE — covering credential setup and alarm rule activation. Once complete, your device will stream live telemetry and trigger automated alerts when voltage or state of charge thresholds are breached.
What Victron Devices Monitor
Once connected to GCXONE, Victron devices continuously report the following categories of telemetry:
- Battery voltage levels across the DC system
- Solar charging current and input power from PV controllers
- Battery state of charge (SOC) as a percentage
- Charger and inverter operational status
- Overall system health and alarm states
Victron is the primary power monitoring system of the tower. Without it, GCXONE cannot detect battery depletion, solar underperformance, or DC voltage anomalies that could cause a site to lose power.
Prerequisites
Before starting device onboarding, ensure the following information and access are available:
| Requirement | Details |
|---|---|
| GCXONE Access | Admin or Operator role with Configuration module access |
| VRM Portal Account | An active Victron VRM Portal account with administrative access to the target device |
| Username & Password | Administrative credentials for the Victron VRM Portal |
| Serial Number | The unique serial number of the Victron device as listed in the VRM Portal |
| Site Created | The site this device will be assigned to must already exist in GCXONE |
The VRM Portal credentials provided must have administrative privileges. Read-only accounts will not allow GCXONE to retrieve the full telemetry data set required for monitoring
Victron Config Guide with GCX-ONE
Follow these steps to add a Victron device to GCXONE. The device will be registered under an existing site and begin reporting telemetry immediately after configuration.
Step 1 — Navigate to the Site
In GCXONE, navigate to the Site where the Victron device is physically installed. This is the parent entity under which the device will be registered.
- Go to Configuration → Sites
- Locate and open the target site
- Click Edit to open the site's configuration panel
Step 2 — Open the Device Dialog
Within the site configuration, navigate to the Devices section and click Add Device to open the device creation dialog.
Step 3 — Select Device Type
In the device dialog, open the Device Type dropdown and select Victron to load the appropriate configuration fields.
Step 4 — Enter Device Details
Fill in all required fields to establish a secure connection between GCXONE and the Victron VRM Portal. Each field is described in detail below.
| Field | Description | Notes |
|---|---|---|
| Device Type | Select 'Victron' from the dropdown | Must match exactly — determines which telemetry model is used |
| Device Name | A unique, descriptive name for this device in GCXONE | Use a naming convention that identifies the site and device, e.g., 'Tower-North-Victron-01' |
| Serial Number | The hardware serial number of the Victron device | Found on the device label or in the Victron VRM Portal |
| Username | Administrative login username for the VRM Portal | Must have full administrative access to the configured device |
| Password | Administrative login password for the VRM Portal | Stored securely within GCXONE; use a strong, unique password |
Step 5 — Save and Verify Connection
After entering all fields, click Save. GCXONE will immediately attempt to connect to the Victron VRM API using the provided credentials and serial number.
A successful connection results in:
- The device appearing in the site's device list with an active status indicator
- GCXONE automatically detecting the available PV Controller and Battery Manager
- Live telemetry data beginning to flow into GCXONE (battery voltage, charging current, solar input, SOC)
- The device becoming available for alarm rule configuration
If the connection fails, verify that the serial number matches the device in the VRM Portal, the credentials have administrative privileges, and the Victron VRM API is reachable from the GCXONE server.
Alarm Rules Configuration
GCXONE uses a JSON-based alarm rule configuration to define which telemetry parameters are monitored, what thresholds trigger alerts, and how those alerts are identified in CMS integrations.
Alarm rules can be configured at the Site level or Device level. Victron energy rules are typically applied at the Device level for precision control.
How to Apply Alarm Rules
- Navigate to the target Site or Device in GCXONE.
- Click Edit and go to the Additional Properties section.
- Locate the property named Custom Alarm Rules.
- Open the property's hamburger menu (⋮) and select Apply Default to load the preconfigured rule set. All rules are inactive by default.
- Modify the JSON to enable specific rules by setting
"active": truefor the relevant parameters. - Set your thresholds, event codes, and group codes as needed.
- Click Save. GCXONE will immediately begin evaluating incoming telemetry against the configured rules.
By default, all alarm rules are inactive. You must explicitly set "active": true for each rule you want GCXONE to monitor. This prevents accidental alerts during initial setup.
Rule Structure
Each alarm rule follows a consistent JSON structure. Understanding the common fields helps when customizing rules:
| Field | Description |
|---|---|
| active | Boolean (true/false). Set to true to enable monitoring for this rule. When false, the rule is ignored. |
| low | Lower threshold value. An alert triggers when the monitored value falls below this level. |
| high | Upper threshold value. An alert triggers when the monitored value exceeds this level. |
| eventCode | Unique string identifier used by GCXONE to communicate this alarm type to CMS integrations (IMMIX, Evalink, AmWin, LISA). This code appears in outbound alarm notifications. |
| groupCode | Logical grouping identifier for Tower Monitoring workflows. Used for filtering, organizing, and managing related alarms within GCXONE's Tower Alarm Manager. |
Victron Energy Alarm Rules
The following alarm rules are available for Victron devices under the Energy Monitoring section of the Custom Alarm Rules JSON. Each rule monitors a specific aspect of power system health and performance.
- Battery Voltage Rule
Monitors the DC system voltage across the battery bank. Voltage outside the acceptable range may indicate a charging fault, excessive load, or battery degradation.
Default JSON Configuration
json
"voltage": { "active": false, "low": 12, "high": 14, "eventCode": "battery.voltage.warning", "groupCode": "tower.solar.voltage.alert" }
| Parameter | Description | Example Value |
|---|---|---|
| low | Minimum acceptable battery voltage (V). Alert triggers when voltage falls below this value. | 12 |
| high | Maximum acceptable battery voltage (V). Alert triggers when voltage exceeds this value. | 14 |
| eventCode | CMS alarm identifier for voltage events | battery.voltage.warning |
| groupCode | Internal tower alarm group for filtering and routing | tower.solar.voltage.alert |
Example Behavior
- When voltage falls below 12V, an alert is triggered indicating the battery is discharging beyond safe levels.
- When voltage exceeds 14V, an alert is triggered indicating a potential overcharge condition.
- The alert clears automatically when voltage returns within the 12V–14V range.
- Adjust thresholds based on your specific battery chemistry — lithium systems typically operate within a different voltage range than lead-acid.
- Battery State of Charge (SOC) Rule
Monitors the remaining charge percentage in the battery bank. SOC is a more reliable indicator of usable energy remaining than voltage alone, especially under load.
Default JSON Configuration
json
"stateOfCharge": { "active": false, "low": 15, "eventCode": "battery.soc.warning", "groupCode": "tower.battery.soc.alert" }
| Parameter | Description | Example Value |
|---|---|---|
| low | Minimum acceptable SOC percentage. Alert triggers when SOC falls below this value. | 15 |
| eventCode | CMS alarm identifier for low SOC events | battery.soc.warning |
| groupCode | Internal tower alarm group identifier | tower.battery.soc.alert |
Example Behavior
- GCXONE triggers an alert when battery SOC drops below 15%.
- The alert clears automatically when SOC rises above the configured threshold.
- Set
lowhigher (e.g., 25–30%) on sites with limited solar input or high power consumption to give operators more lead time before a potential outage.
Event Codes and Group Codes Summary
Quick reference for all Victron Energy event codes and group codes:
| Rule | Event Code | Group Code |
|---|---|---|
| Battery Voltage Warning | battery.voltage.warning | tower.solar.voltage.alert |
| Battery State of Charge Warning | battery.soc.warning | tower.battery.soc.alert |
Configuration Reference
Complete Victron Energy Alarm Rules JSON. Copy this into the Custom Alarm Rules property and modify as needed for your deployment.
json
"energyMonitoring": { "voltage": { "active": false, "low": 12, "high": 14, "eventCode": "battery.voltage.warning", "groupCode": "tower.solar.voltage.alert" }, "stateOfCharge": { "active": false, "low": 15, "eventCode": "battery.soc.warning", "groupCode": "tower.battery.soc.alert" } }
Configuration Best Practices
- Always start with Apply Default to load the complete preconfigured rule set before making changes.
- Enable both rules together — Voltage and SOC complement each other and together give a complete picture of battery health.
- Set
lowfor SOC at 25–30% on sites with limited solar exposure or during winter months when solar input is reduced. - Adjust voltage thresholds based on your battery chemistry — lithium systems have different safe operating ranges compared to lead-acid batteries.
- Test alarm rules on a single device before deploying to all sites.
- Document your event codes and group codes in your CMS configuration to ensure correct alarm routing.
Troubleshooting
Device Won't Connect
| Symptom / Check | Resolution |
|---|---|
| Connection fails immediately after Save | Verify that the VRM Portal credentials are correct and have administrative access. Log in directly to the Victron VRM Portal to confirm. |
| Serial number not recognized | Confirm the serial number matches exactly what is listed in the Victron VRM Portal. Check for leading/trailing spaces or incorrect characters. |
| Authentication error | Ensure the account used has administrative privileges — read-only accounts are not supported. |
| No telemetry data after successful connection | Verify the Victron device is online and actively reporting to the VRM Portal. Check device status in the VRM Portal directly. |
Alarm Rules Not Triggering
| Symptom / Check | Resolution |
|---|---|
| No alerts received for a breached threshold | Verify the rule has "active": true in the JSON. Check that the Custom Alarm Rules JSON is valid (no syntax errors). |
| eventCode not appearing in CMS | Confirm the event code is configured in your CMS integration. Check the CMS channel mapping in GCXONE under the site's integration settings. |
| Voltage alerts firing unexpectedly | Adjust the low and high thresholds to better match your battery system's normal operating voltage range. |
| SOC alert not clearing after charging | Allow a few polling cycles for GCXONE to retrieve the updated SOC value from the VRM API. If the alert persists, manually refresh the device status in GCXONE. |
For additional support, contact your NXGEN representative or refer to the full GCXONE Tower Monitoring Configuration Guide, which covers EFOY Fuel Cell and Teltonika IoT monitoring in addition to Victron Energy.