Steuerung über externe Schnittstelle (alte Version)

3D-Modellbahn Studio stellt eine Programmierschnittstelle zur Verfügung, mit der das Studio über externe Programme um zusätzliche Funktionen erweitert werden kann, um somit noch komplexere Anlagenbetriebe zu ermöglichen. Die Schnittstelle ermöglicht das Abfragen von Zuständen, das Bearbeiten von Objekten sowie das Reagieren auf Ereignisse in eigens entwickelten Programmen. Zusätzlich können mit vorgefertigten Programmen, die von anderen Benutzern kostenfrei zur Verfügung gestellt werden und die ebenfalls die Steuerschnittstelle verwenden, die eigenen Anlagen einfach erweitert werden. Die Schnittstelle steht jedem Benutzer von 3D-Modellbahn Studio Professional zur Verfügung.

Technische Grundlagen

Die Steuerschnittstelle des 3D-Modellbahn Studios unterscheidet zwischen Kommandos und Ereignissen. Ein Kommando stellt dabei einen Befehl dar, den das externe Programm an das Studio sendet und der verarbeitet werden soll. Ein Ereignis hingegen wird vom Studio an das externe Programm übermittelt, falls auf der Anlage eine entsprechende Veränderung auftritt. Kommandos und Ereignisse sind dabei einfache Textzeilen, die über eine TCP-Netzwerkverbindung zwischen den Programmen ausgetauscht werden.

Das 3D-Modellbahn Studio verwendet für die Kommandos und Ereignisse zwei getrennte TCP-Verbindungen, sodass Kommandos und Ereignisse immer getrennt voneinander übertragen werden. Dies vereinfacht die Programmierung externer Programme, da diese ebenfalls den Code strikt nach Kommandos und Ereignissen trennen können und keine Vermischung behandeln müssen. Auch benötigt ein Programm z.B. keine Ereignis-Verbindung, wenn dieses nicht an den Ereignissen interessiert ist.

Die Kommando-Verbindung wird standardmäßig über Port 31285 und die Ereignis-Verbindung über Port 31286 aufgebaut. Beide Ports können in den Programmeinstellungen des 3D-Modellbahn Studios geändert werden. Bei der Installation des 3D-Modellbahn Studios wird die Windows-Firewall automatisch konfiguriert. Wird eine andere Firewall verwendet, so muss sichergestellt werden, dass eingehende und ausgehende TCP- und UDP-Verbindungen auf den beiden Ports freigegeben werden.

Eine Verbindung mit dem 3D-Modellbahn Studio wird über die IP bzw. den Host-Namen des Computers aufgebaut, auf dem das Studio läuft. Im lokalen Netzwerk bietet das Studio auch ein Broadcasting an, um ohne eine Eingabe der IP oder des Host-Namens eine Verbindung aufzubauen. Zu diesem Zweck sendet das externe Programm eine Broadcast-Nachricht (UDP) mit der Textzeile "{362E4489-482E-4E45-B782-43F80FF58809}" (ohne Anführungsstriche) in das lokale Netzwerk. Empfängt ein Computer mit laufendem 3D-Modellbahn Studio diesen Text, so sendet dieses den gleichen Text an den Sender zurück, wodurch das externe Programm Kenntnis über die IP des 3D-Modellbahn Studios erlangt.

Kommandos

Ein Kommando, welches über die TCP-Verbindung an das 3D-Modellbahn Studio gesendet wird, besitzt folgendes Format:

Eine ID (Zahl), die den Befehl identifiziert
Eine beliebige Liste von Parametern, die abhängig vom Kommando den Befehl genauer spezifizieren
Ein Linefeed (Zeilenvorschub), um das Ende einer Kommandozeile zu markieren

Die ID und die Parameter sind jeweils durch ein Semikolon (;) voneinander getrennt. Die Textzeile "5;Parameter 1;Parameter 2;Parameter 3" ist ein Beispiel für ein gültiges Kommando mit der ID 5 und 3 Parametern (der Zeilenvorschub ist hier nicht abgebildet).

Empfängt das 3D-Modellbahn Studio ein Kommando, wertet es dieses samt den Parametern aus und führt den Befehl entsprechend aus. Anschließend sendet das Studio auf der gleichen TCP-Verbindung eine Antwort zurück, die das Ergebnis des Befehls beinhaltet. Die Antwort ist dabei ebenfalls eine Textzeile mit folgendem Format:

Ergebniscode 0 oder 1 für einen nicht erfolgreichen bzw. erfolgreichen Befehl
Eine beliebige Liste von Parametern, die im Falle eines nicht erfolgreichen Befehls weitere Fehlerdetails und im Falle eines erfolgreichen Befehls das Ergebnis beinhalten
Ein Linefeed (Zeilenvorschub), um das Ende der Antwort zu markieren

