Node-RED + Home Assistant How-To

May 14, 2018

Integrating Node Red with Home Assistant

Today on the hookup we’re going to look at how to integrate Home Assistant – a comprehensive smart home component platform, with Node Red – a simple and powerful automation platform.

A fair warning before we start, this video is longer than I had anticipated. If this is your first time using node red I’d suggest you watch from the beginning to the end. If you’ve been using node-red for a while and would like to jump around the video here’s a basic table of contents for you to scrub to the part of the video that interests you.

I’ve been coding in different languages for about 10 years now and I feel pretty confident picking up new languages on the fly, but for some reason writing automations and scripts in yaml always felt unnecessarily difficult to me. Not only was I confused by the mixing of syntaxes, but I was often discouraged from trying more complicated automations because I had a hard time troubleshooting them if they didn’t work.

Enter NodeRED, a platform that combines visual flow charts with simple scripting and programming to produce a fantastic automation experience.

Today we’re going to write some example flows to learn how to use each of the most useful nodes included in node red, and even some optional nodes.

Before we start, let’s talk a little bit about terminology. Over on the left here you’ve got a bunch of these little rounded square things. Each of these is called a “node type”, if I drag 2 of the same type out I would say that I had 2 nodes, but only a single node type.

Next, at the top we have all of our different flows. I’m actually not thrilled about this terminology. A flow in node red actually refers to everything in one of these tabs, I tend to make the mistake of calling a set of connected nodes a flow, but I believe the actual terminology for that is sequence.

So a single rounded square is a node, a series of connected nodes is a sequence, and all of the sequences on a single tab are called a flow. This may seem like worthless knowledge, but it’s actually important for understanding the different variable scopes in node red.

The information sent through a single sequence is called a message object, and it can contain as many individual variables as you want. Each of these variables will have the prefix M S G, the default message variable sent out of a node is called msg.payload. A variable with the msg prefix only exists in the current sequence, meaning that if there isn’t a line connecting nodes together the msg from one node cannot be processed by another node.

A different type of variable scope is called “flow”, these variables can be called by all nodes on the same tab, which if you recall is called a flow. All the variables in this scope will the prefix “flow”. A third type of scope is called “global” and variables from the global object can be called by any node anywhere in node red.

Okay, lets start with an easy example. I have an input Boolean set up in home assistant for “Rob Home”, that’s me, and “Lindsay Home”, that’s my wife. These input Booleans are toggled when our phones connect or disconnect from google wifi. In order to use these states to control the “house occupied” input Boolean I have the following two sequences in node red.

The first node type we’re going to look at is the home assistant events state node. This node will send a message any time the selected home assistant entity changes states and the payload of that message will be the state that it switched to. Setting up these nodes is simple because it will auto populate the entity id for you as you start typing.

In this automation We’ve got 2 event states that correspond to the “Lindsay home” Boolean, but each of them has a different “halt if” condition set. If halt if “on” is selected it will only send the message on if she leaves the house, if halt if “off” is selected it will only trigger when she comes home.

In the event that my wife or I come home it doesn’t matter whether the other person is home, we always want to set the house occupied Boolean to on. We do this with a home assistant “call service” node. These are slightly more difficult to configure because you have to use json to specify your entity ID, this is a necessary evil because using json allows you to pass additional arguments with your service data (things like brightness if you’re calling the light.turn_on service, or message if you’re using the notify service). If you don’t feel comfortable writing your own json that’s okay because you can go to your services developer tool in home assistant and use the dropdown menus to generate the correct json data. The call service node for an input Boolean lets us either turn it on, turn it off, or toggle it. In our case we want to specifically call turn on, not toggle.

This is just about as simple as of a flow as you can get.

Conversely, In the event that one of leaves the house we don’t automatically want to set the house to not occupied. In these events we utilize a different home assistant node, the current state node. The current state node is set up almost exactly like the event state node, but it never triggers a sequence, it only goes in the middle of a sequence. By using this current state node we can check if I’m still in the house when my wife leaves. If I’m still in the house (meaning the “Rob Home” input Boolean is on) the flow will be halted there. If I’m not home it sends the message on to the next current state node, which checks an input Boolean called “house guests”, because we don’t want to be turning out the lights on our guests if my wife and I happen to both leave the house. If that Boolean is on, the flow stops, and if it’s off it gets to continue on to trigger the call service node, this triggering the turn_off service.

My favorite part about node red is how logical it is, lets just talk through this sequence real quick: Lindsay left, is rob home? If not, are there house guests? If not the house is unoccupied. Simple and intuitive.

If you are ever trouble shooting a sequence and you can’t figure out where things are going wrong you can attach a debug node to the sequence and see what is contained in the message object that is passing through that node. If you ever want to see what will happen when a node is triggered with a specific payload you can also use an inject node. You can choose what kind of payload you want to send from your inject node with the dropdown box. Once you’ve set up your inject node, hit deploy and you’ll be able to click this small square to trigger the message.

Lets kick this up a notch and do an automation with multiple variables.

In this automation I want to send an actionable ios notification to my phone and my wife’s phone when a window is opened in our house. I want the notification to include a message stating which window was opened, a picture from our security cameras of that window, and a button that would allow us to manually trigger the siren on the house if we don’t like what we see in the picture.

Before starting this sequence we need to make sure we’ve already done a few things in home assistant:

Install the homeassistant iOS app
Enable the ios component in home assistant
Add a push action under your ios component
go back to your home assistant iOS app and enable notifications and then tap “update push settings”

Here’s how the sequence works. To start, I have an event state node for each window. The sensors on my window send 1 of 3 message types: open, closed, or a replace battery message that includes the current voltage of the battery. Those 3 states are the 3 possible msg.payloads that will come out of the node, but I don’t really care about the closed message, so I have a “halt if” condition set for the “closed” payload. The next node type that it runs into is called a switch node, this node is like a fork in the road. Each fork can have different conditions associated with it, and it’s possible for more than 1 of those conditions to be true causing the payload to split off in multiple directions. In our case I want the conditions to be msg.payload equal to open or msg.payload not equal to open. The reason I have it set up this way is that I won’t know what the battery voltage is when it comes through, so I can’t know what the exact message will be equal to. Another way I could have set this up is to use the contains flag set the value to “replace”.

Next we are going to set the value of our notification properties. To do this we use a change node. I am not going to change the original message which is usually passed as msg.payload, instead I want to set a new variable within the message. I’m going to call this variable msg.windowName, and I set it to the message that I want to appear on my notification, in this case “Family room window open”. I’m also going to set another variable called msg.image where I put the url of the snapshot from my cameras, I had to blur out most of this url, but I’ll include a generic version of it in the github code. I’m not sure if the home assistant people intended for this snapshot url to be known, but it works great for me.

Now that we’ve got all of the parts for our message we just need to put them in the right format. To do this I’m going to use a function node. I like to cheat here and use a YAML to JSON converter, not because I can’t write JSON, but why do more work than you need to? The actionable notification documentation is not great, so I’ll post both the YAML and the JSON for a successful notification down in the description. You can see that for the message and attachment properties I have the variables msg.windowName and msg.image called instead of hardcoded values. After passing through this function node our msg.payload now contains this formatted json code.

The final step for the actionable notification is to pass this beautifully formatted json to a call services node and the trick here is to just put a set of empty curly brackets in the data field because your msg.payload is automatically included into this field.

There’s another branch comes off this function node and checks to see if our exterior alarms are armed, and if they are it sends a load of other messages out to activate sirens and lights on the house.

The last little thing on this automation is this other path on the first switch node. This sequence passes the low battery warning message in a standard non-actionable notification to my iphone only, because lets be honest, the wife isn’t going to replace the batteries.

So far we’ve used the standard node red nodes: change, switch, and function, and we’ve used the home assistant nodes: event state, current state, and call service.

Before we move on any further I’m going to say something about function node. The function node is probably the most powerful node type in node red, and I’m sure a very common criticism of this video is going to be that I could have combined many of the nodes in my sequences together with a single function node. And it’s true, but the whole reason we’re using node red in the first place is to move away from having to write significant amounts of complicated code for our automations. The purpose of this video is to show how simple it is to use node red to do complex automations, and putting too many function nodes in is a good way to confuse home automation enthusiasts who are not also javascript programmers. I may do a video in the future about using javascript to do crazy stuff in node red, but this is not that video. Moving on!

For our last automation we’re gonna get crazy. Lets check out the node-red dashboard and make a nice little alarm panel that can be displayed on a tablet mounted to the wall.

We’ll start by installing the node pack for node red dashboard. Click on the hamburger in the upper right to open the menu and select manage pallete. The node red dashboard is called node (dash) red (dash) dashboard. Just search for it and click install.

To see our end result we just change our url to /ui instead of /flow and that will bring us to our new security keypad.

Wow that was a long video. Hopefully this was enough of a primer on node types with enough examples to help get you started with Node-RED. I’ll post all of the flows I talked about in this video down in the description. If you want to use them as a starting point in your projects you can select import clipboard from the menu and paste in the code that I’ve posted. Fair warning: If you import the flow before installing the necessary node types in palette manager you’re going to get spammed with error messages in your debug window.

Now for a personal note: Because this is a new channel catering to a fairly niche market, I’m not a youtube partner yet which means these videos have zero monetization. Normally I make at least a few bucks from people using my amazon links in the description, but we didn’t build anything in this video so I don’t have any amazon links to post. If you’d like to support me and you need to buy something on amazon anyways, go ahead and click the link in the description for the new echo spot. You don’t actually have to buy the spot, anything you buy on amazon after arriving with my link will earn me a small referrer fee, which allows me to buy new products to showcase and motivates me to make more videos. So far I’m still a few hundred in the red for this video making venture, but that’s not really why I’m doing it, so no big deal if you don’t need anything right now. Anyways, if you enjoyed this video please consider subscribing and as always, thanks for watching the hook up.