Mehr Doku

README.md

@@ -6,12 +6,29 @@ lang: de
 
 # KsKit für Eisenbahn.exe
 
-KsKit sind ein paar Lua-Scripte, welche ich auf meinen Anlagen nutze.
+Ich hatte mir nicht lange nach EEP16 die Zusatz-Modelle V15NGK30267 und V15NGK30268 dazugekauft.
-Von denen habe ich ein paar Dokumentiert, sie sind bisweilen recht nützlich.
+Die darin enthaltenen Ks-Signale haben sehr viele Stellungen, mit denen sich komplexe Signalsituation wie die herabgestufte Signalisierung oder den Halbregelabstand realisieren lassen.
-Es ist auch immer dazugeschrieben, welche Vorraussetzungen man braucht.
+Der Einbau auf meinen Anlagen war aber alles andere als einfach:
+
+- EEP16 kann nur einfache Signalverknüpfungen mit einer Bedingung und einer Folge.
+  Das reicht nicht für Mehrabschnittssignale und auch nicht für die Verwendung der Zusatzanzeiger.
+  Eine Lösung mit Schaltkringeln ist möglich, habe ich auch hinbekommen, war mir aber vom Bauaufwand wesentlich unangenehmer als die Callbacks dazu händisch zu schreiben.
+  Im Bahnhofsvorfeld wird das auch mit den Callbacks sehr schwer überschaubar.
+- Damit die Mehrabschnittssignale auch für sie normale Signalbilder zeigen dürfen, müssen auch mehrere Abschnitte geschaltet sein.
+  Bisherige Lua-Schaltungen für Fahrstrassen schalten lediglich einen einzelnen Abschnitt.
+
+Daraus ergaben sich dann die zwei Kernbestandteile von KsKit:
+
+- Die Callback-Steuerung `On`:
+  Ürsprünglich als Bequemlichkeitstool für schnelles Lua-Scripting entwickelt, hat sich dieses Modul in vielen meiner Experimente und Anlagen bewährt.
+  Mit der späteren Erweiterung um die Multi-Funktionen kristallisierte sich eine Lösung für die teilweise sehr komplexen Verschaltungen von Ks-Signalen und deren Zusatzanzeigern.
+- Die `Fahrstrassen`-Logik:
+  Eine mit dem RuS-Packet vergleichbare Schaltung, welche aber auch das Schalten von Fahrstrassenketten sicher beherrscht.
+  Damit können an jedem Signal beliebig viele Folgeabschnitte abhängig voneinander geschaltet werden.
 
 Alle Scripte können [hier](https://github.com/nero/kskit/archive/refs/heads/master.zip) als Zip-Datei heruntergeladen werden, die lässt sich dann wie ein Modell installieren.
 Die Scripte werden unterhalb vom LUA-Ordner im EEP-Stammverzeichnis installiert.
+Demoanlagen sind auch mit drin, die benötigen aber teilweise das Ks-Signalset von GK3.
 
 ## On-Modul
 
@@ -180,7 +197,7 @@ Das sind z.b. Weichen, Zs3-Zusatzanzeiger von Hauptsignalen, einzeln stehende Zs
 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.
+Werden mehrere Fahrwegelemente gleichzeitig umgestellt (z.b. durch Fahrstrasse), werden die Callbacks der Einzelelemente als ein Aufruf 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.
@@ -221,11 +238,11 @@ Eine Demo mit AH1-Mehrabschnittsignalen (Grundbestand, denke ich) wird unter dem
 
 Die Lua-Umgebung wird von EEP in bestimmten Situationen zurückgesetzt und verliert dabei die Inhalte aller Variablen.
 Daher müssen persistente Werte via `EEPSaveData` gespeichert und nach dem Reset wieder geladen werden.
-Bei Zeichenketten und Zahlen ist das kein Problem, das Speichern von Tabellen ist nicht ohne umwege möglich.
+Bei Zeichenketten und Zahlen ist das kein Problem, das Speichern von Tabellen ist nicht ohne Umwege möglich.
 
 KsKit bringt einen Serializer mit, der in der Lage ist, die gängigen Lua-Daten und Tabellen in eine Zeichenkette zu serialisieren.
 
-### Funktion serialize
+### serialize(Tabelle)
 
 Die `serialize`-Funktion ist das Herz des Serializers.
 Sie nimmt ein Argument und gibt eine Zeichenkette zurück.
@@ -248,11 +265,13 @@ print(serialize(Tabelle))
 Unterstützt werden Wahrheitswerte, Zeichenketten, Zahlen und einfach verschachtelte Tabellen.
 Lambda-Funktionen werden ignoriert, ebenso wie rekursiv in sich selbst verschachtelte Tabellen.
 
-### Funktion speicherTabelle
+### speicherTabelle(Slot, Tabelle)
 
 Diese Funktion macht genau das, was der Name vermuten lässt.
 Eine Lua-Tabelle wird in einem EEPSlot abgespeichert.
 
+Man beachte, das ein Slot maximal etwa 1000 Zeichen abspeichern kann, bei zu großen Tabellen werden die Slotdaten abgeschnitten und sind dann ungültig.
+
 Das erste Argument zu der Funktion ist dabei die Slotnummer, das zweite Argument eine Lua-Tabelle.
 
 Die Tabelle wird mittels `serialize` in eine Zeichenkette umgewandelt.
@@ -276,7 +295,7 @@ speicherTabelle(1, Tabelle)
 -- DS_1 = "{bol=true,lst={1,2,3},str=%22abcdef%22}"
 ```
 
-### Funktion ladeTabelle
+### ladeTabelle(Slot)
 
 Das pendant zu `speicherTabelle`.
 Als Argument wird die Slotnummer übergeben, als Return-Wert erhält man die vorher gespeicherte Tabelle zurück.
@@ -294,7 +313,7 @@ print(serialize(ladeTabelle(1)))
 
 ### Praxisbeispiel
 
-Es ist nicht notwendig, eine Tabelle vor jeder Benutzung zu laden und wieder zu speichern.
+Es ist nicht unbedingt notwendig, eine Tabelle vor jeder Benutzung zu laden und wieder zu speichern.
 
 Viel schneller ist es, die Tabelle als globale Variable zu halten und nur beim Lua-Start einmal einzulesen.
 Die Tabelle kann dann wie jede andere Tabelle verwendet werden.