Der Ergebniscode und die Antwortparameter sind ebenfalls durch ein Semikolon voneinander getrennt, z.B. "0;Falscher Parameter" für einen nicht erfolgreichen Befehl oder "1;Bodenplatte;Dampflok" für einen erfolgreichen Befehl mit zwei Rückgabewerten.

Das 3D-Modellbahn Studio sendet auf jedes Kommando eine Antwort zurück, unabhängig ob der Befehl erfolgreich verarbeitet werden konnte oder nicht. Ein zweites Kommando darf daher erst dann versendet werden, wenn die Antwort des ersten Kommandos empfangen wurde (eine Ausnahme spielen hier Kommandogruppen). Eine Antwort wird auch dann gesendet, wenn der Befehl keine Rückgabewerte ausgibt. In diesem Fall wird nur der Ergebniscode ohne Parameter zurückgesendet.

Kommandogruppen

Jedes Kommando, welches an das 3D-Modellbahn Studio gesendet wird, wird sofort von diesem bearbeitet. Mehrere versendete Kommandos werden nacheinander abgearbeitet, wobei der Nutzer zwischen den Kommandos auch andere Aktionen im Programm ausführen kann. Diese mögliche Unterbrechung der Abarbeitung von Kommandos durch den Nutzer kann durch die Nutzung von Kommandogruppen umgangen werden. Eine Kommandogruppe stellt für das 3D-Modellbahn Studio eine Sammlung von Kommandos dar, die immer als Einheit ausgeführt werden, ohne dass der Nutzer in der Zwischenzeit durch eine andere Aktion im Programm den Zustand ändern kann. Kommandogruppen eignen sich daher bei mehreren Aktionen, die aufeinander aufbauen (z.B. drehen und positionieren eines Objektes).

Das Gruppieren von Kommandos geschieht durch zwei explizite Einzelkommandos (10 und 11). Durch Senden des Kommandos 10 wird dem Studio mitgeteilt, dass alle folgende Kommandos Teil einer Gruppe sind und zusammen abgearbeitet werden sollen. Mit dem Senden des Kommandos 11 wird die Gruppe beendet, wodurch nachfolgende Kommandos wieder als Einzelkommandos betrachtet werden.

Im Gegensatz zu den Einzelkommandos werden die Kommandos, die innerhalb einer Gruppe versendet werden, nicht sofort, sondern lediglich zwischengespeichert und erst beim Beenden der Gruppe (Kommando 11) verarbeitet. Das bedeutet auch, dass auf ein Gruppenkommando keine sofortige Antwort vom 3D-Modellbahn Studio gesendet wird. Die Antwort wird erst nach Beendigung der Gruppe versendet. Beispiel:

Senden der Kommandos
1. Start der Gruppe: Kommando 10
2. Kommando X
3. Kommando Y
4. Kommando Z
5. Beenden der Gruppe: Kommando 11 -> Jetzt beginnt die Verarbeitung aller gesendeten Kommandos
Empfang der Antworten

Antwort von Kommando 10
Antwort von Kommando X
Antwort von Kommando Y
Antwort von Kommando Z
Antwort von Kommando 11

Da die Antworten der Einzelkommandos erst nach dem Beenden der Gruppe gesendet werden, können nur solche Kommandos gruppiert werden, deren Parameter nicht von dem Ergebnis eines vorhergehenden Gruppenkommandos abhängen.

Ereignisse

Tritt auf der geöffneten Anlage ein Ereignis ein, so informiert das 3D-Modellbahn Studio ein extern verbundenes Programm über die Ereignis-Verbindung. Ein Ereignis wird z.B. ausgelöst, wenn ein Zug ein Gleis betritt oder ein Schalter betätigt wird. Ein einzelnes Ereignis besitzt dabei folgendes Format:

Eine ID (Zahl), die den Ereignistyp spezifiziert
Eine beliebige Liste von Parametern, abhängig des Ereignisses, die weitere Informationen zum aufgetretenen Ereignis beinhalten
Ein Linefeed (Zeilenvorschub), um das Ende eines Ereignisses zu markieren

Ereignisse werden automatisch vom 3D-Modellbahn Studio versendet. Die Ereignis-Verbindung wird dabei nur zum Senden verwendet, d.h. das Studio erwartet keine Antwort auf der Ereignis-Verbindung. Reaktionen auf Ereignisse müssen per Kommando über die Kommando-Verbindung gesendet werden.

Datentypen

Die Kommandos und Ereignisse werden immer in Textform (UTF8-kodiert) übertragen. Dennoch erwartet das 3D-Modellbahn Studio die Parameter je nach Befehl in einer bestimmten Form bzw. Datentypen:

