Blueprints — Handig gereedschap, geen zwarte doos

In het vorige hoofdstuk heb je gezien dat templates Home Assistant veel flexibeler maken. Met templates kun je waarden vergelijken, berekeningen uitvoeren en beslissingen laten afhangen van informatie die op dat moment beschikbaar is.

Daarmee kun je bijzonder krachtige automatiseringen bouwen.

Maar er ontstaat ook een nieuw probleem.

Hoe uitgebreider een automatisering wordt, hoe minder aantrekkelijk het is om precies hetzelfde werk nog een keer te doen.

Stel dat je in De Werkplaats een goede automatisering hebt gemaakt voor verlichting op basis van beweging. Je hebt rekening gehouden met:

• een bewegingssensor;
• een lamp;
• een minimale lichtsterkte;
• een wachttijd;
• opnieuw gedetecteerde beweging;
• het uitschakelen van de lamp nadat de ruimte leeg blijft.

De automatisering werkt goed.

Vervolgens wil je ongeveer hetzelfde gedrag in de gang.

En daarna misschien in het toilet, de berging en de garage.

Je zou de automatisering kunnen kopiëren en iedere keer de sensoren, lampen en tijden kunnen aanpassen.

Dat werkt.

Maar zodra je later iets wilt verbeteren, ontdek je het nadeel.

Je hebt niet één automatisering om te onderhouden, maar vijf bijna gelijke exemplaren.

Home Assistant heeft daarvoor blueprints.

Een blueprint is in feite een herbruikbaar ontwerp voor een automatisering. De algemene werking staat al vast, terwijl je bij het gebruiken ervan zelf aangeeft welke apparaten, entiteiten en instellingen moeten worden gebruikt.

Home Assistant ondersteunt blueprints voor onder andere automatiseringen, scripts en template-entiteiten.

Dat klinkt misschien alsof je daarmee niet meer hoeft te begrijpen hoe automatiseringen werken.

Dat is juist niet de bedoeling van dit hoofdstuk.

Een blueprint is vooral handig wanneer je begrijpt wat hij voor je doet.

Een blueprint is geen automatisering

Het verschil tussen een gewone automatisering en een blueprint wordt duidelijker met een eenvoudig voorbeeld.

Stel dat je deze regel wilt maken:

Als beweging wordt gedetecteerd in De Werkplaats, zet dan de plafondlamp aan.

Een gewone automatisering bevat bijvoorbeeld rechtstreeks:

• de bewegingssensor van De Werkplaats;
• de plafondlamp van De Werkplaats;
• de voorwaarden;
• de acties.

De automatisering is daardoor specifiek gemaakt voor die ene situatie.

Een blueprint zou dezelfde logica algemener kunnen beschrijven:

Als de gekozen bewegingssensor beweging detecteert, zet dan de gekozen lamp aan.

De bewegingssensor en lamp staan dus niet vast.

Ze worden invoerwaarden, meestal inputs genoemd.

Wanneer je daarna een automatisering met die blueprint maakt, vul je bijvoorbeeld in:

Bewegingssensor:
Bewegingssensor Werkplaats

Lamp:
Plafondlamp Werkplaats

Gebruik je dezelfde blueprint daarna opnieuw, dan kun je invullen:

Bewegingssensor:
Bewegingssensor Gang

Lamp:
Ganglamp

De logica blijft gelijk.

Alleen de onderdelen waarmee die logica werkt veranderen.

Dat is precies waar blueprints sterk in zijn.

Zie een blueprint als een mal

Je kunt een blueprint vergelijken met een boormal.

Stel dat je in De Werkplaats meerdere kastdeuren moet maken waarop het handvat steeds op dezelfde plaats moet komen.

Je kunt iedere deur afzonderlijk meten.

Dat werkt, maar iedere meting kan iets verschillen.

Je kunt ook één mal maken.

Je legt de mal op iedere deur en boort vervolgens op dezelfde plaatsen.

