Using Helium To Automate Your Home

This is a project tak­ing you through the basics of how to use the Heli­um LoRaWAN for projects around the home. Relax, we won’t be automat­ing your entire house and acci­den­tal­ly unleash­ing Ter­mi­na­tor. This is just a very sim­ple start into using Helium.

At the end, if you fol­low all the direc­tions, you’ll have a light that turns on when a door or gate opens. Super sim­ple. Here’s what it looks like in broad strokes.

Obvi­ous­ly you have a badass iron gate at the entrance to your man­sion. You’re in cryp­to, right?

Here’s how the flow works in writ­ing, with a lit­tle more detail.

The door sen­sor sends an “open” or “close” pack­et of data along with and iden­ti­fi­ca­tion of the sen­sor (“I’m a door sen­sor named 2r782sdhvwjf, and the door is now open”) over LoRa to any near­by Hotspot. 

That Hotspot pass­es the info on to the Heli­um router via the inter­net. When the data gets to the router, the router says, “Hey, any­one want to buy this pack­et from 2r782sdhvwjf?”

Your Con­sole account (which you’ve set up to watch for pack­et from 2r782sdhvwjf) says “Hell yes I’ll buy that pack­et!”, pays with Heli­um data cred­its, and receives the pack­et data. 

The data from the pack­et goes into your Con­sole, where it’s decod­ed and passed on to an “inte­gra­tion”. The inte­gra­tion in this case is to an MQTT (Mes­sage Queu­ing Teleme­try Trans­port) “bro­ker”.

A “bro­ker” in this case is an appli­ca­tion that receives and for­wards MQTT mes­sages. That MQTT mes­sage is sent by the bro­ker to an open source pro­gram called “Home Assis­tant”. Home Assis­tant lives on the Rasp­ber­ry Pi. 

The Rasp­ber­ry Pi receives the data from the MQTT bro­ker, process­es it in Home Assis­tant, and spits out a nice lit­tle “open” or “close” mes­sage which it then trans­mits over WiFi to your Kasa (or any smart plug) say­ing, “Hey dawg, door’s open, get that light on stat!”

And that’s it, at broad strokes. Ok, let’s dive into how to do this thing at home. We’ll start with spend­ing mon­ey, about $130 total. Relax, most of that is the Rasp­ber­ry Pi, and once you have one you can use it to do all sorts of oth­er things. Think of the Pi as a Swiss Army knife. This time you’re buy­ing it for cut­ting bread with the knife, but in the future you can use the corkscrew for wine, the screw­driv­er for open­ing that wood­en ship­ping box with the Lis­ter engine you’ll won­der how you lived with­out, and the tweez­ers for remov­ing that SD card. But…let’s not get ahead of ourselves.

Purchase List

I put in the option for an indoor or an out­door Kasa plug, which depends on where you have your light plugged in.

Once you’ve received all the phys­i­cal things we’ll go through the fol­low­ing steps in order:

• Door Sen­sor
  • Add the sen­sor as a Device
  • Add a Decoder function
• Home Assis­tant (HA)
  • Install on RPi and con­firm it’s avail­able on your network
  • Con­fig­ure Home Assistant
• MQTT Mes­sag­ing Broker
• Con­nect everything

Aight! Let’s get this par­ty started! 

Add The Sensor To Helium Console

Step one: Add the door sen­sor to Heli­um Con­sole. Now, this is writ­ten in Decem­ber of 2022, about a month (maybe more) before we make the giant switch from Heli­um run­ning Con­sole for every­one (10 device free lim­it) over to when you’ll need to find anoth­er LNS (LoRaWAN Net­work Serv­er). These spe­cif­ic instruc­tions may not apply for­ev­er, but the broad strokes will. 

Find the DEVEUI, APPEUI, and APPKEY asso­ci­at­ed with your sen­sor. If they’re not in the box, you’ll have to do some fid­dly bits and buy one more thing for about $15. If that’s the case, lemme know in the com­ments and I’ll do up a tuto­r­i­al on that for you. Easy when you know how. Daunt­ing when you don’t.

Ok, I’ll assume you got the DEVEUI, APPEUI, and APPKEY. Enter them into the appro­pri­ate fields in Con­sole (or what­ev­er you end up using.). It should some­thing like this:

Ok, so con­cep­tu­al­ly, what we’ve done so far is tell the Heli­um net­work that when­ev­er any Hotspot receives data from this sen­sor (iden­ti­fied by the all the APP/DEV EUI keys) that you’ll buy that data. Relax, it won’t cost you that much, and if you want you can lim­it how often you’ll buy it or from how many dif­fer­ent Hotspots you want to buy it (if mul­ti­ple Hotspots “hear” it).

To make sure we’re get­ting pack­ets through, go ahead and move the sensor/magnet apart a few times, as if the door was open­ing and clos­ing. Pro tip: Do NOT install the sen­sor until the very end, oth­er­wise you may be doing a bunch of walk­ing back and forth to your door. 

You should see lit­tle dots march­ing across the screen on the Device page, like this.

Cool, so you’ve bought the data, now you have to decode it. Semi-con­fus­ing­ly, this data will need sev­er­al mod­i­fi­ca­tions in how its pre­sent­ed along the path sketched out above. Think of it this way: Not all com­put­ers speak the same lan­guage, and each time the data moves from one sys­tem to anoth­er, it (usu­al­ly) needs to be trans­lat­ed. This “decod­ing” is the first translation.

Add The Decoder

For this (and any) sen­sor, the man­u­fac­tur­er will usu­al­ly pro­vide you with the decoder to use. In this case, Heli­um also main­tains a Github repos­i­to­ry with a decoder for this device. Con­fus­ing­ly, the decoder for this device in Heli­um’s Github is called an LDS02, even though the device is an LDS01. I’ma use the Heli­um-sug­gest­ed LDS02version below. If you use any oth­er decoder you’ll have to make some changes to the code fur­ther down. If this is your first time doing this, just use Heli­um’s ver­sion. Here’s how to do that if you’ve nev­er used Github before.

Go to the page here, and look for “Decoder-v1.5.js” in the list of files.

Click on that and you’ll see a box with a bunch of code. Click the lit­tle dou­ble-square but­ton up in the top right to copy this. You’ll be past­ing this into the Heli­um Con­sole next.

Now that you’ve got the decoder copied onto your clip­board, head over to Con­sole and look for Func­tions on the left menu.

You’re crush­ing, nice work. Now we’re going to add a Func­tion, past­ing in the code you just copied. Hit the plus button.

Ok, we’re going cus­tom here, ’cause you’re worth it. Hit the Cus­tom decoder button.

That’ll take you to the func­tion page, where you’ll name your func­tion (I called mine LSD 01 Door Sen­sor) and then you’ll paste in the code from the github decoder.

Remem­ber, this isn’t the Device you’re nam­ing, it’s the Func­tion. Once you have this Func­tion decoder in Con­sole, you can add a ton of devices and have all of them use the same Decoder Func­tion. Cool, huh?

Now, if you just want­ed to know if the door is open or closed when­ev­er you looked at a dash­board, you could do one more step (add an inte­gra­tion to Dat­a­cake) and you’d be done. The flow would look like this in Console:

How­ev­er, I don’t think that’s ultra use­ful. I mean, you’d have to open up a Dat­a­cake dash­board just to see if the door’s open. That ain’t automag­ic, that’s a PITA. Onward!

Set Up Home Assistant On A Raspberry Pi

Let’s fire up that Rasp­ber­ry Pi you bought! I put mine in a very snazzy FLIRC case, but you don’t have to.

Now, despite my love for explain­ing things, the inter­netz has done a far bet­ter job of Pi tuto­ri­als than I have, so I’ll just leave ya with what the good folks over at Home Assis­tant (HA) have writ­ten as far as set­ting up HA on your Pi. Come back when you’re done! 

It should look some­thing like this when you’ve fin­ished. I mean, it might not be sun­ny and 57°F, but hey, that’s the bit­ter depths of win­ter here in San Diego.

Great! For now, we’ll leave Home Assis­tant and make sure we’ve got a reli­able place for our MQTT bro­ker (com­ing up next) to check in with Home Assistant.

Set Up A Publicly Accessible IP Address

Step 1 of the MQTT flow is to set up an IP address that Heli­um Con­sole will con­nect to the bro­ker on. The Heli­um Con­sole MQTT Inte­gra­tion will need to con­nect to this bro­ker at a pub­licly acces­si­ble ip address and port. Unless you have a fixed ip address (you prob­a­bly don’t), you should set it up so that you can refer to this address with a name that does not change. 

I used the free ser­vice pro­vid­ed by https://www.noip.com/ (check out that link for how to do it all, and heads up…port for­ward­ing is a lit­tle tricky for first timers!)

With noip.com, I can get to my home net­work using an address like “gksupernet.hopto.org”. That’ll send it to my cur­rent IP address as well as what­ev­er my pub­lic IP address changes to next month when my inter­net ser­vice provider rolls it. 

Now that we’ve set it up so you’ve got a reli­able URL to send to (gksupernet.hopto.org, or what­ev­er you set up on noip.com), let’s jump back into Home Assistant. 