String: Definiert eine Zeichenkette und wird nicht speziell interpretiert.
Boolean: Definiert einen Zustand mit zwei Werten (Wahr/Falsch bzw. An/Aus), wobei eine 0 als falsch/aus und eine 1 als wahr/an interpretiert wird.
Zahl: Definiert eine ganze Zahl, z.B. 5 oder -3.
Gleitkommazahl: Definiert eine gebrochene Zahl, z.B. 3.141 oder -100.9. Zu beachten ist, dass Gleitkommazahlen im englischen Format interpretiert werden, d.h. der Dezimaltrenner ist immer der Punkt.

Plugins

Die Steuerschnittstelle kann in beliebigen Programmen verwendet werden, um das 3D-Modellbahn Studio mit neuen Funktionen zu erweitern. Damit alle Nutzer einen schnellen und einfachen Zugriff auf die Programme erhalten, erlaubt das 3D-Modellbahn Studio die Integration der Steuerschnittstellenprogramme in den Online-Katalog (Plugins). Dadurch ergeben sich folgende Möglichkeiten:

Die Programme können direkt aus dem 3D-Modellbahn Studio heraus aufgerufen werden (Menü "Katalog - Plugins"), ohne diese manuell zu entpacken oder zu installieren
Aktualisierte Programme werden automatisch heruntergeladen, sodass alle Nutzer immer die neueste Version besitzen
Plugins können mit Anlagen verknüpft werden, sodass diese beim nächsten Öffnen der Anlage automatisch starten

Anforderungen

Plugins sind normale ausführbare Anwendungen, die jedoch ein paar Anforderungen erfüllen müssen, damit sie zum Online-Katalog hinzugefügt werden können:

Das Plugin muss aus einem beliebigen Verzeichnis heraus aufgerufen werden können. Das 3D-Modellbahn Studio entpackt ein Plugin automatisch in ein temporäres Verzeichnis vor dem Start und löscht es auch wieder nach Beendigung.
Alle Dateien, die das Plugin zur Ausführung benötigt, müssen im Plugin-Verzeichnis (oder Unterverzeichnis) mitgeliefert werden. Es gibt keine getrennte Plugin-Installation.
Das Plugin muss ohne Administrator-Rechte laufen und stellt wenn möglich automatisch eine Verbindung zum 3D-Modellbahn Studio her. Die verwendeten Ports für die Steuerschnittstelle werden beim Start übergeben (siehe Startparameter).
Programmeinstellungen dürfen nicht im Programmverzeichnis gespeichert werden (da dieses eh nach dem Beenden des Plugins gelöscht wird). Einstellungen sollten im DataDir abgespeichert werden (siehe Startparameter).
Das Plugin sollte idealerweise ohne Rückfragedialoge beendet werden, da das 3D-Modellbahn Studio Plugins automatisch beendet, wenn die Anlage geschlossen wird.
Zur Veröffentlichung im Online-Katalog wird eine Kurzbeschreibung, ein Vorschaubild (512 x 384 Pixel) und ein eigenes Thema im Plugin-Forum benötigt. Die Kurzbeschreibung muss den Link zum Forenthema enthalten. Das Thema sollte eine ausführliche Beschreibung enthalten und dient für Nutzer-Rückfragen.
Zusätzliche Dateien, die nicht zur Ausführung benötigt werden (wie z.B. der Quellcode oder Hilfedateien), sollten gesondert im Forumthema als separater Download angeboten werden.

Eine Sammlung vorhandener Plugins sind im Plugin-Forum zu finden.

Startparameter

Plugins werden direkt vom 3D-Modellbahn Studio gestartet und wieder beendet. Um die Kommunikation zwischen einem Plugin und dem Studio zu vereinfachen, übergibt das 3D-Modellbahn Studio einige Kommandozeilenparameter an das Plugin:

/DataDir:"Pfad" - Enthält den Namen eines Verzeichnisses, das das Plugin für dauerhafte Datenspeicherungen nutzen kann. Dieses Verzeichnis ist für jedes Plugin individuell und kann z.B. zum Speichern von Einstellungsdateien verwendet werden. Die Daten stehen auch beim nächsten Plugin-Start zur Verfügung und werden erst mit der Deinstallation des 3D-Modellbahn Studios gelöscht.
/Locale:Name - Enthält die im 3D-Modellbahn Studio eingestellte Sprache, sodass die Plugins ihre eigene Sprache anpassen können.
/CommandPort:Port - Enthält den Port für die Kommando-Verbindung zur Steuerschnittstelle.
/EventPort:Port - Enthält den Port für die Ereignis-Verbindung zur Steuerschnittstelle.

Liste der verfügbaren Kommandos und Ereignisse

Kommandos.pdf Ereignisse.pdf