Dokumentation für MultiOn und MultiSchalten

README.md

@@ -65,52 +65,62 @@ Ebenfalls werden zwei größere Fehlerquellen ausgeschlossen:
 
 Zum Beispiel können eine Vorsignalsteuerung und eine Türsteuerung beide einen Callback auf das Abfahrtssignal registrieren, ohne voneinander zu wissen zu müssen.
 
-### On
+### On(CallbackName, Funktion)
 
-So wie das Modul heisst auch die zentrale Funktion.
-Diese registriert eine Funktion für einen EEP-Callback.
-Das Anlegen der Callback-Funktion wird bei dem Registrieren der ersten Funktion vorgenommen.
-Dabei wird, falls notwendig, der Callback von `On` auch bei EEP registriert.
-Das händische Aufrufen von `EEPRegister*` entfällt!
+Bildet das Rückgrat dieses Modules.
+Diese Funktion wird im Hintergrund von allen anderen Funktionen des `On`-Moduls benutzt.
+In der Regel verwendet man eine der folgenden Funktionen.
 
-Als erster Parameter wird dabei der Name des Callbacks als String übergeben.
-Als zweiter Parameter wird eine Funktion übergeben.
+- Parameter 1: Name des Callbacks als String
+- Parameter 2: Callback-Code als Funktion
+- Rückgabewert: keiner
 
-Man beachte die Syntax: Es wird eine Funktion ohne Namen verwendet, ebenfalls ist die Funktion innerhalb der Parameterübergabe definiert.
-Die Funktion wird nicht ausgeführt, sondern selbst als Wert übergeben.
+Ist Parameter 1 `EEPOnSignal_x` oder `EEPOnSwitch_x`, wird für das jeweilige `x` der Callback mittels `EEPRegister...` bei EEP registriert.
 
-Der übergebenen Funktion werden die Callback-Parameter weitergeleitet, als wäre sie selbst von EEP aufgerufen worden.
+Der Funktion im Parameter 2 werden die Parameter übergeben, welche das `On`-Modul von EEP erhalten hat.
 
 ```
 require("kskit\\On")
 
 On("EEPOnTrainCoupling", function(Zug_A, Zug_B, Zug_neu)
-  print(" Aus "Zug_A.." und "..Zug_B.." wurde "..Zug_neu)
+  print("Aus "Zug_A.." und "..Zug_B.." wurde "..Zug_neu)
 end)
 ```
 
-Das ganze in längerer Form mit Umweg über eine Variable:
+### Main(Funktion)
+
+Bindet ein Stück Programmcode an die EEPMain.
+
+- Parameter 1: Der Code in Form einer Funktion
+- Rückgabewert: keiner
+
+Beispielcode:
 
 ```
 require("kskit\\On")
+require("Zugtuersteuerung_FS2.lua")
 
-callback4=function(Zug_A, Zug_B, Zug_neu)
-  print(" Aus "Zug_A.." und "..Zug_B.." wurde "..Zug_neu)
-end
+Main(function()
+  print(EEPTime)
+end)
 
-On("EEPOnTrainCoupling", callback4)
+-- RUS-Packet von Parry36 aktivieren
+Main(inEEPMain)
+-- Zugtuersteuerung vom Fried aktivieren
+Main(BewegeZugtueren)
 ```
 
-Diese Funktion wird im Hintergrund von allen anderen Funktionen des `On`-Moduls benutzt.
+### OnSignal(SignalID, Funktion)
 
-### OnSignal
+Bindet ein Stück Programmcode an einen Signal-Callback.
 
-Die wohl meistgenutzte Funktion dieses Modules.
-Als ersten Parameter nimmt sie die ID eines Signales, als zweiten Parameter nimmt sie eine Funktion.
-Die übergebene Funktion bekommt die Parameter wie üblich übergeben.
-Der Aufruf von `EEPRegisterSignal` erfolgt automatisch.
+- Parameter 1: Die ID des Signals als Zahl
+- Parameter 2: Der Code in Form einer Funktion
+- Rückgabewert: keiner
 
-Hier werden zwei anonyme Funktionen an ein Signal gebunden:
+Der Funktion im Parameter 2 wird die Stellung des Signales als Parameter übergeben.
+
+Ist ID kein Signal, wird eine Warnung im Ereignisfenster ausgegeben.
 
 ```
 require("kskit\\On")
@@ -124,41 +134,88 @@ OnSignal(3, function(Stellung)
 end)
 ```
 
-Man beachte die sich schließende Klammer nach dem `end`.
-
-Es können auch vorhandene Funktionen mittels Namen an `OnSignal` übergeben werden:
-
-```
-require("kskit\\On")
-
-OnSignal(4, print)
-```
-
-In dem Falle wird die neue Signalstellung direkt an `print` weitergegeben und ausgegeben.
-
-### OnSwitch
+### OnSwitch(WeichenID, Funktion)
 
+Bindet ein Stück Programmcode an einen Weichen-Callback.
 Das selbe wie `OnSignal`, nur für Weichen statt für Signale.
 
-### Main
+- Parameter 1: Die ID der Weiche als Zahl
+- Parameter 2: Der Code in Form einer Funktion
+- Rückgabewert: keiner
 
