LoRa: Connect your first device and use it in Home-Assistant

After having presented principles and how LoRa networks work (LoRa: what is it ? what’s the use ?), we are now going to connect a first LoRa device on a network and retrieve datas in Home-Assistant.

For memory, LoRa allows you to connect remote sensors and/or out of reach for your home-automation system. You can, for example, connect a weather station in your backcountry house, a mailbox or a gate at the other end of your property.

As examples, we’ll use a classic ambient sensor (Temperature/Humidity) made by Dragino, a door sensor (Dragino too) and a wireless 4 buttons remote from RakWireless.

Network choice

First step we’ll need to select a network to connect our devices. As we have discovered in the previous article, 3 types of LoRa networks exist. Privates are not for us but connection system with Home-Assistant (as explained below) is still valid. We’ll discard also commercial ones as network access conditions make them available only for businessses. We are going to foucis on shared ones although they are not so many. The three most important ones are listed below. Other ones exist but are lot more limited, these three ones have a global coverage more or less.

• Hélium (Helium & LoRaWAN): american network quite recent on market and whose network hosts also a blockchain. Some specific LoRa gateways exist for Helium network that mines crypto in same time, and the operator pays back users in crypto when they run an Helium gateway. Helium grants a free use for personal use with maximum 10 devices, which may be quite enough for a regular property ! You can use existing coverage if one or more gateways cover your area (Helium Coverage) or install one LoRa gateway connected at Helium network. Choice and setup of a LoRa gateway will be discussed in a separate article soon avalaible.
• The Things Network (The Things Network): dutch network that exists since around 10 years now. The Things Network (TTN) is a shared network supplied by The Things Industries, the mother company that offers commercial services around LoRa for companies. An approximate coverage map is available on the third party website TTN Mapper, but it’s a volunteer map so you can get coverage even if map states the contrary.
• Loriot (Loriot): swiss network that, quite similar with TTN, offers a shared community service (limited at max 30 devices per account) and service for professionals with dedicated server(s). As for the two previous ones, you can use it freely if you are in a zone already covered, or install your own gateway connected on that same network.

For this article, we’ll use TTN network but it’s very similar for other networks whatever they are private or public. I’ll show briefly Swisscom (Switzerland) console as demonstration for a commercial network.

Devices to connect

Regarding devices, we’ll use three different type of devices: temperature/humidity sensor from Dragino: LHT65N, 4 buttons remote from RakWireless: Wisnode Button 4K, and a door opening sensor from Dragino: LDS02. We are going first to focus on “connection” of device with TTN LoRa network. I’ll present it also with Loriot network. We’ll see then how to get these datas in Home-Assistant: LoRa and MQTT integrations. It’ll be the same whatever LoRa devices used, there’ll be just more or dess datas sent (for example, a LoRa tracker will send GPS datas (latitude, longitude, altitude).

 

Connection of a LoRa device with a LoRa network

In a LoRa system, each device is identified by three different “codes”. They allow pairing of the device with its LoRa network and then communication. These three codes are given by manufacturer of the device (usually on a sticker THAT YOU MUST NOT LOOSE), and they can be modified on some devices by direct connection on it (for example with our test devices, it’s possible for the temp/humidity sensor and the 4 buttons remote but not for the door opening sensor). Let’s see more in details what are these three codes:

• DevEUI: First identifier (with that syntax: A0 B1 C2 D3 E4 F5 01 23) is equivalent of MAC address for network card. It allows to identify in a unique way a device, so it’s better not to modify it to avoid any conflict in LoRa network with an other device (manufacturer makes sure it’s unique).
• JoinEUI (previously named AppEUI): this identifier, same format as DevEUI, allows to identify server that will handle the pairing request of device in LoRa network. It’s usually same one for all devices of same type, or even of same manufacturer.
• AppKey: this indentifier (with that syntax: A0 B1 C2 D3 E4 F5 01 23 45 67 89 0A BC DE F1 23), often made by combining DevEUI and JoinEUI, will be used as encryption key for communication with LoRa server. It’ll warrant confidentiality of radio communication and has to be kept confidential.

Pairing

Once you have in hand a LoRa device, its identifiers and being in an area with LoRa coverage (either with your own gateway or existing cover of network you want to use), we’ll need to “pair” the device with LoRa server (Join process). We are going to connect at LoRa operator console to add device and so it can then communicate. We’ll see in parallel TTN configuration(The Things Network) and Loriot (swiss one). Up to you to select depending of radio cover in your area. For TTN, console is available on these links:

• Console EU1 for European server
• Console NAM1 for Americas (north and south)
• Console AU1 for Asia and Australia.

For Loriot, we can access it for example on this link for Amsterdam server: Console EU2. Once logged in console, we are going to create an Application (it’ll allow to organise devices in your account, you can organise as you wish, it has no technical consequences). Once choosen an id (in lower characters and no space) and, in option, a  description, you’ll then reach interface that allows you to add devices in LoRa network. TTN console will guide you during the process to add devices to make it easier (it allows also to add device by scanning a QR code but never seen any device that have that QR code !). Loriot has a more technical interface where you have to select LoRa version used by your device instead of using a known list of devices as on TTN.

For TTN (on the left above), you just need to select manufacturer, device and Radio zone among choices offered to add easily a device. Radio zone must be the one for your geographical area (check LoRa: what is it ? what’s the use ? if needed) and radio frequency of your device). For Loriot (on the right above), you’ll just need to select LoRa version implemented by device (check documentation of device) and “Join/Enrollment” mode. By default, we’ll always use OTAA mode (unique mode avalaible on TTN) that is the most secured for LoRa. An other mode of join exists: ABP that is not much used and lot less secure. All we need now is to fill the three identifiers in console to register device in the network. Then, we’ll need on device added in console trigger JOIN command. It’s a special message that allows the unique pairing of the device with the LoRa network (based on identifiers of the device, a new set of encryption keys is going to be generated and stored in device and used for future messages sent by the device).

