Visualiseer data van je bluetooth-sensors

Als je een borstband, smartwatch of fitnesstracker met hartslagsensor hebt en je hartslag met een app op je smartphone in het oog houdt, dan loopt de communicatie tussen het apparaat en je smartphone via bluetooth low-energy (BLE). Het is een laagdrempelig protocol voor draadloze communicatie op afstand omdat elke smartphone en laptop het tegenwoordig ondersteunt.

Heel wat draadloze temperatuursensors werken via BLE, zoals de RuuviTag of de plantensensor Xiaomi Mi Flora. Die sensors kun je allemaal uitlezen via apps van de producenten zelf of van andere partijen. Maar uiteindelijk gebruiken die apparaten allemaal een standaardprotocol, dus je kunt ook zelf de waardes in je eigen programma’s uitlezen.

01 Hoe werkt bluetooth low-energy?

Laten we eerst even stilstaan bij bluetooth low-energy (BLE). Er zijn twee soorten BLE-apparaten: een zogenoemde peripheral (een randapparaat zoals een sensor) en een zogenoemde central (een centrale eenheid zoals je smartphone). In deze masterclass maken we van onze laptop en van een ander apparaatje een central om de gegevens van de peripherals uit te lezen.

Er zijn nu twee manieren voor peripherals om hun gegevens uit te sturen. De gemakkelijkste manier is broadcasting. Daarbij stuurt een peripheral continu pakketjes van maximaal 31 bytes aan gegevens rond en alle centrals in de buurt kunnen deze gegevens oppikken. Een temperatuursensor zoals de RuuviTag werkt zo, maar elk BLE-apparaat zendt sowieso zijn aanwezigheid uit.

02 Een-op-eencommunicatie

De tweede manier voor BLE-communicatie heet Generic Attribute Profile (GATT) en werkt met een echte verbinding. De central verbindt met een peripheral en beide apparaten kunnen dan in twee richtingen met elkaar communiceren.

Belangrijk om te weten is dat een peripheral maar met één central tegelijk verbonden kan zijn. Bovendien stopt de peripheral met broadcasten zodra er een verbinding actief is. Daarom is je hartslagsensor bijvoorbeeld niet meer zichtbaar voor andere apparaten zodra je deze in de sport-app op je smartphone gebruikt.

03 Verken bluetooth-apparaten op je smartphone

Genoeg theorie, laten we je hartslag eens uitlezen op je smartphone, dan tonen we wat er op de achtergrond gebeurt. We gaan ervan uit dat je een apparaat hebt dat je hartslag uitleest. Zo niet, volg onze uitleg dan met een ander BLE-apparaat. Je zult dan alleen wat andere eigenschappen zien.

Een goede app die je zowel op Android als iOS kunt gebruiken om je BLE-apparaten te onderzoeken, is nRF Connect. Die is gemaakt door Nordic Semiconductor, een Noors halfgeleiderbedrijf dat draadloze chips voor onder andere BLE produceert. Open je de app, dan scant die onmiddellijk naar BLE-apparaten in je buurt en krijg je ze allemaal te zien met de naam die ze in de broadcastpakketjes adverteren, hun MAC-adres en hun signaalsterkte.

04 Verbind met je hartslagsensor

Als nRF Connect je hartslagsensor vindt (in ons voorbeeld de goedkope Chinese Xanes F15-smartwatch), druk ernaast dan op Connect. Zodra je verbonden bent, zie je in het tabblad Client een heleboel services, met namen als Device Information, Battery Service en Heart Rate. Bij elke service staat ook een UUID, een uniek (hexadecimaal) getal. Al die services zijn samen met hun UUID gedefinieerd in de bluetooth-specificatie.

Als je nu op een van die services klikt (bijvoorbeeld Heart Rate), ontvouwt er zich een lijst met karakteristieken. Elke karakteristiek heeft een naam, zoals Heart Rate Measurement of Body Sensor Location, een UUID, en eigenschappen zoals READ of NOTIFY. Elke karakteristiek stelt een waarde voor die je kunt lezen of in sommige gevallen schrijven. Fabrikanten kunnen bedrijfseigen karakteristieken definiëren of gebruikmaken van de standaardkarakteristieken die in de bluetooth-standaard zijn gedefinieerd.

