An introduction to using Node-red with Home Assistant

Home Assistant is an incredible powerful platform and it is growing every day. With its two-weekly release schedule, it is quickly becoming the top home automation platform to go to.

One thing which hasn’t always been easy in Home Assistant is setting up automations. That’s until the Node-red add-on came into existence. Node-red is a tool, developed by IBM, to create flows in a visual way. This means that with this add-on, you’ll be able to set up your automations using a flow-based editor.

This post will take you through setting Node-red up and building your first simple flows.

Setting up Node-red

For the rest of this post, I will assume that you run Home Assistant under Hass.io. In that case, Node-red is available as one of the Community Hass.io Add-ons. The quickest way to install it is to go to your Hass.io hub in your HA installation, find the Add-on store and look for the Node-red add-on under the Community Hass.io Add-ons. Once installed, fill in the details in the config (the username and password have to be filled for all three groups). After clicking start, the server will only take a few minutes before it is ready.

Node-red 101

As soon as you open the Node-red server, you will see a screen similar like the one below.

The area with the grey grid in the middle is where we will soon build our first automation. Before that, let’s first get some terminology straight. In Node-red, our beloved automations are actually called sequences. Each sequence consists of a number of nodes that together define that automation. Finally, all the sequences on the sheet together are called a flow. Below you can see it summarised.

Creating your first sequence

The problem with any example here is that it will always be biased on my setup and therefore it will be more difficult for you to replicate it. To solve this, I will start with a pure debugging example, to show the basic behaviour. These debugging hints also form a solid basis to later test on your automations.

Let’s get started. Each automation will always have one (or more) triggers and one (or more) actions. Examples of trigger nodes for Home Assistant are: ‘events: all’ or ‘events: state’. Examples of action nodes are ‘call service’.

For now, we will use the more generic ‘inject’ node as a trigger (under input) and the ‘debug’ node as an action node (under output). Simply drag them to a new flow and connect them to form your first sequence. The result should look like the one below.

Node-red works by passing messages from one node to the next. Each node can of course change the content of the message. The default message that you will be working with is msg.payload.

Double-click on the ‘inject’ node to start setting up your first messages. Click on timestamp and change it to string. As a first message I symbolically took ‘Hello world’, but any message will work. The result should look like this.

We will not waste another minute. Click deploy (top right) (1) to deploy your first automation. Before running the sequence, open the debug pane (top left, below the deploy button) (2). If you now click the trigger of your trigger node, you should see the ‘Hello world’ debug message (3).

Great, you have just created your very first Home Assistant automation using Node-red. Tastes for more, right? Alright, let’s start the real work by incorporating some HA nodes.

Add an ‘events:state’ node to the flow pane. Double click on the node to adapt its settings. For this example, I chose the sun.sun entity ID since everybody has it. However, feel free to choose another more interesting trigger. The list is dynamic, meaning that you can just start to type and it will show the available entities. After changing the name and the entity ID, my settings look like this.

Now save it and connect it to the debug node. The result should look like this.

As you can see, it is no problem to connect multiple nodes to one. The second node will work its magic if any of those input nodes is triggered. The current setup is quite boring as it will generate a debug message only twice a day. For the record, the ‘event:state’ node is only triggered if the state changes. The sun rises once a day (below_horizon -> above_horizon) and sets once a day (above_horizon -> below_horizon).

You can make the result a bit more interesting by connecting it to a presence sensor or something else that changes more quickly.

For now, we will stick to this example and add a light. The light is supposed to turn on when the sun sets. We do this by adding ‘call service’ node. This node type can also be found under the Home Assistant group. You know the drill, drag it to the flow and connect it to the Sun trigger.

Again, double click to pop up its settings. This time the settings are a bit more complicated. The name and the server are the same as before. However, instead of having a simple entity ID like before, this time there are three fields. Domain sets the entity type. Select ‘light’. Service defines what will happen. It is also dynamic. We will select ‘turn_on’ here.

The data field is why this process is a bit more cumbersome. In order to specify which light and with what settings, we must use JSON. Don’t worry, you can use Home Assistant to generate it. In the side pane on HA, select the remote icon under developer tools. This will open the services view.

You can add [domain].[service] here to open up the options. Under entity you can find your light. The service data is the content that you have to copy in the data field in the node settings. My result in the services view looks as follows.

Finally my node settings look like this.

Now select deploy and you are ready to go. The lights now turn on at sunset… and at sunrise. How do we select the right one? For this simple case, there is a quick solution.

Go back to your trigger. In the settings you can see that we skipped a field. The ‘Halt If State’ pretty much does what it says. Whatever value is in here, will stop the trigger. In our case, this is above_horizon. Fill this in to complete your first automation.

Other node types

We won’t add examples for all other node types, but here are few to get you started.

The ‘current state‘ node acts a lot like the ‘event: state’, the difference being that is does not trigger an action. It is only useful when you use a different trigger, but then also need a value from another sensor. Don’t forget to give it an input node.

The ‘events: all‘ node basically triggers at everything. It find it very useful as a fallback. If something is not doable with the ‘current state’ node, use this one.

The ‘switch‘ node is convenient to process information. It works very well with the ‘events: all’ node as a filter. You can also use it to separate one (or more) paths. For instance, if your Chromecast might report ‘playing’ or ‘paused’, this node can be used to split the payload in two subpaths.

This post only scratches the surface of everything that is possible in Node-red. Give it a go and post the results in the comments below.

Leave a Reply

Your email address will not be published. Required fields are marked *