Victron nodes in Node-RED

Victron palette

Node-RED has its own basic set of nodes. Venus OS Large adds the Victron nodes — the node-red-contrib-victron palette. It is installed by default. The nodes work on D-Bus, that is, on the values Venus OS exposes from devices connected to the GX. In a node, you choose the device and parameter; paths with placeholders, such as {tracker}, are automatically expanded by the editor into options available on connected devices.

• Palette update — only together with a new Venus OS Large. The palette cannot be updated from the editor or from the command line. If a newer palette is already available online, you must wait for the next Venus OS Large release — it usually appears soon after the palette update.
• Node descriptions — the project wiki on GitHub describes each node and its paths (Input nodes, Output nodes and Virtual devices pages). The paths and values on this page come from it.
• Other palettes — additional nodes, such as dashboard, are installed from the internet to the GX data partition, so they remain after a Venus OS update. Required spare space: first opening.

Node types

The wiki divides Victron nodes into input, control and virtual devices, and separately lists two custom nodes.

Full list of device nodes

All 33 input nodes; 18 of them also have a control version (marked “Control” in the wiki). Descriptions according to the wiki.

When the node sends a message

• On every value change — this is the input node’s basic behaviour.
• With “only changes” selected — only when the value changes.
• Without “only changes” — additionally, every 5 s the node sends the current value, even if it has not changed.
• Value at a fixed interval — use a change node to save msg.payload in context (flow. or global.), and an inject node to read it at the chosen interval. That is how the built-in “Only Messages at Regular Intervals” example works.
• Context after a restart — by default, context is kept only in RAM and is lost after a GX restart or a power outage. Disk writes are enabled in /data/home/nodered/.node-red/settings-user.js (localfilesystem storage; in the manual’s example, saved every 300 s). Do not save too often, to avoid wearing out the flash memory.

How the control node works

The Control node writes the value from msg.payload to the device. Parameters with a list of values (enum) are set by number — in Victron examples, the inject node sends, for example, the number 3 to the Vebus Control node to switch on the inverter/charger. The values for each path are in the table below and in the wiki.

• Scheduling — the inject node can send a value at a fixed time, on selected days, or every few minutes within a defined time window. Node-RED uses the time zone set in Remote Console; after changing it, you need to restart Node-RED.
• State keeping — the “Event Based Scheduling” example links the Vebus input node (/Mode) with the control node so that, during scheduled hours, it keeps the selected mode even if someone changes it by mistake.
• Special schedules — for holidays, random offset, or dusk and dawn, Victron recommends the additional node-red-big-timer node (Manage palette → Install).

Useful paths

Each parameter has its own D-Bus path. The editor expands placeholders in paths to values available in the connected devices:

Selected paths from the wiki — for automation based on battery state, PV production and inverter mode:

Relays — what to set first

For Node-RED to switch a relay, you must first set it to manual control — most often in VictronConnect. Then the Relay Control node operates the relay: 1 closes the contact (Closed), 0 opens it (Open).

• Generator relay — set it in the GX console to the “Generator” function, and send start and stop with the Generator Control node (/Start: 1 Start, 0 Stop). Fischer Panda generators are started directly by the Generator node via D-Bus.
• Switch on the dashboard — the “Relay Switching” example controls a relay from the dashboard. To make the switch also show changes made elsewhere, for example in the GX menu, connect the Relay input node to the switch input as well. The node-red-dashboard palette is required — see dashboard and remote access.
• Ready-made flow — relay switched on and off according to battery state: step-by-step example.

Virtual devices

A virtual device lets you connect hardware or a data source to GX that Victron does not support. Once created in Node-RED, it appears in GX and behaves like a real Victron device — also in the VRM portal. Manual examples: weather from an API as a virtual weather station, calculated import and export as a virtual grid meter, position from GPSd as a virtual GPS, LoRa or MQTT sensors as a virtual tank or temperature sensor.

1. Current Venus OS. Update the GX device to the latest version.
2. Virtual Device node. Add it to the flow and select the device type.
3. Data. Connect a data source or control logic. Send msg.payload to the node as an object: the keys are D-Bus paths without the leading slash, and the values are readings, for example {"Dc/0/Voltage": 48.2, "Dc/0/Current": 12.5, "Soc": 85}.