De mal boort het gat niet voor je.

Hij beschrijft vooral waar het gat moet komen.

Een blueprint doet iets vergelijkbaars.

De blueprint bevat de algemene structuur.

Je eigen automatiseringen vullen de concrete onderdelen in.

Dat betekent ook dat je één blueprint meerdere keren kunt gebruiken. Iedere automatisering die je ermee maakt krijgt zijn eigen apparaten en instellingen.

Waarom blueprints aantrekkelijk zijn

Zeker wanneer je net met Home Assistant begint, kom je op internet al snel blueprints tegen.

Dat is niet vreemd.

Veel problemen in woningen lijken immers sterk op elkaar.

Bijvoorbeeld:

• lamp inschakelen bij beweging;
• lamp weer uitschakelen na een bepaalde tijd;
• melding geven wanneer een batterij bijna leeg is;
• verwarming regelen op basis van aanwezigheid;
• een melding sturen wanneer de wasmachine klaar is;
• verlichting afhankelijk maken van zonsondergang.

Voor dit soort toepassingen heeft iemand anders mogelijk al een nette oplossing gemaakt.

Je hoeft dan niet zelf alle triggers, voorwaarden, acties, wachttijden en templates te bedenken.

Home Assistant beschrijft blueprints daarom als kant-en-klare configuraties waarbij je zelf de onderdelen kiest die specifiek zijn voor jouw woning.

Dat kan veel tijd besparen.

Maar tijd besparen is iets anders dan blind kopiëren.

Het gevaar van de zwarte doos

Stel dat je op een forum een blueprint vindt met de titel:

Advanced Smart Motion Lighting 4.2

De beschrijving klinkt goed.

Hij ondersteunt:

• beweging;
• aanwezigheid;
• verschillende helderheidsniveaus;
• zonsondergang;
• luxwaarden;
• meerdere timers;
• handmatige bediening;
• nachtmodus;
• overgangstijden;
• scènes.

Dat lijkt aantrekkelijk.

Waarom zelf iets bouwen als iemand anders het probleem al heeft opgelost?

Je importeert de blueprint, kiest een aantal sensoren en lampen en activeert de automatisering.

De eerste avond werkt alles.

De tweede avond blijft de lamp ineens aan.

De derde dag gaat hij niet meer automatisch aan nadat je hem eerder handmatig hebt uitgeschakeld.

Dan ontstaat het echte probleem.

Je weet niet waarom.

Niet omdat Home Assistant onbetrouwbaar is, maar omdat je een automatisering gebruikt waarvan je de beslissingen niet begrijpt.

De blueprint is een zwarte doos geworden.

Er gaat informatie in.

Er komt gedrag uit.

Maar wat er tussenin gebeurt is onduidelijk.

Dat is precies wat je wilt voorkomen.

Begin niet met de blueprint

Wanneer je een interessante blueprint tegenkomt, is de eerste vraag daarom niet:

Waar kan ik op Importeren klikken?

Vraag eerst:

Welk probleem lost deze blueprint eigenlijk op?

Probeer de werking in gewone taal te beschrijven.

Bijvoorbeeld:

Wanneer er beweging is en het buiten donker genoeg is, moet de lamp aangaan. Zolang er opnieuw beweging wordt gezien, blijft hij aan. Wanneer er gedurende vijf minuten geen beweging meer is, gaat hij uit.

Dat is begrijpelijk.

Vervolgens kun je bekijken of de blueprint inderdaad ongeveer hetzelfde doet.

Als je de beschrijving niet kunt terugbrengen tot begrijpelijke regels, is dat een eerste waarschuwing.

Dat betekent niet automatisch dat de blueprint slecht is.

Misschien is hij simpelweg uitgebreider dan je op dit moment nodig hebt.

Meer mogelijkheden zijn niet automatisch beter

Dit is een belangrijk verschil met veel andere software.

Bij een gereedschap lijkt een langere lijst functies vaak aantrekkelijk.

Bij automatiseringen hebben extra mogelijkheden ook een prijs.

Iedere extra mogelijkheid kan zorgen voor:

• extra voorwaarden;
• extra toestanden;
• extra combinaties;
• extra instellingen;
• extra uitzonderingen;
• extra mogelijkheden waardoor gedrag anders wordt dan je verwacht.

Stel dat je alleen wilt:

Lamp aan bij beweging en na vijf minuten zonder beweging weer uit.

Dan heb je waarschijnlijk geen blueprint nodig met twintig verschillende instellingen voor scènes, kleuren, helderheid, nachtstanden en handmatige overrides.

Een kleine blueprint die precies doet wat je nodig hebt kan veel beter zijn.

En soms is een gewone automatisering nog eenvoudiger.

Wanneer een blueprint wél handig is

Blueprints zijn vooral interessant wanneer dezelfde logica meerdere keren terugkomt.

Neem opnieuw De Werkplaats.

Je hebt bijvoorbeeld vier ruimtes:

• Werkplaats;
• Gang;
• Berging;
• Garage.

In iedere ruimte zit:

• een bewegingssensor;
• een lamp.

Het gewenste gedrag is vrijwel gelijk:

• Beweging wordt gedetecteerd.
• Alleen wanneer het donker genoeg is gaat de lamp aan.
• Na een instelbare periode zonder beweging gaat de lamp weer uit.

Dan heb je een duidelijk herhalend patroon.

Een blueprint kan daarvan één algemene oplossing maken.

Bij iedere automatisering kies je vervolgens alleen:

• bewegingssensor;
• lamp;
• luxsensor;
• grenswaarde;
• uitschakeltijd.

Dat is een goed gebruik van een blueprint.

Wanneer je beter gewoon een automatisering maakt

Een blueprint is minder interessant wanneer een situatie uniek is.

Stel dat je automatisering voor De Werkplaats zegt:

Wanneer ik op werkdagen na 19:00 uur De Werkplaats binnenkom, er niemand thuis televisie kijkt, de buitentemperatuur lager is dan 12 °C, mijn werkplaatsmodus actief is en de ruimte kouder is dan 17 °C, schakel dan gedurende maximaal twintig minuten de verwarming in.

Je zou daar technisch een blueprint van kunnen maken.

Maar als deze regel maar op één plaats wordt gebruikt, levert dat waarschijnlijk weinig voordeel op.

Je voegt dan vooral een extra abstractielaag toe.

In plaats van één automatisering heb je ineens:

• een blueprint;
• inputs;
• een automatisering die de blueprint gebruikt.

Meer techniek betekent niet automatisch een betere oplossing.

Gebruik een blueprint dus vooral wanneer hergebruik werkelijk iets oplevert.

Blueprints vinden

Home Assistant heeft een eigen community waarin gebruikers blueprints delen. Blueprints kunnen bovendien worden geïmporteerd vanuit onder andere het Home Assistant-forum, GitHub en GitHub Gists.

Je kunt daardoor een enorme hoeveelheid voorbeelden vinden.

Maar dat betekent ook dat de kwaliteit verschilt.

Een blueprint kan gemaakt zijn door:

• een ervaren Home Assistant-gebruiker;
• iemand die net begonnen is;
• iemand die hem jarenlang onderhoudt;
• iemand die hem één keer heeft gepubliceerd en daarna nooit meer heeft aangepast.

Behandel een willekeurige blueprint daarom ongeveer zoals code die je van internet downloadt.

Niet automatisch als fout.

Maar ook niet automatisch als betrouwbaar.

Kijk naar de ingangen

Wanneer je een blueprint opent, kijk dan eerst naar de instellingen die je moet invullen.

Die vertellen vaak al veel over de manier waarop de blueprint denkt.

Stel dat je een blueprint voor bewegingsverlichting vindt.

