Posted by Peter Kennedy on 7/24/2023 to System Integration
Node Red is a flow based programming tool initially developed by IBM. It allows people with minimal programming experience to write routines using a graphic user interface. The program is a very mature tool with widespread adoption throughout the "Internet of Things" world. Node Red is open source software and is not a Victron product, but Victron have built it in to the Cerbo GX and have written all the "Nodes" necessary to use it with their products. They don't offer support for it but do provide a number of help files and a three part webinar series to get you going. There is a section of the Victron Community site devoted to Node Red and a number of other resources available which we will list at the end of this article. Our aim here today is to get you started with a basic flow, so the title of this should really be "Node Red 101". The video below talks you through everything you need to get started. If you scroll down we will follow along with a text version and include additional links.
To use Node Red you will need a GX device such as the Cerbo GX or one of its more recent variations like the Ekrano GX and you must have it connected to the internet. To get started you should update the firmware to the latest version. Once that is done you can update the image type to Large. This is done in the Cerbo menu at SETTINGS>FIRMWARE>FIRMWARE UPDATES and the page looks like this:
Once you have updated the image type to large you need to check for updates again and it will prompt you do do an additional update. Once all that is done you can scroll down the the very bottom of the settings menu to see SETTINGS>VENUS OS LARGE FEATURES
Here you will have the option to enable Node Red as shown in the screenshot below. Then it will give you the address to access Node Red in a browser on your computer. The standard address it gives is https://venus.local.1881 For this to work both the Cerbo GX and your computer have to be connected to the same network. You will have to bypass the security messages. Since you are running in local mode the site is self certified and you can ignore the security messages.
You can also access Node Red through the VRM where it will show up as one of the options in the user interface. You shouldn't have to worry about security messages here since the VRM is a secure site. Here is where to find Node Red on the VRM
Here is what you will see in your browser the first time you look in the local window using the address https://venus.local:1881
For our first programming exercise we are going to set up a flow to operate the relay in the Cerbo. You can already operate the relay remotely over the VRM so in a real situation there isn't any real need to use Node Red for this. We are just using this as an easy example for our first "Flow". We chose to work with Relay 2 because Relay 1 is often used as a generator start control. In order to allow Node Red to control the relay we have to set the relay to manual control in the Cerbo. This we do by going to SETTINGS>RELAY and setting Relay 2 to manual control. Now we are ready to begin our programming.
To get started we are going to use the Inject function, found at the top of the "Common" Palette on the top left of the screen. The Inject function will send whatever we tell it, and we are going to use two of them, one to act as an ON button and one to act as an OFF button. We drag the buttons into our work area, doing it twice, once for each function.
By default the Inject Button is set to inject a timestamp but we want to change that so it injects a number instead. 0 will be the number for OFF and 1 will be the number for ON. When we double click on the Inject Button a dialog box opens up to allow us to configure this. We need to change the message payload to be a number and then make one of the Buttons has a value of 0 for OFF and the other has a value of 1 for ON.
Now we have our switches set up for OFF (0) and ON (1) they look like this:
Next we need to find the relay to control. For this we scroll all the way to the bottom of the list of Palettes to find the dark blue Victron Nodes and when we do we find there are two buttons that say relay. One has a dot on the left hand side of the button and one has a dot on the right hand of the button. The one with the dot on the left signifies that we are sending information IN to the relay and the one with the dot on the right signifies that we are getting information OUT of the relay.
The lower one, labelled Relay Control, is the one with the dot to the left indicating it will accept an input from our switches. When we drag this into the workspace it will show up with a little red carrot shaped mark on the top that signifies it has not been configured yet. We have to double click it to do the configuring.
When we double click the Node we get the configuration box and we select Relay 2 from the dropdown menu and we get to make a label for our Node, we are going to call it GX Relay 2
At this stage our routine is almost complete so all we have to do is connect the dots and hit DEPLOY.
The little blue dots in the image above signify that the flow has not been Deployed (another word for saved) and once we hit Deploy the flow is active and the blue dots go away.
Deploy is found in the top right corner of the workspace. At this point our flow is active and when we click one of the ON or OFF buttons we will get the "successfully injected" message:
When I got this far and realized that we had completed our first flow I felt proud of my success but also a bit underwhelmed. It was quite a lot of work to get to this very minor outcome. The problem is that you don't get any feedback to know if the routine is working. Unless you are standing beside the Cerbo and can hear it click there is no feedback to know if it worked or not other than the "successfully injected" message. So to take this to the next stage we need to make a Dashboard that will let us see the results of this and any other flows we make.
The Dashboard is not enabled by default so we have to go to the very top right hand corner of the workspace, click on the three bars, and scroll down to "Manage Palette". Then click on the "Install" tab and search for "Dashboard". We are looking for the one called "node-red-dashboard" Click to install and it will load in the background. It will add a whole new light blue colored palette to the left of the screen when it is done. Here is the sequence of screenshots:
I'm going to talk about the next part of the exercise in a slightly different sequence than we did in the video. We are going to grab a "Switch" node from our new palette and use it to send a signal to our existing relay node. We need to configure our switch to give the same 0 or 1 output. Notice that the switch has dots at both ends so it can output a command but also input something. By default the switch is set up with a "true" or "false" logic. We need to use the drop down menu to set the payload to "number" and then make the ON payload a "1" and the OFF payload a "0"
You can't use the Dashboard without configuring a Group so click on the pencil logo and make a Group name and when you are all done your properties tab will look like the screenshot below. You can also name the switch in the lower box below.
Hang on in there, we are almost done. We could just connect our configured switch as shown below and call it a day but then there would be some confusion because there are multiple ways to trigger the switch and we need a way to keep track of where it is set to. We can turn the relay on and off from the screen of the Touch 50, we can turn it on and off from the VRM, and now we can turn it off in Node Red also. If we just went with the flow below we wouldn't really be able to keep track of its state when one of the other interfaces triggered it.
To finish off our flow we need to grab the "Relay" Node from the Victron Palette. We need the one with the dot on the right because it is going to send the information out from the relay to our switch. We need to configure it to be the Cerbo Relay 2 and it will automatically be set up that 1 in ON and 0 is OFF. We can name it Relay 2 State.
The very last thing to do is connect the dots and Deploy so the finished flow looks like the view below. You can see that the switch has an icon to show which way it is set to.
At this point we can open the dashboard to view our finished work. All the way in the top right there is a dropdown box for Dashboard, and when you click on that there is a little icon to open the dashboard in a new tab. At that point you can click the switch to operate the relay, or if you operate it from elsewhere the dashboard will reflect what happened.
HOMEWORK AND FURTHER READING
There are lots of resources available for further learning including quite a few published by Victron. Be sure to check out the Victron 3 part video series about getting started with Node Red. Further reading about Victron specific attributes of Node Red can be found on the Venus OS Large page and Victron’s Node Red GitHub page For more general Node Red information check out the Node Red Tutorials and the Node Red’s Essentials YouTube playlist
This was a fairly challenging project to begin with considering the small amount we achieved. We wanted a project that would introduce you to as much as possible without being too long or complicated. Its not all as hard as this. Now that you have your dashboard set up you can play around by introducing Victron Nodes from the list that have outputs (ie that have the dot on the right hand side) and then pairing them up with Nodes from the Dashboard palette that can display the information. You can display text, graphs, gauges etc. Just choose Nodes that represent things that you have present in your system. If you have a Ruuvi sensor its a great start because it has multiple values including temperature, pressure and humidity and these can be represented by text, gauges or a graph, or all three. By default the text value will display many decimal places but if you hunt around a bit you will figure out how to trim them to what you want. Also if you have a battery monitor in the system there will be lots of values you can play with. Then you can pair these information sources with some of the nodes on the dashboard palette. Here are some suggestions:
Here is one example dashboard I made: