Venus OS Large: Signal K and Node-RED

1. Introduction

This manual documents the “large” version of Venus OS, which adds Signal K and Node-RED. For more information on either of the two, search online.

Status and where this development is going

Currently, these images are available as beta versions. Many users are utilizing this version without issues and are very satisfied with its functionality. Ongoing work focuses on small improvements, cleanups, and testing.

There will be two versions of Venus OS available for installation:

1. The standard version, developed over many years, with all normal and supported functionality.
2. The large, or extended, flavor. This version includes all features of the standard version plus Signal K & Node-RED.

Switching between these versions will be straightforward via a simple setting in the graphical user interface (GUI). Updates will also be easy, functioning similarly to the online updates for the standard images.

Currently, installation and updates are performed using an offline method, requiring a USB stick or SD card.

To save download and installation time for users who may not require these additional features, they are offered in a separate version. These features also significantly increase the download and installed size.

More details can be found here:

• Victron Energy GitHub Issues
• SignalK Server Node GitHub Issues

2. Where to find support

Official support for the functionalities included in this image is not provided. For assistance, please visit the Modifications Space on the Victron Community forum.

3. Requirements

3.1 GX Device compatibility

A compatible GX device is required:

• Cerbo GX
• Venus GX (serial number HQ1842 or later, or upgraded to the large partition layout - refer to Appendix A for more information)
• Octo GX
• MultiPlus-II GX
• EasySolar-II GX

The CCGX and CanVU GX devices are not supported for the extended version. Venus OS extended is also compatible with certain Raspberry Pi models. Installation files and specific instructions for Raspberry Pi can be found here.

3.2 CPU & Memory resources

Both Signal K and Node-RED are resource-intensive applications. Their performance on a GX Device depends on CPU usage and available RAM memory. The intensity varies based on the complexity of Node-RED flows or the volume of data handled by Signal K.

Among the supported GX devices, the Venus GX has the least resources. Running both Signal K and Node-RED simultaneously may strain the system. The Cerbo GX, with its dual-core CPU and increased RAM, offers significantly better performance.

For more details on CPU and RAM differences, consult this document: Victron Wiki Machines.

Insufficient RAM or CPU resources can lead to system slowdowns and automatic reboots due to the watchdog timer.

3. How to install

Step by step instructions

• Step 1. (For Venus GX devices with a serial number below HQ1842 only) Perform the procedure detailed in Appendix A. This procedure requires technical expertise.
• Step 2. Disable automatic updates. Navigate to Settings → Firmware → Online updates in the Remote Console.
• Step 3. Download the latest Venus OS Extended image from the comments section of the relevant issue.
• Step 4. Install the downloaded file using the GX Offline install method. This requires a USB stick or Micro SD card.
• Step 5. Verify successful installation by navigating to Settings → Services and checking if Signal K and Node-RED are available to be enabled.
• Step 6. Enable Signal K or Node-RED. Enabling both on a Venus GX might lead to performance issues. Installer access level is required to enable/disable these servers (Settings → General).
• Finished. The Venus OS Extended image installation is complete. Proceed to the Node-RED or Signal K chapter.

Special note for the Raspberry Pi

Installing the .swu file on an existing image may not work due to partition size limitations. You will need to reflash the image to an SD card at least once. After that, .swu files can be used for updates. Both the SD card image and the .swu file are available via the link provided earlier.

4. Node-RED

A tutorial for working with Node-RED is available at: Node-RED First Flow Tutorial.

The Node-RED editor can be accessed at http://venus.local:1880/. If this address does not work, replace 'venus.local' with the device's IP address.

The default username is “admin”, and the password is the remote console password.

4.1 Introduction

4.2 Installing extra nodes

Node-RED includes a core set of nodes, with many more available from the Node-RED project and the community. These nodes can provide functionalities like weather data access or timer operations.

You can search for available nodes in the Node-RED library. The Victron Palette and the Dashboard Palette are pre-installed.

Refer to the Node-RED documentation for instructions on how to install and manage palettes: Adding nodes to the Palette.

Installing new nodes or palettes requires an active internet connection. Palettes are installed on the GX Device's data partition and will persist through Venus OS updates. Self-installed palettes can be removed using the palette manager.

It is not possible to remove pre-installed nodes, but they can be disabled. When a newer version of a palette is installed than the one pre-installed in Venus OS, Node-RED will use the newer version.

TODO: Document behavior when a user-installed palette conflicts with a newer pre-installed version. Ensure at least 30MB of free space on the data partition. Consider adding memory usage, free memory, and CPU statistics to the dashboard.

4.3 Controlling relays

GX Device relays

Relays are controllable. Ensure they are configured for manual control.

MPPT Relay

A Victron node allows control of the relay in solar chargers (only those with a relay). However, this functionality is currently not working because VictronConnect does not offer the required “Manual control” option in the selectable Relay modes for MPPTs. This is planned for a future fix.

BMV Relay

Currently, the driver in Venus OS does not support controlling the BMV relay. This will be addressed in a future update.

Multi & Quattro Relays

This includes alarm relays and the AC-out 2 relay. These relays are not controllable, and there are no current plans to enable Node-RED control for them.

5. Signal K

5.1 Introduction

5.1.1 Why have Signal K on your GX Device?

Integrating Signal K with the GX device transforms it into a data hub for all marine electronics on a yacht, enabling the aggregation of data such as audio, boat speed, wind data, and more. Signal K acts as an interface between these devices and protocols, and mobile applications on phones, tablets, and similar devices.

Signal K is not a visualization tool itself; its primary purpose is to collect data and make it accessible to web, phone, and tablet applications for visualization.

Signal K plugins can also forward data to influxdb & Grafana.

Popular Apps compatible with Signal K:

• Wilhelm SK: A highly customizable boat instrument display for iPhone, iPad, Apple Watch, and Apple TV.
• (Additional compatible apps can be added here)

5.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 from NMEA2000 and SAE 1939.
• Fusion Stereo.
• And many more.

5.1.3 What is Signal K?

Signal K server is a software application that, within this manual's context, runs on your GX Device and interfaces with all Victron protocols and more. It utilizes plugins and benefits from a large community of enthusiasts, making it a flexible and comprehensive software solution for understanding the numerous protocols used in marine electronics.

For more information on Signal K, please read the Signal K website and our related blog post.

Victron Energy supports Signal K as a community-driven open-source project, finding it to be an excellent match for the GX Device.

5.1.4 Signal K - the data format

Signal K is fundamentally a data format, with Signal K server being the associated software. This section explains the rationale behind the data format.

Signal K is a modern, open data format for marine use, designed to create a shared data model for marine-related data, making it easy to access, handle, and build applications upon.

The shared data model enables uniform data handling, irrespective of the data's origin. For instance, battery voltage can be referenced using a standard path like `electrical/batteries/1/voltage`, regardless of whether the data originates from a Victron BMV, an NMEA 2000 bus, or another voltage sensor.

This approach facilitates the use of modern standards like HTTP, WebSockets, and JSON, which are widely adopted. Knowledge and skilled personnel are readily available, requiring no specialized marine knowledge to begin.

Within Venus OS, Signal K consolidates all available GX system data, including NMEA 2000 data, into a single data model and programming interface.

5.1.3 Considerations on how to install Signal K

The installation method described in this document, running Venus OS with Signal K, offers advantages such as making Signal K more mainstream and less of a niche product. This approach was driven by a desire to broaden Signal K's accessibility.

An alternative common Signal K installation involves a Raspberry Pi running Raspbian, offering greater flexibility and easier installation of additional components like Grafana or Influx. However, this requires setting up and maintaining a Linux system yourself. The Venus OS approach provides a more complete, managed product, eliminating the need to worry about individual component updates and compatibility.

The optimal installation method depends on individual requirements. Raspberry Pi users can easily experiment with both methods by using separate SD cards.