Druk op de drie puntjes naast Server en dan op Read characteristics. De app leest nu de waardes van alle karakteristieken uit en toont ze. Zo zie je bij de Body Sensor Location de waarde Wrist. Je kunt ook op het downloadicoontje naast een specifieke karakteristiek drukken om alleen die karakteristiek uit te lezen.

05 Web bluetooth

We hebben nu met een smartphone de metingen van de hartslagsensor uitgelezen. Hoe zie je die gegevens op je laptop? Dat kan onder meer met de standaard Web bluetooth, ontwikkeld door Google en voorlopig alleen nog maar ondersteund in Chrome. Web bluetooth laat webapps met apparaten in de buurt te communiceren via bluetooth low-energy. Je hebt hiervoor minstens Chrome versie 56 nodig, en het werkt zowel op Windows, Linux als macOS. De Web Bluetooth Community Group heeft enkele leuke demo’s op zijn GitHub-pagina staan, waaronder het uitlezen van een hartslagsensor. Open de hartslagdemo in Chrome, dan toont de browser de beschikbare bluetooth-apparaten (let op: dit werkt dus alleen voor bluetooth-apparaten die niet al rechtstreeks aan een ander apparaat zijn gekoppeld). Selecteer je hartslagsensor en klik op Koppelen. Daarna krijg je je huidige hartslag op een webpagina te zien, inclusief een grafiekje van de historische gegevens eronder.

06 Arduino-code op een M5Stack Core

Hoe interessant Web bluetooth ook is, je gaat niet de hele tijd naar je computerscherm kijken om je hartslagmeter of een temperatuursensor in het oog te houden. We zijn daarom fan van de M5Stack Core, een ESP32-microcontroller in een behuizing van 5 bij 5 cm met een schermdiagonaal van 2 inch (ook zo’n 5 cm). Het apparaatje ondersteunt wifi en bluetooth, en je programmeert hem eenvoudig via het programma Arduino IDE.

Download Arduino IDE, open het menu Bestand / Voorkeuren en vul bij Additionele Board Beheer URLs de url https://dl.espressif.com/dl/package_esp32_index.json in. Ga dan naar Hulpmiddelen / Board / Board Beheer en installeer het pakket esp32 van Espressif Systems. Ga daarna naar Hulpmiddelen / Bibliotheken beheren en installeer de bibliotheken M5Stack en NimbLE-Arduino. Die eerste ondersteunt het scherm en de knoppen van de M5Stack, die tweede is nodig om via bluetooth low-energy te communiceren.

Selecteer vervolgens Hulpmiddelen / Board / ESP32 Arduino / M5Stack-Core-ESP32 en open het voorbeeldbestand Bestand / Voorbeelden / M5Stack / Basics / HelloWorld. Klik bovenaan links op het icoontje met het vinkje om de code te compileren. Als alles goed gaat, krijg je geen foutmelding. Sluit je M5Stack Core met een usb-kabel aan op je laptop en klik op het icoontje met het pijltje links bovenaan om de code naar het apparaat te flashen. Daarna krijg je “Hello World” op het schermpje te zien.

07 Hartslag op het scherm tonen

De bibliotheek NimBLE-Arduino heeft in zijn GitHub-repository enkele voorbeeldsketches voor Arduino staan – ‘sketch’ is de naam die Arduino IDE gebruikt voor ‘programmacode’. Wij hebben onze code gebaseerd op het voorbeeld NimBLE_Client in de map examples. Download onze aangepaste code via hier door het linkadres te kopiëren door er met je rechtermuisknop op te klikken en Linkadres kopiëren te kiezen en in een ander tabblad in de adresbalk te plakken (de code van het bestand M5Stack-Heart-Rate-Display.ino zit in een zip-bestand en moet je eerst uitpakken).

Als je een hartslagsensor bij de hand hebt, dan kun je de sketch nu gewoon zonder wijzigingen naar je M5Stack flashen. Wil je andere sensors uitlezen, dan leggen we je later in dit artikel uit hoe.