• D-Bus name: com.victronenergy.<typ>.virtual_<node id>.
• Disconnect and reconnect: msg.connected = false disconnects the device and releases the D-Bus service name; msg.connected = true restores it.
• Output: one port — passes through the original message with msg.connected set to the current D-Bus connection state.

Virtual Switch

Creates a switch without a physical relay — for example, for an IoT switch with Tasmota software, which the flow controls according to battery state. According to the manual, it appears in the Switch panel of the new Venus OS interface, can be turned on and off like a real switch, and its state is stored in the GX device and can survive a restart.

• Control: {"SwitchableOutput/output_1/State": 1} turns it on, {"SwitchableOutput/output_1/Dimming": 75} sets dimming to 75%. msg.connected = false disconnects the switch.
• 11 types: On/Off (0 off, 1 on), Dimmable (on/off and dimming 0–100%), Temperature setpoint (thermostat slider in °C), Stepped, Basic slider, Dropdown, Numeric input, Three state (0 Off, 1 On, 2 Auto), RGB colour wheel, CCT wheel and RGB+White dimmer.
• Outputs: port 1 passes the message with msg.connected; port 2 sends the new state when it changes; port 3 sends the new dimming value or setpoint (types with dimming, steps, numbers and RGB).

Notifications and events

Built-in examples

In the editor: menu in the top right corner → Import (or Ctrl+I) → Examples → node-red-contrib-victron. The same examples are in the wiki on the Example Flows page. Some of them require extra palettes — most often node-red-dashboard.

Where the sources differ

• Virtual device types. The Venus OS Large manual (section 5.8) lists 9: Battery, Generator, GPS, Grid meter, Meteo, Motor drive, PV inverter, Tank sensor and Temperature sensor. The wiki (Virtual devices) lists 14: it adds AC Load, DC Load, Electric Vehicle, Energy meter and Pulse meter, and “Motor drive” appears as E-drive (service com.victronenergy.motordrive). Which types are available to you is shown by the type list in the Virtual Device node.
• Where the virtual switch appears. Instructions: in the switch panel of the new Venus OS interface. Wiki: Venus OS sees it as a connected Cerbo GX I/O extender, and the GX interface lets you control it.
• How often messages arrive. FAQ Q9 and the “Only Messages at Regular Intervals” example: on every change, and without “only changes” additionally every 5 s. The “Event Based Scheduling” example: by default every 5 s, with changes sent immediately — “about once a second”.
• Times in “Trigger Based Scheduling”. Description: turn on at 6:00, turn off at 22:00. In the flow itself, the node “Trigger 'ON' at 22:00” sends 3 (On) at 22:00, and “Trigger 'OFF' at 6:00” sends 4 (Off) at 6:00. After importing, check the times and values in the inject nodes.
• Updating the palette. Section 5.3 and FAQ Q2: you cannot update the Victron palette from the editor or the command line — only through the new Venus OS Large. Section 5.6 says more generally that if you install a newer version of the palette than the factory one, Node-RED will use the newer version. The Victron palette is stated plainly in Q2: only the new Venus OS Large.
• Placeholders. The wiki legend lists {type}, {tracker}, {phase}, {day}, {input}, {channel} and {index}, but the path descriptions also use {relay} (/Relay/{relay}/State), {line} (/Ac/Consumption/{line}/Power in the System node) and {historyDay} (/History/Daily/{historyDay}/Yield in the Solarcharger node).

Devices this applies to

Cerbo GXSystem control centre and gateway to the VRM portal.Ekrano GXGX centre with built-in 7″ touchscreen.

Sources

• node-red-contrib-victron wiki — Available nodesgithub.com · EN
• node-red-contrib-victron wiki — Input nodesgithub.com · EN
• node-red-contrib-victron wiki — Output nodesgithub.com · EN
• node-red-contrib-victron wiki — Virtual devicesgithub.com · EN
• node-red-contrib-victron wiki — Example Flowsgithub.com · EN
• Venus OS Large image: Signal K and Node-RED — sections 2, 5.3–5.8, FAQ Q2, Q9, Q11victronenergy.com · EN