Jump to content

  • Steuerung über externe Schnittstelle (API)

    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 verwenden dabei das JSON-RPC-Format und werden über eine TCP-Netzwerkverbindung zwischen den Programmen ausgetauscht. Jeder JSON-RPC-Request muss als eine Textzeile (UTF-8) gesendet werden, die mit einem Linefeed abschließt.

    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 über Port 31385 und die Ereignis-Verbindung über Port 31386 aufgebaut. 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.

    Datentypen

    Die Kommunikation zwischen Studio und dem externen Programm basiert auf JSON. Einfache Datentypen wie Zeichenketten, Zahlen oder Listen verwenden die entsprechenden JSON-Datentypen. Tabellen im Studio werden als JSON-Objekte versendet. Studio-Objekte wie z.B. 3D-Modelle, Ereignisse oder Fahrstraßen werden ebenfalls als JSON-Objekte interpretiert, in der Form:

    • Feld _class: Gibt die Objektklasse an (table, keyword, time, entity, event oder route)
    • Feld name: Gibt den Namen des Objekts an

    Kommandos

    Folgende Übersicht listet alle zur Verfügung stehenden Kommandos mit Beispielaufrufen auf: 

    {"jsonrpc": "2.0", "method": "app.getInfo", "id": 1}
{"jsonrpc": "2.0", "method": "layout.invokeScript", "params": "print('Hallo Welt') return 42", "id": 1}
{"jsonrpc": "2.0", "method": "layout.invokeUserEvent", "params": {"event": {"_class": "event", "name": "Benutzerdefiniert"}, "params": {"Bool": true, "Zahl": 42}}, "id": 1}

{"jsonrpc": "2.0", "method": "editor.getEntityContentID", "params": {"_class": "entity", "name": "Gleis 1"}, "id": 1}
{"jsonrpc": "2.0", "method": "editor.createEntity", "params": "F38B36A9-E8A0-4943-B3D8-00D78185EDA9", "id": 1}
{"jsonrpc": "2.0", "method": "editor.deleteEntity", "params": {"_class": "entity", "name": "Gleis 1"}, "id": 1}
{"jsonrpc": "2.0", "method": "editor.cloneEntity", "params": {"_class": "entity", "name": "Gleis 1"}, "id": 1}

{"jsonrpc": "2.0", "method": "editor.groupEntities", "params": [{"_class": "entity", "name": "Gleis 1"}, {"_class": "entity", "name": "Gleis 2"}, {"_class": "entity", "name": "Gleis 3"}], "id": 1}
{"jsonrpc": "2.0", "method": "editor.ungroupEntities", "params": {"_class": "entity", "name": "Gruppe"}, "id": 1}

{"jsonrpc": "2.0", "method": "editor.getSelectedEntities", "id": 1}
{"jsonrpc": "2.0", "method": "editor.setSelectedEntities", "params": [{"_class": "entity", "name": "Gleis 1"}], "id": 1}

    Das Kommando "layout.invokeScript" führt das übergebene Lua-Skript direkt im Kontext der Ereignisverwaltung auf. In dem Skript stehen daher alle Funktionen und Eigenschaften zur Verfügung, die auch in einem Lua-Skript innerhalb eines Ereignismoduls zur Verfügung stehen. Die Netzwerkschnittstelle hat somit Zugriff auf alle Informationen, auf die auch der Anlagenbauer mit Hilfe von Ereignissen zugreifen kann.

    Ereignisse

    Folgende Ereignisse sendet das Studio an die Steuerschnittstelle: 

    {"jsonrpc": "2.0", "method": "layout.loaded", "params": ["{C92654A6-16BB-4722-8CE5-11448BC94FA5}"]}
{"jsonrpc": "2.0", "method": "layout.closed", "params": ["{C92654A6-16BB-4722-8CE5-11448BC94FA5}"]}

{"jsonrpc":"2.0", "method": "layout.eventTriggered", "params": {...}}
{"jsonrpc":"2.0", "method": "layout.eventNotify", "params": {...}}

    Das Ereignis "layout.eventTriggered" wird für jedes Ereignis in der Anlage gesendet, während "layout.eventNotify" vom Nutzer ausgelöst wird, durch die EV-Aktion "Netzwerkkommando senden". Der Nutzer kann dabei einen beliebigen Namen und Parameter wählen.

    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ü "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.
     Teilen
    Zurück zu Wiki-Artikel


×
×
  • Neu erstellen...