NEWS
"Blockly for dummies" ... Starthilfe und Tipps
-
Bitte hier nicht antworten
Dieser Thread soll den blutigen Anfängern in Sachen Blockly ein wenig Starthilfe bieten und helfen, die ersten Hürden zu meistern und die häufigsten Fallstricke zu vermeiden.
Fragen/Anmerkungen/Änderungen/Ergänzugen bitte ausschließlich hier!Dokumentation
Du bist neu bei Blockly?
Dann mach Dir die Mühe und schau Dir die Doku an, bevor Du im Forum einen neuen Beitrag eröffnest.
Die Erfahrung zeigt, dass immer wieder die gleichen "Probleme" behandelt werden.
https://www.iobroker.net/#de/documentation/logic/blockly.mdScript starten/stoppen/pausieren
Ein Blockly-Script wird in ioBroker (genau wie ein reines JavaScript) grundsätzlich zunächst erstellt und dann auch gestartet. Danach läuft es dauerhaft und wird (außer in sehr seltenen Ausnahmefällen) nicht gestoppt oder neu gestartet.
ACHTUNG: Scripte - egal welcher Art - gehören nur in sehr seltenen Ausnahmefällen in den Ordner "global". Du solltest Dir eine sinnvolle Ordnerstruktur - im Normalfall unterhalb von "common" - ausdenken.Namensgebung:
Die Namen von Scripten sollten keine Leer- oder gar Sonderzeichen enthalten. Das gilt insbesondere für Umlaute.
Statt einem Leerzeichen solltest Du einen Binde- oder Unterstrich verwenden.
Diese Regel gilt grundsätzlich auch für Datenpunkte und Variablen!
Wobei man bei Variablen auch auf den Bindestrich verzichten sollte. Der wird zwar intern in einen Unterstrich gewandelt, aber wenn man später mal in JS programmiert, erzeugt man sich schnell eine Subtraktion.Trigger und Zeitpläne
Alles was auf Ereignisse reagieren bzw. zu bestimmten Zeiten oder zyklisch ablaufen soll, benötigt einen "Trigger" oder "Zeitplan".
ACHTUNG: Was außerhalb dieser Blöcke platziert wird, wird genau 1x - beim Start des Script - ausgeführt.
Mehr dazu hierWerte auslesen
Werte aus Datenpunkten werden (in den meisten Fällen) mit diesem Baustein gelesen:
ACHTUNG:
Wenn der Wert desjenigen DP benötigt wird, der mit dem Trigger überwacht wird, muss der Wert nicht mit dem "Wert von" Baustein gelesen werden.
Stattdessen verwendest Du diesen Baustein:
und änderst ihn anschließend von "Objekt ID" auf "Wert".
(Ab Version 7.5 des JS-Adapters ist "Wert" hier bereits die Vorgabe).
Wenn der Trigger ausgelöst wurde, sind (so ziemlich) alle Eigenschaften des betroffenen DP bereits bekannt.
Hier nochmal zu lesen ist unnötig und kann zu Fehlern führen.ACHTUNG:
Das hier ist etwas völlig anderes und liefert das komplette Objekt - also den ganzen DP und nicht nur seinen Wert:
Mehr dazu hier
Werte schreiben (Datenpunkte ändern)
Grundsätzlich gibt es zwei unterschiedliche Wege, einen Wert in einen DP zu schreiben.
Steuere
Dieser Baustein wird für alle DP verwendet, die einem Adapter "gehören". Das gilt auch für Alias-Datenpunkte, die auf einen Adapter-DP zeigen.
Aktualisiere
Verwende diesen Baustein nur für eigene DP, die Du unterhalb von0_userdata.0
selbst angelegt hast.Mehr dazu hier
Variablen
Variablen dienen dazu, ermittelte oder berechnete Werte für die weitere Verarbeitung vorzuhalten.
Variablen werden manuell erstellt und sind im gesamten Script gültig.
Variablen sollten überall dort eingesetzt werden, wo ansonsten der Wert aus einem DP mehrfach ausgelesen werden müsste.
Auch die Les- und Wartbarkeit eines Scriptes lässt sich durch die Verwendung von Variablen deutlich verbessern.
Insbesondere komplexe Prüfungen werden durch Variablen deutlich besser lesbar und damit verständlicher.Mehr dazu hier
... to be continued
-
Falls / mache / sonst
Um Entscheidungen anhand von Werten zu treffen und zumindest ein Minimum an Logik in ein Script einzubauen, müssen Werte überprüft werden.
Diese Prüfungen können selbstverständlich miteinander kombiniert werden.
Dies sind nur rudimentäre einfach Beispiele.
Mehr dazu siehe hierVerzögerungen (Timeouts)
Es kommt verhältnismäßig häufig vor, dass bestimmte Aktionen erst nach einer gewissen Zeit ausgeführt werden sollen.
Es soll z.B. eine Meldung erfolgen, wenn ein bestimmter Wert mindestens eine gewisse Zeit vorliegt. Oder eine Lampe soll ausgeschaltet werden, wenn ein Bewegungsmelder eine gewisse Zeit X keine Bewegung mehr erkannt hat.
Dazu bedient man sich eines "timeout".
In den allermeisten Fällen muss auch dafür Sorge getragen werden, dass ein laufender timeout abgebrochen wird, wenn die Bedingung nicht mehr zutrifft.Mehr dazu hier
Schleifen
Will man aus eine Menge von Einzelwerten - z.B. eine Liste von Statuswerten, jeden Einzelwert verarbeiten, verwendet man Schleifen.
Diese Liste kann man (wie hier) natürlich selbst erzeugen. Wesenlich häufiger enthalten aber Datenpunkte solche Listen als Wert. Das können die Genre eines laufenden Films oder die Musikstile des gerade über Alexa gespielten Liedes sein etc.
Mehr dazu hierListen
Im letzten Absatz wurde gezeigt, wie man mit einer Schleife durch eine "Liste" iteriert.
Das war in den Beispielen eine bereits existierende Liste von Werten.
Man kann solche Listen natürlich auch selbst erzeugen und mit diesen mehr oder weniger sinnvolle Dinge anstellen.Mehr dazu hier
-
Hier noch ein paar grundsätzliche Überlegungen:
Lesbarkeit
Code (auch Blockly) wird deutlich häufiger gelesen als geschrieben.
In der Regel muss man früher oder später an ein Script nochmal "Hand anlegen".
Viel häufiger als zu vermuten kommt es dann vor dass man denkt "welcher Vollhorst" hat das denn verbrochen?", um dann vielleicht festzustellen: "huch, das war ich ja selbst!"
Es liegt also im eigenen Interesse, den Code so zu gestalten, dass er auch nach Wochen und Monaten noch problemlos zu verstehen ist. Damit verbessert man die Wartbarkeit ... und die Notwendigkeit dafür kommt - garantiert.
Ich zitiere hier gerne aus "Refactoring" von Martin Fowler:
"Any fool can write code that a computer can understand. Good programmers write code that humans can understand."Kommentare
Man kann Bausteine mit Kommentaren versehen
oder zusätzlich bzw. alternativ Kommentarbausteine einfügen
Man erkennt hier hoffentlich schon:
Es ist sinnvoller, seinen Variablen und/oder Funktionen sprechende Namen zu geben, statt sie aufwändig zu kommentieren.
"Don't comment bad code - rewrite it"Verstehen vor Kopieren
Die Verlockung ist groß: Man sucht sich etwas passendes im Internet und kopiert das ohne groß nachzudenken in seinen ioBroker. Der Anbieter hat ja schließlich geschrieben, was das Ding macht.
Aber macht der Code auch wirklich (nur) das was der nette Kerl (m/w/d) da geschrieben hat?
Versuche zunächst zu verstehen, was der angebotene Code so tut. Im Zweifelsfall kannst Du hier im Forum nachfragen.
Wäre blöd, wenn der Code Deine Zugangsdaten zu einem Service benötigt und diese irgendwo hinschickt.
Mindestens genau so blöd wäre es, wenn der Code Deinen ioBroker zerschießt oder Geräte unbrauchbar macht.Code behind
Wer zumindest eine grundsätzliche Ahnung von Programmierung hat, sollte sich ab und an mal ansehen, was Blockly da "unter der Haube" an Code produziert. Das hilft möglicherweise, die Funktionsweise zu verstehen und ggf. Fehler zu finden.
-
Grundsätzliches
Insbesondere wer von der prozeduralen Programmierung oder einer SPS zu Blockly kommt, muss sich hier neu orientieren und umdenken.
Im ioBroker werden Programme nicht bei Zeile 1 gestartet und laufen dann bis Zeile xyz nacheinander ab.
In der Regel "reagieren" Programme (Scripte) nur auf äußere Einflüsse und werden aktiv, wenn ein bestimmtes Ereignis eintritt. Das kann die Änderung eines Datenpunktes oder auch das Erreichen eines bestimmten Zeitpunktes sein.
Die meiste Zeit "schlafen" die Programme ... solange, bis eines der genannten Ereignisse eintritt.Trigger
Ein Trigger ist eine Ereignisbehandlung. Das kann man sich als eine Art Abonnement vorstellen.
Tritt das Ereignis ein, wird der Code im Trigger ausgeführt.-
Will man bei bool'schen Datenpunkten (true/false) nur reagieren, wenn der DP auf
true
wechselt, verwendet man am besten "ist größer als Letztes".
Analog dazu lässt sich der Wechsel auffalse
mit "ist kleiner als Letztes" verarbeiten.
Hintergrund: Eintrue
wird intern als1
und einfalse
intern als0
verarbeitet. -
Echte "Änderungen" am DP prüft man mit "wurde geändert". Datenpunkte werden von den Adaptern gerne mal zyklisch "aufgefrischt". Eine Prüfung auf "wurde aktualisiert" würde dann viel zu häufig den Trigger auslösen.
Hier ein ganz einfaches Beispiel: Ändert sich der Zustand eines Schalters "SwitchState", wird die Lampe "Licht" mit dem Wert des Schalters (an oder aus) geschaltet.
Was es mit dem Baustein "Wert" auf sich hat, wird hier erläutert.
ACHTUNG:
Niemals mehrere Trigger (oder Zeitpläne oder eine Kombination daraus) ineinander verschachteln. Sowas hier funktioniert nicht:Zeitpläne
Mit einem Zeitplan kann man Dinge zu bestimmten Zeiten oder auch zyklisch alle x-Minuten ausführen lassen.-
Vermeide den "Wizard", sondern verwende nach Möglichkeit CRON.
Mit dem Wizard produzierte Zeitpläne funktionieren häufig nicht - zumindest nicht wie gewünscht -
Vermeide zyklisch Ausführungen alle x-Minuten, wenn die gleiche Aufgabe auch mit einem Trigger ausgeführt werden kann.
Man muss nicht alle paar Minuten prüfen, ob ein Datenpunkt einen bestimmten Wert angenommen hat. Das belastet das System. Besser ist es, einen Trigger auf den DP zu setzen.
In diesem einfachen Beispiel wird eine Lampe täglich um 20:00 Uhr eingeschaltet.
Alles was außerhalb von Triggern oder Zeitplänen hinzugefügt wird, wird nur 1x - beim Start des Scriptes - ausgeführt.
Damit lassen sich z.B, verwendete Variablen beim Start des Scriptes auf einen definierten Wert setzen.
Dabei ist es unerheblich, ob der Baustein losgelöst von allen anderen "in der Luft schwebt" oder ob er z.B. oben (oder unten) an einen anderen Baustein angepinnt wird.ACHTUNG: Ein in Blockly erzeugter Zeitplan wird nur 1x beim Start des Scriptes aktiviert.
Wenn man "variable" Zeitpläne benötigt, die sich z.B. bei Änderungen an einem Datenpunkt ändern sollen, muss man etwas mehr Aufwand treiben.
Die Details führen allerdings an dieser Stelle zu weit. Wenn Du so etwas benötigst, schau in die Doku. -
-
Werte auslesen
So ziemlich jedes Blockly benötigt den Wert aus einem oder gar mehreren Datenpunkten.
Dabei ist zu beachten, dass hier in der Regel der "Wert" des Objektes von Interesse ist.
Wählt man hier nur ein Objekt (rechts), enthält dieses die definierten (statischen) Eigenschaften desselben (ID, Name, Typ, Rolle usw.).
Das ist in den meisten Fällen nicht das gewünschte - gefordert ist hier lediglich der "Wert" des Objektes und nicht sämtliche Eigenschaften.Tipp:
Möchte man innerhalb eines Triggers auf den Wert des auslösenden Objektes zugreifen, muss der Wert nicht mit "Wert vom Objekt" ausgelesen werden.Stattdessen verwendet man den Baustein "Objekt ID" aus dem Bereich Trigger.
Sobald man diesen Baustein hinzugefügt hat, kann man dort statt "Objekt ID" auch "Wert" auswählen.
(Ab Version 7.5 des JS-Adapters ist "Wert" bereits die Vorgabe).
Damit vermeidet man unnötige Leseoperationen. Die belasten nicht nur das System, sondern können auch zu Fehlern führen. -
Werte schreiben (Datenpunkte ändern)
Um den Wert eines Datenpunktes zu ändern und damit z.B. ein Gerät einzuschalten, stehen grundsätzlich zwei (relativ ähnliche) Bausteine zur Verfügung.Steuere
Diesen Baustein verwendet man, um Datenpunkte zu verändern die einem Adapter "gehören", um z.B. eine Lampe oder einen Schalter zu schalten.
Im Detail wird damit eine Änderung "ohne Bestätigung" (Ackknowledge) geschrieben. Diese fehlende Bestätigung ist für den Adapter die Veranlassung, etwas zu tun.
Die allermeisten Adapter reagieren nicht, wenn hier eine Änderung per "Aktualisiere" (mit Bestätigung) geschrieben wird.
Das gilt im Übrigen auch für Alias-Datenpunkte, die auf den "echten" DP eines Adapters verweisen.Aktualisiere
Dieser Baustein wird zur Änderung eigener Datenpunkte verwendet, die Du unterhalb von0_userdata.0
selbst angelegt hast.
Hierbei wird "mit Bestätigung" geschrieben. Damit wird verhindert, dass der Wert im Objektbaum in rot dargestellt wird. In den meisten Fällen also eine lediglich kosmetische Sache. -
Variablen
Mit Variablen lassen sich ermittelte oder berechnete Werte für die weitere Verarbeitung zwischenspeichern.
Variablen werden manuell erstellt und sind im gesamten Script gültig.
Sinnvoll ist das überall dort, wo ansonsten der Wert aus einem DP mehrfach ausgelesen werden müsste.
Auch die Les- und Wartbarkeit eines Scriptes lässt sich durch die Verwendung von Variablen deutlich verbessern.
Insbesondere komplexe Prüfungen werden durch Variablen deutlich besser lesbar und damit verständlicher.Klingt zunächst unwichtig. Aber Code wird in aller Regel deutlich häufiger gelesen als dass er geschrieben (geändert) wird. Auch Blockly.
Wichtig wird das, wenn man nach Wochen oder gar Monaten nochmal da ran muss, um etwas zu überprüfen oder zu verändern. Es kommt nicht unbedingt selten vor, dass man dann seinen eigenen Code nicht mehr versteht
In diesem Beispiel müsste der Wert des Objektes "Licht" ohne die Verwendung von Variablen 2x gelesen werden.
So etwas belastet das System unnötig und kann durch die Verwendung von Variablen vermieden werden.Auch die Prüfung, ob "Licht" gerade eingeschaltet "und Vormittag" wird gleich wesentlich besser lesbar.
Dabei gelten Variablen im ganzen Script! Aber nur in diesem Script!
ACHTUNG: In den Namen von Variablen sollten auf keinen Fall Leer- oder gar Sonderzeichen verwendet werden.
Dazu gehören insbesondere Umlaute.
Ausnahme:_
und$
- aber auch die würde ich persönlich vermeiden.Auch in JavaScript reservierte Schlüsselworte und Anweisungen wie "Object", "true", "String" oder "let" etc. sollte man tunlichst vermeiden. Das führt zu ganz seltsamen Verhaltensweisen und schwer zu findenden Fehlern.
Eine Liste der reservierten Wörter usw. findest Du hier.
Auch sollten Variablen und Funktionen oder deren Parameter niemals den gleichen Namen tragen. -
Falls / mache / sonst
In den allermeisten Scripten muss zur Laufzeit mindestens eine Bedingung geprüft werden.
Dabei wird oft nicht nur eine, sondern ggf. mehrere Bedingungen geprüft.Tipp 1
Wenn mehrere Bedingungen geprüft werden müssen, wird das Ganze oft übersichtlicher wenn man die Ansicht auf "externe Eingänge" umstellt:
Tipp 2
Kleiner Ausflug in bool'sche Algebra:
Wenn eine Bedingung mit "falls" geprüft wird, muss der zu prüfende Ausdruck entweder "wahr" oder "falsch" werden. Heißt auf Deutsch: " Ist der Wert von "power" jetzt gößer als 500? Ja oder Nein?Das gleiche gilt hier aber auch für den zweiten Ausdruck: Ist "istEingeschaltet" jetzt "wahr" oder "falsch"?
Der Punkt ist: "istEingeschaltet" ist ja bereits ein Wert, der entweder nur "wahr" oder "falsch" sein kann (Boolean). Das lässt sich jetzt also folgendermaßen vereinfachen:
Falls auffalsch
geprüft werden soll, ist dieser Ansatz hier der bessere:
Zum Einen benötigt man hier nur 2 statt 3 Bausteine und zum Anderen wird mit einem "nicht" der Code minimal schneller ausgeführt.Tipp 3
Verschachtelte Ausdrücke werden schnell unübersichtlich.
Hier hilft es oft, wenn man einzelne Teilausdrücke vorher einer Variablen zuweist.
Wie bereits erwähnt: Code wird häufiger gelesen als geschrieben.
Es erleichtert die Fehlersuche und die spätere Wartung, wenn Code gut lesbar ist.Tipp 4
Es ist in den allermeisten Fällen nicht nötig, mehrere Prüfungen mit einzelnen "Falls"-Bausteinen auszuführen.
Viel einfacher ist eine Logik nach dem Motto " Falls x" => "mache etwas" => "sonst" => ... mache etwas anderes.
Dazu klickst Du auf das kleine blaue Zahnrad und ziehst den gewünschten Block nach rechts unter das "falls".
Tipp 5
Noch komplexere Prüfungen? Dann ist vielleicht der folgende Baustein der richtige:
Das ist schneller und erspart einiges an "Puzzelei".Aber Achtung: Der Wert eines DP muss zunächst einer Variablen zugewiesen werden. Die Prüfung funktioniert nicht direkt mit dem "Wert vom Objekt"-Baustein!
Und unbedingt darauf achten, dass hinter jedem "Im Falle von" ein Wert steht. Hier stehen keine logischen Ausdrücke!
-
Verzögerungen (Timeouts)
Der Klassiker unter den Anforderungen in Richtung "timeout" ist der berühmte Bewegungsmelder, der bei erkannter Bewegung eine Lampe ein- und nach Ablauf einer gewissen Zeit ohne Bewegung wieder ausschalten soll.
Auch wenn es zunächst einfach und verlockend aussieht: Die Option "mit Verzögerung" funktioniert häufig nicht bzw. nicht so wie erwartet.Als Alternative kann (und sollte) stattdessen ein "timeout" verwendet werden.
Hier hat man deutlich mehr Kontrolle über den Ablauf.
Zu beachten ist hier der Block "stop timeout". Der sorgt dafür, dass eine einmal angestoßene Verzögerung zum Ausschalten wieder abgebrochen wird, falls sich der Wert des Objektes (Bewegungsmelder) erneut ändert.Im Beispiel passiert folgendes:
- Wird irgendwann erkannt, dass keine Bewegung im Erfassungsbereich mehr stattfindet, startet der Timeout. Der soll nach 10 Sekunden eine Lampe ausschalten.
- Sollte innerhalb der Zeitspanne erneut eine Bewegung erkannt werden, wird der Timeout gestoppt.
- Sobald dann wieder keine Bewegung stattfindet, startet der Timeout erneut.
Ändert sich der Zustand (keine Bewegung) nun 10 Sekunden lang nicht mehr, wird die Lampe tatsächlich ausgeschaltet.
Da diese Anforderung im Forum recht häufig nachgefragt wird, gibt es dieses Blockly hier ausnahmsweise auch als Vorlage:
-
Schleifen
So etwas hier wird relativ häufig benötigt:
Das kann eine Liste der Musikstile zum durch den MediaPlayer abgespielten Song, eine Liste von Genres zum gerade gezeigten Film oder ein anderes beliebiges "Array" sein.
Hilfreich (im Sinne von "lesbar") ist es, den Inhalt des DP zunächst in eine sinnvoll benannte Variable einzulesen.
Damit hat man beim Lesen schon mal eine Idee, was da denn drinsteckt.
Und als Nächstes sollte man die "Laufvariable" umbenennen. Die heißt per Vorgabe standardmäßig "i". Hier solltest Du einen besseren, "sprechenderen" Namen vergeben.Was man auf jeden Fall vermeiden sollte, wäre ein solches Konstrukt:
Da innerhalb der Schleife der Wert vonpower
nicht verändert und neu zugewiesen wird, hat man hier eine wunderbare Endlosschleife produziert.
Solche Endlosschleifen können ein System innerhalb kürzester Zeit in die Knie zwingen.
Dabei "stürzt" es nicht unbedingt ab. Es ist aber schnell dermaßen mit sich selbst beschäftigt, dass es auf keine Aktion mehr reagiert. Was dann letztendlich aufs Gleiche hinausläuft.Achtung:
Schleifen mit "Wiederhole solange" oder "Wiederhole bis", in denen Datenpunkte gelesen oder geschrieben werden, sind ebenfalls Kandidaten für einen plötzlichen System-Suizid.
Wenn man hier nicht genau weiß was man da tut, hat man sich ganz schnell das System lahmgelegt. -
Listen
Hier mal ein halbwegs sinnvolles "real life" Beispiel, was man z.B. mit Listen anstellen kann:
Hier wird eine Liste dazu verwendet, die Tagesmitteltemperatur zu ermitteln.Zunächst wird beim Start des Scriptes eine leere Liste erzeugt.
Der Zeitplan sorgt nun dafür, dass jede Minute die Temperatur aus einem Datenpunkt gelesen und am Anfang der Liste eingefügt wird.
Das "vorne anfügen" hat den Vorteil, dass Änderungen auch im Objektbaum ersichtlich sind.
Der ermittelte Mittelwert wird hier nur ausgegeben. Wie man das in einen DP schreibt, ist hier beschrieben.Am Ende wird per Zeitplan um 23:59:30 Uhr die Liste wieder geleert, damit am nächsten Tag wieder mit komplett neuen Werten gerechnet werden kann.
Das Ganze stellt hier nur ganz rudimentär das grundsätzliche Verhalten dar.
Man kann das je nach den Anforderungen noch abwandeln/ergänzen:- Man arbeitet nicht zyklisch per Zeitplan, sondern triggert auf das Temperatur-Objekt
- Man arbeitet mit einer festen Anzahl an Werten. Wurde die erreicht, wird die Liste geleert
Hier ins Detail zu gehen, würde eindeutig zu weit gehen.
Bei besonderen Anforderungen wird Dir sicher im Forum weitergeholfen. - Man arbeitet nicht zyklisch per Zeitplan, sondern triggert auf das Temperatur-Objekt