Met LoRaWAN verbind je draadloze apparaten over grote afstanden met internet, zonder dat ze veel energie verbruiken. Ideaal voor sensoren die jarenlang op één batterij moeten werken, zoals weerstations of waterpeilsensoren of tuinmetingen. In dit artikel bouwen we stap-voor-stap een eigen LoRaWAN-netwerk met een gateway en de opensource-oplossing ChirpStack. We behandelen de installatie, configuratie en koppeling van sensoren, en laten zien hoe je de data uitleest en integreert in andere systemen.
Dit gaan we doen
LoRaWAN is een protocol voor energiezuinige, draadloze communicatie over lange afstanden. We leggen uit hoe LoRa en LoRaWAN werken, welke hardware je nodig hebt en hoe je ChirpStack installeert en configureert. Je leert een gateway opzetten, sensoren koppelen en hun data decoderen. Daarna tonen we hoe je metingen bekijkt, problemen oplost en de gegevens integreert in domoticasystemen via MQTT en Node-RED. Zo beschik je over een compleet eigen netwerk voor het betrouwbaar verzamelen en verwerken van sensorinformatie.
Ook interessant: Bedien je slimme apparaten met een zelfgebouwd touchscreen
LoRaWAN is een zogenoemd Low-Power Wide-Area Network (LPWAN): het protocol implementeert draadloze communicatie over grotere afstanden (in perfecte omstandigheden zelfs meer dan tien kilometer) met een laag stroomverbruik. De keerzijde is dat de overdrachtssnelheid laag is, maximaal enkele kilobits per seconde. Maar voor veel toepassingen is dat voldoende. Denk maar aan het uitlezen van het peil van je regenwaterput of van het weerstation in een boomgaard. Door elke tien minuten een klein pakketje met sensorwaarden door te sturen, kan een LoRaWAN-sensor gemakkelijk tien jaar op één batterij werken.
LoRa
LoRa (Long Range) is de specificatie van de fysieke laag van het netwerkmodel, die definieert hoe de radiosignalen eruitzien. De standaard specificeert de gebruikte frequentiebanden (868 MHz in Europa, 915 MHz in Noord-Amerika en Australië en 923 MHz in Azië) en modulatie. Speciaal aan LoRa is dat het goed tegen interferentie kan. Dat is ook nodig, want in Europa werken bijvoorbeeld Z-Wave en draadloze alarmsystemen in dezelfde frequentieband.
LoRa is een propriëtair protocol van Semtech (https://www.semtech.com) dat is gebaseerd op chirp spread spectrum. Met deze techniek wordt informatie gecodeerd in de vorm van een 'tjilp': een sinusoïdaal signaal waarvan de frequentie met de tijd verhoogt (up-chirp) of verlaagt (down-chirp). De snelheid waarmee de frequentie van het signaal verandert, is de chirp rate. Hoe hoger de chirp rate, hoe meer informatie er in dezelfde tijd doorgestuurd kan worden, maar hoe moeilijker ze te decoderen is.
LoRa definieert zes spreading factors, van SF7 (snelle chirp rate) tot SF12 (trage chirp rate). Hoe hoger de spreading factor, hoe verder het signaal nog ontvangen kan worden.
Semtech produceert diverse LoRa-chips.
LoRaWAN
Terwijl LoRa slechts de fysieke laag definieert, bouwt LoRaWAN daarop voort om communicatie tussen de end devices (ook nodes genoemd) en internet mogelijk te maken. Zo'n end device is elk apparaat met een LoRa-antenne en firmware die de LoRaWAN MAC-laag implementeert. LoRaWAN is een open standaard die door de LoRa Alliance (https://www.lora-alliance.org) wordt gepromoot.
Om die communicatie met internet mogelijk te maken, is een LoRaWAN-gateway nodig. Die is uitgerust met zowel een LoRa-antenne als een wifi-antenne, ethernetpoort of 4G-antenne. De gateway stuurt de ontvangen LoRaWAN-pakketten via internet door naar een centrale netwerkserver.
Mogelijk ontvangen meerdere gateways hetzelfde pakket van een node. De netwerkserver filtert die dubbel ontvangen pakketten eruit. Ook verzekert de netwerkserver de authenticiteit van elke node op het netwerk en de integriteit van elk pakket. Alle LoRaWAN-pakketten tussen de nodes en de netwerkserver zijn met een AES-sleutel van 128 bit versleuteld.
ChirpStack
We hebben dus een of meerdere LoRaWAN-gateways nodig, een netwerkserver, en uiteraard LoRaWAN-nodes met sensors die we willen uitlezen. Voor de gateway en de netwerkserver maken we in dit artikel gebruik van versie 4 van het opensource-project ChirpStack (https://www.chirpstack.io). Overigens is ChirpStack compatibel met de meeste LoRaWAN-gateways, als die werken met de Semtech Packet Forwarder of Semtech Basics Station. De documentatie van ChirpStack bevat voor diverse merken van gateways uitleg over de configuratie (https://www.kwikr.nl/csgatew).
Een alternatief is om ChirpStack Gateway OS op een ondersteunde LoRaWAN-gateway te draaien. Dit is een op OpenWrt gebaseerde Linux-distributie met gateway-software en webinterface voor de configuratie. Dit besturingssysteem installeer je dan op een Raspberry Pi met LoRa HAT of een andere ondersteunde gateway. Voor dit artikel installeerden we ChirpStack Gateway OS op een Seeed Studio SenseCap M2.
🛜 ChirpStack Gateway OS
🛜 Ondersteunde gateways
🛜 Seeed Studio SenseCap M2
ChirpStack biedt uitgebreide documentatie over de diverse componenten van het LoRaWAN-project.
Gateway OS installeren
Voor de Raspberry Pi bestaan er twee types images (https://www.kwikr.nl/csospi) van Gateway OS: Base en Full. Met Base installeer je een volledig functionele LoRaWAN-gateway, terwijl Full op hetzelfde apparaat ook een netwerkserver en Node-RED (www.nodered.org) installeert. Wil je een alles-in-één LoRaWAN-oplossing, kies dan het Full-image. We gaan er in dit artikel van uit dat je het Base-image draait. Later installeren we de netwerkserver en Node-RED in Docker-containers op een Linux-server.
Volg dan de installatie-instructies (https://www.kwikr.nl/csosins) voor je merk van gateway. We lieten onze SenseCap M2 eerst upgraden naar de nieuwste firmware van Seeed Studio. Daarna downloadden we het image van ChirpStack Gateway OS 4.7.0 voor de SenseCap M2. In de webinterface ga je dan naar System en vervolgens naar Backup / Flash Firmware. Klik op Flash image… onderaan de pagina, selecteer het image en klik op Upload.
We flashen het image van ChirpStack Gateway OS op de Seeed SenseCap M2 via de webinterface.
Andere lange-afstands-protocollen
Er bestaan nog andere protocollen die op LoRa voortbouwen. Zo is er Meshtastic of https://www.kwikr.nl/mtas. Terwijl bij LoRaWAN de nodes alleen met de gateways communiceren, is Meshtastic een mesh-netwerk waarbij alle nodes peer-to-peer met elkaar kunnen communiceren om berichten door te sturen. Meshtastic is ook meer bedoeld om tekstberichten uit te wisselen tussen bewegende clients.
Bij LoRaWAN ligt de focus op het zo energiezuinig mogelijk doorsturen van sensordata. Ook Amazon Sidewalk, een netwerktechnologie die Amazon in apparaten zoals zijn nieuwste Echo en Ring ingebouwd heeft, maakt gebruik van LoRa voor een hoger bereik. Door deze apparaten als Sidewalk Bridges in te zetten, heeft Amazon een uitgebreid netwerk om allerlei sensors van connectiviteit te voorzien.
Gateway configureren
Nadat je gateway met de net geïnstalleerde firmware is opgestart, log je in met gebruikersnaam root en een leeg wachtwoord. Stel daarna een wachtwoord in. Klik daarna links op het menu ChirpStack / Concentratord. In het tabblad Global configuration vink je Enabled aan en selecteer je de chipset van je LoRa-hardware, in ons geval SX1302/SX1303.
Ga dan naar het tabblad van je geselecteerde chipset en vul de juiste gegevens in. De Antenna gain (dBi) staat standaard op 2 ingesteld, maar onze gateway is met een 3dBi-antenne uitgerust, dus dat veranderen we. Belangrijk is ook het Channel-plan. Voor Europa kies je daar EU868, zodat de gateway op de juiste frequenties werkt.
Klik daarna op Save & Apply om de instellingen door te voeren. Na enkele seconden zou onderaan in de footer Could not read Gateway ID moeten veranderen naar de ID van je gateway. Mogelijk moet je hiervoor de pagina verversen.
ChirpStack Gateway OS heeft enkele basisinstellingen nodig.
Netwerkserver installeren
De netwerkserver en andere benodigde componenten installeer je op een Linux-server. De documentatie van ChirpStack toont de installatie-instructies voor Debian/Ubuntu, evenals voor Docker Compose (https://www.kwikr.nl/csdock). Wij voerden die laatste methode uit op een Debian 12-server. Installeer Docker en Docker Compose met:
sudo apt install docker.io docker-compose
Geef je gebruiker toegang tot de Docker-daemon met:
sudo usermod -aG docker $USER
Log daarna uit en weer in. Download dan de Git-repository met de Docker Compose-bestanden van ChirpStack met de opdracht:
git clone https://github.com/chirpstack/chirpstack-docker.git
Navigeer dan naar die directory met:
cd chirpstack-docker
Het bestand README.md bevat uitleg voor de configuratie. Bekijk eens alle bestanden in de map configuration voor de mogelijkheden.
Met Docker Compose start je de netwerkserver en andere componenten van ChirpStack.
Netwerkserver opstarten
Er is maar één configuratie die je zeker moet aanpassen: maak een willekeurig 'secret' met deze opdracht:
openssl rand -base64 32
De uitvoer is iets van deze vorm:
v3sUJjR0sa8BJOhiSDE7rq5WAZ0VOD+NuHbcqQfjWMI=
Open nu het bestand configuration/chirpstack/chirpstack.toml en zet dit secret op de plaats van you-must-replace-this in de regel die begint met secret=. Sla dit bestand op. Voer daarna deze opdracht uit in de directory van de repository:
docker-compose up -d
Nadat alle containers zijn aangemaakt, kun je op de webinterface van ChirpStack aanmelden op http://IP:8080 (met in plaats van IP het ip-adres van de Linux-server) en als gebruikersnaam en wachtwoord admin. Klik bovenaan rechts op je gebruikersnaam admin en kies Change password om dit standaardwachtwoord aan te passen.
Gateway toevoegen
Nu moet je de gateway nog aan je netwerkserver koppelen. Het Docker Compose-bestand installeert ook de MQTT-broker Mosquitto. We laten de gateway daarom met diezelfde MQTT-broker verbinden. Klik in de gateway op MQTT Forwarder onder ChirpStack. Dat component is standaard ingeschakeld, je hoeft alleen maar in het tabblad MQTT configuration bij Server de waarde tcp://IP:1883 in te vullen (met in plaats van IP het ip-adres van de netwerkserver) en onderaan op Save & Apply te klikken.
Klik daarna in de netwerkserver links op Tenant / Gateways / Add gateway. Geef je gateway een naam en vul de gateway-ID in dat ChirpStack Gateway OS onderaan rechts toont. Klik op Submit.
Daarna is je gateway onder Gateways te zien met de status (Online). Klik je op de gateway-ID, dan krijg je in het dashboard wat statistieken te zien, en in het tabblad Metadata van het tabblad Configuration zie je allerlei systeemgegevens die de gateway al stuurt, zoals de regio, het hardwaremodel en versienummers van concentratord en de MQTT-forwarder.
De netwerkserver ziet onze gateway online.
Apparaatprofiel
Met de gateway hoef je nu verder niets te doen. De rest van de configuratie gebeurt in de netwerkserver van ChirpStack. Voor elk type apparaat dat je wilt toevoegen, moet je eerst een apparaatprofiel aanmaken; die vind je in de productspecificaties. Haal die erbij en klik bij Device Profiles op de blauwe knop Add device profile bovenaan rechts.
We demonstreren hoe je dit doet voor de LSN50v2-S31 van Dragino, een temperatuur- en luchtvochtigheidssensor. Geef het profiel de naam van het producttype. Voor de MAC-versie volgen we de gebruikershandleiding en kiezen we LoRaWAN 1.0.3. Aangezien het standaard interval waarmee deze sensor data doorstuurt twintig minuten is, vullen we bij Expected uplink interval als waarde 1200 seconden in. Onder het tabblad Join (OTAA / ABP) staat Device supports OTAA standaard ingeschakeld. Dat houden we zo, omdat het apparaat dit volgens de handleiding ondersteunt. De rest van de standaardwaarden zijn oké.
Maak een apparaatprofiel voor de Dragino LSN50v2-S31.
Codec
LoRaWAN-apparaten sturen hun data als een reeks opeenvolgende bytes, waarvan het formaat in de documentatie van het apparaat wordt uitgelegd. We hebben dus voor elk apparaatprofiel een functie nodig die deze datareeks decodeert en in voor ons leesbare vorm omzet, in JSON-formaat (https://www.json.org). Die functie dien je in het tabblad Codec in te voeren. Kies hier bij Payload codec voor JavaScript functions.
Je ziet nu dat het tekstveld Codec functions een sjabloon bevat met functies decodeUplink voor de data die het apparaat naar de netwerkserver stuurt en decodDownlink voor de data die de netwerkserver naar het apparaat stuurt. Deze functies moet je dus implementeren, maar de meeste leveranciers van LoRaWAN-apparaten bieden zelf al de juiste JavaScript-functies aan.
Dragino biedt deze functies voor al zijn apparaten aan in een GitHub-repository (https://www.kwikr.nl/dragit). Navigeer daar naar de juiste directory, open het bestand waarvan de naam eindigt op Chirpstack v4 decoder.txt en plak de inhoud van het bestand in dit tekstveld. Klik op Submit om het apparaatprofiel met de bijbehorende decoder op te slaan.
Decodeer de bytes in een LoRaWAN-pakket met behulp van JavaScript-code.
Apparaat toevoegen
LoRaWAN-apparaten worden gegroepeerd per applicatie. Bijvoorbeeld temperatuursensors groepeer je onder één applicatie en contactsensors onder een andere. Maak dus eerst een applicatie aan onder Applications door bovenaan rechts op Add application te klikken, de applicatie een naam te geven en dan met Submit aan te maken. Als je onder Applications op deze applicatie klikt, kun je met een klik op Add device apparaten toevoegen aan deze applicatie.
Vul nu een naam in voor je apparaat, bijvoorbeeld Temperatuursensor buiten, en kies het apparaatprofiel dat je juist hebt aangemaakt. Daarna vul je de Device EUI in. Join EUI is niet nodig als je apparaat via OTAA wordt geactiveerd. Klik op Submit. In het tabblad OTAA keys dat nu verschijnt, vul je de Application key in. Al deze tekenreeksen van hexadecimale cijfers vind je doorgaans op een sticker in de verpakking van het apparaat. Schakel daarna het apparaat in.
Alle LoRaWAN-apparaten worden gegroepeerd per applicatie.
Uplinks bekijken
Als alles goed gaat, zie je nu in het tabblad LoRaWAN frames pakketten van je apparaat voorbijkomen. Als allereerste een JoinRequest, gevolgd door een JoinAccept wanneer het apparaat door je LoRaWAN-netwerk is geaccepteerd. Wanneer je beide berichten ziet, weet je dat je apparaat op het LoRaWAN-netwerk is geactiveerd.
Ga daarna naar het tabblad Events. Hier zie je een join-gebeurtenis die aangeeft dat je apparaat tot het netwerk is toegetreden. En zodra het apparaat een eerste meting stuurt, zie je ook een up-gebeurtenis. Klik op join of up voor een gestructureerde weergave van de gegevens; dit is een JSON-structuur. Zoek de sleutel data met daarin de sleutel object. Die laatste bevat de data die de payload-decoder heeft gedecodeerd, met onder andere de temperatuur (TempC_SHT31), de luchtvochtigheid (Hum_SHT31) en de batterijspanning (BatV).
ChirpStack toont de sensormetingen met alle bijbehorende metadata van het LoRaWAN-protocol.
Op zoek naar een weerstation?
Kijk en shopMetingen tonen
Wanneer ChirpStack de uplinks van je apparaat (gegevens die je apparaat uitstuurt) kan decoderen, kun je deze ook visualiseren. Verlaat daarvoor de applicatie en ga naar het apparaatprofiel van de sensor. Open het tabblad Measurements. Je ziet dat ChirpStack hier al de sleutels uit de JSON-structuur met gegevens heeft toegevoegd als meetsleutels. De soort meting staat echter telkens op Unknown / unset, waardoor ze voorlopig worden genegeerd.
Geef nu elke meetsleutel die je wilt visualiseren een type. Voor de batterijspanning, temperatuur en luchtvochtigheid kiezen we Gauge; in de andere waarden zijn we niet geïnteresseerd. Klik tot slot op Submit.
Als je nu even wacht tot de volgende uplink, zie je grafieken van de opgegeven metingen in het tabblad Device metrics van het tabblad Dashboard van het apparaat onder de applicatie waarbij het hoort. Overigens toont ChirpStack ook de status van de batterij van elk apparaat in de lijst met apparaten van een applicatie.
ChirpStack toont grafieken van de sensormetingen.
Problemen oplossen
ChirpStack biedt ook voldoende informatie om problemen op te lossen. Draadloze communicatie is nooit 100% betrouwbaar, want er kunnen allerlei storingen voorkomen. Het tabblad Link metrics van een apparaat biedt je zicht op de prestaties. Hier zie je grafiekjes per dag, maand of jaar van enkele belangrijke karakteristieken.
Zo toont Received het aantal ontvangen uplinks. In de daggrafiek is dat per uur. Van een apparaat met een uplinkinterval van twintig minuten verwacht je drie ontvangen uplinks per uur. Zie je er in een uur minder, dan kan dat aan het apparaat liggen. Maar zie je bij alle apparaten een bepaalde periode minder dan verwachte uplinks, dan ligt het waarschijnlijk aan de verbinding tussen de gateway en de netwerkserver.
Plaatsing van de gateway
Voor LoRa-signalen is rechtstreeks zicht tussen de antennes van zender en ontvanger belangrijk om een goed bereik te halen. Staan je LoRaWAN-sensors buiten, dan zet je de gateway het best ook buiten. Het liefst ook hoog, op een dak of paal, met zo weinig mogelijk obstakels zoals bomen of gebouwen tussen de gateway en de sensors. In ideale omstandigheden haal je zo zelfs tientallen kilometers bereik.
Maar wil je gewoon sensors in je grote tuin kunnen uitlezen, dan is een bereik van 100 meter wellicht voldoende. Dan maakt het niet uit dat je gateway niet optimaal staat. Met een plaatsing binnen haal je die afstanden ook. Binnengateways zijn bovendien heel wat goedkoper dan buitengateways, omdat ze niet weersbestendig hoeven te zijn.
RSSI
Een andere belangrijke indicator is de RSSI (Received Signal Strength Indicator), een maat voor hoe sterk het ontvangen signaal nog is. Het wordt gemeten in dBm (decibel-milliwatts) en is een negatief getal. Hoe dichter dit bij nul ligt, hoe sterker het ontvangen signaal. Een sensor op tien meter van de gateway kan bijvoorbeeld ontvangen worden met -50 dBm, terwijl dit op tientallen meters en/of met muren of andere obstakels ertussen al snel kan afnemen tot -100 dBm.
Maar ook de anteversterking en de verliezen in de kabels en connector naar de antenne (zowel bij de gateway als de sensor) hebben een invloed op de RSSI. In de grafiek van de RSSI kun je deze invloeden experimenteel onderzoeken om je LoRaWAN-netwerk te optimaliseren. Bij minder dan -120 dBm wordt de ontvangst onbetrouwbaar. Komt de RSSI van een van je apparaten in deze buurt, probeer dan bijvoorbeeld je gateway te verplaatsen of antennes te vervangen.
De RSSI van dit apparaat veranderde van -50 naar -90 dBm nadat we het in het midden van de tuin plaatsten.
SNR
Ook uit de SNR (Signal-to-Noise Ratio) kun je heel wat afleiden over de betrouwbaarheid van de draadloze verbinding. Dit is de verhouding tussen het vermogen van het ontvangen signaal en van de ruis. Dit laatste zijn alle ongewenste signaalbronnen die interfereren met het LoRaWAN-signaal en dit dus kunnen verstoren. Hoe groter de SNR, hoe beter de gateway het signaal van de sensor van de ruis kan onderscheiden.
De SNR wordt in dB gemeten en is een waarde die doorgaans tussen -20 dB en +10 dB ligt. Een negatieve SNR betekent dat de ruis groter dan het signaal is. Normaal gezien is dit signaal dan niet meer van de ruis te onderscheiden, maar LoRa spreidt het signaal over een breder spectrum dan nodig uit en spreidt de ruis ook, waardoor het afhankelijk van de instellingen zelfs nog signalen kunt ontvangen met een SNR tot -20 dB.
LoRaWAN heeft met Adaptive Data Rate (ADR) bovendien een mechanisme waarbij de netwerkserver automatisch de SNR monitort en het apparaat indien nodig de opdracht geeft om zijn signaal over een breder spectrum uit te breiden om de SNR te verbeteren.
MQTT-berichten
De netwerkserver decodeert nu al je LoRaWAN-sensors en stuurt deze data in de vorm van MQTT-pakketten uit naar de MQTT-broker. Hierop kun je nu andere software laten luisteren, zoals je domoticaysteem. Daarvoor moet je eerst inzicht hebben in het formaat van de data. Gebruik daarvoor een MQTT-client die zowel voor Windows, macOS als Linux bestaat (zoals MQTTX, https://www.mqttx.app). Vul als hostname voor de broker het ip-adres of domein waarop de broker van je ChirpStack-netwerkserver draait en klik op Connect.
Klik dan op New Subscription en type het MQTT-onderwerp in dat je wilt volgen. De vorm van dit onderwerp staat uitgelegd in de documentatie van ChirpStack over MQTT (https://www.kwikr.nl/csmq). Om alle uplinks van een specifiek apparaat te ontvangen in de MQTT-client, vul je dit onderwerp in: application/APPLICATION_ID/device/DEV_EUI/event/up. De Application ID vind je op de pagina van de applicatie in ChirpStack naast de naam, en de Device EUI op de pagina van het apparaat. Je kunt ook single-level wildcards + gebruiken om alle uplinks van alle apparaten van alle applicaties te zien met application/+/device/+/event/up. Verander na het aanmaken van de subscription bovenaan Plaintext in JSON om de structuur van de boodschappen te zien.
In MQTTX kunnen we de MQTT-berichten zien die ChirpStack voor elke sensormeting uitstuurt.
Integreren in domoticasysteem
Je kunt nu de sensormetingen in je domoticasysteem integreren als dit MQTT ondersteunt. We tonen hoe dit gaat in Node-RED (https://www.nodered.org). De makers van ChirpStack voorzien zelf een pakket voor Node-RED: node-red-contrib-chirpstack (https://www.kwikr.nl/csnr). Installeer dat op de Linux-server of in de Docker-container waarin je Node-RED hebt draaien, met deze opdracht:
npm install @chirpstack/node-red-contrib-chirpstack
Na een herstart van Node-RED zie je links onderaan twee nieuwe nodes in de categorie ChirpStack.
Voeg nu een mqtt in-node aan je flow toe, voeg een nieuwe broker toe en kies als onderwerp het MQTT-onderwerp voor de uplink van je apparaat. Als je nu op Deploy klikt, moet er bij de node een groen icoontje met connected bij staan. Koppel daarna een device event-node aan je mqtt in-node en zorg dat Event Type op Uplink staat (de standaard). Koppel hierachter een change-node waarbij je msg.payload gelijkstelt aan de waarde msg.payload.object.TempC_SHT31.
Hang hier een debug-node achter. Klik nog eens op Deploy, en wanneer je LoRaWAN-sensor weer een uplink stuurt, krijg je de temperatuur in het debugvenster te zien. De uitvoer van de change-node kun je nu ook op andere manieren verwerken, bijvoorbeeld door de temperatuur in een dashboard te visualiseren.
In Node-RED kun je reageren op de MQTT-berichten van de LoRaWAN-netwerkserver van ChirpStack.