• For the temperature sensor, all you need to do is to push few seconds on the unique button on it to get it to send the JOIN command.
• For the 4 buttons remote, just push few seconds on button 2 to get it to send the JOIN command.
• For door opening sensor, you’ll just need to trigger a message from the sensor (move magnet along sensor) and it’ll automatically JOIN the LoRa network.

Below what you’ll see in TTN console if JOIN has succeeded. In case of error, double-check the three identifiers, that you are well in a zone covered by a gateway connected at TTN/Loriot, your device is well powered, and that it’s working in the proper frequency bands for your geographical area.

Note: with a commercial network (Swisscom as example), it works in a similar way. You fill a name for the device, the DevEUI, JoinEUI, and AppKey and you are done.

Messages decoding

Last point to configure now is the “payload decoder” or decode messages. As we have talked previously, LoRa messages are encrypted and encoded. We’ll need to decode them so we can get access at datas transmitted. So far, if you check in console messages received, payload is as below, which is not really usable.

“frm_payload”: “AUcNABQEsAPoAAAAAAAAAE2W”

We’ll go then in the “Payload Formatters” tab where it’s possible to put a Javascript or connect with an external service for decoding. If you have selected the proper device when you added device in TTN console, the “formatter” will be by default the good one. It’s the case here for our RakWireless and also Dragino devices, which make everything a lot easier. In other cases, you’ll need to get from manufacturer the proper Javascript that you’ll just copy/paste in Uplink tab (messages from devices to LoRa server).

And then, miracle, payload, that was unreadable till now, becomes suddenly a lot more understandable with the different values returned by device. We now have some datas we can use in Home-Assistant.

Home-Assistant Integration

We have choice with two solutions:

• use an integration that is the fast and easy solution but with limitations/drawbacks and that is only avalaible for TTN so far
• or use the MQTT solution a little more complicated, but a lot more powerful and usable with all LoRa servers.

TTN Integration through HACS:

We are not going to use the official TTN Integration as it has numerous restrictions due to constraints for official integration in Home-Assistant. We are going to use the non official version, written by same developer, and easy to install with HACS: https://github.com/angelnu/home_assistant_thethingsnetwork Once installed with help of HACS, you’ll just need to add it as an official integration (Settings -> Integration and search for “The Things Network”. We’ll just need to fill the App ID previously created in TTN console and the API key, that has to be created on App page in TTN console (careful to save it as you won’t get access at it anymore after). You’ll need also on App page activate the “Storage Integration” (menu Integrations -> Storage Integration and activate it and that’s it). After few minutes, sometimes immediately, your devices added in TTN will show up in TTN integration:

If we select our device, we’ll get all details of sensors and other datas that device sends. We can see all details of datas sent by device including battery level (on the left the temperature/humidity sensor, on the right the door sensor).

• Quick and easy to configure.
• Devices such as the 4 buttons remote don’t send back datas and so they don’t show up in the integration.
• Integration use TTN API to communicate and API is broken from time to time or with a long latency.
• Only compatible with TTN LoRa network.
• Integration is not able to guess by itself type of datas returned by devices, so it’s often needed to use the Configure menu of the integration and select “Fields” and then select parameter to modify so it’s properly configured.