Je ziet bijvoorbeeld deze invoervelden:

Bewegingssensor

Lamp

Wachttijd

Dat is eenvoudig te begrijpen.

De blueprint doet waarschijnlijk ongeveer dit:

Beweging → lamp aan → wachten totdat er geen beweging meer is → wachttijd → lamp uit.

Zie je daarnaast:

Luxsensor

Maximale luxwaarde

Dan kun je voorspellen dat lichtsterkte onderdeel van de beslissing wordt.

Zie je vervolgens:

Night mode

Night brightness

Transition time

Manual override

Scene before activation

Scene after activation

Dan weet je dat er aanzienlijk meer logica aanwezig is.

Dat hoeft geen probleem te zijn.

Maar je moet jezelf wel afvragen hoeveel daarvan je werkelijk nodig hebt.

Voorspel eerst het gedrag

Gebruik dezelfde werkwijze die je eerder in deze gids hebt gebruikt.

Voordat je een blueprint activeert, voorspel je wat er volgens jou gaat gebeuren.

Bijvoorbeeld:

Ik loop De Werkplaats binnen.

Wat verwacht je?

De bewegingssensor wordt actief.

Daarna?

Omdat de luxwaarde lager is dan 300 lux, wordt de plafondlamp ingeschakeld.

En als je vervolgens wegloopt?

Zodra de bewegingssensor weer inactief wordt, begint de ingestelde wachttijd van vijf minuten.

En als je binnen die vijf minuten terugloopt?

Dan verwacht ik dat de lamp aanblijft en de wachttijd opnieuw begint.

Dat laatste is belangrijk.

Je controleert niet alleen of het gewenste eindresultaat ontstaat.

Je denkt na over het proces.

Dat maakt fouten later veel gemakkelijker te begrijpen.

Importeer daarna pas

Wil je een blueprint gebruiken, dan kun je dit vanuit Home Assistant doen via:

Instellingen → Automatiseringen & scènes → Blueprints

Daar kun je bestaande blueprints bekijken en een nieuwe blueprint importeren.

Bij het importeren geef je de URL van de blueprint op. Home Assistant laat vervolgens eerst een voorbeeld zien voordat je hem daadwerkelijk importeert.

Na het importeren staat er nog geen complete automatisering klaar voor jouw woning.

Je gebruikt de blueprint vervolgens om een nieuwe automatisering te maken.

Daar kies je de benodigde apparaten, entiteiten en instellingen.

Maak één testautomatisering

Gebruik een nieuwe blueprint niet onmiddellijk door het hele huis.

Begin met één situatie.

Bijvoorbeeld alleen De Werkplaats.

Maak dus niet direct:

• Werkplaats verlichting;
• Gang verlichting;
• Garage verlichting;
• Berging verlichting;
• Toilet verlichting.

Maak eerst alleen:

Werkplaats verlichting — blueprint test

Gebruik die automatisering een tijdje bewust.

Loop de ruimte binnen.

Loop weer weg.

Kom tijdens de wachttijd terug.

Zet de lamp handmatig uit.

Zet hem handmatig aan.

Herstart eventueel Home Assistant.

Probeer bewust situaties te veroorzaken waarvan je wilt weten hoe de automatisering reageert.

Pas wanneer je begrijpt wat er gebeurt, is het zinvol dezelfde blueprint ergens anders te gebruiken.

Een blueprint blijft afhankelijk van zijn bron

Er is nog een belangrijk verschil tussen een gekopieerde automatisering en een blueprint.

Een automatisering die op een blueprint is gebaseerd blijft de configuratie uit die blueprint gebruiken. Als de blueprint verandert, kunnen de automatiseringen die ervan afhankelijk zijn daardoor eveneens ander gedrag krijgen nadat de automatiseringen opnieuw zijn geladen.

Dat is handig.

Een fout kan bijvoorbeeld één keer in de blueprint worden opgelost.