First, let’s set your HA pro­file to Advanced mode. Go to your Pro­file (down in the bot­tom left menu, it’ll be your name), then scroll down until you see Advanced Mode and turn it on.

Add the Mosquitto Broker to Home Assistant

Next, we’ll add the MQTT bro­ker add-on. This is basi­cal­ly a trans­la­tor and mes­sage for­warder for IoT devices. You can dive in here if you want, but for now, think­ing of it as a translator/forwarder is prob­a­bly fine. Instruc­tions on how to add the “Mosquit­to Bro­ker” are here if you want ’em direct from the horse’s mouth. I’ll do the paint-by-num­bers next just in case ya need it. 

Start in your Home Assis­tant “front end” (I have mine saved as a book­mark), and look for the Add On Store.

Once you go to Add Ons, look at the bot­tom right for the Add On store. 

In the store, search “Mosquit­to Bro­ker” and install the Add On. That should look like this.

Once you’ve installed Mosquit­to bro­ker, next you’ll need to set up a user. Go back to the main menu (NOT in the Mosquit­to Add On) and look for Settings–>People

Then look for the User tab, and set up a user. I set up “mqtt-user” and used “asd;lfjas;ldkfjasd;lfjkas” for a pass­word. No, that’s not real­ly my pass­word. Sheesh.

Saweet!

AIGHT, let’s set up a port forward!

For this spe­cif­ic guide, you only need to set up one port for­ward: 1883. That’s the default port for an MQTT bro­ker. Hav­ing that port open on your net­work and for­ward­ing it to the local IP of the RPi run­ning Home Assis­tant means the MQTT bro­ker can receive mes­sages from Heli­um Con­sole and pass them on to Home Assis­tant. Con­cep­tu­al­ly, that looks like this:

Port for­wards poke a very spe­cif­ic hole in your net­work that is open to the out­side world. If you think of your pub­lic IP as your home address that will take some­one to your “front door on the inter­net”, a port for­ward is like a tun­nel from that door to a spe­cif­ic place in your house. That place could be a room, or a thing. In this case, the port for­ward is to one part (the MQTT bro­ker) of one thing (the Rasp­ber­ry Pi) on your network. 

So, we’re in kind of an odd spot here. “Port for­ward­ing” is one of those things that is cus­tom to your router. The absolute best way to fig­ure it out is to Google [your router mod­el] and “how to port for­ward”, then fol­low the direc­tions. It may be (has always been for me) a pain in the ass, but even­tu­al­ly I get it. You’re wel­come to jump into the GK Dis­cord and ask ques­tions, usu­al­ly there are a few help­ful folks in #gen­er­al.

What you should have when you fin­ish is a pub­licly acces­si­ble address of your bro­ker. It’ll look some­thing like this:

mqtt://myusername:mysecurepw@gksupernet.hopto.org:1883

Sub­sti­tute your user name, pass­word, and the dynam­ic pub­lic IP you set up with noip.com above and every­thing *should* work. 

Now, that URL pro­l­ly does noth­ing for you, but you need to check that your set up is cor­rect! We’ll do that next.

Down­load the MQTT Explor­er app, fill in your creds, and test the con­nec­tion. Once the con­nec­tion tests out as good (it may take some fid­dling, and you may need to restart Home Assis­tant), open and close the door a few times. You should see some­thing like this in MQTT Explor­er (as long as you’re see­ing “heli­um” under the $SYS, you’re fine). 

Now that we’ve got the port for­ward set up and test­ed so that Heli­um Con­sole can send the data it gets and decodes from your sen­sor to the MQTT app run­ning on Home Assis­tant, let’s go back to Con­sole and get ‘er firing!

Setting up the MQTT Integration on Console

In Heli­um Con­sole, look for “Inte­gra­tions” in the left menu, then click the “+” but­ton and select MQTT.

Then fill in the address you set up ear­li­er, like this. It’ll be some­thing like this: mqtt://USERNAME:PASSWORD@gksupernet.hopto.org:8123

Once the Inte­gra­tion is set up we’ll put togeth­er a Flow in Con­sole. This is prob­a­bly the only place in all of my ultra-lim­it­ed cod­ing expe­ri­ence where they added a drag ‘n drop to make things easy. Start off with the Flows menu item, then look for Nodes and hit the “+” sign.

Now, the next 3 steps are straight­for­ward. You’re going to find your Device, your Func­tion, and your Inte­gra­tion, and add them all to the Flow board. I’ll show you how to add the Device, after that it’s the same thing for Func­tion & Inte­gra­tion. You got this!

