Zo maak je je eigen bewegingssensor
BTHome is een nieuwe open standaard voor sensors en knoppen die data via bluetooth doorsturen, ontstaan via het opensource-project Home Assistant. Elk apparaat dat het BTHome-protocol implementeert, wordt automatisch door Home Assistant herkend. Dat is handig als je zelf een bluetooth-sensor wilt maken.
In dit artikel leggen we uit hoe BTHome werkt en programmeren we in CircuitPython een sensorbordje dat detecteert wanneer het beweegt en zijn toestand via bluetooth aan Home Assistant doorstuurt.
Lijkt dit je interessant, maar weet je nog maar weinig van Home Assistant, lees dan eerst dit artikel: Maak je huis slim met Home Assistant
Code downloaden In dit artikel worden best lange voorbeelden van stukken code gegeven. Omdat overtikken van code erg foutgevoelig is, kun je die code beter downloaden en daarna bekijken of kopiëren. Zie het bestand code-bthome.txt voor de code-snippets die in dit artikel genoemd worden. De volledige code van dit project vind je op GitHub.
Heel wat goedkope sensors sturen via bluetooth low-energy data rond naar iedereen in de buurt die het maar wil oppikken. Dat heet broadcasting. Zo’n sensor doet een meting, stuurt de data rond, gaat even in slaap, wordt wakker en stuurt dan de volgende meting door.
Een domoticacontroller zoals Home Assistant kan die bluetooth-pakketjes oppikken via de bluetooth-chip in bijvoorbeeld de Raspberry Pi waarop je de software draait. Maar met alleen het datapakketje ben je nog nergens: je hebt nog een decoder nodig die het formaat van de data kent en er de nuttige sensorwaarden uit haalt. Omdat elke fabrikant zijn eigen formaat gebruikt, heb je daardoor allerlei integraties nodig in Home Assistant: voor Xiaomi, ThermoPro, Inkbird, Govee, Qingping enzovoort.
Eén standaard voor alle sensors
De makers van Home Assistant besloten daarom om een formaat te bedenken dat allerlei soorten sensors ondersteunt: BTHome. Apparaten die bluetooth-data uitsturen volgens dit formaat, worden dan automatisch door Home Assistant herkend aan de hand van de BTHome-integratie.
Het BTHome-formaat waarmee compatibele apparaten hun data uitzenden, is uitgebreid gedocumenteerd. Dit kun je raadplegen als je in je eigen apparaten van BTHome wilt gebruikmaken. Hiervoor kun je de programmeertaal van jouw keuze voor jouw hardware gebruiken, zolang je maar BLE-advertisements kunt uitsturen.
Bluetooth in Home Assistant inschakelen
Voor je met BTHome aan de slag gaat, dien je eerst na te gaan of je bluetooth-adapter door Home Assistant wordt herkend. Heb je een ingebouwde bluetooth-adapter, bijvoorbeeld op je Raspberry Pi, dan wordt die normaal gesproken al herkend op de pagina Instellingen / Apparaten & Diensten / Integraties. Zo niet, bijvoorbeeld als je een externe bluetooth-adapter via usb aansluit, klik dan rechts onderaan op die pagina op Integratie toevoegen en kies Bluetooth. Bevestig met Opslaan dat je de herkende adapter wilt toevoegen.
Als dit werkt, zul je in de integraties doorgaans al allerlei bluetooth-apparaten herkend zien worden. Dat is dankzij de integraties voor Xiaomi, ThermoBeacon, Qingping, ThermoPro, RuuviTag en vele andere die standaard al ingeschakeld zijn. De ondersteuning voor BTHome dien je nog expliciet in te schakelen, maar daarvoor hebben we eerst een werkend BTHome-apparaat nodig.
Energiezuinig bluetooth-bordje
Voor bluetooth alleen hebben we geen ESP32-microcontrollerbordje of een Raspberry Pi Pico nodig, die immers ook een wifi-chip hebben en daardoor meer energie verbruiken. Daarom kiezen we voor een microcontrollerbordje gebaseerd op de nRF52840, een populaire bluetooth-chip van Nordic Semiconductor. Dit soort bordjes zijn energiezuinig en worden door talloze programmeeromgevingen ondersteund.
In dit artikel gebruiken we als sensorbordje een XIAO nRF52840 Sense van Seeed Studio. Het is een uiterst compact bordje (21 bij 17,5 mm) waarin een microfoon, accelerometer en gyroscoop zijn ingebouwd. Met die twee laatste kun je detecteren wanneer het bordje beweegt. Kies je een ander bordje, dan zul je de instructies in dit artikel wellicht hier en daar moeten veranderen, maar de aanpak blijft hetzelfde.
CircuitPython op de Seeed XIAO nRF52840 Sense
Eerst dienen we CircuitPython op het bordje te installeren, een op Python gebaseerde programmeertaal voor microcontrollers. Download op de website van CircuitPython het firmwarebestand voor je bordje, in ons geval CircuitPython 8.0.2 voor de Seeed Studio XIAO nRF52840 (Sense). Het bordje bestaat ook in een versie zonder de sensors maar met dezelfde firmware, maar voor dit artikel hebben we de Sense-versie met sensors nodig.
Sluit daarna het bordje via usb aan op je computer en druk twee keer snel na elkaar op het minuscule resetknopje (aangeduid met RST) naast de usb-aansluiting.
Op je computer verschijnt nu een schijf met de naam XIAO-SENSE. Sleep het gedownloade bestand adafruit-circuitpython-Seeed_XIAO_nRF52840_Sense-nl-8.0.2.uf2 naar de schijf. Daarna koppelt je computer de schijf af en koppelt hij een nieuwe schijf met de naam CIRCUITPY aan. Je bordje is nu klaar om te programmeren.
©Seeed Studio
Mu-editor
De eenvoudigste manier om je bordje in CircuitPython te programmeren, is met de code-editor Mu, die zowel voor Windows als voor macOS en Linux beschikbaar is. Start Mu op, klik bovenaan links op Mode, kies CircuitPython uit de lijst en klik op OK. Doorgaans wordt nu je aangesloten bordje herkend. Klik bovenaan op Serial om dit te controleren. Dit opent onderaan een tekstveld van de REPL (read–eval–print-loop). Druk je daarin op Enter, dan krijg je de CircuitPython-versie te zien die je bordje draait, samen met de naam van het bordje.
In het grotere tekstveld bovenaan kun je nu je code typen die je op je bordje wilt uitvoeren. Om te testen of de hardware werkt, typ je daarin de volgende code die de ingebouwde led doet knipperen:
Klik bovenaan op Save, selecteer code.py en bevestig dat je dit bestand wilt overschrijven. Als je nu in de REPL op Ctrl+D drukt om het bordje te herstarten, draait je CircuitPython-code en knippert de led.
Te ingewikkeld?
Een bewegingsmelder kopen hoeft ook niet duur te zijnSensordata uitlezen
Door de led te laten knipperen, weten we dat je bordje werkt. Maar we willen de sensordata uitlezen. We gebruiken de IMU (Inertial Measurement Unit), die een accelerometer en gyroscoop bevat. Deze wordt ondersteund door een bibliotheek van Adafruit. Download dus de CircuitPython-bibliotheken, met name de bundel voor CircuitPython 8.x. Pak het zip-bestand uit en kopieer de mappen adafruit_bus_device, adafruit_lsm6ds en adafruit_register naar de map lib van de drive genaamd CIRCUITPY. Die map bevat nu dus drie mappen.
Schrijf nu in het bestand code.py het volgende programma:
Deze code schakelt de IMU in, wacht 50 ms tot de sensor is ingeschakeld, stelt de I2C-bus in en initialiseert dan de IMU. Daarna lezen we elke seconde de versnelling en hoeksnelheid over de drie assen in en tonen deze. Sla je dit bestand op met Ctrl+S, dan krijg je in de REPL de sensorwaardes te zien. Als je wat zwaait met het bordje, zie je onmiddellijk het effect op de metingen.
Bewegingsdetectie
Dan moeten we nu uit deze data, die continu veranderen, beweging detecteren. We willen een eenvoudig signaal: het bordje beweegt of het bordje beweegt niet. Dat kun je op allerlei geavanceerde manieren doen, met de accelerometer, gyroscoop of een combinatie van de twee. Voor de eenvoud gebruiken we hier gewoon de gyroscoopwaardes. We kwadrateren elk van de drie componenten en tellen ze op, en we beschouwen het resultaat als beweging wanneer dit groter is dan 0,01.
Onze while-lus wordt dan eenvoudig:
We verminderen het slaapinterval tot 100 ms om een snellere reactie te krijgen. Elke keer dat je nu het bordje beweegt, krijg je “Moving” te zien in de REPL. Pas indien nodig de drempelwaarde 0.01 aan.
Apparaten die BTHome ondersteunen Grote fabrikanten blijven hun eigen formaat gebruiken, maar er bestaan wel diverse opensource-projecten die ondertussen BTHome ondersteunen. Het bekendste is ATC_MiThermometer, alternatieve firmware voor sommige bluetooth-thermometers van Xiaomi. Als je deze firmware op een apparaat hebt geïnstalleerd, kun je instellen dat deze de temperatuur in BTHome-formaat uitstuurt.
Ook de b-parasite, een grondvochtigheidssensor waarvan het ontwerp van de hardware én de firmware opensource is, kan zijn data in BTHome-formaat uitsturen.
©Raphael Baron
Bluetooth-advertenties
Ons bordje detecteert nu beweging en toont dat in de REPL, maar nu willen we dit signaal via bluetooth uitsturen. Daarvoor dienen we eerst in de specificatie van het BTHome-formaat te duiken. In bluetooth kunnen we via een advertentie data uitsturen naar iedereen in de buurt. Zo’n advertentie bestaat uit meerdere elementen en elk element op zijn beurt uit een aantal bytes: eerst de lengte van het element (dit lengtebyte uitgezonderd), dan het type element en daarna data waarvan de betekenis van het element afhangt.
Een advertentie die door BTHome wordt begrepen, kan uit drie elementen bestaan. Eén element is verplicht: Service Data (16bit-UUID). Hierin komen de sensordata te staan. Een element Flags is sterk aangeraden. En optioneel is een element Local Name, waarmee het apparaat zijn naam adverteert.
Structuur BTHome-advertentie
Laten we dus eens byte voor byte de advertentie samenstellen, met deze drie elementen. Eerst nemen we de flags op en die bytes zijn altijd hetzelfde voor BTHome: [0x02, 0x01, 0x06]. We gebruiken hier de Python-notatie voor een lijst (met rechte haken rond de elementen van de lijst) en de hexadecimale notatie van de bytes, elk voorafgegaan dor 0x. De 2 staat voor de lengte van het element (het aantal bytes erna), de 1 duidt aan dat het element van het type Flags is en 6 betekent LE General Discoverable Mode en BR/EDR Not Supported. Samengevat: dit is een apparaat met alleen bluetooth low-energy dat algemeen te vinden moet zijn.
Daarna komt een element met de eigenlijke sensordata. De lengte weten we nog niet, dus die laten we even open. Het type is 0x16, wat betekent dat het om service data met een 16bit-UUID gaat.
Daarna komen de data zelf. Die beginnen met het UUID en dat zijn altijd de bytes [0xD2, 0xFC]: het UUID van Allterco Robotics (de maker van Shelly-apparaten), dat gebruikers een licentie geeft om dit UUID te gebruiken voor BTHome.
Daarna komt een byte met apparaatinformatie. Als het om versie twee van het BTHome-formaat zonder encryptie gaat, is dit byte altijd 0x40.
Dan komen nog twee bytes: één met het type data (beweging wordt voorgesteld door 0x22) en één met de data zelf: 0 voor geen beweging, 1 voor wel beweging.
En nu kunnen we dus de bytes voor de sensordata aanmaken: [0x06, 0x16, 0xD2, 0xFC, 0x40, 0x22, 0x01]. Het eerste byte is 6, omdat het de lengte is van de bytes erna.
Tot slot voegen we nog een element met de naam van het apparaat toe, bestaande uit de lengte, 0x09 voor het type en dan de bytes van de naam.
Klasse voor BTHome-advertentie
Om dit wat overzichtelijker te maken, definiëren we een klasse in onze CircuitPython-code die deze elementen samenneemt en ze daarna eenvoudig naar de bytes omzet die we in de bluetooth-advertentie kunnen uitsturen. De code ziet er als volgt uit:
Je ziet hier dat we de elementen voor de flags en service data definiëren. In de methode __init__ (die een object van de klasse aanmaakt) zetten we de naam die je aan het object doorgeeft om naar een element voor de local name. Op het moment dat we de bewegingstoestand van de sensor willen adverteren, kunnen we dan eenvoudigweg de methode adv_data van het object roepen met als argument 1 voor beweging en 0 voor geen beweging. Die methode plakt al die reeksen bytes op de juiste manier aan elkaar en vervangt het laatste byte van de service data door de bewegingstoestand.
Beweging adverteren
Dan komt nu de laatste stap, de bewegingsdetectie via bluetooth adverteren. Daarvoor importeren we in het begin van de code eerst de adapter van de module _bleio):
from _bleio import adapterWe maken dan op het einde van onze code een object van de klasse BTHomeAdvertisement met de naam van ons apparaat, en de while-lus breiden we uit om de bewegingstoestand telkens te adverteren:
Bij beweging vragen we aan het object bthome de advertentiedata voor beweging op en anders de advertentiedata voor geen beweging. We tonen de data in de REPL en adverteren ze via de bluetooth-adapter. Na 100 ms stoppen we met adverteren en doen we weer een meting. Daarna adverteren we weer met de nieuwe data en zo blijft dat aan de gang. Zoals eerder gezegd vind je op GitHub de volledige code.
Integratie in Home Assistant
Dan nu de test: detecteert Home Assistant onze sensor? Ga in het dashboard van Home Assistant naar Instellingen / Apparaten en Diensten / Integraties. Klik rechts onderaan op Integratie toevoegen en kies BTHome. Als je bordje aan het adverteren is, wordt het hier al onmiddellijk herkend. Klik op Opslaan, ken het eventueel aan een ruimte toe en klik dan op Voltooien. Daarna kun je het apparaat bekijken en de bewegingssensor erin toevoegen aan je dashboard of automatisaties.
Flexibel formaat
We hebben in dit artikel een eenvoudig voorbeeld gemaakt van een sensor die één type data uitstuurt: 1 of 0 voor wel of geen beweging. Maar het BTHome-formaat ondersteunt tientallen datatypes, waaronder temperatuur, luchtvochtigheid, batterijpercentage, stroom en snelheid.
BTHome is ook een flexibel formaat: je kunt de data van meerdere sensors tegelijk in één advertentie uitsturen. Stel dat we op onze XIAO nRF52840 Sense na de beweging ook de temperatuur willen uitsturen, dan voegen we aan de service data gewoon 0x02 voor de temperatuur toe en dan twee bytes die de temperatuur in honderdsten van een graad Celsius voorstellen. En we kunnen er ook nog 0x01 voor het batterijpercentage aan toevoegen en dan een byte met een waarde van 0 tot 100. De BTHome-integratie van Home Assistant pikt al die types en bijbehorende data op. Als je dus ooit een eigen bluetooth-sensor wilt maken, probeer dan BTHome eens uit.
13 Een greep uit de types sensors die BTHome ondersteunt.
Sensordata versleutelen Het BTHome-formaat dat we in dit artikel hebben gebruikt, stuurt alle sensordata onversleuteld uit. Iedereen in de buurt met een bluetooth-ontvanger kan deze data dus meelezen. Heb je dat liever niet, dan moet je gebruikmaken van de versleuteling in BTHome. De service data bevatten dan na de formaataanduiding 0x41 (BTHome v2 met versleuteling) versleutelde data, een teller en een Message Integrity Check (MIC). Alleen wie de sleutel heeft waarmee de data zijn versleuteld, kan de oorspronkelijke sensordata uit deze geadverteerde data reconstrueren. De BTHome-integratie in Home Assistant vraagt je om de sleutel in te voeren als je een BTHome-apparaat met encryptie wilt toevoegen.
