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 drie soorten expressies gebruikt:

expressies voor DERIVED kanalen
expressies voor webhooks en notificaties
expressies voor HTTP meters

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.

Het derde type expressie wordt gebruikt in de registers van een HTTP meter. Deze expressie haalt waardes uit het antwoord van een databron van de HTTP Client module. Zie HTTP meters voor meer informatie.

Algemeen

Onderstaande constanten, functies en operatoren kunnen worden gebruikt in alle 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.

In de expressie van een DERIVED kanaal is een extra variabele beschikbaar: delta_t. Deze bevat de tijd in seconden van de periode waarover de berekening wordt uitgevoerd. Hierbij wordt geen rekening gehouden met verschillende lengtes van dagen, maanden en jaren. delta_t is alleen geschikt om bij benadering iets uit te rekenen. Een dag is altijd 86400s en voor een maand wordt gerekend met 30.437 dagen en voor een jaar met 365.25 dagen.

delta_t kan bijvoorbeeld worden gebruikt om een energie (kWh) om te rekenen naar een vermogen (W). De formule ((ch1 * 3600) / delta_t) * 1000 rekent kWh om naar W, waarbij ch1 het kanaal van energie is.

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/5minutes: afgelopen 5 minutenblok (indien ingeschakeld)
last/10minutes: afgelopen 10 minutenblok (indien ingeschakeld)
last/15minutes: afgelopen 15 minutenblok
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.

HTTP meters

In de registers van een HTTP meter wordt een expressie gebruikt om een waarde uit het antwoord van een databron te halen. Het antwoord is beschikbaar onder de variabele die je bij de databron hebt ingesteld. Zie HTTP Client voor meer informatie over het instellen van een databron en een HTTP meter.

Naast de variabelen en functies in Algemeen, zijn de volgende functies beschikbaar:

functie	beschrijving
`jsonpath(var, expr)`	Geeft de waarde uit het JSON-antwoord in variabele `var` die overeenkomt met de JSONPath expressie `expr`
`jsonpath_list(var, expr)`	Werkt hetzelfde als `jsonpath`, maar geeft alle gevonden waardes terug in een lijst

De JSONPath expressie begint altijd met $, dit is de basis van het antwoord. Met een punt . ga je een niveau dieper, met [0] selecteer je het eerste item uit een lijst en met [*] alle items. Met een filter zoals [?(@.sn == '123')] selecteer je alleen de items die aan een voorwaarde voldoen.

Voorbeeld: Een waarde uitlezen

jsonpath(hw_water, "$.total_liter_m3")

Voorbeeld: Een waarde uit een lijst selecteren op basis van een serienummer

jsonpath(solis1, "$.data.page.records[?(@.sn == '94324B0216340532')].etotal1")

Voorbeeld: Alle waardes uit een lijst ophalen

jsonpath_list(solis1, "$.data.page.records[*].etotal1")

Dit geeft de waarde etotal1 van alle omvormers in het antwoord terug als lijst.

Voorbeeld: De waardes van alle omvormers optellen

sum(jsonpath_list(solis1, "$.data.page.records[*].etotal1"))

De functie sum telt alle waardes in de lijst bij elkaar op. NULL waardes worden hierbij genegeerd.