5.2 Where to find support?

As previously mentioned, the Modifications space on Victron Community is the primary resource for support. Additionally, for Signal K specific inquiries, the Victron channel in the Signal K Slack is recommended.

Please do not contact normal Victron support for Signal K assistance, as it relies on community support rather than official channels.

5.3 Signal K details

TODO: Remove these version numbers and replace them with a link to the change log. Add specific information about the Signal K installation within Venus OS.

• Signal K node version: 1.18.0
• Victron Venus Plugin: v1.10.0

5.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. Further documentation is available here.

Step 2. Configure serial connections

Use this section to configure USB-connected NMEA0183 connections in Signal K. Navigate to the dashboard (http://0.0.0.0:3000), then go to Server → Connections.

Avoid adding connections for built-in serial ports (e.g., /dev/ttyO0, /dev/ttyO2, /dev/ttyO4, /dev/ttyO5). These are the VE.Bus and VE.Direct ports on the Venus GX, and their data is already available in Signal K via the “Victron Venus Plugin” (Dashboard → Server → Plugin Config). Configuring these ports in Signal K is unnecessary and may prevent them from being recognized by Venus OS.

Note: Once a USB-serial port is configured in Signal K, it may no longer be available in Venus OS. For instance, configuring a USB-GPS port in Signal K might prevent Venus OS from recognizing the GPS.

Step 3. Configure can-bus connections

For the Venus GX, Signal K includes a pre-configured NMEA2000 listener for VE.Can ports, named “n2k-on-ve.can-socket”, which uses canboatjs.

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

Step 4. Adding Signalk Plugins or Webapps

TODO: Explain and warn about data partition size and available space, as plugins are installed here. Filling the data partition can corrupt Venus OS. More information about the data partition on Venus OS is available here: Victron Wiki Data Partition.

5.5 Signal K FAQ

Q1 How to best handle & install a GPS

To ensure GPS data is available in both Signal K and Venus OS (for VRM reporting), and to obtain quality GPS data:

USB GPS Dongle

Plugging a USB GPS dongle into the GX Device will automatically recognize it within Venus OS. The data will also be available in Signal K via the Victron Venus plugin, requiring no further configuration.

NMEA2000 GPS

Connect the NMEA2000 GPS to the GX Device's CAN bus port. Consider using a VE.Can to NMEA2000 cable to connect NMEA2000 Micro-C cables to the GX Device's RJ-45 port.

In Venus OS v2.60 and later, support for NMEA2000 GPS devices has been added.

Signal K can receive this data in two ways: directly from the NMEA2000 CAN bus (if configured as a data provider in Signal K) or via the native Venus OS functionality through the Victron-Signal K plugin.

Conclusion (untested): When using an NMEA2000 GPS, the data should be available in both Venus OS and Signal K.

Regarding NMEA0183 networks: It's generally not possible to have NMEA0183 within a network; it's typically point-to-point.

6. Remote access via VRM

6.1 Node-RED flow editor and Signal K

It is possible to access the Node-RED flow editor and Signal K remotely via VRM. The interface and functionality are identical to accessing them via LAN (e.g., using http://venus.local:1880/ or http://venus.local:3000).

Step by step instructions

• Step 1. Log in to or open the regular VRM 'dashboard' or 'advanced' page for your site.
• Step 2. Modify the URL to include `/proxy/` after the site URL ID (note that the trailing `/` is required). For example: `https://vrm.victronenergy.com/installation/12345/proxy/`, where `12345` is the unique site URL ID.
• Step 3. Click on the Node-RED or Signal K button in the Proxy relay screen. Depending on your location and internet connection speed, there might be a short delay during loading.
• Step 4. The Node-RED flow editor or Signal K interface screen will appear.

6.2 Node-RED Dashboard/User Interface

The Node-RED dashboard/user interface can also be accessed remotely via VRM, offering the same functionality as accessing it via LAN (e.g., using http://venus.local:1880/ui).

Step by step instructions

• Step 1. Follow steps 1 to 4 in section 6.1 to establish the remote connection.
• Step 2. The new proxy URL needs to be modified to include `/ui` after `.....victronenergy.com`. For example: `https://12345-nodered.proxyrelay3.victronenergy.com/ui`, where `12345` is the unique site URL ID.
• Step 3. The Node-RED dashboard/user interface screen will appear.

Appendix A - Repartitioning Venus GX flash memory

The Venus GX has sufficient flash memory for the Venus OS Extended image. However, units produced before the end of 2018 had a partition layout unsuitable for larger Venus OS versions. This appendix explains how to update the partitions to the new format.

Perform this procedure only when connected via Ethernet. Do not use the built-in WiFi AP, as it will not function correctly during the procedure. Any existing WiFi client configuration will also be wiped.

WARNING: This procedure is provided for technically skilled users who wish to upgrade their Venus GX to be compatible with the extended Venus OS version. Victron Energy offers no support or warranty for this process. While running the installer is not a standard end-user procedure, it is typically performed in the factory. It is impossible to permanently damage the device using this procedure; the installer can be run again. However, to restore device operation, files may need to be restored as well.

Venus GX devices with serial numbers HQ1842xxxxx and later come with the new partition layout pre-installed from the factory.

Requirements

• An SD Card
• Computer skills

Note: USB sticks are not supported; installer images can only be run from an SD Card.

Step A. Enable and obtain root access

Refer to these instructions.

Step B. Secure factory files

Copy the following files from your computer:

• `/data/venus/serial-number`
• `/data/venus/wpa-psk`
• `/data/venus/part-number`
• `/data/conf/vrm_auth_token.txt` (skip if it does not exist)

The following command-line instructions demonstrate how to copy these files on Linux. For Windows, use Mobaxterm or WinSCP. Putty is not suitable for file transfers, although Putty SCP (PSCP) can be used if you are familiar with the Windows command line.

Procedure on Linux:

mkdir my-temp
cd my-temp
mkdir conf
mkdir venus
scp "root@192.168.178.122:/data/venus/*" ./venus/
scp "root@192.168.178.122:/data/conf/vrm_auth_token.txt" ./conf/

Background information on the factory files

The first two files are necessary for the built-in access point to function. Without them, the script may enter an infinite loop.

The third file is not currently used but can be recreated manually.

The fourth file is essential for the system to send data to VRM. Ensure this file is kept, or after booting the new version, navigate to VRM Portal → Settings → General. At the bottom, there is an option to reset the token, which becomes visible only after the portal receives data from the reflashed device.

Step C. Run the installer image

First, download the latest official installer image. Then, write it to an SD card (tip: use BalenaEtcher, see Google).

Finally, run the installer by inserting the SD card containing the installer and powering up the device while pressing the small recessed button next to the long green connector (e.g., using a paperclip).

A bi-color LED on the other side of the green connector indicates the status:

• Off: No image found
• Red blinking: Busy
• Green on: Done
• Red on: Error

For more details on installing an image, see here.

Once completed, reboot the device.

After booting (30-60 seconds), the LED will blink green slowly, indicating the WiFi access point is off (as expected). Refer to the Venus GX manual for LED operation details. You will need to regain root access:

• Go to Remote Console on LAN, change the access level, enable SSH, change the root password, and log in.
• As previously warned, this must be done via the LAN port. The built-in WiFi access point will be disabled, and any prior WiFi client configuration will be lost as the installer wipes all settings.

Step D. Restore the files

To restore the files on Linux:

scp ./conf/vrm_auth_token.txt "root@192.168.178.122:/data/conf/"
scp ./venus/* "root@192.168.178.122:/data/venus/"
# reboot
ssh 192.168.178.122 reboot

Once completed, the WiFi access point will be operational again.

Step E. Install extended Venus OS

The Venus GX has now been repartitioned and has a version of the normal Venus OS installed. The next step is to install the extended image. Refer to the Installation instruction chapter above.