Detecteer personen in je huis met Frigate

Realtime detectie van personen in camerabeelden is mogelijk dankzij machine learning. We gebruiken daarvoor een neuraal netwerk dat getraind is op beelden van personen. Als je dit netwerk daarna nieuwe beelden toont, kan het met de kennis die het tijdens de training opgedaan heeft personen detecteren. Dat werkt vrij goed: de technologie is de laatste jaren met rasse schreden vooruitgegaan.

01 Raspberry Pi 4 met Coral USB Accelerator

Er is één nadeel: deze detectie vereist heel wat rekenwerk. Gelukkig bestaat er speciale hardware die geoptimaliseerd is voor de berekeningen in neurale netwerken. Een van die hardwareversnellers is de Google Coral USB Accelerator, die voor rond de 70 euro te koop is. Het is een klein kastje ter grootte van een wat brede usb-stick, en wordt via een meegeleverde usb-c-kabel op een usb3-poort aangesloten voor de communicatie met de computer.

Als computer waarop we de herkenningssoftware draaien, kiezen we voor de energiezuinige Raspberry Pi (maar het kan ook op een Ubuntu-server, bijvoorbeeld met Ansible-NAS (zie Computer!Totaal 9). Hoewel de eerdere modellen in principe ook kunnen, raden we de nieuwe Raspberry Pi 4 aan omdat die twee usb3-poorten heeft; anders wordt de snelheid van de Coral USB Accelerator afgeknepen door de usb2-poort. Een ander voordeel van de Pi 4 is dat die naast de basisversie met 1 GB RAM ook versies met 2 en 4 GB RAM heeft. Wij hebben deze masterclass met succes uitgevoerd op een Pi 4 met 2 GB RAM.

We gaan ervan uit dat je Raspbian Buster Lite op je Raspberry Pi 4 geïnstalleerd hebt. Dat doe je door het image met balenaEtcher op een micro-sd-kaart te schrijven, er een leeg bestand ssh in op te slaan en eventueel (als je wifi gebruikt in plaats van ethernet) een bestand wpa_supplicant.conf met de wifi-configuratie. Steek de micro-sd-kaart daarna in je Pi, sluit de Coral USB Accelerator op een usb3-poort van de Pi aan, sluit eventueel de ethernetkabel aan en tot slot de voedingsadapter om je Pi op te starten.

02 Domoticacontroller en mqtt-broker

Als domoticacontroller maken we gebruik van Home Assistant. Dat kun je op een Raspberry Pi installeren (eventueel zelfs dezelfde die de beeldherkenning doet), of op je nas of een Linux-server via Docker. Een eenvoudige manier om Home Assistant te installeren is via Hass.io. In de masterclass in Computer!Totaal 7/8 vind je uitgebreide instructies.

Ook met een ander domoticasysteem kun je deze masterclass uitvoeren, zolang je het systeem maar met een mqtt-broker kunt laten communiceren. Die mqtt-broker dien je zelf nog te installeren: Eclipse Mosquitto is een populaire keuze. Gebruik je Hass.io, dan installeer je Mosquitto eenvoudig via de add-on Mosquitto MQTT broker.

Een mqtt-broker is een centrale server die verbonden clients toelaat om boodschappen uit te wisselen zonder dat ze van elkaars bestaan hoeven te weten. Wanneer onze Pi 4 een persoon detecteert in het camerabeeld, stuurt die via mqtt een boodschap naar de broker en wanneer de persoon weer uit beeld is een andere boodschap. Home Assistant heeft zich ondertussen geabonneerd op de boodschappen, zodat het domoticasysteem onmiddellijk door de mqtt-broker op de hoogte gehouden wordt bij het verschijnen of verdwijnen van een persoon.

03 Camera’s

Dan ontbreekt nog maar één component in onze opstelling: de camera’s. De software Frigate kan personen in streams van meerdere camera’s tegelijk detecteren. Dat werkt in principe met elke ip-camera die rtsp (Real Time Streaming Protocol) ondersteunt, dus die camera’s kunnen overal in je huis staan.

De detectie van personen verloopt dan als volgt. De Pi 4 leest continu één of meer streams van ip-camera’s in via het netwerk, laat er zijn neuraal netwerk op los, dat via de aangesloten Coral USB Accelerator versneld wordt uitgevoerd, en stuurt dan de boodschap dat er een persoon verschijnt of verdwijnt via mqtt-boodschappen over het netwerk. Home Assistant pikt die boodschappen op en reageert erop, bijvoorbeeld door verlichting aan of uit te doen of je een notificatie te sturen.

04 Configuratiebestand

De volgende stap is om een configuratiedirectory op je Pi 4 aan te maken en daarin een configuratiebestand in te vullen:

mkdir frigate_config
nano frigate_config/config.yml

De inhoud daarvan hangt van je situatie af. Gebruik als inspiratie het voorbeeldconfiguratiebestand van de GitHub-pagina van Frigate. Het resultaat zal er ongeveer zo uitzien:

web_port: 5000
mqtt:
host: 192.168.0.63
topic_prefix: frigate
cameras:
voordeur:
rtsp:
user: frigate
host: 192.168.0.118
port: 5540
password: geheim
path: /ch0
take_frame: 5
regions:
- size: 200
x_offset: 140
y_offset: 340
min_person_area: 5000
threshold: 0.5

Sla dit op met Ctrl+O en sluit nano dan af met Ctrl+X.

De variabele web_port stelt de poort voor waarop Frigate de mjpeg-stream en jpg-snapshots van de gedetecteerde personen ter beschikking stelt. Onder mqtt definieer je de hostname of het ip-adres van de machine waarop je mqtt-broker draait en het prefix waaronder Frigate al zijn mqtt-boodschappen publiceert.

Onder cameras definieer je één of meerdere camera’s, in dit geval slechts één (voordeur). Onder rtsp vul je de gegevens in over de hostnaam, poort, gebruikersnaam en wachtwoord en het pad waaronder het beeld van de camera beschikbaar is. Als je camera geen authenticatie vereist, vul je een willekeurige gebruikersnaam en wachtwoord in. Met take_frame: 5 zeggen we dat Frigate maar elke vijf frames moet verwerken. Dat is handig voor camera’s waarvan je de framerate niet kunt instellen.

05 Naar personen zoeken

Onder regions tot slot definieer je in welke regio’s Frigate naar personen zoekt. We hebben hier één regio gedefinieerd, maar om rekentijd uit te sparen definieer je er beter enkele kleinere. De juiste waardes hangen van de resolutie van je camera af en waar je personen verwacht.

De variabele min_person_area stelt het product van lengte en breedte in pixels voor dat iemand minimum van oppervlakte moet hebben om als persoon gedetecteerd te worden. En met de drempelwaarde in de laatste regel stellen we in dat we van het detectie-algoritme minstens 50% kans dat het om een persoon gaat verwachten voor we op mqtt publiceren dat we een persoon hebben gevonden. Met al deze waardes zul je wat moeten experimenteren zodra je het beeld ziet.

06 Docker installeren

Frigate wordt verspreid in de vorm van een Docker-container. Installeer dus eerst Docker. Helaas bevatte de versie van Docker in Raspbian Buster tijdens de redactiesluiting een fout, waardoor je die niet met een eenvoudig sudo apt install docker.io kon installeren. Download daarom in de plaats het installatiescript van de website van Docker en voer het uit:

curl -sSL https://get.docker.com | sh

Geef dan je gebruiker toestemming om Docker te gebruiken:

sudo usermod pi -aG docker

Log uit met exit en log dan weer in, zodat de gebruikersrechten van toepassing zijn.

07 Frigate installeren

Download nu de broncode van Frigate:

git clone https://github.com/blakeblackshear/frigate.git

Tijdens de redactiesluiting werkte Frigate nog niet out-of-the-box op een Raspberry Pi, maar met één wijziging werkt het wel. Open het bestand Dockerfile:

cd frigate
nano Dockerfile

En zoek dan naar de volgende regels:

# VAAPI drivers for Intel hardware accel
libva-drm2 libva2 i965-va-driver vainfo \

Plaats een hekje (#) voor de tweede regel, want deze pakketten bestaan niet voor de Raspberry Pi. Sla je wijzigingen op met Ctrl+O en sluit nano af met Ctrl+X.

Daarna creëren we de Docker-container van Frigate met:

docker build -t frigate .

Dat duurt een tijdje, je kunt de stappen van het bouwproces (van 1 tot 24) volgen terwijl ze worden uitgevoerd. Daarna kunnen we de Docker-container van Frigate installeren:

docker run --privileged -v /dev/bus/usb:/dev/bus/usb -v /home/pi/frigate_config:/config:ro -p 5000:5000 frigate:latest

Op deze lange opdrachtregel zie je onder andere dat we verwijzen naar het eerder aangemaakte configuratiebestand en dat we poort 5000 in de Docker-container laten forwarden naar poort 5000 op de Raspberry Pi.

Houd je Pi koel!

08 Persoon gevonden

Als je nu een foutmelding te zien krijgt, moet je misschien in het configuratiebestand van Frigate enkele zaken aanpassen. Probeer de framerate bijvoorbeeld te verlagen en de regio’s te verkleinen. Zo mag een regio niet deels buiten het gezichtsveld van de camera vallen. Als alles goed gaat, kun je nu in je webbrowser een stream van het beeld van elke camera opvragen via http://IP:5000/voordeur.

De regio’s voor de detectie worden als witte vierkanten getoond. Als deze verkeerd staan, pas de regio’s dan in het configuratiebestand aan, sluit de Docker-container af met Ctrl+C en start hem opnieuw op met de laatste opdracht uit de vorige stap.

Als er nu een persoon in het beeld gedetecteerd wordt, krijg je er in het rood ‘person’ en een percentage bij te zien. Dat is de kans dat het volgens het neurale netwerk om een persoon gaat. Misschien zie je ergens in beeld ook een ander object herkend worden, zoals een ‘refrigerator’ of ‘cat’. Naast ‘person’ kent het gebruikte neurale netwerk immers ook andere objecten. Op de url http://IP:5000/voordeur/best_person.jpg vind je het recentste beeld van de persoon met het beste herkenningspercentage.

09 Camerabeeld in Home Assistant

Dit statische jpg-beeld kun je eenvoudig in Home Assistant (of een ander domoticasysteem) integreren door de url als een camera te definiëren. Zet daarvoor de volgende code in je configuration.yaml:

camera:
- name: Laatste persoon
platform: generic
still_image_url: http://IP:5000/voordeur/best_person.jpg

Deze ‘virtuele camera’ kun je nu in het dashboard van je Home Assistant tonen om altijd een beeld van de laatst herkende persoon te zien. Dat kan bijvoorbeeld met de volgende Lovelace-configuratie:

- type: picture-glance
title: Voordeur
entities: []
camera_image: camera.laatste_persoon

10 Mqtt-boodschappen

Je hebt nu altijd een beeld van de laatste persoon die in het camerabeeld kwam, maar als we van de mqtt-boodschappen die Frigate uitstuurt gebruikmaken, kunnen we Home Assistant ook op de aanwezigheid van personen in beeld laten reageren.

Dat gaat als volgt: als Frigate een persoon in de camera voordeur vindt, publiceert het programma een boodschap {"person": "ON"} op het mqtt-onderwerp frigate/voordeur/objects. Gaat de persoon daarna uit beeld, dan stuurt Frigate de boodschap {"person": "OFF"} naar hetzelfde onderwerp. Heb je nu ook een camera achterdeur gedefinieerd waarvan je door Frigate het beeld laat analyseren, dan verschijnen dezelfde boodschappen op het onderwerp frigate/achterdeur/objects. De boodschappen zelf hebben de vorm van een json-dictionary.

11 Persoonssensor in Home Assistant

Daarmee weten we nu genoeg om Home Assistant te laten reageren op de aanwezigheid van personen. Creëer een nieuwe binaire sensor in je configuration.yaml van Home Assistant:

binary_sensor:
- name: Camera persoon
platform: mqtt
state_topic: "frigate/voordeur/objects"
value_template: '{{ value_json.person }}'
device_class: motion
availability_topic: "frigate/available"

Als je Home Assistant daarna herstart, krijg je een extra binaire sensor te zien die aan of uit is naargelang er een persoon in het camerabeeld gedetecteerd wordt. En omdat Frigate op het mqtt-onderwerp frigate/available met de boodschap online respectievelijk offline aangeeft wanneer het programma start en stopt, kun je ook van in Home Assistant zien of Frigate wel draait. Als Frigate om een of andere reden gecrasht is, zie je dan in Home Assistant ‘Niet beschikbaar’ als status bij je sensor.

12 Op personen reageren in Home Assistant

Nu kun je Home Assistant in een automatisering laten reageren op de persoonssensor. Open in de webinterface van Home Assistant links Instellingen / Automatisering en klik dan rechtsonder op het plusteken om een nieuwe automatisering aan te maken. Geef je automatisering een naam.

Bij de triggers laat je het type op Staat staan en kies je als entiteit je binaire sensor, bijvoorbeeld binary_sensor.camera_persoon. Zorg dat bij de van-waarde off staat en bij de naar-waarde on. Zo laat je deze automatisering reageren op het verschijnen van een persoon. Wil je daarentegen bij het verdwijnen van een persoon een actie uitvoeren, draai dan beide waardes om.

Vul eventueel bij Voor een duur in, bijvoorbeeld als je de automatisering alleen wilt uitvoeren als een persoon minstens een bepaalde tijd aanwezig of afwezig is. Dat helpt ook om niet op elke snelle schakeling tussen on en off te reageren, want in sommige configuraties doet Frigate dat wel eens, terwijl er gewoon de hele tijd een persoon in beeld is.

13 Voorwaarden

Het volgende onderdeel zijn de voorwaarden. Je wilt immers waarschijnlijk niet elke keer dat Frigate een persoon detecteert iets doen. Misschien wil je bijvoorbeeld alleen als je afwezig bent alarm slaan terwijl er een persoon op het camerabeeld van je voordeur te zien is. Klik dan op Voorwaarde toevoegen en vul hier als voorwaarde toe dat je afwezig bent, bijvoorbeeld op basis van het bluetooth-signaal van je smartphone of fitnesstracker. In Computer!Totaal 7/8 vind je hoe je dat doet.

Kies je als type voorwaarde voor Tijd, dan kun je ook instellen dat de gedefinieerde actie alleen uitgevoerd wordt als de persoon ná of vóór een tijdstip of tussen twee tijdstippen gedetecteerd wordt. Je kunt zoveel voorwaarden toevoegen als je wilt.

14 En … actie!

Als laatste onderdeel van de automatisering komen de acties. Wat je hier doet, hangt natuurlijk af van wat je in Home Assistant allemaal gedefinieerd hebt. In de meeste gevallen zul je als type actie Service aanroepen gebruiken, in het uitklapmenu eronder een service kiezen en dan eronder service data toevoegen. De details hiervan hangen van de service af, en daarvoor verwijzen we naar de documentatie van Home Assistant.

Om je wat inspiratie te geven enkele ideeën die je hier kunt uitvoeren wanneer Frigate een persoon detecteert: stuur een notificatie naar je smartphone inclusief een foto van de persoon op de camera, activeer een willekeurig script, laat je verwelkomen met een gesproken boodschap, of stuur je Philips Hue-verlichting aan. Mogelijkheden genoeg!

Onder de motorkap van Frigate