Maar hetzelfde mechanisme betekent ook dat een wijziging gevolgen kan hebben voor meerdere automatiseringen.

Home Assistant waarschuwt daarom ook bij het opnieuw importeren van een bijgewerkte community-blueprint: een niet-compatibele versie kan bestaande automatiseringen breken en aanpassing noodzakelijk maken.

Dat is geen reden om updates te vermijden.

Het is wel een reden om te weten waarvan je automatiseringen afhankelijk zijn.

Een update is een wijziging

Stel dat je één blueprint gebruikt voor vier ruimtes.

Alles werkt al maanden.

Dan verschijnt versie 3 van de blueprint.

In de omschrijving staat:

Improved motion handling.

Dat klinkt onschuldig.

Maar misschien is de interne manier waarop wachttijden worden verwerkt veranderd.

Je kunt dan beter niet denken:

Nieuwe versie, dus installeren.

Denk:

Er verandert iets in vier automatiseringen tegelijk.

Dat is dezelfde voorzichtigheid die je ook bij gewone automatiseringen wilt gebruiken.

Verander bij voorkeur één ding tegelijk.

Werk eerst één testautomatisering bij.

Controleer het gedrag.

Pas daarna kun je besluiten de wijziging breder te gebruiken.

Kijk zo nodig naar de YAML

Ook wanneer je automatiseringen vooral via de grafische interface maakt, kan het nuttig zijn om bij een blueprint een keer naar de YAML te kijken.

Je hoeft nog niet iedere regel te begrijpen.

Probeer vooral structuren te herkennen die je inmiddels kent.

Bijvoorbeeld:

trigger:

Je weet inmiddels:

Hier staat wat de automatisering start.

Of:

condition:

Dan weet je:

Hier wordt besloten of de automatisering verder mag.

En:

action:

Daar gebeurt het werkelijke werk.

Misschien kom je ook templates tegen die in eerste instantie ingewikkeld lijken.

Dat is niet erg.

Probeer dan niet meteen iedere letter te ontleden.

Zoek eerst de hoofdlijn.

Wat start deze automatisering?

Welke voorwaarden worden gecontroleerd?

Welke acties kunnen uiteindelijk worden uitgevoerd?

Als je die drie vragen kunt beantwoorden, is de blueprint al een stuk minder zwart.

Blueprints kunnen ook leerzaam zijn

Een goede blueprint is niet alleen een kant-en-klare oplossing.

Hij kan ook een voorbeeld zijn van hoe iemand anders een probleem heeft opgebouwd.

Je kunt bijvoorbeeld ontdekken:

• hoe meerdere triggers worden gecombineerd;
• hoe choose wordt gebruikt;
• hoe wachttijden worden afgehandeld;
• hoe templates beslissingen nemen;
• hoe instellingen als inputs worden aangeboden;
• hoe dezelfde automatisering geschikt wordt gemaakt voor verschillende apparaten.

Daarmee kan een blueprint een interessante volgende stap zijn nadat je zelf de basis begrijpt.

Niet:

Ik hoef dit niet meer te leren omdat de blueprint het doet.

Maar:

Nu ik de basis begrijp, kan ik kijken hoe iemand anders hetzelfde probleem heeft opgelost.

Dat verschil is belangrijk.

Zelf een blueprint maken

Je hoeft blueprints bovendien niet alleen van anderen te gebruiken.

Je kunt ook je eigen automatisering omzetten naar een herbruikbare blueprint.

Een blueprint bestaat uit algemene configuratie en metadata waarin onder andere wordt beschreven welke invoerwaarden beschikbaar zijn. Home Assistant gebruikt die invoer vervolgens om de configuratie geschikt te maken voor jouw specifieke apparaten en instellingen.

Voor deze beginnersgids gaan we niet uitgebreid een complete blueprint in YAML programmeren.