Integration through MQTT:

We are going to use the good old method of MQTT broker. For the ones that don’t know MQTT, it’s a protocol/software to distribute short messages, mainly used for IoT. It’s a very lightweight protocol but can be secured if needed, and of course handled perfectly by Home-Assistant ! For the ones that’d like to know more about MQTT, the official website gives a good presentation. MQTT is now a standardised protocol. First step (probably useless for most of you): install the add-on MQTT Broker. Once installed, be sure to activate these options in add-on (you’ll need too to create the folder mosquitto in /share folder of HA):

active: true

folder: mosquitto

One add-on running, you can now install the official MQTT Broker integration. Once installed and started, integration will auto-configure to communicate with the broker we just installed before. We are going to let Home-Assistant aside for a while and continue configuration by going back at TTN. In the TTN console, we’ll select Application and then the one that contains sensor we want to get data from. We select then in left menu: API then “Add API key”. We decide a name (it’s just for us as reference), if wanted an expiration date if not let empty. You can let by default all rights (although we really need only “Write Downlink application traffic” to send messages at devices, and “Read Application Traffic” to get datas from devices).

WARNING: once displayed, save in a secure place the API key as it won’t be displayed again anymore.

Now we need to get ID of the LoRa device we are interested in. We are going to select “End Devices” in left menu and click on end device that we want. We can then copy device’s ID. Now we just need a little of extra configuration in HA te get datas. First we are going to link or “bridge” HA MQTT broker with the one of TTN. It’s going to be done by adding a bridge.conf file for MQTT that will let it know how to establish the link. The file must be create in the “share” folder of H (this folder is not accessible by the file browser of HA but by the file share (samba) of HA). In this share folder, you’ll create a new folder named mosquitto and in it you’ll create a file named bridge.conf (only one file is needed even if you have multiple bridges to configure, you just list them one after another in one file !). The file will contain these parameters:

connection nameidecide

address eu1.cloud.thethings.network

bridge_protocol_version mqttv311

remote_username idofmydevice@ttn

start_type automatic

notifications false

try_private false

remote_password NNSXS.xxxxxxxxxxxxxxxxxxxxxxxx

bridge_insecure true

topic # in 0

cleansession true

• nameidecide is label you assign at bridge (it’s only for your own reference and each one has to be unique in the bridge.conf file)
• eu1… has to be replaced by TTN server you use depending where you are in the world
• idofmydevice has to be replaced by ID of your device previously found in TTN console
• and last parameter is the API key you’ll paste in the remote_password field

You can then restart the Mosquitto broker add-on in HA and, if everything is well configured, you should find in logs of Mosquitto broker add-on lines similar at ones below:

1684589377: Loading config file /share/mosquitto/bridge.conf
1684589377: Warning: Bridge nameidecide using insecure mode.

If you get these, it’s perfect, it means MQTT broker communicates well with the one of TTN and that we are going to receive automatically datas sent by our LoRa devices. All we need now is to extract datas to be able to use them in HA. Messages received from TTN through MQTT are JSON formatted, so it’ll be quite easy to extract them. Here is a simple case with our temperature/humidity sensor LHT-52. When checking messages displayed in TTN console, here is what shows up out of headers and other useless informations for us:

We are now able to create a MQTT sensor in HA that will get data automatically from the JSON received:

sonde-ambiance should be replaced by your application ID in TTN console.

To reduce risk of error and for the ones that have an Android device (there is probably similar app for IoS but I don’t have any IoS devices to test), there is a very useful application named MQTT Snooper so you can spy on all messages passing through a MQTT broker. Once installed application, you add a new host (you indicate TTN server as server, ID for the username followed by @ttn and API key as password). Once connected, you’ll see all messages passing on MQTT sent by TTN and easy to find fields you want to extract data from.

Limits/Drawbacks of the solution:

• Compatible with all LoRa devices and allows also to send Downlinks to configure LoRa devices.
• Compatible with large majority of LoRa servers  (TTN, Helium, Chirpstack), not directly compatible with Loriot.
• Needs a little more effort to configure and use with Home-Assistant.
• Instant communication with LoRa devices as MQTT is implemented straight in the heart of the LoRa server, not like API that sometimes suffer of delays/unavalaibility.

This post is a large revamp of a previous one dated of 2021 that it replaces.

Word of the End

I hope you’ll have succeeded to connect and use your first LoRa device with Home-Assistant.

You now have access at a very powerful and useful tool for remote/far remote sensors or detectors without Wifi range problem or pull cables.