Mijn eerste Chinese ESP32 verbonden met The Things Network

Tot voor kort had ik 2 verschillende LoraWAN nodes in huis: een tweetal LoPy‘s, waarvan er eentje dienst doet als single channel gateway en een Marvin. Beide zijn niet bijzonder goedkoop, een LoPy met ontwikkelbordje en antenne kost zo’n 50 euro excl. verzendkosten. Een Marvin kost bijna 85 euro excl. verzendkosten. Niet echt sensoren dus die je ergens “kwijt” wilt raken. Terwijl een LoraWAN sensor toch juist vaak op een plek moet komen te hangen die iets verder van alles weg is (zoals sensoren langs een weg die fijnstof meten of zo).

Je kunt zelf een sensor bouwen door een chip te bestellen voor de communicatie, een ESP8266 te kopen, antenne etc en dan solderen. Maar dat kost tijd en extra werk.  De “868MHz/915MHz SX1276 ESP32 LoRa 0.96 Inch Blue OLED Display Bluetooth WIFI Lora Kit 32 Module IOT Development Board for Arduino” zoals de listing op AliExpress voluit luidt, is een voorbeeld van een tussenweg: voor €13,90 incl. verzendkosten heb je een ESP32 + SX1276 chip op een ontwikkelbord. Als je het LCD-scherm dat er dan op zit niet nodig hebt, kun je nog een paar euro besparen en €10,29 betalen incl. verzendkosten. Het is niet mijn eerste node op basis van een ESP32, ook de LoPy maakt daar gebruik van, maar het was wel de eerste die ik via AliExpress bestelde. En ik wist dat het daar bestellen een keerzijde heeft: documentatie is niet altijd voorhanden.

Gelukkig is er ook een heel actief forum bij The Things Network waar een heel topic specifiek voor deze combinatie van ESP32 en SX1276 chip (inclusief het OLED schermpje) ingericht is. En daar hadden sinds oktober 2017 al een paar slimme mensen alles uitgezocht wat ik nodig had om ook mijn exemplaar aan de praat te krijgen. En omdat het een proces is dat ik over een paar maanden zeker niet meer uit mijn hoofd weet te herhalen, documenteer ik het hier weer even.

Stap 1 was het er voor zorgen dat de Arduino IDE in staat was om code voor het board te compileren en te uploaden. Daarvoor moet je naar deze respository. Als je naar beneden scrolt dan zie je de installatie-uitleg ook in het Engels. Ik heb geen gebruik gemaakt van het uitchecken via git, maar gewoon de ZIP-download (grote groene knop rechtsboven) gebruikt. In de map ..\Documents\Arduino\hardware op mijn laptop heb ik de map “heltec” aangemaakt en daarbinnen de mappen “esp32” en “esp8266” uit de ZIP gekopieerd.

Belangrijk: in de map ..\Documents\Arduino\hardware\heltec\esp32\tools staat een bestand get.exe. Hier moet je op dubbelklikken zodat een aantal andere, aanvullende bestanden gedownload worden.

Stap 2 is het downloaden van de Arduino-LMIC library die zorgt voor het aansturen van de SX1276 chip op het board. Ook hier heb ik gebruik gemaakt van de ZIP-download. Dit is een bibliotheek, dus die moet geïnstalleerd worden vanuit de Arduino IDE via  Schets > Bibliotheek gebruiken > .ZIP bibliotheek toevoegen.

Stap 3 is dan nog het installeren van de U8x8lib bibliotheek. Die kun je gewoon via de ingebouwde download voor bibliotheken installeren, dus via Schets > Bibliotheek gebruiken >  Bibliotheken beheren.

En dán heb je echt alles bij elkaar om aan de slag te gaan.

Als board selecteer je “WiFi_LoRa_32”. Bij de repository van Matthijs Kooijman vind je bij de LMIC bibliotheek ook een aantal voorbeelden van het gebruik van The Things Network. Je kunt kiezen voor zowel OTAA als ABP. Daarvoor moet je eerst in de console van TTN een nieuw device aanmaken. Dat levert je namelijk de benodigde codes op die je in jouw exemplaar van het script toe moet voegen (zodat de data van het device op de juiste plek aan komt).