Maar het is nuttig om te begrijpen wanneer je daar later misschien behoefte aan krijgt.

Stel dat je de automatisering voor bewegingsverlichting inmiddels in zes ruimtes gebruikt.

Je merkt dat je overal vrijwel dezelfde wijzigingen uitvoert.

Dat is het moment waarop je kunt denken:

Eigenlijk heb ik hier één algemene oplossing voor.

Dat is een veel betere aanleiding om een blueprint te maken dan:

Blueprints bestaan, dus ik moet ze gebruiken.

Eerst begrijpen, daarna abstraheren

In softwareontwikkeling bestaat een nuttig principe:

Maak iets eerst werkend en begrijpelijk. Maak het daarna pas algemeen.

Dat principe past ook uitstekend bij Home Assistant.

Bouw bijvoorbeeld eerst één goede automatisering voor De Werkplaats.

Test hem.

Bekijk de traces.

Pas de voorwaarden aan.

Ontdek wat er gebeurt wanneer opnieuw beweging wordt gedetecteerd.

Controleer wat er gebeurt wanneer Home Assistant opnieuw start.

Pas wanneer die automatisering betrouwbaar werkt, kun je bekijken of dezelfde oplossing ergens anders nodig is.

Dan weet je namelijk wat je probeert te hergebruiken.

Een praktische beslisregel

Wanneer je twijfelt of je een blueprint moet gebruiken, stel jezelf dan drie vragen.

Gebruik ik dezelfde logica meerdere keren?

Nee?

Dan is een gewone automatisering waarschijnlijk eenvoudiger.

Begrijp ik wat de blueprint doet?

Nee?

Gebruik hem dan nog niet voor iets belangrijks.

Kan ik het gedrag controleren?

Nee?

Dan weet je bij problemen ook niet waar je moet zoeken.

Als het antwoord op alle drie de vragen ja is, kan een blueprint bijzonder nuttig zijn.

En hoe zit het met betrouwbaarheid?

Blueprints veranderen niets aan een basisregel die door deze hele gids loopt:

Een automatisering is pas nuttig wanneer je erop kunt vertrouwen.

Dat geldt misschien zelfs sterker voor een blueprint.

Iemand anders kan een prachtige oplossing hebben gemaakt.

Maar die persoon woont niet in jouw huis.

Hij gebruikt misschien andere:

• sensoren;
• lampen;
• netwerken;
• integraties;
• wachttijden;
• gewoontes.

Een automatisering die bij iemand anders uitstekend werkt, moet je daarom nog steeds in jouw situatie testen.

Dat gaan we in het volgende hoofdstuk veel systematischer doen.

Wat je nu moet onthouden

Een blueprint is een herbruikbaar ontwerp voor een automatisering, script of template-entiteit. Je vult zelf de apparaten, entiteiten en instellingen in die bij jouw situatie horen.

Het grote voordeel is hergebruik.

Je kunt één goede algemene oplossing gebruiken voor meerdere vergelijkbare situaties.

Maar het grote gevaar is dat je automatiseringen importeert die je niet begrijpt.

Gebruik een blueprint daarom niet omdat hij indrukwekkend veel mogelijkheden heeft.

Gebruik hem omdat je begrijpt welk probleem hij oplost.

De beste volgorde blijft:

Begrijpen → voorspellen → instellen → testen → controleren → pas daarna vertrouwen.

En dat brengt ons bij iets wat eigenlijk voor iedere automatisering geldt, of je hem nu zelf hebt gemaakt of vanuit een blueprint hebt opgebouwd.

In het volgende hoofdstuk gaan we daarom kijken naar:

Automatiseringen testen voordat je erop vertrouwt

Daarbij gaan we niet alleen controleren of een lamp inderdaad aangaat.

We gaan bewust situaties veroorzaken waarin een automatisering misschien verkeerd zou kunnen reageren.

Want een automatisering die één keer werkt, is nog geen betrouwbare automatisering.