Expressies

Expressies zijn kleine stukjes code die worden gebruikt om bepaalde berekeningen uit te voeren. Ze zijn vergelijkbaar met formules in Excel. Deze expressies kan je op een aantal plekken in de CEMM gebruiken, zoals bij het berekenen van tijdreeksen, notificaties en webhooks.

Dit klinkt misschien ingewikkeld, maar een expressie kan ook heel simpel zijn, bijvoorbeeld ch1 + ch2. Hiermee tel je de waardes van twee kanalen bij elkaar op.

In de CEMM worden twee soorten expressies gebruikt:

expressies voor DERIVED kanalen
expressies voor webhooks en notificaties

De DERIVED expressie wordt gebruikt door kanalen met aggregatie methode DERIVED om van één of meer kanalen een nieuwe waarde te berekenen. De expressie wordt onder andere gebruikt om tijdreeksen te berekenen. Zie Berekende kanalen voor meer informatie.

Het tweede type expressie wordt gebruikt voor webhooks en notificaties. Deze expressie werkt met actuele gegevens van andere kanalen. Deze gegevens noemen we "topics". Deze topics worden iedere minuut bijgewerkt nadat de CEMM de gegevens van die minuut heeft verwerkt. De expressie kan deze topics gebruiken om een waarde te berekenen. Naast de variabelen en functies in Algemeen, zijn er een aantal extra variabelen en functies beschikbaar. Zie Webhooks en notificaties voor meer informatie.

Algemeen

Onderstaande constanten, functies en operatoren kunnen worden gebruikt in beide soorten expressies.

constante	beschrijving
`true`, `True`	Waar
`false`, `False`	Onwaar
`null`, `None`	Lege waarde

functie	beschrijving	bij NULL waarde
`sum(x, ...)`	Optellen van meerdere waardes	wordt genegeerd
`filternull(x, ...)`	Filtert alle NULL waardes uit de lijst	-
`coalesce(x, ...)`	Geeft de eerste niet-NULL waarde terug	-
`min(x, ...)` en `max(x, ...)`	Geeft de minimale of maximale waarde terug	foutmelding
`min(filternull(x, ...))` en `max(filternull(x, ...))`	Geef de minimale of maximale waarde terug	wordt genegeerd
`avg(x, ...)`	Gemiddelde van de waardes	wordt genegeerd
`count(x, ...)`	Telt het aantal niet-NULL waardes	wordt genegeerd
`abs(x)`	Absolute waarde van x	wordt genegeerd
`round(x[, n])`	Afronden van x op n decimalen, n is optioneel en standaard 0	wordt genegeerd

Operatoren: +, -, *, /, ** (macht) en % (modulo)
Boolean operatoren: ==, !=, >, <, >=, <=, and, or, not
een "shorthand-if" statement is ook mogelijk, bijvoorbeeld: 0 if x < 20 else x
gebruik een punt . als decimaalteken, bijvoorbeeld 3.14
haakjes () kunnen worden gebruikt om de volgorde van de berekening te bepalen, bijvoorbeeld 3 * (2 + 4)

`DERIVED` expressie

Een derived expressie werkt altijd voor dezelfde kanalen. De expressie wordt voor ieder datapunt in een tijdreeks uitgevoerd. In de expressie kan je gebruik maken van de variabelen zoals ch1, ch2, etc. Bij het instellen van de expressie moet je kiezen welke kanalen je wilt gebruiken. Zie Berekende kanalen voor meer informatie.

Webhooks en notificaties

Bij webhooks kan de expressie worden gebruikt om te bepalen of de webhook moet worden uitgevoerd. De uitkomst van de expressie moet in dat geval waar of onwaar zijn. Bij notificaties triggers van het type expression worden twee expressies gebruikt. De eerste bepaalt of de notificatie moet worden aangemaakt, de tweede bepaalt de inhoud van het bericht.

Naast de variabelen en functies in Algemeen, zijn er een aantal extra variabelen en functies beschikbaar. Deze worden hieronder beschreven, daarna volgen een aantal voorbeelden van expressies.

variabele	beschrijving
`time`	Unix timestamp van het moment waarop de gegevens voor het laatst zijn bijgewerkt
`datetime`	Een Python datetime object van het moment waarop de gegevens voor het laatst zijn bijgewerkt
`ch1`, `ch2`, ...	Ieder kanaal is als object beschikbaar in de variable `ch` + het ID van het kanaal, bijvoorbeeld `ch7`. Het object heeft onder andere de properties `label` en `unit`

Ga naar 'Instellingen' > 'Meters' en kies bij de gewenste meter voor 'Geavanceerde instellingen'. In de tabel met kanalen vind je de ID's van de kanalen.

functie	beschrijving
`latest(ch, topic)`	Geeft de laatst bekende waarde voor het opgegeven kanaal en topic
`updated(ch, topic)`	Geeft de unix timestamp van de laatst bekende waarde voor het opgegeven kanaal en topic
`node(id)` of `node(key)`	Geeft het node object op basis van het ID of key
`channel(id)` of `channel(full_id)`	Geeft het kanaal object op basis van het ID of full ID
`format(x, unit)`	Formateert de waarde x met de opgegeven eenheid volgens de ingestelde taal. `format(26.3584, 'kWh')` -> `26,36 kWh`

In bovenstaande functies wordt verwezen naar topics. De volgende topics worden ondersteund:

realtime: meest actuele waarde
reading: laatst bekende meterstand
this/day: vandaag
this/month: deze maand
this/year: dit jaar
last/minute: afgelopen minuut
last/15minutes: afgelopen 15 minuten
last/day: gisteren
last/month: vorige maand
last/year: vorig jaar

Let op: niet alle topics zijn beschikbaar voor ieder kanaal, bekijk dit overzicht voor de beschikbaarheid.

Voorbeeld: Aan het eind van de dag een notificatie sturen met een samenvatting van het verbruik en productie

Trigger: datetime.hour == 22 and datetime.minute == 0

Bericht: Vandaag is er {{format(latest(ch1, 'this/day') + latest(ch2, 'this/day'), 'kWh')}} verbruikt en {{format(latest(ch8, 'this/day'), 'kWh')}} opgewekt.

In dit voorbeeld zijn ch1 en ch2 de kanalen electric_energy_import_t1 en electric_energy_import_t2 van de slimme meter. ch8 is het kanaal electric_energy van de zon meter.

Voorbeeld: Een webhook alleen 's nachts actief maken

datetime.hour < 6 or datetime.hour > 22

Voorbeeld: Een webhook alleen actief maken als de zon schijnt

latest(ch1, 'realtime') > 0

ch1 is het kanaal electric_power van een zon meter.