When you’re done adding those, your Flow board will look like this:

Yes, I still have the Dat­a­cake inte­gra­tion in there. Relax, you don’t need to. All those dot­ted lines should be mov­ing like ants crawl­ing; that’s how you know infor­ma­tion is flow­ing from left to right. It’s no guar­an­tee that the thing on the right is receiv­ing it cor­rect­ly though. 🙂 

Next up: Set­ting this up so when the MQTT gets the mes­sage it trans­lates it to “open” or “close”

Creating a Door “Binary Sensor” in HA

Kk, back in Home Assis­tant (HA, remem­ber?) we’re going to set up the sen­sor that’s “bina­ry” (one of two things, i.e. Open or Close). Let’s go into Home Assis­tant –> Set­tings –> Devices & Ser­vices –> Integrations.

You should see the MQTT Inte­gra­tion already, just wait­ing to be con­fig­ured. Hit that Con­fig­ure but­ton and let’s dive in. It may ask you if you want to con­fig­ure Home Assis­tant to con­nect to the MQTT bro­ker. You do. 😉 

Once you’ve added it via the (con­fus­ing­ly labeled) blue Con­fig­ure but­ton, you’ll have to actu­al­ly con­fig­ure it by hit­ting the blue Con­fig­ure text. 

That will open up the MQTT set­tings win­dow. At the bot­tom of that, look for “Lis­ten to a top­ic”, enter the pound sign (#), and hit “Start Listening”.

Open and close the door sen­sor a cou­ple of times and you should see mes­sages start com­ing in beneath the Stop Lis­ten­ing line. Now, you’ll have to copy the Mes­sage Top­ic Name, which is the text after “Mes­sage x received on”, start­ing with “heli­um”. In my case, it’s
helium/032a7107-7e45-41b7-9a69-ff1955dc5348/rx

I past­ed mine into a Sub­lime Text Edi­tor file, but you can use Notepad or what­ev­er you’d like. 

Now we’re going to set up a place in Home Assis­tant to paste that info. 

Installing File Edi­tor Addon

In Home Assis­tant, go to Settings–>Addons–>Addon Store–>File Editor. 

Type the first few let­ters of File to make it easy to find, then hit that sucker.

Once you’ve got it installed, turn on “Start on boot” and “Show in sidebar”.

Once all that’s done, hit the blue Start but­ton, then go to File Edi­tor in the side­bar. As my paraglid­ing adven­ture bud­dy Robert says, “Now we’re cook­ing with Crisco!” I think he means we’re mak­ing progress. 

Now that you’re in File Edi­tor you have to find the “configuration.yaml” file. Sounds com­pli­cat­ed, right? It’s not. You got this. Go up to the fold­er at the top left of the screen:

Then look for it in the menu that pops up. 

Once you’ve select­ed it and opened it up, we’re going to add the fol­low­ing at the bot­tom of that file. Remem­ber to change the last line to YOUR “state_topic” will be the one you copied earlier. 

mqtt:
binary_sensor:
- name: "Gate Sensor"
device_class: opening
payload_on: "1"
payload_off: "0"
payload_not_available: ""
value_template: "{{ value_json.decoded.payload.DOOR_OPEN_STATUS }}"
state_topic: "helium/032a7107-7e45-41b7-9a69-ff1955dc5348/rx"

Hey, two quick things to note. First, in the obscure world of yaml code, the rules are strict. The exact inden­ta­tion shown above is required. Each lev­el is indent­ed two spaces from the pre­vi­ous one. Sec­ond, the “value_template” in the yaml code spec­i­fies the hier­ar­chy and names in the Heli­um sen­sor mes­sage (decod­ed ?payload?DOOR_OPEN_STATUS in this case). If you used a dif­fer­ent door sen­sor or Heli­um decoder Func­tion than we did, you will prob­a­bly need to mod­i­fy this text to match your sen­sor message.

Once you’ve past­ed in your fan­cy mqtt code from above, save the file with the red fold­er icon. 

Now, reload the con­fig­u­ra­tion by going to Devel­op­er Tools ? YAML con­fig­u­ra­tion reload­ing ? MANUALLY CONFIGURED MQTT ENTITIES. Hit that, it’ll turn green for a sec­ond, then back to normal.

Check your work back in Settings–>Devices & Services–>Entities. You should find an entry like this.

Oh. My. G. We’re com­ing into the home stretch here. The next (and pret­ty much last) thing we’ll do is set up a smart switch on Home Assis­tant and switch it based on the door sen­sor state changes. I’m going to use a Kasa Smart Wifi switch.

Now, I’m going to skip pic­tures and hand-hold­ing for the Kasa Switch set­up; that should be pret­ty straight­for­ward. Buy the switch, put the Kasa app on your phone, add the switch to your phone. 

Setting Up The Smart Switch in Home Assistant

With the switch installed on your local WiFi net­work, let’s head over to Home Assis­tant, where we’ll add a Kasa Smart inte­gra­tion. Go to Settings–>Devices & Services–>Integrations–>Add Inte­gra­tion. I skipped the pic­ture for Devices & Ser­vices. You got this. 

Use the Search field to nar­row it down, then select TP-Link Kasa Smart. Leave the “host” field emp­ty, it’ll find your devices.

If you’re run­ning mul­ti­ple WiFi net­works in your home to sep­a­rate out your per­son­al devices (like phones, com­put­ers) from those scum-suck­ing IoT devices, you’ll need to get a lit­tle geeky on your own with allow­ing Home Assis­tant to access your net­works. I had to Google on this, but because it’s a router/modem relat­ed issue, there’s not a great way for my expe­ri­ence to trans­late to yours. GIYF here. Google Is Your Friend. 

When you get it all right, you’ll see the Kasa devices you have on your net­work. Heat­ed mat for the win in the San Diego win­ter. For now, we’re going with the one labeled GK HA Garage Switch Inte­gra­tion. Fun note: I renamed this to just be GK Garage Switch, as the addi­tion of Inte­gra­tion at the end con­fused me when I was trou­ble shoot­ing later.

When you’re done with adding it in, our final steps will be to add an Automa­tion in HA that turns on the switch when the door sen­sor fires. Restart Home Automa­tion to lock in your changes (HA Settings–>System–>Restart (top right) and pre­pare for the final push. We’re close now!

In Home Assis­tant, go to Settings–>Automation & Scenes. 

Then look in the bot­tom right for “Cre­ate Automation”.

Start with an emp­ty Automa­tion (don’t get suck­ered into the pre-filled ones yet!)

You’ll see a win­dow where the “flow” should make sense. We’re going to add a Trig­ger, a Con­di­tion, and an Action.

Start by adding (“+”) a Trig­ger, which will be a “State” change.

• Trig­ger name: When Gate Sen­sor changes from off to on.
• Enti­ty: Gate Sensor
• From: Off
• To: On
• For: 0:00:00

Now we’ll set a Con­di­tion for the State of the sun so that this only fires when the sun ain’t out. You may rush, as I did, into using the Con­di­tion of Sun, instead of a State. It prob­a­bly does­n’t mat­ter, but for my Automa­tion, which is test­ed and works, I used the State, which is indi­cat­ed by that lit­tle tri­an­gle of arrows.

Final­ly, we’ll set the Action, which will be a Device action, as indi­cat­ed by the lit­tle Device sym­bol out­lined in red, below.

You done, dawg. Open and close the sen­sor a few times to make sure the light switch­es. It should. If it does­n’t, go back and care­ful­ly check you fol­lowed the instruc­tions. One lit­tle thing, like the wrong decoder, or choos­ing the wrong thing from a drop­down, or what­ev­er, will stop the flow of oper­a­tions need­ed to make the mag­ic work. 

A quick and geeky note: Home Assis­tant won’t know the state of your sen­sor until the sen­sor sends a mes­sage. That hap­pens the first fimte you open or close the sen­sor. This is because sen­sors in the world of IoT typ­i­cal­ly don’t con­stant­ly broad­cast their state. That would be a waste of ener­gy. The gate sen­sor only needs to broad­cast one mes­sage, as it hap­pens. “I opened.” Or, “I closed”. That’s it. It does­n’t need to say “I’m open I’m open I’m open I’m open etc” until it runs out of juice. This is why in the Trig­ger in HA has to be “Gate sen­sor changes from off to on”, not “Gate sen­sor is on”.

With that…

El FIN. Con­grats! You are now a stone cold HA MQTT sen­sor inte­gra­tion killer. Now get out there and dream up some rad new automa­tions for Home Assis­tant, and please, make sure you share your best one with the rest of us over on the GK Dis­cord.

A GIANT THANK YOU to Dirk Beer (dirkbeer#3592 on Dis­cord) for walk­ing me through this thing soup to nuts and mak­ing sure that us non-engi­neers have access to get­ting deep in the weeds with Heli­um. Rock on Dirk! Addi­tion­al­ly, the secre­tive group known only as the “AF” were instru­men­tal in mak­ing sure I got through sev­er­al hur­dles in the realm of MQTT and home net­work­ing. AFF!