Venus OS Large: Signal K and Node-RED

1. Introduction

This manual documents Venus OS Large, the software running on Victron Energy's Cerbo GX monitoring device and other GX devices. Venus OS Large is an extended version of the common software, adding Node-RED and Signal K server capabilities.

Node-RED offers PLC-like programming for connecting hardware devices, APIs, and online services. It provides a browser-based editor that makes it easy to wire together flows, enabling complex algorithms and functionalities without writing traditional source code. Node-RED is also known as Low-code programming for event-driven applications. It features a fully customizable dashboard viewable in a web browser, both locally and remotely via VRM Servers. Example flows are available to demonstrate its possibilities.

Signal K Server is a server application that runs on a central hub, such as a Victron GX device. It multiplexes data from NMEA0183, NMEA 2000, Signal K, and other sensor inputs. A popular feature is its function as a wireless AIS and navigation server for popular apps like Navionics, iSailor, iNavX, Aqua Map, and WilhelmSK on phones and tablets. For more information on Signal K Server, refer to its readme.

2. Where to find support

Official support for Venus OS Large functionalities is not provided. For support, users are directed to the Modifications Space on Victron Community and/or the Node-RED Space on Victron Community. Users should first search for existing solutions and then create a new question, ensuring to add "Node-RED" to the topic. For SignalK support, a dedicated #victron channel exists in the SignalK Slack workspace.

3. Requirements

3.1 GX Device compatibility

The following GX devices are compatible with Venus OS Large:

• Cerbo GX
• Cerbo-S GX
• Venus GX
• Octo GX
• MultiPlus-II GX
• EasySolar-II GX

The Color Control GX (CCGX) and CanVU GX are not able to run Venus OS Large. Venus OS Large is also available for certain RaspberryPi models; installation files and specific instructions are provided separately.

3.2 CPU & Memory resources

Both Signal K and Node-RED are resource-intensive applications. The intensity depends on the complexity of Node-RED flows and the volume of Signal K messages. The Venus GX has fewer resources compared to the Cerbo GX, which features a dual-core CPU and more RAM. Running both Signal K and Node-RED simultaneously on a Venus GX can strain its resources. More details on CPU & RAM differences are available at github.com/victronenergy/venus/wiki/machines. Insufficient resources can lead to device slowdown or watchdog reboots.

3. How to install and update

Step 1. Preparations

• Cerbo GX: No preparations required.
• Venus GX: First install and boot v2.73 or later, then install Venus OS Large to ensure correct partitioning.
• MultiPlus-II GX: No preparations required.
• EasySolar-II GX: No preparations required.
• RaspberryPi 3: No preparations required.
• RaspberryPi 4: No preparations required.

For RaspberryPi installations, familiarize yourself with the Venus OS for RaspberryPi documentation.

Step 2. Update to the latest firmware version (v2.90 or later)

Navigate to Settings → Firmware → Online updates. Refer to the GX device's user manual for more information.

Step 3. Set the image type Venus OS Large

Go to Settings → Firmware → Online updates → Image type. Change the Image type to Large, then navigate up and check for a new version to install.

[Image Description: A screenshot of the Venus OS firmware update screen showing options for Auto update, Update feed, Image type, and Check for updates. The 'Image type' is currently set to 'Normal'.]

Step 3. Verify and enable

1. Verify successful installation by checking for the Venus OS Large menu in the Settings menu.
2. Enable either Signal K or Node-RED. Enabling both on a Venus GX may cause performance issues; this is less problematic on a Cerbo GX due to its superior resources. Installer access level is required to enable/disable these settings.

