Eventing Eventing...1 Introductie...1 Regel verwerking...1 Basis structuur...1 Waar of Onwaar...2 AND en OR...2 Haakjes...3 Operatoren...3 Apparaten...3 Functies...4 Acties...4 Parameters van apparaten gebruiken...5 Optimalisaties...5 Introductie De pilight eventing functionaliteit maakt het mogelijk om je huis te automatiseren door het schrijven van event regels. De regels vertellen pilight wat er moet gebeuren op een bepaalde tijd of bij een bepaalde gebeurtenis. pilight event regels volgen de standaard mathematische conventies en omdat je gebruik kunt maken van een oneindige hoeveelheid haakjes, kunnen deze regels erg geavanceerd worden, maar zijn ze tevens ook erg flexibel. Zoals met alles binnen pilight, is de eventing functionaliteit volledig modulair. Dit betekent dat de operatoren, acties en functies allemaal makkelijk uit te breiden externe modules zijn. Ontwikkelaars en gebruikers hoeven niet aan de basis van de eventing functionaliteit te komen om aanvullende functionaliteit toe te voegen. Regel verwerking Er zijn een aantal dingen die goed zijn om te weten zodra je aan de slag gaat met pilight event regels. Als je beter begrijpt hoe pilight de regels verwerkt, dan wordt het ook makkelijker om efficiëntere en meer geavanceerde regels te schrijven. Basis structuur In de basis volgens de regels allemaal dezelfde structuur: 1 IF... THEN... Een regel start altijd met een IF, gevolgd door de logica van de regel en wordt afgesloten door een THEN. Alle acties worden achter de THEN geplaatst.
Waar of Onwaar Laten we beginnen met hoe pilight omgaat met slagende of falende condities. pilight zet alle mathematische en logische stappen om in true (waar) of false (onwaar). Als de uiteindelijk uitkomst van een regel waar is dan zal de actie worden uitgevoerd. Als de uiteindelijke uitkomst van een regel onwaar is dan zal actie overgeslagen worden. Deze twee voorbeelden zullen beide slagen: 1 IF (1 == 1) == True THEN... [SLAAGT] 2 IF (1 == 1)!= False THEN... [SLAAGT] Deze twee voorbeelden zullen beide falen: 1 IF (1 == 0) IS True THEN... [FAALT] 2 IF (1!= 1) IS False THEN... [FAALT] AND en OR In het eerste voorbeeld zagen we dat er gebruik werd gemaakt van enkele condition. Enkele condities geven ons echter niet de mogelijkheid om geavanceerde en flexibele regels te schrijven. Daarvoor moeten we verschillende condities kunnen combineren in een enkele regel. Dit is mogelijk door gebruik te maken van AND (en) en OR (of) operatoren. Laten we eerst een paar simpele voorbeelden bekijken: 1 IF 1 == 1 AND 1 == 2 THEN... [FAALT] 2 IF 1 == 1 OR 1 == 2 THEN... [SLAAGT] 3 IF 1 == 2 OR 1 == 1 AND 2 == 3 THEN... [FAALT] 4 IF 1 == 1 OR 1 == 1 AND 2 == 3 THEN... [SLAAGT] 5 IF 1 == 2 AND 1 == 1 OR 2 == 3 THEN... [FAALT] 6 IF 1 == 1 AND 2 == 2 OR 2 == 3 THEN... [SLAAGT] In de eerste twee voorbeelden zien we dat er een enkele AND en een enkele OR is gebruikt. In de overige voorbeelden zien we meerdere ANDs en ORs. Het is goed om te weten dat pilight deze regel van links naar rechts evalueert en daarbij niet meer doet dan nodig. In de voorbeelden worden de groene gedeeltes daadwerkelijk geëvalueerd, de rode gedeeltes worden overgeslagen. In de eerste regel zien we een enkele AND operator. Dit betekent dat beide condities moeten slagen om de gehele regel te laten slagen. pilight moet dus beide condities evalueren. In de tweede regel zien we een enkele OR operator. Dit betekent dat een van beide condities moet slagen om de hele regel te laten slagen. Aangezien de eerste condities slaagd hoeft pilight niet ook de tweede condities te evalueren en dus wordt deze overslagen. De actie zou ik dit geval gelijk na het evalueren van het eerste gedeelte uitgevoerd worden. Hetzelfde is te zien in regel vier. Deze regel start met een OR operator waarvan de eerste conditie slaagt. De daaropvolgende AND operator wordt daarom niet meer geëvalueerd. In regel vijf zien we dat de eerste conditie faalt. Aangezien deze eerste conditie onderdeel uitmaakte van een AND operator hoeven we de tweede conditie niet meer te evalueren. Deze kan de uitkomst van de AND operator toch niet meer veranderen. pilight zal wel de laatste conditie evalueren, omdat deze nog wel invloed kan hebben op de uitkomst van regel vijf. Hetzelfde zien we gebeuren in regel zes. Aangezien de eerste twee condities (als onderdeel van de AND) slagen hoeven we de laatste conditie niet meer te evalueren.
Haakjes Zoals we in het eerste voorbeeld zagen kan er in pilight regels gebruik gemaakt worden van haakjes. Dit kan handig zijn voor het beter structureren van je regel en voor het combineren van verschillende condities. Laten we kijken naar een wat geavanceerdere regel en hoe haakjes de uitkomst van deze regel kan veranderen zonder iets aan de condities te doen. 1 IF 1 == 2 OR 2 == 3 AND 2 == 3 OR 1 == 1 THEN... [SLAAGT] 2 IF (1 == 2 OR 2 == 3) AND (2 == 3 OR 1 == 1) THEN... [FAALT] Ondanks dat alle condities in deze regels hetzelfde zijn gebleven is de uiteindelijke uitkomst door het gebruik van haakjes toch verschillend. Dit komt omdat we expliciet tegen pilight hebben gezegd dat we de eerste twee OR condities willen evalueren als onderdeel van de uiteindelijke AND. In de eerste regel hadden we gewoon een enkele OR, een enkele AND en een enkele OR. pilight geeft je de mogelijkheid om oneindig veel haakjes te gebruiken: 1 IF ((1 == 2 OR 2 == 3) AND 2 == 3) OR 1 == 1 THEN... [SLAAGT] Operatoren Verschillende mathematische operatoren kunnen gebruikt worden om berekeningen in onze regels op te nemen. A lijst van deze operatoren kan gevonden worden verderop in deze handleiding. Hier laten we een aantal voor de hand liggende voorbeelden zien: 1 IF 1 + 1 == 2 THEN... [SLAAGT] 2 IF 2 % 2 == 0 THEN... [SLAAGT] 3 IF 1 < 10 THEN... [SLAAGT] 4 IF 10 / 2 == 4 THEN... [FAALT] Apparaten pilight zijn vrij nutteloos wanneer we niet met echte data werken. Dit data kan aangeleverd worden door de apparaten in en rond ons huis. Stel nu dat we een schakelaar hebben geconfigureerd genaamd switch en we aan de hand van deze schakelaar een regel willen maken: 1 IF switch.state IS on THEN... Afhankelijk van de daadwerkelijke status van de schakelaar zal deze regel slagen of falen. Laten we hetzelfde eens doen met een geconfigureerde dimmer genaamd dimmer: 1 IF dimmer.dimlevel > 10 THEN... Opnieuw, deze regel zal falen of slagen afhankelijk van het daadwerkelijke dim niveau van de dimmer. Beide voorbeelden kunnen natuurlijk ook gecombineerd worden: 1 IF switch.state IS on AND dimmer.dimlevel > 10 THEN... Zoals je ziet kunnen is het afhankelijk van het apparaat welke velden (state of dimlevel) we kunnen gebruiken. Een schakelaar heeft geen dimlevel veld, maar een dimmer heeft wel een state veld.
Functies In sommige gevallen voldoende standaard operatoren niet voor wat we in onze regel willen bereiken. Het rekenen met tijd is bijvoorbeeld een moeilijke opgave aangezien er maar 24 uren zijn en 60 minuten en seconden. Ook zijn er geen negatieve nummers. Ook is er niet mogelijke om een willekeurig nummer te genereren met de standaard operatoren. Deze meer geavanceerde functionaliteit is toegevoegd in de vorm van functies. Een simpel voorbeeld: 1 IF datetime.hour == RANDOM(21, 23) THEN... Zoals je kunt zien gebruiken we in dit voorbeeld de RANDOM functie om te kijken of het uur ofwel 21, ofwel 22, ofwel 23 is. Dit maakt het mogelijk om acties uit te voeren of willekeurige momenten van de dag. Acties Acties zijn het doel van onze regels. Deze vertellen pilight wat er moet gebeuren wanneer er aan een bepaalde conditie is voldaan. A regel kan een oneindig aantal acties bevatten en elke actie kan oneindig veel apparaten bedienen. Twee voorbeelden met een schakelaar genaamd lamp en een dimmer genaamd ambientlight: 1 IF... THEN switch DEVICE lamp TO on 2 IF... THEN dim DEVICE ambientlight TO 10 Beide acties bedienen maar een enkel apparaat. We kunnen beide acties echter ook samenvoegen tot een enkele actie: 1 IF... THEN switch DEVICE lamp AND ambientlight TO on Zoals je kunt zien moet er in de switch actie tenminste een DEVICE en een TO parameter worden gebruikt. In het geval van een switch actie, kunnen verschillende apparaten gecombineerd worden door gebruik te maken van ANDs. We kunnen echter ook verschillende soorten acties combineren. Stel nu dat we de schakelaar lamp willen aanzetten en de dimmer ambientlight naar dim niveau 10 willen zetten in een regel. 1 IF... THEN switch DEVICE lamp TO on AND dim DEVICE ambientlight TO 10 Op deze manier kunnen acties in de oneindigheid gecombineerd worden. Opnieuw zien we dat de AND wordt gebruikt om verschillende acties te combineren. We kunnen verschillende apparaten in verschillende acties onderbrengen in een enkele regel. Stel nu dat we ook een relais willen schakelen verbonden met onze televisie genaamd televison: 1 IF... THEN switch DEVICE lamp AND television TO on AND dim DEVICE ambientlight TO 10
Parameters van apparaten gebruiken De parameters die bij de geconfigureerde apparaten horen kunnen vrijwel overal in de event regels gebruikt worden. Laten we aan de hand van een aantal voorbeelden bekijken hoe dit werkt: 2 IF 1 == 1 THEN dim DEVICE dimmer TO dimmermax.dimlevel FOR dimmerduration.dimlevel In dit voorbeeld gebruiken we drie dimmers. Een dimmer genaamd dimmer die we uiteindelijk willen dimmen en twee dimmers die pilight vertellen hoe deze actie uitgevoerd dient te worden. De dimmermax vertelt pilight welk dim niveau de dimmer zou moeten aannemen. De dimmermax vertelt pilight hoe lang het moet doen voordat hij dit dim niveau bereikt. Een tweede voorbeeld: 1 IF 1 == 1 THEN switch DEVICE lamp1 TO lamp2.state In dit voorbeeld schakelen lamp1 naar dezelfde stand als lamp2. Deze parameters kunnen ook in functies gebruikt worden: 1 IF RANDOM(randomLow.dimlevel, randomhigh.dimlevel) == 10 THEN switch DEVICE lamp1 TO on In dit voorbeeld gebruiken we twee dimmers genaamd randomlow en randonhigh om dynamisch de mogelijke waarde van de RANDOM functie te veranderen. Een uitgebreidere en geavanceerd voorbeeld: 1 IF sunriseset.sunset == DATE_FORMAT(DATE_ADD(datetime, +1 HOUR), \"%Y-%m-%d %H: %M:%S\", %H.%M) THEN switch DEVICE lamp1 TO on In dit geval gebruiken we een datetime apparaat genaamd datetime als invoer voor de DATE_ADD functie en de uitkomst van de DATE_ADD functie wordt weer gebruikt als de invoer voor de DATE_FORMAT functie. Deze voorbeelden geven een idee van hoe we de parameters van onze apparaten kunnen gebruiken in onze event regels. Optimalisaties Ondanks dat pilight regels ontzettend snel evalueert, kunnen er simpele stappen genomen worden om de prestaties verder te verbeteren. Een regel is niks meer dan meerdere condities die onafhankelijk geëvalueerd dienen te worden. Laten we eens kijken hoe we tijd gebaseerde events verder kunnen optimaliseren: 1 IF datetime.hour == 23 AND datetime.minute == 0 AND datetime.second == 0 THEN... Om deze regel te optimaliseren moeten we nagaan hoe vaak verschillende condities worden geëvalueerd. Regels met datum/tijd waardes worden elke seconde geëvalueerd. Dus elke gedeelte heeft een bepaalde aantal keren waarop hij waar kan zijn per dag wanneer we uitgaan van evaluaties elke seconde. Hour is 23 3600 keer per dag (60 minuten * 60 seconden). Minute is 0 1440 keer per dag (24 uren * 60 seconde). Second is 0 1440 keer per dag (24 uren * 60 minuten). In de bovenstaande regel is de eerste conditie waar 3600 keren, de tweede conditie één keer en de laatste conditie ook één keer. Laten we kijken wat er gebeurd als we de regel aanpassen. 1 IF datetime.second == 0 AND datetime.minute == 0 AND datetime.hour == 23 THEN... Nu zal de eerste stap 1440 keren waar zijn, de tweede stap één keer en de laatste stap ook één keer. Waar de eerste regel 3602 keer volledig werd geëvalueerd is dat bij de tweede regel nog maar 1442 keer. Door het veranderen van de volgordes van onze condities, kunnen we de prestaties van een enkele regel
vergroten. Laten we een tweede voorbeeld bekijken. Nu willen we een actie uitvoeren gebaseerd op de zonsondergang. In dit geval is de zonsondergang om 19:00 en we willen de kerstboom om 0:00 weer uitzetten. 1 IF ((sunriseset.sunset == (datetime.hour + (datetime.minute / 100)) AND christmasstree.state IS off) AND datetime.second == 0) THEN switch DEVICE christmasstree TO on Opnieuw kijken we hoe vaak een bepaalde regel waar is, gebaseerd op een evaluatie per seconde. Sunset is 19:00 60 keer per dag (60 seconde). Hour is 19 3600 keer per dag (60 minuten * 60 seconden). Minute is 0 1440 keer per dag (24 uren * 60 seconden). Second is 0 1440 keer per dag (24 uren * 60 minuten). State is off voor 68400 keren per dag (19 uren * 60 minuten * 60 seconden). Dus in de bovenstaande regel zal de eerste stap 60 keer per dag waar zijn, de tweede stap ook 60 keer en de laatste stap maar één keer. Ondanks dat deze regel maar weinig evaluaties kent gebruiken we toch een aantal mathematische evaluaties in het eerste gedeelte. Laten we kijken wat er gebeurd als we de regel veranderen: 1 IF ((datetime.second == 0 AND sunriseset.sunset == (datetime.hour + (datetime.minute / 100))) AND christmasstree.state IS off) THEN switch DEVICE christmasstree TO on In dit geval zal de eerste conditie waar zijn 1440 keren, de tweede conditie 60 keren en de laatste maar één keer. Dus bij het verplaatsen van de condities wordt de prestatie van deze regel slechter. De eerste versie had maar 121 evaluaties nodig en de tweede regel 1501. Ondanks dat de eerste regel verschillende mathematische logica bevatte is hij wel 14 keer zo efficiënt. Als je je pilight regels dus verder wilt optimalizeren is het goed als je kijken naar de volgorde van je condities. Deze volgorde veranderen kan het evalueren van de regels sneller maken.