iobroker.javascript 10.2.5 → 10.3.0

package/build/types.d.ts

@@ -8,6 +8,8 @@ import type { EventObj } from './lib/eventObj';
 import type { PatternEventCompareFunction } from './lib/patternCompareFunctions';
 import type { AstroEvent } from './lib/consts';
 import type { Secrets } from './lib/secrets';
+import type { FbDebugCommand, FbDebugStatus } from './lib/fb/types';
+import type { FbDebugSettings } from './lib/fb/runtime';
 
 /** ECMAScript version the user scripts are compiled for */
 export type TsTarget = 'es2018' | 'es2019' | 'es2020' | 'es2021' | 'es2022' | 'es2023' | 'es2024' | 'es2025' | 'esnext';
@@ -129,7 +131,7 @@ export type JavascriptTimer = {
     scriptName: string;
 };
 
-export type ScriptType = 'TypeScript/ts' | 'Blockly' | 'Rules' | 'Javascript/js';
+export type ScriptType = 'TypeScript/ts' | 'Blockly' | 'Rules' | 'FBD' | 'Javascript/js';
 
 export type TimeRule = {
     time: string | { hour: number; minute: number };
@@ -811,6 +813,12 @@ export interface JavascriptContext {
     prepareStateObject: (id: string, state: ioBroker.SettableState | null) => ioBroker.State;
     debugMode: string | undefined;
     rulesOpened: string | null; // opened rules
+    /** Function block diagrams shown online in an editor: until when, and which viewer asked last */
+    fbdWatch: Map<string, { until: number; viewer: number; paths?: Map<string, number> }>;
+    /** The runtimes of the running diagrams take the commands of the online view here, by script */
+    fbdDebug: Map<string, (command: FbDebugCommand) => FbDebugStatus>;
+    /** Forced values and breakpoints of the online view, kept while a diagram starts again */
+    fbdDebugSettings: Map<string, FbDebugSettings>;
     language: ioBroker.Languages;
     getAbsoluteDefaultDataDir: () => string;
     logError: (scriptName: string, msg: string, e: Error, offs?: number) => void;

package/docs/de/fbd.md

@@ -0,0 +1,274 @@
+# Funktionspläne (FBD)
+
+Ein Funktionsplan ist Logik aus Bausteinen, so wie eine SPS in CFC programmiert wird: Timer, Flipflops, Vergleiche
+und Arithmetik, verbunden mit ioBroker-Datenpunkten. Er ist für Logik gedacht, die dauerhaft läuft - Verzögerungen,
+Selbsthaltungen, Schwellwerte - und für Nutzer, die diese Art aus der SPS-Welt kennen. Wer auf ein einzelnes Ereignis
+reagieren will, ist mit Blockly oder Rules meist einfacher unterwegs.
+
+Beim Speichern wird der Plan in JavaScript übersetzt und läuft wie jedes andere Skript dieses Adapters.
+
+## Einen Plan anlegen
+
+Ein neues Skript hinzufügen und **Funktionsplan** wählen. Der Editor hat drei Bereiche:
+
+- **Palette** (links), mit einer Suche und drei Reitern:
+  - **Blöcke**: die Bausteine nach Kategorien - auf die Fläche ziehen oder anklicken. Eine Kategorie klappt mit
+    einem Klick auf ihren Namen auf und zu.
+  - **Variablen**: die Datenpunkte, die der Plan liest und schreibt; ein Klick zeigt den Baustein.
+  - **Favoriten**: die Bausteine, die mit dem Stern markiert sind - er erscheint, wenn die Maus über einem Baustein
+    steht.
+- **Fläche**: einen Ausgang (rechts am Baustein) mit einem Eingang (links) verbinden. Nur passende Typen lassen
+  sich verbinden - die Farbe eines Anschlusses zeigt seinen Typ; wird eine Verbindung auf einem unpassenden
+  Anschluss losgelassen, steht oben, warum. Ein Eingang nimmt genau eine Verbindung. `Entf` löscht das Ausgewählte.
+- **Eigenschaften** (rechts): **Eigenschaften** zeigt die Einstellungen des gewählten Bausteins in Abschnitten, die
+  auf- und zuklappen - Allgemein (Instanzname, Typ, ein Kommentar), Parameter, Eingänge und bei Timern, Flipflops,
+  Flanken und Regelungsbausteinen eine **Vorschau**: ein Zeitdiagramm des Bausteins mit seinen Werten.
+  **Dokumentation** beschreibt den Baustein und seine Anschlüsse. Ist nichts gewählt: die Einstellungen des Plans
+  und die Tastenkürzel.
+
+Ein Baustein zeigt das Wichtige direkt in sich: den Datenpunkt, den er liest oder schreibt, den Wert eines `CONST`
+und die Werte der Eingänge, die nicht verbunden sind - sie lassen sich gleich dort ändern: Ein Klick schaltet ein
+BOOL um, alles andere wird eingetippt und mit `Enter` übernommen. Im Kopf eines Bausteins zeigt das Zahnrad seine
+Eigenschaften, das Menü `⋮` dupliziert oder löscht ihn (online auch: Haltepunkt; bei einem eigenen Baustein:
+Innenansicht).
+
+Probleme stehen unten auf der Fläche; ein Klick wählt den Baustein aus. Ein Plan mit Fehlern lässt sich speichern,
+sein Skript läuft aber nicht, sondern meldet die Fehler im Protokoll.
+
+Der Knopf **FBD → JS** zeigt den erzeugten Code.
+
+Bearbeiten geht wie gewohnt: `Strg+Z` / `Strg+Y` (oder die Knöpfe der Werkzeugleiste) machen rückgängig und
+wiederholen, `Strg+C`, `Strg+X` und `Strg+V` kopieren, schneiden aus und fügen die ausgewählten Bausteine samt der
+Verbindungen zwischen ihnen ein - auch in einen anderen Plan. Eingefügte Bausteine bekommen neue IDs und, wo der
+alte Name vergeben ist, neue Namen.
+
+Die Leiste über der Fläche zeigt den Plan (und den Pfad in eine Instanz hinein) und hat die Werkzeuge:
+
+- den Zoom: kleiner, der Zoom (ein Klick: 100 %), größer
+- **Automatisch anordnen** stellt die Bausteine in Spalten entlang des Datenflusses auf: Eingänge links, Ausgänge
+  rechts, jeder Baustein auf der Höhe der Bausteine, mit denen er verbunden ist. Kommentare bleiben, wo sie sind.
+  `Strg+Z` nimmt es zurück.
+- **Im Plan suchen** (`Strg+F`) findet Bausteine nach Instanzname, Typ, Datenpunkt oder anderem Parameter, Kommentare
+  nach ihrem Text. `Enter` geht zum nächsten Treffer, `Umschalt+Enter` zum vorigen, `Esc` schließt die Suche.
+- **Raster** an oder aus (mit Raster rasten die Bausteine ein), und Verbindungen als Kurven oder rechtwinklig wie in
+  CFC - beides merkt sich der Browser, nicht der Plan
+- rechts die Onlineansicht, siehe unten
+
+**Verbindungsmarken**: Eine Verbindung quer durch den Plan lässt sich statt als Linie als Marke an beiden Enden
+zeigen - Verbindung auswählen und in ihren Eigenschaften **Als Verbindungsmarke zeigen** einschalten. Beide Marken
+zeigen den Namen des Bausteins, von dem die Verbindung kommt, oder einen eigenen. Ein Doppelklick auf eine Marke
+springt zum anderen Ende. Nur die Darstellung ändert sich, die Verbindung wirkt wie zuvor.
+
+## Onlineansicht
+
+**Online** (rechts in der Leiste über der Fläche) zeigt die Werte des laufenden Plans: an jedem Ausgang,
+BOOL-Leitungen grün (`TRUE`) oder grau (`FALSE`), andere Leitungen mit ihrem Wert in der Mitte. Neben oder unter dem
+Knopf stehen:
+
+- der Zykluszähler - er bleibt stehen, wenn der Plan nicht mehr rechnet
+- eine Warnung, wenn keine Daten kommen (das Skript läuft nicht, oder seine Instanz ist gestoppt)
+- ein Hinweis, wenn der Plan nach dem Speichern geändert wurde: Die Werte gehören zur gespeicherten Fassung
+
+Schlägt ein Zyklus fehl, wird der Baustein, dessen Code fehlschlug, rot umrandet und der Fehler unten links
+aufgeführt; auch das Protokoll nennt den Baustein (`Error in the function block diagram in block b7: ...`).
+
+Die Werte fließen nur, solange ein Editor den Plan online zeigt: Der Editor fragt alle 10 s beim Adapter an, nach
+30 s ohne Anfrage hört der Plan auf zu senden. Es kommen höchstens vier Aktualisierungen pro Sekunde, jede nur mit den
+geänderten Werten. Ein Plan, der vor dieser Version gespeichert wurde, zeigt den Zykluszähler, aber keine Werte -
+einmal speichern.
+
+### In eine Instanz hinein
+
+Ein Doppelklick auf eine Instanz eines eigenen Bausteins (oder **Innenansicht** in ihren Eigenschaften) zeigt den
+Plan des Bausteins - so, wie dieser Plan ihn mitführt, nur lesbar - und online mit den Werten genau dieser Instanz.
+Eine Instanz darin öffnet sich genauso; der Pfad oben links führt zurück, ebenso `Esc`. Werte im Inneren lassen sich
+erzwingen; Haltepunkte werden im Plan selbst gesetzt. Die Werte im Inneren brauchen einen Plan, der mit dieser
+Version gespeichert wurde.
+
+### Werte erzwingen, Haltepunkte, Einzelschritte
+
+Solange der Plan online gezeigt wird, lässt er sich steuern:
+
+- **Erzwingen**: einen Baustein (oder eine Verbindung) auswählen - die Eigenschaften zeigen seine Ausgänge mit ihren
+  Werten. **TRUE** / **FALSE** oder ein Wert und **Erzwingen** halten den Ausgang auf diesem Wert, gleich was der
+  Baustein rechnet; die Bausteine dahinter und die Datenpunkte, die der Plan schreibt, bekommen den erzwungenen Wert.
+  Ein erzwungener Wert ist orange umrandet; **Freigeben** lässt ihn los.
+- **Haltepunkte**: der Punkt oben links an einem Baustein, `F9` oder **Haltepunkt** in seinen Eigenschaften. Der
+  Plan hält vor diesem Baustein an; der Baustein, der als nächster läuft, ist gelb umrandet, und die Werte zeigen, wie
+  weit der Zyklus kam.
+- Die Knöpfe links von **Online**: **Anhalten** / **Fortsetzen** (`F8`), **Ein Zyklus** und **Ein Baustein** (`F10`).
+  Solange der Plan wartet, warten auch die Änderungen seiner Eingänge. Ein Zyklus von Hand rechnet mit einer
+  Zykluszeit als vergangener Zeit - Timer verhalten sich so, wie sie es täten, egal wie lange der Plan wartete.
+
+Das alles endet mit der Onlineansicht: Schaltet der Editor sie aus, wird er geschlossen oder verschwindet er (30 s
+ohne Anfrage), gibt die Laufzeit die erzwungenen Werte frei, entfernt die Haltepunkte und läuft weiter - und
+protokolliert das. Beim Speichern des Plans bleiben erzwungene Werte und Haltepunkte erhalten, solange die
+Onlineansicht offen ist. Haltepunkte und Einzelschritte brauchen einen Plan, der mit dieser Version gespeichert
+wurde; ein älterer lässt sich schon erzwingen und anhalten.
+
+**Vorsicht:** Ein erzwungener Wert wirkt auf echte Geräte - der Plan schreibt seine Datenpunkte damit.
+
+## Bausteine
+
+| Kategorie  | Bausteine                                                        |
+|------------|------------------------------------------------------------------|
+| ioBroker   | `STATE_IN`, `STATE_OUT`, `CONST`                                 |
+| Logik      | `AND`, `OR`, `XOR`, `NOT`                                        |
+| Speicher   | `RS`, `SR`, `R_TRIG`, `F_TRIG`                                   |
+| Zeit       | `TON`, `TOF`, `TP`, `BLINK`                                      |
+| Zähler     | `CTU`, `CTD`, `CTUD`                                             |
+| Vergleich  | `GT`, `GE`, `LT`, `LE`, `EQ`, `NE`                               |
+| Arithmetik | `ADD`, `SUB`, `MUL`, `DIV`, `MIN`, `MAX`, `ROUND`                |
+| Umwandlung | `TO_BOOL`, `TO_INT`, `TO_REAL`, `TO_TIME`, `TO_STRING`, `CONCAT` |
+| Regelung   | `HYST`, `RAMP`, `PT1`, `PID`                                     |
+| Kalender   | `CLOCK`, `TIMEWINDOW`, `SCHEDULE`, `ASTRO`                       |
+| Meldungen  | `LOG`, `NOTIFY`, `SENDTO`                                         |
+| Experte    | `JS`                                                             |
+
+Namen und Verhalten folgen IEC 61131-3. `AND`, `OR`, `XOR`, `ADD`, `MUL`, `MIN`, `MAX` und `CONCAT` haben 2 bis 16
+Eingänge. Zeiten werden wie `500ms`, `2s`, `1m30s` oder `T#2s` eingegeben, Uhrzeiten wie `08:30`.
+
+Die Regelungsbausteine:
+
+- `HYST` - Zweipunktschalter: `Q` geht an, wenn `IN` über `HIGH` steigt, und aus, wenn `IN` unter `LOW` fällt;
+  dazwischen bleibt `Q`, wie es ist. Eine Heizung, die unter `LOW` einschaltet, nimmt `Q` invertiert (`NOT` oder
+  ein invertierter Eingang).
+- `RAMP` - `OUT` folgt `IN`, ändert sich aber um höchstens `UP` pro Sekunde aufwärts und `DOWN` pro Sekunde abwärts;
+  `0` begrenzt nicht. Sie beginnt bei `IN`.
+- `PT1` - Tiefpass erster Ordnung: `OUT` folgt `IN` mit der Zeitkonstante `T` (nach `T` sind 63 % eines Sprungs
+  erreicht). Glättet einen unruhigen Wert; er beginnt bei `IN`.
+- `PID` - PID-Regler: Sollwert `SP`, Istwert `PV`, Stellgröße `Y` zwischen `YMIN` und `YMAX`. `KP` ist die
+  Verstärkung, `TN` die Nachstellzeit des I-Anteils, `TV` die Vorhaltzeit; `TN` oder `TV` gleich `0` lässt den Anteil
+  weg. Steht `Y` an einer Grenze, wächst der I-Anteil nicht weiter (Anti-Windup); der D-Anteil wird aus `PV` gebildet,
+  ein neuer Sollwert gibt also keinen Stoß. `RST` löscht den I-Anteil.
+
+`RAMP`, `PT1` und `PID` hängen von der Zeit ab: Ein Plan mit ihnen läuft zyklisch.
+
+Blinker und Zähler:
+
+- `BLINK` - solange `EN` wahr ist, ist `Q` für `TH` wahr und für `TL` falsch, beginnend mit wahr.
+- `CTU` zählt die steigenden Flanken an `CU`; `R` setzt `CV` auf 0 zurück, `Q` ist wahr, sobald `CV` `PV` erreicht
+  hat. `CTD` zählt bei `CD` herunter, `LD` lädt `PV`, `Q` ist bei 0 und darunter wahr. `CTUD` kann beides; `R` geht
+  vor `LD`, und Flanken an `CU` und `CD` im selben Zyklus heben sich auf. Ein Eingang, der beim Start des Skripts
+  schon wahr ist, ist keine Flanke. Der Zählerstand bleibt über einen Neustart des Skripts nicht erhalten.
+
+Umwandlung: `TO_BOOL`, `TO_INT`, `TO_REAL`, `TO_TIME` und `TO_STRING` nehmen jeden Typ. `TO_INT` rundet, ein
+Dezimalkomma gilt als Punkt, und was keine Zahl ist, ergibt 0; `TO_TIME` liest eine Zahl als ms und einen Text wie
+`2s` oder `08:30`. `CONCAT` fügt seine Eingänge zu einem Text zusammen - Zahlen so, wie sie sind, also vorher mit
+`ROUND` runden (`DIGITS` Nachkommastellen, 0 bis 10).
+
+Der Kalender:
+
+- `CLOCK` - die Ortszeit: `TOD` (Uhrzeit), `HOUR`, `MIN`, `WDAY` (1 Montag ... 7 Sonntag), `DAY`, `MONTH`, `YEAR`.
+- `TIMEWINDOW` - `Q` ist von `START` bis `END` an den gewählten Tagen wahr (jeden Tag, Montag bis Freitag, Samstag
+  und Sonntag). Ein Fenster über Mitternacht wie `22:00` bis `06:00` gehört zu dem Tag, an dem es beginnt: Bei
+  Montag bis Freitag reicht es von Freitagnacht bis Samstagmorgen, aber nicht von Sonntagnacht in den Montag.
+- `SCHEDULE` - `Q` ist einen Zyklus lang wahr, wenn die Zeit des Cron-Musters kommt, etwa `0 8 * * 1-5` für 8:00 von
+  Montag bis Freitag, oder mit Sekunden vorne `*/5 * * * * *` für alle 5 Sekunden. Der Knopf neben dem Feld öffnet den Dialog für das Muster.
+- `ASTRO` - `Q` ist von einem Sonnenereignis bis zu einem anderen wahr, etwa von `sunset` bis `sunrise`, jeweils mit
+  einem Versatz in Minuten. `START` und `END` sind die Zeiten der beiden Ereignisse heute. Die Position ist die aus den
+  Einstellungen des Adapters; ohne sie gibt es keine Zeiten, und `Q` bleibt falsch.
+
+`CLOCK`, `TIMEWINDOW` und `ASTRO` lassen einen Plan zyklisch laufen. `SCHEDULE` nicht: Wenn seine Zeit kommt, läuft
+der Plan sofort, und gleich danach noch einmal, um den Impuls zu beenden.
+
+- `STATE_IN` liest einen Datenpunkt und wandelt ihn in den gewählten Typ (`BOOL`, `INT`, `REAL`, `STRING`). Ein
+  Wert, der sich nicht wandeln lässt, wird einmal im Protokoll gemeldet und als 0 gelesen. Ändert sich die ID des
+  Datenpunkts - im Dialog gewählt oder eingetippt -, wird der Typ aus seinem Objekt übernommen, und ein Baustein,
+  der noch seinen ersten Namen hat, bekommt den Namen des Datenpunkts. Den Typ kann man danach anders setzen; neu
+  übernommen wird er erst mit der nächsten ID.
+- `STATE_OUT` schreibt einen Datenpunkt nur, wenn sich der Wert ändert. `Mindestzeit zwischen zwei
+  Schreibvorgängen` begrenzt, wie oft er schreibt; der letzte Wert wird geschrieben, wenn die Zeit um ist.
+- `CONST` ist ein Wert des gewählten Typs. Mit einem Eingang anderen Typs verbunden, übernimmt er dessen Typ und
+  behält seinen Wert, soweit es geht (`"0"` wird für eine `TIME` zu 0 ms) - außer er speist schon andere Eingänge,
+  die den neuen Typ nicht nehmen.
+
+Die Meldungen:
+
+- `LOG` schreibt eine Zeile ins ioBroker-Protokoll, mit der gewählten Stufe (`info`, `warn`, `error`, `debug`):
+  bei steigender Flanke an `TRIG` oder wann immer sich `IN` ändert. `%s` im Text ist der Wert von `IN`. Höchstens
+  20 Zeilen pro Minute - ein Plan, der alle 200 ms läuft, würde das Protokoll sonst fluten; die 20. Zeile sagt das.
+- `NOTIFY` sendet den Text als ioBroker-Benachrichtigung - als Meldung oder als Alarm -, `SENDTO` an einen Adapter
+  wie `telegram.0`, `pushover.0` oder `email.0`, als `{ text, message, title, subject }` mit dem gewählten Befehl
+  (`send`). Beide senden, wenn `LOG` schreiben würde, höchstens 5-mal pro Minute; das Protokoll sagt, wenn mehr
+  ausgelassen wurden.
+
+Der Expertenbaustein `JS` führt eigenen Code aus. Der Code ist der Rumpf einer Funktion, die die Eingänge `IN1` ...
+`INn` (0 bis 8, beliebiger Typ) bekommt, dazu `dt` (ms seit dem letzten Zyklus), `firstScan` und `state` - ein Objekt,
+das von einem Zyklus zum nächsten erhalten bleibt. Er gibt den Wert von `OUT1` zurück oder ein Feld
+`[OUT1, OUT2, ...]` für mehr Ausgänge (1 bis 8); wo er `undefined` liefert, behält ein Ausgang seinen Wert. Die
+Ausgänge dürfen an Eingänge jedes Typs, der Code muss also liefern, was diese erwarten.
+
+```js
+// zählt, wie oft IN1 über IN2 gestiegen ist
+if (IN1 > IN2 && !state.above) {
+    state.count = (state.count || 0) + 1;
+}
+state.above = IN1 > IN2;
+return state.count || 0;
+```
+
+Der Code läuft im Skript des Plans, er kann also Funktionen der Skripte wie `log()` aufrufen - er sollte aber auf
+nichts warten: Der nächste Baustein braucht seine Ausgänge sofort. Ein Syntaxfehler wird schon vor dem Speichern
+angezeigt, ein Fehler beim Ausführen am Baustein.
+
+Signaltypen: `BOOL`, `INT`, `REAL`, `TIME`, `STRING`. Ein `INT` darf an einen `REAL`-Eingang; andere Umwandlungen
+geschehen nicht von selbst.
+
+## Eigene Bausteine
+
+Ein Plan kann selbst ein Baustein sein, den andere Pläne beliebig oft einsetzen - wie ein Funktionsbaustein in der
+SPS. Dazu in den Einstellungen des Plans **Dieser Plan ist ein Baustein** einschalten und dem Baustein einen Namen
+und eine Beschreibung geben.
+
+- Die Eingänge des Bausteins sind `FB_IN`-Bausteine, seine Ausgänge `FB_OUT`-Bausteine (Kategorie **Schnittstelle**,
+  nur im Plan eines Bausteins angeboten). Der Anschlussname ist der Name des Ein- oder Ausgangs am Baustein; `FB_IN`
+  hat außerdem einen Typ und den Wert, den der Eingang hat, wenn er nicht verbunden ist.
+- Ein Baustein greift nicht auf Datenpunkte zu: `STATE_IN` und `STATE_OUT` sind in ihm nicht erlaubt, `CONST`
+  schon. Er darf andere eigene Bausteine verwenden, aber nicht sich selbst.
+- Jede Instanz hat ihren eigenen Zustand - zwei Instanzen eines Bausteins mit einem Timer laufen unabhängig.
+- Das Skript eines Bausteins tut nichts, wenn es läuft; der Baustein arbeitet nur in den Plänen, die ihn einsetzen.
+
+Die Bausteine aller Pläne stehen in der Palette unter **Eigene Bausteine**. Der Plan, der einen Baustein einsetzt,
+speichert eine Kopie davon und damit die Version: Jede gespeicherte Änderung eines Bausteins ist eine neue Version.
+Pläne mit einer älteren arbeiten mit ihr weiter und zeigen einen Hinweis - **Aktualisieren** in den Eigenschaften
+einer Instanz übernimmt die neue Version in den Plan, **Baustein öffnen** öffnet den Plan des Bausteins.
+Verbindungen zu Ein- oder Ausgängen, die es nicht mehr gibt, entfernt das Aktualisieren.
+
+Weil die Kopie im Plan steht, läuft ein Plan weiter, wenn der Baustein gelöscht wird, und lässt sich allein
+exportieren und importieren. Beim Kopieren von Instanzen in einen anderen Plan kommt der Baustein mit.
+
+Ein Fehler in einem Baustein wird an der Instanz gemeldet, die ihn ausgeführt hat, im Editor und im Protokoll.
+
+## Ausführung
+
+Die Bausteine laufen in der Reihenfolge des Datenflusses; die Zahl in der Ecke jedes Bausteins ist seine Position.
+Was gleichzeitig laufen könnte, läuft von links nach rechts, dann von oben nach unten.
+
+- **Ereignisgesteuert**: Hängt kein Baustein von der Zeit ab, läuft der Plan, sobald sich ein Eingang ändert.
+  Änderungen innerhalb von 20 ms laufen gemeinsam in einem Zyklus.
+- **Zyklisch**: Sobald der Plan einen Timer enthält, läuft er alle 200 ms (50 ms bis 10 s, siehe Einstellungen des
+  Plans) und zusätzlich direkt nach der Änderung eines Eingangs.
+
+Die Betriebsart wird automatisch gewählt oder in den Einstellungen des Plans festgelegt.
+
+Eine Rückkopplung ist nur über einen speichernden Baustein erlaubt (Timer, Zähler, Flipflop, Flanke, Regelungsbaustein,
+`JS`, eigener Baustein): Die zurückführende
+Verbindung liest, was dieser Baustein im vorigen Zyklus ausgegeben hat, und wird als Doppelstrich gezeichnet. Eine
+Rückkopplung ohne einen solchen Baustein ist ein Fehler.
+
+Ein Timer zählt ab dem Zyklus, in dem er die Änderung seines Eingangs sieht. Er läuft also nie vor seiner Zeit ab,
+höchstens einen Zyklus später.
+
+## Grenzen
+
+- Nicht für sicherheitsgerichtete Funktionen. Ein Plan läuft in einem ioBroker-Skript, ohne Echtzeitgarantien.
+- Der Zustand der Bausteine bleibt über einen Neustart des Skripts nicht erhalten.
+- Noch nicht vorhanden: Haltepunkte in einem eigenen Baustein, eine manuelle Ausführungsreihenfolge, Verbindungen,
+  die um Bausteine herum geführt werden.
+
+## Ablage
+
+Der Plan steht im Skript selbst, als letzte Zeile von `common.source` (`//#fbd:{...}`); darüber steht der erzeugte
+Code. Der Plan enthält die Kopien der eigenen Bausteine, die er einsetzt. Die Bausteine der Bibliothek sind im Modul `@iobroker/fb-runtime` umgesetzt, das mit dem Adapter kommt, und werden nicht in
+jedes Skript kopiert.

package/docs/en/fbd.md

@@ -0,0 +1,260 @@
+# Function block diagrams (FBD)
+
+A function block diagram is logic drawn from blocks, the way a PLC is programmed in CFC: timers, flip-flops,
+comparisons and arithmetic, wired to ioBroker states. It is meant for logic that runs all the time - delays,
+latches, thresholds - and for users who know this style from a PLC. To react to a single event, Blockly or Rules
+are usually the simpler choice.
+
+The diagram is turned into JavaScript when it is saved and runs like every other script of this adapter.
+
+## Creating a diagram
+
+Add a new script and choose **Function block diagram**. The editor has three parts:
+
+- **Palette** (left), with a search and three tabs:
+  - **Blocks**: the blocks by category - drag one onto the canvas, or click it to add it. A category opens and
+    closes with a click on its name.
+  - **Variables**: the states the diagram reads and writes; a click shows the block.
+  - **Favorites**: the blocks marked with the star that shows when the mouse is over a block.
+- **Canvas**: connect an output (right side of a block) with an input (left side). Only fitting types can be
+  connected - the color of a pin shows its type; a link let go on a pin that does not take it says why. An input
+  takes one link. `Delete` removes what is selected.
+- **Properties** (right): **Properties** shows the settings of the selected block in parts that open and close -
+  general (instance name, type, a comment), parameters, inputs and, for timers, flip-flops, edges and control blocks,
+  a **preview**: a timing diagram of the block with its values. **Documentation** describes the block and its pins.
+  With nothing selected: the settings of the diagram, and the keys.
+
+A block shows what matters right in it: the state it reads or writes, the value of a `CONST`, and the values of the
+inputs that are not connected - these can be changed right there: a click switches a BOOL, anything else is typed in
+and taken with `Enter`. In the head of a block, the gear shows its properties, the menu `⋮` duplicates or deletes it
+(online also: breakpoint; for an own block: inside view).
+
+Problems are listed at the bottom of the canvas; a click selects the block. A diagram with errors can be saved, but
+its script does not run - it logs the errors instead.
+
+The button **FBD → JS** shows the generated code.
+
+Editing works as usual: `Ctrl+Z` / `Ctrl+Y` (or the buttons of the toolbar) undo and redo, `Ctrl+C`, `Ctrl+X`
+and `Ctrl+V` copy, cut and paste the selected blocks with the links between them - also into another diagram. Pasted
+blocks get new IDs, and new names where the old ones are taken.
+
+The bar above the canvas shows the diagram (and the path into an instance) and has the tools:
+
+- the zoom: smaller, the zoom (a click: 100 %), larger
+- **Arrange automatically** puts the blocks in columns along the data flow: inputs on the left, outputs on the
+  right, each block level with the blocks it is linked to. Comments stay where they are. `Ctrl+Z` takes it back.
+- **Find in the diagram** (`Ctrl+F`) finds blocks by instance name, type, state ID or other parameter, comments by
+  their text. `Enter` goes to the next match, `Shift+Enter` to the one before, `Esc` closes the search.
+- **Grid** on or off (with it, blocks snap to it), and links as curves or at right angles as in CFC - both are kept
+  by the browser, not in the diagram
+- on the right the online view, see below
+
+**Connection marks**: a link across the whole diagram can be shown as a mark at both ends instead of a line - select
+the link and switch on **Show as a connection mark** in its properties. Both marks show the name of the block the
+link comes from, or a name of their own. A double click on a mark jumps to the other end. Only the drawing changes,
+the link works the same.
+
+## Online view
+
+**Online** (on the right of the bar above the canvas) shows the values of the running diagram: at every output, BOOL
+links in green (`TRUE`) or grey (`FALSE`), other links with their value in the middle. Next to the button, or under
+it:
+
+- the cycle count - it stands still when the diagram stopped running
+- a warning when no data comes (the script does not run, or its instance is stopped)
+- a hint when the diagram was changed after saving: the values belong to the saved version
+
+When a cycle fails, the block whose code failed is framed in red and the error is listed at the bottom left; the
+log names the block too (`Error in the function block diagram in block b7: ...`).
+
+The values only flow while an editor shows the diagram online: the editor asks the adapter every 10 s, and after 30 s
+without a request the diagram stops sending. At most four updates a second are sent, each with the values that
+changed only. A diagram saved before this version shows the cycle count, but no values - save it once.
+
+### Inside an instance
+
+A double click on an instance of an own block (or **Inside view** in its properties) shows the diagram of the
+block - as this diagram carries it, read only - and online with the values of just this instance. An instance inside
+it opens the same way; the path at the top left leads back, and so does `Esc`. Values inside can be forced;
+breakpoints are set in the diagram itself. The values inside need a diagram saved with this version.
+
+### Forcing values, breakpoints, single steps
+
+While the diagram is shown online, it can be steered:
+
+- **Forcing**: select a block (or a link) - its properties show the outputs with their values. **TRUE** / **FALSE**,
+  or a value and **Force**, hold the output at that value, whatever the block computes; the blocks behind it and the
+  states the diagram writes get the forced value. A forced value is framed in orange; **Release** lets it go.
+- **Breakpoints**: the dot at the top left of a block, `F9` or **Breakpoint** in its properties. The diagram stops in
+  front of that block; the block that runs next is framed in yellow, and the values show how far the cycle got.
+- The buttons left of **Online**: **Pause** / **Run on** (`F8`), **One cycle**, and **One block** (`F10`). While the
+  diagram waits, the changes of its inputs wait too. A cycle started by hand counts one cycle time as time passed,
+  so timers behave as they would, however long the diagram waited.
+
+All of that ends with the online view: when the editor switches it off, is closed or goes away (30 s without a
+request), the runtime releases the forced values, removes the breakpoints and runs on - it logs that. Saving the
+diagram keeps forced values and breakpoints while the online view stays open. Breakpoints and single steps need a
+diagram saved with this version; a diagram saved before can already be forced and paused.
+
+**Careful:** a forced value acts on real devices - the diagram writes its states with it.
+
+## Blocks
+
+| Category   | Blocks                                                           |
+|------------|------------------------------------------------------------------|
+| ioBroker   | `STATE_IN`, `STATE_OUT`, `CONST`                                 |
+| Logic      | `AND`, `OR`, `XOR`, `NOT`                                        |
+| Memory     | `RS`, `SR`, `R_TRIG`, `F_TRIG`                                   |
+| Timers     | `TON`, `TOF`, `TP`, `BLINK`                                      |
+| Counters   | `CTU`, `CTD`, `CTUD`                                             |
+| Comparison | `GT`, `GE`, `LT`, `LE`, `EQ`, `NE`                               |
+| Arithmetic | `ADD`, `SUB`, `MUL`, `DIV`, `MIN`, `MAX`, `ROUND`                |
+| Conversion | `TO_BOOL`, `TO_INT`, `TO_REAL`, `TO_TIME`, `TO_STRING`, `CONCAT` |
+| Control    | `HYST`, `RAMP`, `PT1`, `PID`                                     |
+| Calendar   | `CLOCK`, `TIMEWINDOW`, `SCHEDULE`, `ASTRO`                       |
+| Messages   | `LOG`, `NOTIFY`, `SENDTO`                                         |
+| Expert     | `JS`                                                             |
+
+The names and the behavior follow IEC 61131-3. `AND`, `OR`, `XOR`, `ADD`, `MUL`, `MIN`, `MAX` and `CONCAT` can
+have 2 to 16 inputs. Times are entered like `500ms`, `2s`, `1m30s` or `T#2s`, times of day like `08:30`.
+
+The control blocks:
+
+- `HYST` - two-point switch: `Q` goes on when `IN` rises above `HIGH` and off when it falls below `LOW`; in between
+  it stays as it is. A heating that switches on below `LOW` takes `Q` inverted (`NOT`, or an inverted input).
+- `RAMP` - `OUT` follows `IN`, but changes by at most `UP` per second upwards and `DOWN` per second downwards; `0`
+  does not limit. It starts at `IN`.
+- `PT1` - low pass of the first order: `OUT` follows `IN` with the time constant `T` (after `T`, 63 % of a step are
+  reached). Smooths a noisy value; it starts at `IN`.
+- `PID` - PID controller: set point `SP`, process value `PV`, output `Y` between `YMIN` and `YMAX`. `KP` is the gain,
+  `TN` the reset time of the integral part, `TV` the derivative time; `TN` or `TV` of `0` leaves that part out.
+  While `Y` is at a limit, the integral part does not grow further (anti-windup); the derivative is taken from `PV`,
+  so a new set point gives no kick. `RST` clears the integral part.
+
+`RAMP`, `PT1` and `PID` depend on time: a diagram with them runs cyclically.
+
+Timers and counters:
+
+- `BLINK` - while `EN` is true, `Q` is true for `TH` and false for `TL`, beginning with true.
+- `CTU` counts the rising edges of `CU`; `R` sets `CV` back to 0, `Q` is true once `CV` reached `PV`. `CTD`
+  counts down on `CD`, `LD` loads `PV`, `Q` is true at 0 and below. `CTUD` does both; `R` goes before `LD`, and
+  edges of `CU` and `CD` in the same cycle cancel out. An input that is already true when the script starts is no
+  edge. The count is not kept over a restart of the script.
+
+Conversion: `TO_BOOL`, `TO_INT`, `TO_REAL`, `TO_TIME` and `TO_STRING` take any type. `TO_INT` rounds, a decimal
+comma counts as a point, and what is no number gives 0; `TO_TIME` reads a number as ms and a text like `2s` or
+`08:30`. `CONCAT` joins its inputs into one text - numbers as they are, so round them with `ROUND` first (`DIGITS`
+decimals, 0 to 10).
+
+The calendar:
+
+- `CLOCK` - the local time: `TOD` (time of day), `HOUR`, `MIN`, `WDAY` (1 Monday ... 7 Sunday), `DAY`, `MONTH`,
+  `YEAR`.
+- `TIMEWINDOW` - `Q` is true from `START` to `END` on the chosen days (every day, Monday to Friday, Saturday and
+  Sunday). A window over midnight, like `22:00` to `06:00`, belongs to the day it starts on: on Monday to Friday it
+  lasts from Friday night into Saturday morning, but not from Sunday night into Monday.
+- `SCHEDULE` - `Q` is true for one cycle when the time of the cron pattern comes, like `0 8 * * 1-5` for 8:00 on
+  Monday to Friday, or with seconds in front `*/5 * * * * *` for every 5 seconds. The button next to the field opens the dialog for the pattern.
+- `ASTRO` - `Q` is true from one event of the sun to another, like from `sunset` to `sunrise`, each with an offset
+  in minutes. `START` and `END` are the times of the two events today. The position is the one in the settings of
+  the adapter; without it there are no times, and `Q` stays false.
+
+`CLOCK`, `TIMEWINDOW` and `ASTRO` make a diagram run cyclically. `SCHEDULE` does not: when its time comes, the
+diagram runs at once, and once more right after it to end the pulse.
+
+- `STATE_IN` reads a state and converts it to the chosen type (`BOOL`, `INT`, `REAL`, `STRING`). A value that
+  cannot be converted is reported once in the log and read as 0. When the state ID changes - picked in the dialog
+  or typed - the type is taken from the object of the state, and a block that still has its first name is named
+  after the state. The type can be set differently afterwards; it is taken again only with the next ID.
+- `STATE_OUT` writes a state only when the value changes. `Minimum time between writes` limits how often it
+  writes; the last value is written when the time is over.
+- `CONST` is a value of the chosen type. Linked to an input of another type, it takes the type of the input and
+  keeps its value as far as it goes (`"0"` becomes 0 ms for a `TIME`) - unless it feeds other inputs already that
+  the new type would not fit.
+
+The messages:
+
+- `LOG` writes a line into the log of ioBroker, with the chosen level (`info`, `warn`, `error`, `debug`): on a
+  rising edge of `TRIG`, or whenever `IN` changes. `%s` in the text is the value of `IN`. At most 20 lines a minute -
+  a diagram that runs every 200 ms would flood the log otherwise; the 20th line says so.
+- `NOTIFY` sends the text as a notification of ioBroker - a message or an alert - and `SENDTO` to an adapter like
+  `telegram.0`, `pushover.0` or `email.0`, as `{ text, message, title, subject }` with the chosen command (`send`).
+  Both send when `LOG` would write, at most 5 times a minute; the log says when more were left out.
+
+The expert block `JS` runs code of its own. The code is the body of a function that gets the inputs `IN1` ...
+`INn` (0 to 8, of any type), `dt` (ms since the last cycle), `firstScan` and `state` - an object that is kept from
+one cycle to the next. It returns the value of `OUT1`, or an array `[OUT1, OUT2, ...]` for more outputs (1 to 8);
+where it gives `undefined`, an output keeps its value. The outputs may be connected to inputs of any type, so the
+code has to put out what they expect.
+
+```js
+// counts how often IN1 went above IN2
+if (IN1 > IN2 && !state.above) {
+    state.count = (state.count || 0) + 1;
+}
+state.above = IN1 > IN2;
+return state.count || 0;
+```
+
+The code runs in the script of the diagram, so it can call the functions of scripts like `log()` - but it should
+not wait for anything: the next block needs its outputs at once. A syntax error is shown before the diagram is
+saved, an error when it runs at the block.
+
+Signal types: `BOOL`, `INT`, `REAL`, `TIME`, `STRING`. An `INT` may be connected to a `REAL` input; other
+conversions are not done by themselves.
+
+## Own blocks
+
+A diagram can be a block itself, which other diagrams use as often as they like - like a function block in a PLC.
+Switch on **This diagram is a block** in the settings of the diagram and give the block a name and a description.
+
+- The inputs of the block are `FB_IN` blocks, its outputs `FB_OUT` blocks (category **Interface**, only offered in
+  the diagram of a block). The pin name is what the input or output is called on the block; `FB_IN` also has a type
+  and the value the input has when it is not connected.
+- A block has no access to states: `STATE_IN` and `STATE_OUT` are not allowed in it, `CONST` is. It may use other
+  own blocks, but not itself.
+- Every instance has its own state - two instances of a block with a timer time independently.
+- The script of a block does nothing when it runs; the block only works in the diagrams that use it.
+
+The blocks of all diagrams are offered in the palette under **Own blocks**. The diagram that uses a block stores a
+copy of it, and with it the version: every saved change of a block is a new version. The diagrams that use an older
+one keep working with it and show a notice - **Update** in the properties of an instance takes the new version into
+the diagram, **Open block** opens the diagram of the block. Links to inputs or outputs that no longer exist are
+removed by the update.
+
+Because the copy is stored with the diagram, a diagram keeps working when the block is deleted, and it can be
+exported and imported alone. Copying instances into another diagram takes the block along.
+
+An error in a block is reported at the instance that ran it, in the editor and in the log.
+
+## Execution
+
+The blocks run in the order of the data flow; the number in the corner of each block is its position. Blocks that
+could run at the same time run from left to right, then from top to bottom.
+
+- **Event driven**: when no block depends on time, the diagram runs whenever an input changes. Changes within
+  20 ms run together in one cycle.
+- **Cyclic**: as soon as the diagram contains a timer, it runs every 200 ms (50 ms to 10 s, see the settings of
+  the diagram), and additionally right after an input changed.
+
+The execution mode is chosen automatically, or can be set in the settings of the diagram.
+
+A loop is only allowed through a block that stores a value (timer, counter, flip-flop, edge, control block,
+`JS`, own block): the link that leads back
+reads what that block put out in the previous cycle and is drawn as a double line. A loop without such a block
+is an error.
+
+A timer counts from the cycle in which it sees its input change, so it never expires before its time - at most
+one cycle later.
+
+## Limits
+
+- Not for safety related functions. A diagram runs in a script of ioBroker, without real time guarantees.
+- The state of the blocks is not kept over a restart of the script.
+- Not yet available: breakpoints inside an own block, a manual execution order, links routed around blocks.
+
+## Storage
+
+The diagram is stored in the script itself, as the last line of `common.source` (`//#fbd:{...}`); the lines above
+are the generated code. The diagram includes the copies of the own blocks it uses. The blocks of the library are implemented in the module `@iobroker/fb-runtime`, which comes with the
+adapter, and not copied into every script.