diff --git a/README.md b/README.md index a1b129a..9df2209 100755 --- a/README.md +++ b/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