Nadat de M5Stack Core geflasht is, start het apparaatje de nieuwe firmware op. Als je hartslagmeter actief is, komt je hartslag na enkele momenten in het rood in het midden van het scherm. Zo niet (of als je gewoon wil weten wat de firmware op de achtergrond doet), dan open je in Arduino IDE via het menu Hulpmiddelen het venster Seriële monitor. Stel onderaan rechts de snelheid in op 115200 baud. In dit venster krijg je ook informatie te zien wanneer je Arduino-sketch een bluetooth-scan uitvoert, nieuwe apparaten vindt of zijn verbinding verliest.

08 Verbinding maken

Hoe werkt de Arduino-sketch M5Stack-Heart-Rate-Display.ino precies? In het begin geven we met twee include-opdrachten aan dat we functies van M5Stack en NimBLE-Arduino gebruiken. Daarna definiëren we de namen UUID_SERVICE en UUID_CHARACTERISTIC die respectievelijk verwijzen naar de UUID’s van de service en de specifieke karakteristiek waarin we geïnteresseerd zijn. Die gestandaardiseerde UUID’s vind je in een document van de Bluetooth SIG met alle toegekende UUID’s.

Scrol dan een heel stuk naar beneden in de code. Elke Arduino-sketch heeft een functie setup() waarin je de opdrachten plaatst die één keer moeten gebeuren, bij het opstarten van je apparaat. Hier initialiseren we de seriële verbinding die je via de seriële monitor van Arduino IDE kunt uitlezen. We initialiseren ook de hardware van de M5Stack Core en daarna NimBLE-Arduino. Daarna definiëren we welke functie wordt aangeroepen als er bluetooth-peripherals gevonden worden, geven we enkele scaninstellingen in en tot slot starten we een scan.

In de functie loop() wachten we tot er een apparaat gevonden is waarmee we willen verbinden (in dit geval een hartslagmeter). Zodra dat is gevonden, verbinden we ermee (we roepen de functie connectToServer() aan) en starten daarna een nieuwe scan. Die functie connectToServer() handelt het verbinden en herverbinden af, en vraagt ook aan de peripheral om notificaties te sturen bij veranderingen in de karakteristiek waarin we geïnteresseerd zijn (de hartslag).

09 Notificaties

Notificaties zijn belangrijk in bluetooth low-energy om energie te sparen. In plaats van continu een nieuwe waarde op te vragen bij een peripheral, kan de central beter de notificaties voor een specifieke karakteristiek afwachten. De peripheral stuurt dan op eigen initiatief de waarde door wanneer die veranderd is. Dat is wat ook in de functie connectServer() wordt ingesteld.

Als onze hartslagmeter een notificatie stuurt, wordt in onze sketch de functie notifyCB() aangeroepen. In tegenstelling tot de rest van de code, die nogal bewerkelijk is, ziet deze functie er vrij eenvoudig uit:

void notifyCB(NimBLERemoteCharacteristic* pRemoteCharacteristic, uint8_t* pData, size_t length, bool isNotify){

M5.Lcd.clear(BLACK);

M5.Lcd.setTextColor(RED, BLACK);

M5.Lcd.setTextSize(7);

M5.Lcd.setCursor(120, 100);

if(length) {

uint16_t heart_rate_measurement = pData[1];

if(pData[0] & 1) {

heart_rate_measurement += (pData[2] << 8);

}

M5.Lcd.printf("%d", heart_rate_measurement);

}

}

Wat gebeurt hier? We maken het scherm zwart, stellen de tekstkleur en -grootte in, plaatsen de cursor en tonen de meting die we doorkrijgen op het scherm. Voor die meting zelf moeten we de specificatie van de Heart Rate Service op de website van de Bluetooth SIG raadplegen (let op, er gaat gelijk een pdf downloaden). En wie het overzicht van alle beschikbare specificaties wil zien gaat naar www.tiny.cc/bluespecs.

De specificatie zegt dat de eerste byte van pData enkele flags met meta-informatie bevat. De belangrijkste flag voor ons is de eerste bit (dat we selecteren met pData[0] & 1): dit bepaalt of de hartslag in één of twee bytes wordt voorgesteld.

10 Andere informatie uitlezen

Deze Arduino-sketch kun je als basis gebruiken voor projecten die andere informatie via bluetooth moeten uitlezen. De code is zo opgebouwd dat er maar op twee plaatsen aanpassingen nodig zijn. In het begin verander je de waardes van UUID_SERVICE en UUID_CHARACTERISTIC in het UUID van de service respectievelijk de karakteristiek die je wilt uitlezen. In de functie notifyCB() verwerk je dan de gegevens die in pData zitten. De exacte structuur van de data vind je in de specificatie van de service, die je op de website van de Bluetooth SIG vindt.

Als je meerdere services en/of meerdere karakteristieken wilt uitlezen, bekijk dan de voorbeeldcode NimBLE_Client.ino waarvan we bovenstaande code hebben afgeleid. Het voornaamste verschil is dat de functie connectToServer() langer wordt: je loopt daar een voor een alle services na en schrijft je bij elke service in op alle karakteristieken waarin je geïnteresseerd bent. In de functie notifyCB() moet je dan ook controleren voor welke karakteristiek de functie is aangeroepen en afhankelijk daarvan de data decoderen en op het scherm tonen. De voorbeeldcode toont ook hoe je verbindt met een apparaat dat een pincode vereist.

11 Broadcastgegevens ontvangen

Zoals we in de eerste paragraaf van dit artikel uitlegden, is er nog een andere manier om bluetooth-gegevens door te sturen: via broadcasting. Een Arduino-sketch om deze gegevens te ontvangen is veel eenvoudiger, omdat je geen verbinding hoeft te maken en te onderhouden. Ook daarvoor heeft het project NimBLE-Arduino een voorbeeldsketch, BLE_Beacon_Scanner. Op basis daarvan hebben we een sketch voor de M5Stack gemaakt die de uitgezonden temperatuur van een RuuviTag-sensor leest.

Download de code door het linkadres te kopiëren door er met je rechtermuisknop op te klikken en Linkadres kopiëren te kiezen en in een ander tabblad in de adresbalk te plakken (de code van het bestand M5Stack-RuuviTag-Display.ino zit in een zip-bestand en moet je eerst uitpakken). De functie setup() initialiseert het apparaat. De functie loop() voert dan elke twee seconden een scan uit naar bluetooth-apparaten. En de methode onResult van de klasse MyAdvertisedDeviceCallbacks wordt bij het ontvangen van een broadcast uitgevoerd. Daar verwerk je dan de gegevens van de broadcast. In het begin van de code vul je bij MAC_ADDRESS het MAC-adres van je RuuviTag in.

12 Manufacturer data

In die methode onResult controleren we nu eerst of het MAC-adres van het gevonden apparaat overeenkomt met wat we in het begin van de code hebben ingesteld. Zo ja, dan controleren we of het apparaat ‘manufacturer data’ heeft, dat zijn de gegevens in een broadcast. We schrijven die gegevens ook naar Serial, zodat je ze in Arduino IDE met de seriële monitor kunt bekijken.

De manufacturer data begint altijd met twee bytes die het manufacturer ID aangeven. In het geval van Ruuvi zijn dat (hexadecimaal) 99 en 04. We controleren hier dus op en ook of de byte daarna gelijk is aan 3. Dat staat in de protocolspecificatie van de RuuviTag namelijk voor het formaat RAWv1.

13 Gegevens decoderen

Daarna is het een kwestie van de juiste bytes verwerken en naar een temperatuur vertalen. In de protocolspecificatie staat dat het gehele deel (dus het deel voor de komma) van de temperatuur in byte 4 staat en het deel na de komma in byte 5. Voor byte 4 controleren we eerst of de meest linkse bit 1 is, want dan is het een negatief getal. En zo tonen we uiteindelijk de temperatuur op het scherm.

Je kunt nu ook de andere sensordata van de RuuviTag decoderen, zoals de luchtvochtigheid en de spanning van de batterij. Nieuwere RuuviTags gebruiken overigens een ander formaat, namelijk RAWv2. Het is een mooie oefening om dit te proberen te decoderen. En voor andere sensors is er uiteraard ook documentatie te vinden, die je op dezelfde manier in je code kunt integreren.