-Jetzt muss man wissen, die `EEPMain` ist auch nur ein Callback, mit dem Unterschied, das er ohne Grund immer wieder aufgerufen wird.
-Dafür gibt es in diesem Modul eine `Main`-Funktion.
-Diese Funktion nimmt nur einen Parameter, jener beinhaltet die Funktion, welche an die `EEPMain` gebunden werden soll.
+Der Funktion im Parameter 2 wird die Stellung der Weiche als Parameter übergeben.
+
+Ist ID keine Weiche, wird eine Warnung im Ereignisfenster ausgegeben.
+
+### MultiOn(IDs, Funktion)
+
+Diese Funktion bindet ein Stück Code an mehrere Signale/Weichen.
+
+- Parameter 1: Eine Liste von Signal/Weichen-IDs als Tabelle mit Zahlen
+- Parameter 2: Der Code in Form einer Funktion
+- Rückgabewert: keiner
+
+Vergleichbar mit OnSignal/OnSwitch, jedoch zwei große Unterschiede:
+
+- An Stelle einer ID wird eine Tabelle von IDs übergeben
+- Die IDs dürfen sich sowohl auf Weichen als auch auf Signale beziehen
+- Der Funktion in Parameter 2 werden alle Stellungen der Signale/Weichen als einzelne Parameter übergeben
+
+Daraus folgt, das die Funktion in Parameter 2 genauso viele Parameter nehmen muss, wie IDs in Parameter 1 eingetragen sind.
+
+Anwendungsbeispiel:
 
 ```
 require("kskit\\On")
-require("Zugtuersteuerung_FS2.lua")
 
--- Definitionen für RUS-Packet hier
-
--- RUS-Packet von Parry36 aktivieren
-Main(inEEPMain)
--- Zugtuersteuerung vom Fried aktivieren
-Main(BewegeZugtueren)
+MultiOn({7,8,2}, function(HS, Zs3, Weiche)
+  print("Hauptsignal zeigt ",HS,", Zs3 ",Zs3)
+  print("Weiche ist auf ",Weiche," gestellt")
+end)
 ```
 
-`Main(...)` ist auch nichts weiteres als ein Bequemlichkeits-Aufruf von `On("EEPMain", ...)`
+Diese Funktion wurde entworfen, damit einzeln platzierbare Vorsignale auch im Weichenbereich vorbildnahe Begriffe zeigen können.
+Für diesen Anwendungsfall werden in der ID-Liste alle Fahrwegelemente angegeben, welche das Vorsignal beeinflussen können.
+Das sind z.b. Weichen, Zs3-Zusatzanzeiger von Hauptsignalen, einzeln stehende Zs3-Anzeiger und vor allem Hauptsignale.
+Im Funktionskörper können die Stellungen dann überprüft werden und abhängig davon das Vorsignal und mögliche Zs3v-Zusatzanzeiger gestellt werden.
+Ein Beispiel dafür (ohne Weichen, benötigt Ks-Signale von GK3) findet sich in der mitgelieferten Demo `MultiOn_KS_Vorsignal_GK3`.
+
+Werden mehrere Fahrwegelemente gleichzeitig umgestellt (z.b. durch Fahrstrasse), werden die Callbacks der Einzelelemente zusammengefasst.
+
+In Verbindung mit eingestellten Signalverzögerungen können die Stellungen der Fahrwegelemente falsche Werte enthalten.
+Dies passiert, wenn Elemente aus der Gruppe umgestellt werden, bevor die Signalverzögerungen aller Elemente abgelaufen sind.
+Dies ist eine Limitation der `EEPGetSignal`-Funktion.
+
+### MultiSchalten(Wenn, Dann)
+
+Diese Funktion erstellt eine Signalverknüfung mit mehr als zwei Elementen.
+
+- Parameter 1: Bedingungs-Liste von Signal/Weichen-IDs und deren Stellungen
+- Parameter 2: Folgen-Liste von Signal/Weichen-IDs und deren Stellungen
+- Rückgabewert: keiner
+
+Beide Parameter haben das gleiche Schema.
+`{4,2,7,1}` bedeutet Signal/Weiche 4 in Stellung 2 und Signal/Weiche 7 in Stellung 1.
+Der erste Parameter gibt die Stellungen an, welche erfüllt sein müssen.
+Ist dies der Fall, werden die Stellungen aus dem zweiten Parameter auf der Anlage angewendet.
+
+Diese Funktion stellt einen häufigen Spezialfall von `MultiOn` dar: Blockabschnitte mit Mehrabschnittssignalen.
+Mehrabschnittssignale sind Hauptsignale mit Vorsignalfunktion.
+Wird ein Blockabschnitt freigeschaltet, wird das Blocksignal auf `Halt erwarten` gestellt, um das nächste Signal anzukündigen.
+Wird der Folgeabschnitt freigeschaltet, wird das Folgesignal ebenfalls auf `Halt erwarten` gestellt, und unser Blocksignal kann auf `Fahrt` gestellt werden, wenn es noch nicht Aufgrund der Zugdurchfahrt auf `Halt` zurückgefallen ist.
+Daraus ergeben sich zwei Bedingungen, beide Signale müssen `Halt erwarten` zeigen, damit das vorherige auf Fahrt gestellt werden darf.
+
+Mit dieser Funktion geht das mit einem Einzeiler je Blockabschnitt:
+
+```
+require("kskit\\On")
+
+-- 4 und 5 sind identische MA-Signale
+-- 2 ist Halt erwarten, 3 ist Fahrt
+MultiSchalten({4,2,5,2},{4,3})
+```
+
+Eine Demo mit AH1-Mehrabschnittsignalen (Grundbestand, denke ich) wird unter dem Namen `MultiSchalten_MAS` mitgeliefert.
 
 ## Serializer: Tabellen in EEP-Slots speichern