Er is nog één aanpassing die je moet maken in de voorbeelden zoals ze bij LMIC staan. Dit stukje code:

// Pin mapping
const lmic_pinmap lmic_pins = {
    .nss = 6,
    .rxtx = LMIC_UNUSED_PIN,
    .rst = 5,
    .dio = {2, 3, 4},
};

Moet je vervangen door:

// Pin mapping
const lmic_pinmap lmic_pins = {
    .nss = 18,
    .rxtx = LMIC_UNUSED_PIN,
    .rst = 14,
    .dio = {26, 33, 32},
};

De voorbeelden van LMIC maken geen gebruik van het OLED schermpje, dus dat zal niets doen. Kan op zich handig zijn als je een versie met scherm hebt en geen status-updates hoeft te tonen, maar als je het wel wilt, dan is dat eenvoudig toe te voegen, zie deze uitleg en uiteindelijk dit resultaat voor OTAA. Ik wilde ABP gebruiken, dus heb ik het LMIC voorbeeld uitgebreid met de benodigde OLED code en hier online gezet. Je moet hier wel zelf nog even je TTN codes invullen op de drie aangegeven plekken boven in het script.

De code “doet” nog niet veel. Het stuurt steeds de zin “Hello, world!” door. Als je in de console van TTN gaat kijken zul je daar niet zomaar die tekst weer terug zien. Waarschijnlijk (als het goed is), zie je daar als payload “48656C6C6F2C20776F726C6421”. Lees eerst even dit bericht. Daarin wordt uitgelegd dat dit de hexadecimale codes zijn voor de string. “48” is de hexadecimale code voor “H” (voor de oudjes: kijk maar in deze ASCII tabel, in de 2e kolom de waarde 48 opzoeken en dan rechts kijken voor het bijbehorende character).
Het laten vertalen van die codes naar een tekst kun je laten doen door een payload function (die vind je als “Payload Formats” op Application niveau). Als je daar bv deze functie toevoegt:

function Decoder(bytes, port) {
    var text = String.fromCharCode.apply(null, bytes);
    return {
        message: text
    }
}

Dan wordt de binnenkomende string netjes vertaald in een JSON-object met daarin de inhoud van de string als “message”.

En nu?
Een node die alleen maar een statische tekst doorstuurt is natuurlijk niet zo zinvol. Dus wil je er sensoren mee kunnen verbinden (voor fijnstof, temperatuur, luchtdruk, snelheid,….). Daarvoor moet je dan natuurlijk wel weten welke van de GPIO-pinnen waarvoor zijn en hoe ze “heten” (hoe je er in de code naar moet verwijzen). Daarvoor heb je zo’n afbeelding nodig:

Een aantal van de pinnen wordt in de code al gebruikt van de Lora chip en het OLED-scherm. Een snelle blik op de code leert dat GPIO-pinnen 15, 4, 16, 18, 14, 26, 33, 32 al in gebruik zijn. Ik moet hier nog mee gaan experimenteren omdat ik op meer plekken “LoRa_” zie staan, dus wellicht zijn die ook al in gebruik, maar de RX/TX poorten bij GPI01 en GPO03 lijken in ieder geval vrij te zijn voor sensoren die een seriële interface gebruiken.

Conclusie
Zomaar een ontwikkelbordje bestellen via AliExpress klinkt leuk, maar je hebt er de nodige slimme mensen voor nodig die het bijbehorende uitzoekwerk willen doen om het geheel aan de praat te krijgen. Gelukkig zijn die mensen er op het TTN forum. Ik heb niet meer hoeven doen dan hun berichten (goed en aandachtig) door te lezen en hun ervaring te combineren tot deze blogpost.

Een laatste opmerking nog over de behuizing die je erbij kon kopen (ik zie nu dat hij niet langer te koop is). Daar mis je niet echt iets aan. De behuizing heeft geen voorziening voor het naar buiten leiden van kabels voor sensoren, de schroefgaten voor het bevestigen van het board aan de binnenkant zitten verkeerd (lang leve de plakband), kortom, het lijkt leuk, maar je kunt beter zelf een behuizing ontwerpen/printen.