[Image Description: A screenshot of the Venus OS Large features menu, showing toggles for Signal K and Node RED, with a note that these features are not officially supported by Victron and directing users to community.victronenergy.com for questions. Documentation is available at https://ve3.nl/vol.]

4. Accessing Node-RED and Signal K

After installation and enabling, Node-RED and Signal K are configured via web interfaces. Access the Node-RED flow editor by typing https://venus.local:1881/ into your browser. If venus.local does not resolve, use the device's IP address (e.g., https://192.168.178.224:1881/). A security warning is normal; proceed according to browser instructions. Refer to the GX manual's Remote Console on LAN chapter for finding the IP address.

Access the Signal K admin panel by typing http://venus.local:3000/. Similar to Node-RED, you may need to use the device's IP address (e.g., http://192.168.178.224:3000/).

[Image Description: A screenshot of the Node-RED editor interface, showing a flow grid, available nodes on the left (common, function), and flow management tools. Below this is a screenshot of the Signal K admin panel dashboard, displaying stats like 'Total server Signal K throughput', 'Number of Signal K Paths', 'Number of WebSocket Clients', and 'Uptime'. It also shows 'Connection & Plugin Status'.]

5. Node-RED

5.1 Introduction

Node-RED is a tool for connecting hardware devices, APIs, and online services, offering a browser-based editor for creating flows. It enables programming functionalities like activating relays based on measurements or building complex algorithms. Node-RED is considered Low-code programming for event-driven applications. It also provides a fully customizable dashboard accessible locally and remotely. Tutorials and example flows are available online, along with introductory webinars on the Victron Tech YouTube channel.

The Node-RED editor can be accessed via LAN at https://venus.local:1881/ or from VRM. Venus OS Large includes a core set of useful nodes plus a specific Victron Pallet. Developer source code for node-red-contrib-victron modules is available, but updates are managed through Venus OS large builds.

5.2 Back-up and restore

It is crucial to back up Node-RED flows regularly using the palette manager's "Export → all flows" option, saving the flows.json file. This file can be imported on a fresh installation. Importing flows with unavailable nodes may cause issues. Always create an extra backup before firmware updates. Note that this process backs up flows, not the entire Node-RED configuration, which is stored in .config.*.json files.

5.3 Installing extra nodes

Beyond the core and Victron nodes, numerous additional nodes are available from the Node-RED project and the community. To install new nodes or palettes, a working internet connection is required. Palettes are installed on the GX Device's data partition and persist through Venus OS updates. Ensure at least 30MB of free space is available on the data partition.

5.4 Controlling relays

GX Device relays: Must be configured to be Manually controlled.

[Image Description: A screenshot showing the configuration of a GX Device relay, labeled 'Function (Relay 1)', set to 'Manual' control. Below it, a diagram labeled 'hotkeys' displays arrow keys and ESC, suggesting input methods.]

Battery Monitor Relay: Controllable via VictronConnect by setting its option to REM (Remote Controlled).

Lynx Shunt VE.Can: Controllable by setting the relay function to "Manual control" in the GX user interface.

Lynx Smart BMS Relay: Not available for control via Node-RED.

SolarCharger MPPT Relay: Currently not controllable due to a limitation in VictronConnect's "Manual control" option for MPPTs. This is planned for future fixes. Only larger models have a relay.

(VE.Bus connected-) Multi, Quattro and similar product relays: The alarm relay and AC-out 2 contactor are not controllable remotely via Node-RED.

RS series (inverter, multi) relays: Not currently controllable, but planned for future implementation.

Charger relays: The Phoenix Smart Charger relay is controllable for remote use when the charger is switched on. This feature is limited and does not apply when the charger is off. This applies to 230V and later 120V/240V models.

5.5 Node-RED Dashboard

Node-RED offers a customizable dashboard for displaying graphs, indicators, and controls like switches and sliders. It is accessible locally and remotely via VRM Servers. The dashboard needs to be installed using the "Manage Palette" feature. Nodes for the dashboard will then appear in the palettes.

[Image Description: A screenshot of a Node-RED dashboard titled "Temperature Controlled Relay". It includes controls for "Operation Mode" (set to Automatic), a temperature gauge showing 20°C with a target of 25°C, and a hysteresis setting of 2°C. There is also an ON/OFF toggle.]

5.6 Configuration files

WARNING: Modifying system files is generally not required. Venus OS and Node-RED are designed to function without command-line intervention. The following information is for advanced users.

On startup, Node-RED reads three settings files:

1. /usr/lib/node_modules/node-red/venus-settings.js: Read first, will be overwritten by Venus OS updates. Do not modify.
2. /data/home/nodered/.node-red/settings-venus.js: Overrides/extends the first file, survives Venus OS updates. For Victron use; do not edit.
3. /data/home/nodered/.node-red/settings-user.js: Overrides/extends the second file, survives Venus OS updates. Editable, but may cause issues after upgrades.

Configuration should be enclosed within a module.exports = {} block.

Other configuration files in /data/home/nodered/.node-red/ include:

• flows.json: Stores your flows; can be exported.
• flows_cred.json: Stores credentials/login information for flows.
• .config.*: Stores Node-RED settings.

For more details on Node-RED configuration, see nodered.org/docs/user-guide/runtime/configuration.

5.7. Node-RED FAQ

Q: Write/read file gives "Error: EACCESS: permission denied"

Since Venus OS 2.90, Node-RED runs as user nodered, not root. Flows can only access files/directories owned by nodered, typically under /data/home/nodered/. Modifying the storage location to /data/home/nodered/storage.txt might resolve this.

Q: How can I update the Victron node palette?

The Victron palette is part of the Venus OS Large package and can only be updated by installing a newer Venus OS Large version.

Q: How can I password protect Node-RED?

Password protection for Node-RED is linked to the remote console. The username is admin, and the password is the remote console password.

Q: How do I restart Node-RED from the Venus GUI?

Restart Node-RED by disabling and then enabling it via Venus OS Large Features → Node-RED.

Q: How does safe mode work and what is it?

Safe mode allows Node-RED to start without executing flows. This enables editing and deploying changes without running flows, useful for debugging errors that cause high CPU loads or other issues.

Q: Can I install the @signalk/node-red-embedded?

No, not into the Venus OS Large instance. For @signalk/node-red-embedded, use the Node-RED plugin/instance optionally installable within Signal K itself. This involves enabling Node-RED in the Signal K server, disabling Venus OS Node-RED, and installing the Victron palette into Signal K's Node-RED.

Q: I get the error: Failed to remove, unrecognised module

This occurs when trying to remove a module that was previously uninstalled but left files behind. To recover:

1. Identify the module name and version from the palette manager.
2. Stop Node-RED.
3. Backup package.json in /data/home/nodered/.nodered/.
4. Edit /data/home/nodered/.node-red/package.json.
5. Add the module and its version to the dependencies, ensuring valid JSON format.
6. Start Node-RED.

After these steps, Node-RED should recognize the module, allowing removal or upgrade.

Q: The browser complains about non-private connection

Node-RED now uses SSL with a self-signed certificate. Browsers may show a "Your connection is not private" warning. To proceed, click "Advanced" or "Show Details" and visit the site. This provides security by encrypting usernames and passwords. Ensure you connect using https://venus.local:1881/. If using the command line interface, set the NODE_EXTRA_CA_CERTS environment variable to /data/etc/ssl/venus.local.crt.

6. Signal K

6.1 Introduction

6.1.1 Why have Signal K on your GX Device?

Adding Signal K turns the GX device into a data hub for marine electronics, collecting data like AIS, boat speed, and wind. It acts as an interface between devices and mobile apps. Signal K is not a visualization tool but gathers and makes data available for apps. Signal K plugins can forward data to influxdb & Grafana.

Popular Apps compatible with Signal K:

• Aqua Map
• iNavX
• iSailor
• Navionics
• Wilhelm SK (customizable boat instrument display)
• ... (more can be added)

6.1.2 Instruments compatible with Signal K

• All Victron products connectable to a GX device.
• NMEA0183 and NMEA2000 GPS data, AIS data, Wind, Temperature, and other environmental data.
• Engine data (NMEA2000 and SAE 1939).
• Fusion Stereo.

And many more.

6.1.3 What is Signal K?

Signal K server is a software application running on your GX Device, interfacing with Victron protocols and more. It is community-driven, making it a flexible and comprehensive solution for understanding marine electronics data from various manufacturers. For more information, read the Signal K Server readme. Signal K is a community project, and Victron Energy supports open-source initiatives.

6.1.3 Considerations on how to install Signal K

Installing Signal K with Venus OS offers advantages like not requiring a RaspberryPi, being an all-in-one solution, and needing no special firmware updates or command-line knowledge. This approach aims to make Signal K Server accessible to mainstream users.

Alternatively, installing Signal K Server on a RaspberryPi running Raspbian offers more flexibility for extra components like Grafana or Influx, but requires self-management of the Linux system. The Venus OS type is a more complete product, reducing the need for component maintenance and compatibility worries.

The best installation method depends on individual requirements. RaspberryPi owners can use two SD cards to try both methods.

6.2 Where to find support?

Support is available via the Modifications space on Victron Community. For Signal K specifically, the Victron channel in the SignalK Slack is recommended. Do not contact normal Victron support for SignalK issues, as it relies on community support.

6.4 First use & configuring

Step 1. Opening the dashboard

Open a web browser and navigate to the Signal K Dashboard at http://venus.local:3000.

Step 2. Configure serial connections

To configure a USB-connected NMEA0183 connection in Signal K, go to the dashboard (http://0.0.0.0:3000) and navigate to Server → Connections. Do not add connections using built-in serial ports (/dev/ttyO0, /dev/ttyO2, etc.), as these are VE.Bus/VE.Direct ports and their data is already available in Signal K via the "Victron Venus Plugin" (see Dashboard → Server → Plugin Config).

Note: Once a USB-serial port is configured in Signal K, it may no longer be available in Venus OS.

Step 3. Configure can-bus connections

For Venus GX, Signal K includes a pre-configured NMEA2000 listener for VE.Can ports, named "n2k-on-ve.can-socket", using canboatjs.

[Image Description: A screenshot of the Signal K server configuration interface, showing sections for Data Connections, Plugin Config, Server Log, and NMEA2000 Socket. It indicates that 'n2k-on-ve.can-socket' is enabled and configured for VE.Can.]

To ensure operation, the port must be configured as a 250kbit VE.Can & NMEA2000 port in the Remote Console.

[Image Description: A screenshot of a CAN-bus profile configuration, showing options for 'VE.Can port BMS-Can port' and 'VE.Can & Lynx Ion BMS (250 kbit/s)'. It also shows settings for 'Devices' and 'NMEA2000-out'.]

Step 4. Adding Signalk Plugins or Webapps

TODO: Explain and warn about data partition size and space, as plugins are installed there. Filling the data partition can corrupt Venus OS. More information is available at github.com/victronenergy/venus/wiki/data-partition.

6.5 Signal K FAQ

Q1 How to best handle & install a GPS

To have GPS data available in both Signal K and Venus OS (for VRM), consider the following:

• USB GPS Dongle: Plug into the GX Device; it's automatically recognized by Venus OS and Signal K via the Victron Venus plugin. No manual configuration is needed.
• NMEA2000 GPS: Connect to the GX Device's canbus port, potentially using a VE.Can to NMEA2000 cable. Venus OS v2.60 added support for NMEA2000 GPS devices. Signal K can receive this data directly from the NMEA2000 bus or via the Venus OS functionality through the Victron-Signal K plugin.
• Part of a NMEA0183 network: NMEA0183 is point-to-point, not a network.

7. Remote access via VRM

The Node-RED flow editor, Node-RED dashboard, and Signal K admin panel can be accessed remotely via VRM. After enabling them, navigate to VRM and select the Venus OS Large menu. Access speed may vary depending on connection quality.