How to get started with Node-RED and Home Assistant

First of all, let’s clarify what Node-RED is. Node-RED is a programming tool for making the automation in Home Assistant more visually. It gives you a browser-based Editor, where you can create the automation flows. The flow is based on nodes you can drag and drop from the left side panel. Node-RED is the perfect companion to Home Assistant and it is very easy to install. The new version of Home Assistant has made it easier to create automation, but in the early days, you would have to write the automation in Yaml.

In this tutorial, I will teach you how to create your automation visually using nodes in flows. You will be introduced to the browser-based Editor and we will go through some of the available nodes from Home Assistant (spoiler – there is a lot of nodes). Also, we’re going to create very simple automation, so you can get started with Node-RED in your Home Assistant setup.

Install Node-RED in Home Assistant

Alright, so the first thing you want to do is install the Node-RED addon through the addon-on Store. Open Home Assistant up in your browser and navigate to > Supervisor > Add-On Store > Select Node-Red under Home Assistant Community Add-ons > Click Install.

When the installation is completed, you have to go to Config on the add-on and configure a password that would be used for encryption. If you would like to enable the dark mode in Node-RED you would also have to change the dark_mode value from false to true in the config. It will look like the following:

credential_secret: Some-Random-Key
theme: default
http_node:
  username: YOUR_USERNAME
  password: YOUR_PASSWORD
http_static:
  username: YOUR_USERNAME
  password: YOUR_PASSWORD
ssl: false
certfile: fullchain.pem
keyfile: privkey.pem
require_ssl: false
system_packages: []
npm_packages:
  - git+https://github.com/hardillb/node-red-contrib-owntracks
init_commands: []

When you are done, click on Save. Head back to the Info tab, please toggle the switch for “Show in the sidebar” and click on Start. Now you will have Node-RED in the left menu panel in Home Assistant. Give it some time (probably a few minutes) to initiate Node-RED.

If Node-RED is not showing up in the sidebar, just refresh the browser (F5). Now we got Node-RED up and running and it’s available in the sidebar.

NOTE: If you got remote access set up in Home Assistant, you won’t need to set up port forwarding rules with Node-RED. This Node-RED add-on already supports Ingress. What this means is that you can access Node-RED securely from your Home Assistant instance no matter where you are.

Getting started with the Node-RED editor

Node-RED is separated into sections. Below is a list of the sections with a short description:

• The header includes the logo and has a Deploy button, that allows you to deploy in three different ways.
• Starting from the left, we have our Palette containing all the Nodes you can youse within a Flow. You can install more Nodes if you would like to.
• In the middle (where the fun stuff happens), you got Workspace where you can drag and drop nodes from the Palette. To make them work, we can drag a wire from one to another. When doing that you are creating a flow.
• In the last column in the right next to our Workspace, we got the Sidebar. This will show us details about the currently selected node, when on the info tab. These are also the columns that give us the debug panel, which might become your best friend. The debug panel will output all messages passed to a debug node within a flow. I will give you a short introduction to the debug node in a moment.

Introduction to Home Assistant Nodes

At the moment we have 18 available Home Assistant nodes in Node-RED. These nodes are already pre-installed when installing Node-RED in Home Assistant, so there is no need to do any further stuff. At the same time, there is no need for extra configuration for Node-RED to communicate with your Home Assistant instance. Alright – to get started, let’s have a quick look at the following nodes:

• events: state -> Checks for a state change on a specific entity and will then output the change. This will result a flow to be triggered.
• call service -> The Call Service is being used when you would like to send a request to Home Assistant in order to trigger a service. This could be a request for open the garage gate or turn on / off the lights in the garden.
• current state -> Current State will get the latest known state of the selected entity. This could be useful if you would like to trigger different commands depending on a state in Home Assistant. You can see this node as what a programmer would call an if statement within the code.

How to make a flow in Node-RED

What a lot of you are here for is some guidance on how to set up your first flow in Node-RED. As an example, I will be creating simple small automation that will turn off the lights in my office depending on the state of my laptop. If my computer is turned on, we are going to turn on the lights and of course, if the computer is off – so will the lights be off.

Step 1 – Check for events on an entity

At this step, we have to check if the computer is running. To do this, we will use the events: state node as described earlier. Drag and Drop the node from the Palette into the Workspace. Double click the node to open the settings. As you can see the Home Assistant Server is already selected for you. You only need to enter the id of your entity. In my case, I would like to check for state change at the switch at my office desk.

When you type in one of the following fields, you will get suggestions for auto-completion.
– Entity ID
– Domain
– Service
– Data
By having autocompleted on, you will minimize the risk of making typos resulting in lots of errors.

Step 2 – Handling of the output from the state change using a switch

To make decisions based on the output from the event change, we can use a Switch node from the palette. This node allows us to add multiple outputs for further interaction. Drag and drop the switch node into the workspace and connect the event state node to the switch node with a line.

Double click the Switch node to open the settings and configure it as I have done below:

When you are finished, click on the Done button. Now we got two outputs on the node. If you hover one of the outputs you will be able to see a label with a value. This gives you an easy way to figure out what output you need to connect other nodes to.

Step 3 – Turn the lights on with a Call Service Node

Okay so now we can check if the power for the desk has been turned on or off. This leads us to the call service node. Drag and drop two of these into the workspace and connect one to each of the outputs on the switch node.

Double click the node and give it a name that is easy to recognize. Configure the domain to be of type light and set the service to turn_on. For the Entity ID, you need to select the light you would like to turn on. If you got Philips Hue bulbs you can parse further data into the data field. This could be if you would like to trigger a special profile for the light. I will show you how to do this in another article – for now, leave it empty as we only want to turn on the lights. Do the same exercise for the off output and remember to change the service to turn_off.

TIP: You can copy a node by clicking CTRL + C (On Windows) or (CMD + C) on MAC.

If you have followed my guide above, you should now have a flow like the one above. Don’t worry about the messages below the on and off nodes.

Step 4 – Let’s debug the output from the service call

Almost there – Before we deploy our flow, we can connect a couple of Debug nodes to the end of our on / off flow for the lights. By using the debug panel (can be found in the sidebar by clicking on the debug tab).

When one of your nodes connected to a debug node is triggered, you will see the payload output in the debug panel. If you hover the message in the sidebar Node-RED will highlight the node in the workspace that made the message. This is a great way to keep track of how far you got in your flow.

Click on deploy and watch the debug panel to check for events when the trigger is activated in Home Assistant.

Step 5 – Getting smart with Time Nodes

Select the node called time range and place it in between our switch and the call service nodes. Double click to open it for settings and change the name of the node. Lat- and Longitude will automatically be set for you. (If you would like to, it’s possible to change these manually)

Now set the start time to sunset and the end time to sunrise.

Your flow should look like the following:

Step 6 – Getting started with “if” nodes (Current State node)

Let’s drag a current state node to our workspace and place it between the time range and call service node. Double click the node and give it a name. Also, specify the Entity ID (the id of your desk lights).

In the if state set the condition to “is not” and the value to “on“. This will now create two outputs on the current state node. The first output will pass on the message that allows us to turn on the light if it’s not already on. The configuration for the “is on” node, will look like the following:

Copy this node and change the if state to on and of course update the name to off or something appropriate for your node. The most important thing is that you can recognize them again and understand your automation. Remember to click deploy to save changes made to your flow.

Summary

I hope my short tutorial on how to get started with Node-RED and Home Assistant has helped you. If we take a look at the entire flow, it’s easy to understand what happens when and why. In short steps – when the desk power is turned on, a message is passed on our switch. This then tests if it’s an on or off command and passes it then to the right output which then turns on or off the lights based on the time and if the light ts is not already turned on.

You also learned a little about debugging your flow with the debug node. In future tutorials, I will cover debugging further to make you a superstar in debugging errors in your flows. If you got any suggestions or questions, please drop them below.