Durch das X-Plane Plugin SDK wird Zugriff auf Kommandos und Daten-Referenzen zur Verfügung gestellt.

Durch die Entwicklung des Plugins ist es jetzt möglich mit dem USB-Controllers über Taster, Drehimpulsgeber und Schalter Kommandos an den Flugsimulator X-Plane zu senden, Variablen zu setzen und mit LEDs den Status von Variablen anzuzeigen.

Das Plugin unterstützt nur die Windows-Version von X-Plane.

Funktionsschema des X-Plane Plugins UCPControl

Das X-Plane Plugin kommuniziert direkt mit dem USB-Controller. Die Ereignisse an der Tastatur-Matrix und an den Eingabeports werden vom USB-Controller verarbeitet und entsprechend der Definitionen in der Konfigurationsdatei werden Kommandos gesendet oder Variablen verändert.

Das UCPControl-Plugin kann Variablen abfragen. Entsprechend der Definition in der Konfigurationsdatei werden diese Variablen zur Ansteuerung von Anzeigen an den Auspabeports genutzt.

Für die Verwendung der ITRA X-Plane Plugin ist eine X-Plane-Version höher 9.0 notwendig. Es müssen die aktuellen Treiber für die ITRA-Geräte installiert sein. Für die Verwendung der USB-Geräte installieren Sie bitte vor dem Anschluss des Gerätes an den PC das ITRA-USB-Treiberpaket.

Speicherort der ITRA X-Plane Plugins:
Das Plugin UCPControl.xpl muss manuell aus dem Installationsordner in den Plugin-Ordner des X-Plane kopiert werden, dieses Verzeichnis \Ressources\plugins liegt unterhalb des X-Plane-Installationsorders.

Speicherort der Konfigurations-Dateien der ITRA X-Plane Plugins:
Win7: C:\Users\Benutzername\AppData\Roaming\ITRA\X-Plane-Plugins
WinXP: C:\Dokumente und Einstellungen\Benutzername\Anwendungsdaten\ITRA\X-Plane-Plugins

Diese Ordner sind standardmäßig versteckt.

Die Konfigurationsdatei kann z.B. mit dem Editor (Programme → Zubehör) angezeigt und bearbeitet werden. Einen entsprechender Link zur Konfigurationsdatei wird bei der Installation im Programmordner erzeugt.

Wir empfehlen die Benutzung der mitgelieferten Konfigurations-Programme.

Das Paket finden Sie im ITRA-Support-Bereich auf Sim&IT. Es besteht aus dem Plugin und Tools zum Erstellen der Konfigurationsdateien.
→ Download ucpplugin-setup.zip

Starten Sie das Setup für die Installation der Plugin-Software.

Nach der Bestätigung der Lizenzbestimmungen erscheint die Komponenten-Auswahl.

In den nächsten Abfragen können Sie den Zielordner der Installation und den Menü-Ordner der Programm-Gruppe ändern. Mit „Fertigstellen“ ist die Client-Installation abgeschlossen.

Nach der Installation finden Sie in der Programmgruppe ITRA → X-Plane-Plugins die Dokumentation, drei Programme für das Erstellen und Bearbeiten der Konfigurationsdatei, Links zum Installationsordner und zur Konfigurationsdatei für manuelles Ändern der Konfigurationsdatei des UCPControl-Plugins.

Sie müssen das Plugin UCPControl.xpl aus dem ITRA-Installationsordner in den Plugin-Ordner des X-Plane kopieren. Dieses Verzeichnis \Ressources\plugins liegt unterhalb des X-Plane-Installationsorders.

Nach dem Starten des X-Plane finden Sie im Menü Plugins einen Menüpunkt

ITRA UCPControl für das Plugin des USB-Controllers.

UCPControl-Info zeigt Statusinformationen wie die Version, den Pfad zur geladenen Konfigurationsdatei und die Lizenzinformationen.

UCPControl-Licence dient der Eingabe der Lizenzinformationen. Ohne Lizenz ist das Plugin für 10 Minuten im Demo-Mode.

Über den Plugin Admin kann das UCPControl-Plugin deaktiviert und wieder aktiviert werden. Mit dem erneuten Aktivieren wird auch die Konfigurationsdatei erneut eingelesen, man kann also Änderungen an der Konfigurations-Datei vornehmen und im X-Plane damit übernehmen.

Deaktivieren Sie das Plugin mit dem Plugin Admin bei der gleichzeitigen Verwendung des Plugins und der Verwendung der Konfigurationsprogramme, mit denen der Controller abgefragt wird, da es ansonsten zu Konflikten in der USB-Kommunikation kommen kann.

Mit der Konfigurationsdatei werden den Taster- und Schalter-Ereignissen sowie den Ausgabe-Ports des USB-Controllers Kommandos und Daten-Referenzen zugewiesen. Die beiden Dateien Commands.txt und DataRefs.txt, in denen die Zeichenketten für Kommandos und Daten-Referenzen beschrieben sind, befinden sich im X-Plane-Unterordner \Ressources\Plugins. Die Zeichenketten werden bei der Definition der Tasten, Schalter und LEDs verwendet. Es werden dort auch Angaben zum Datentyp gemacht, die wichtig beim Zugriff auf die Daten-Referenzen sind.

Weitere Informationen können Sie auch über die X-Plane-SDK Web-Seite erhalten.
X-Plane Plugin SDK2 und X-Plane SDK3

Die Zeichenketten der Daten-Referenzen werden beim Setzen von Variablen und bei der Ansteuerung der Ausgabeports verwendet.

Bei der Erstellung der Konfigurationsdatei ist darauf zu achten, dass die richtige Zugriffsart auf die Daten-Referenzen gewählt wird. Hinter dem Referenzstring steht die Angabe zum Typ, ob die Daten-Referenz änderbar ist und oftmals auch der Wertebereich wie z.B. bool für {0,1}, Aufzählungstyp enum {0,1,2,3} für definierte Zustände, float {-1..1} für Gleitkommawerte zwischen -1 und 1.

int       Ganzzahl-Variable, auch für boolaen (0,1) verwendet
float     Gleitkomma-Variable
int[x]    Integer-Array, es ist über einen Index der Zugriff auf ein Feld-Element möglich
float[x]  Gleitkomma-Array, es ist über einen Index der Zugriff auf ein Feld-Element möglich

Der standardmäßig verwendete Dateiname für die Konfigurationsdatei ist ITRA-UCPControl.cfg.

Es gibt vier Sektionen in der Konfigurationsdatei:

[UCPControl]          Grundlegende Definitionen
INDEX=0               -> je nach programmiertem Index des 
                         USB-Controllers, Standard ist 0
DEBOUNCE=0            -> Entprellung (Wert*50ms)

[UCP_KEYS]            Definition der Tastenzuordnungen
Z0_S0                 -> String-Definition entsprechend der Dateien im Plugin-Ordner 
                         Commands.txt bzw. DataRefs.txt
Z0_S0_COMMANDMODE     -> {0 .. 4} Command, DataRef-Integer, DataRef-Float
                         DataRef-Array-Integer, DataRef-Array-Float
Z0_S0_ARG             -> Argument für DataRef-Mode
                         Ganzzahl- bzw. Festkomma-Werte
Z0_S0_ARRAYINDEX      -> Index des Wertes im DataRef-Feld
Z0_S0_REPEAT          -> {0..10} Faktor zum Definieren der Repeatfunktion, 0=aus
                         1 entspricht ca. 50 ms
                         10 entspricht ca. 500ms
...
Z8_S15
Z8_S15_COMMANDMODE	
Z8_S15_ARG	
Z8_S15_ARRAYINDEX	
Z8_S15_REPEAT         -> derzeit werden 144 Taster unterstützt von 
                         Zeile0/Spalte0 bis Zeile8/Spalte15

[UCP_SWITCHES]        Definition der Schalter bei Verwendung der Eingabeports 
                      (I²C-Adressen 20..23)
P0_B0_OFF             -> String-Definition für Ausschalt-Ereignis des Schalters
                         entsprechend der Dateien im Plugin-Ordner 
                         Commands.txt bzw. DataRefs.txt
P0_B0_OFF_COMMANDMODE -> {0 .. 4} Command, DataRef-Integer, DataRef-Float
                         DataRef-Array-Integer, DataRef-Array-Float
P0_B0_ON              -> String-Definition für Einschalt-Ereignis des Schalters
                         entsprechend der Dateien im Plugin-Ordner
                         Commands.txt bzw. DataRefs.txt
P0_B0_N_COMMANDMODE   -> {0 .. 4} Command, DataRef-Integer, DataRef-Float
                         DataRef-Array-Integer, DataRef-Array-Float
P0_B0_OFF_ARG         -> Argument für DataRef-Mode
                         Ganzzahl- bzw. Festkomma-Werte
P0_B0_ON_ARG          -> Argument für DataRef-Mode
                         Ganzzahl- bzw. Festkomma-Werte
P0_B0_OFF_ARRAYINDEX  -> Index des Wertes im DataRef-Feld
P0_B0_ON_ARRAYINDEX   -> Index des Wertes im DataRef-Feld

...
P3_B7_OFF
P0_B0_OFF_COMMANDMODE
P3_B7_ON
P0_B0_N_COMMANDMODE
P3_B7_OFF_ARG
P3_B7_ON_ARG
P0_B0_OFF_ARRAYINDEX
P3_B7_ON_ARRAYINDEX    -> Es werden maximal 4 Ports (32 Eingänge) unterstützt

[UCP_LEDS]            Definition der Anzeige-Ausgänge bei Verwendung der Ausgabeports
                      (I²C-Adresse 24..27)
P0_B0                 -> String-Definition für DataRef-Variable
                         entsprechend der Dateien im Plugin-Ordner
                         Commands.txt bzw. DataRefs.txt
P0_B0_READMODE        -> {0 .. 3} DataRef-Integer, DataRef-Float
                         DateRef-Array-Integer, DataRef-Array-Float
P0_B0_ARRAYINDEX      -> Index des Wertes im DataRef-Feld
P0_B0_LEVEL           -> Bei der Verwendung von Integer-/Float-Variablen kann hier
                         eine Schaltschwelle angegeben werden, ab dem der Ausgang
                         geschaltet wird, RANGE beeinflusst das Verhalten
P0_B0_RANGE           -> Bei der Verwendung von LEVEL kann ein Wertebereich verwendet
                         werden, bei dem der Ausgang geschaltet wird. (Standard ist 0)
                         0: alle Werte gleich und größer LEVEL aktivieren den Ausgang
                         1: nur bei LEVEL wird der Ausgang aktiviert
                         größer 1: von LEVEL bis < LEVEL+RANGE ist der Ausgang aktiv
P0_B0_INVERSE         -> {0,1} Die Ausgangslogik wird umgekehrt.

...
P3_B7
P3_B7_READMODE
P3_B7_ARRAYINDEX
P3_B7_LEVEL
P3_B7_RANGE
P3_B7_INVERSE         -> Es werden maximal 4 Ports (32 Ausgänge) unterstützt

Mit dem Setup können Sie eine Beispiel-Konfiguration installieren.

Mit dem Key Command Editor können der Tastatur-Matrix des USB-Controllers Kommandos und Set-Befehle für Daten-Referenzen zugeordnet werden. Zu jeder Taste kann zusätzlich eine Wiederholrate eingestellt werden.

Zuerst müssen alle Programme deaktiviert werden, die mit dem USB-Controller kommunizieren.

Sie können eine bereits bestehende Konfiguration laden oder mit einer leeren Matrix beginnen und diese dann speichern.

Die Abfrage der Tasten erfolgt, indem die entsprechende Taste gedrückt wird und anschließend mit der Maus die Schaltfläche UCP-Taste lesen geklickt wird. Es öffnet sich die zugehörige Eingabe-Maske.

Sie können aber auch mit der Maus in der Matrix das gewünschte Feld doppelklicken, um die Eingabemaske zu öffnen.

Es werden Zeile und Spalte angezeigt sowie bereits definierte Ereignisse. Bei einfachen Kommandos sind keine weiteren Argumente notwendig, es kann eine Wiederholrate eingestellt werden.

Für das Setzen von Integer- und Gleitkomma-Variablen ist ein Wert, auf den die Variable gesetzt werden soll einzugeben. Wenn die Variable in einem Datenfeld (Array) ist, dann bestimmt der Index die Stelle des zu ändernden Wertes. Der Index beginnt üblicherweise mit 0, z.B. für die erste Maschine, das Bug-Rad usw. Das Beispiel zeigt das Setzen des Gemisch-Hebels der 2. Maschine auf 50%.

Für einige Kommandos existieren nur Ein- und Aus-Kommandos. Manchmal soll aber über eine Taste ein Wechsel realisiert werden. Wenn beim Argument eines Setz-Befehls ein X eingetragen wird, so wird im Plugin ein Wechsel zwischen 0 und 1 realisiert.

Der Abfragezyklus des Plugins beträgt 50ms. Es kann mit Taster entprellen für alle Ereignisse eine Anzahl zusätzlicher Zyklen angegeben werden, in der ein Tastensignal gültig sein muss. Beachten Sie, dass dies beim Einsatz von Drehimpulsgebern nicht verwendet werden kann.

Die Belegung der Matrix kann mit Druckvorschau auch als Liste angezeigt werden. Diese Liste kann dann ausgedruckt werden.

Mit dem Switch Command Editor können den Schaltwechseln der Schalter an einem Eingabeport Kommandos und Set-Befehle für Daten-Referenzen zugeordnet werden. Es gibt jeweils ein ON- und ein OFF-Ereignis.

Zuerst müssen alle Programme deaktiviert werden, die mit dem USB-Controller kommunizieren.

Sie können eine bereits bestehende Konfiguration laden oder mit einer leeren Matrix beginnen und diese dann speichern.

Die Abfrage der Schalterwechsel erfolgt, indem der entsprechende Schalter betätigt wird und anschließend mit der Maus die Schaltfläche Abfragen geklickt wird. Es öffnet sich die zugehörige Eingabe-Maske. In der Zeile neben dem Abfrage-Knopf wird der Bit-Zustand der Ports angezeigt.

Sie können aber auch mit der Maus in der Matrix das gewünschte Feld doppelklicken, um die Eingabemaske zu öffnen.

Die Programmierung erfolgt wie im Key Command Editor.

Es wird jeweils nur einmal ein Kommando gesendet, wenn ein Zustandswechsel eine Ports festgestellt wird!

Die Belegung der Matrix kann mit Druckvorschau auch als Liste angezeigt werden. Diese Liste kann dann ausgedruckt werden.

Mit dem LED DataRef Editor können den Daten-Referenzen LED-Funktionen den Ausgabeports zugeordnet werden.

Zuerst müssen alle Programme deaktiviert werden, die mit dem USB-Controller kommunizieren.

Sie können eine bereits bestehende Konfiguration laden oder mit einer leeren Matrix beginnen und diese dann speichern.

Die Definition der Zuordnung erfolgt, indem Sie im entsprechenden Feld der Matrix doppelklicken. Die mit dem entsprechenden Ausgang verbundene LED kann mit dem Knopf LED-Test für 2 Sekunden getestet werden.

Für einfache ON-/OFF-Variablen (boolean) wird nur die Daten-Referenz in das Eingabefeld eingetragen. Schwellwert und Bereich bleiben auf 0. Im ON-Zustand ist der Ausgang aktiv. Mit dem Aktivieren von Umgekehrte Funktion ist der Ausgang im OFF-Zustand aktiv.

Für das Abfragen von Integer- und Gleitkomma-Variablen ist ein Wert, auf den die Variable getestet werden soll einzugeben. Wenn die Variable in einem Datenfeld (Array) ist, dann bestimmt der Index die Stelle des abzufragenden Wertes innerhalb des Feldes. Der Index beginnt üblicherweise mit 0, z.B. für Maschine 1, Bug-Rad usw.

Um Variablen auf bestimmte Werte und Wertebereiche zu testen und daraufhin einen Ausgang zu aktivieren, kann ein Schwellwert (Level) angegeben werden, ab dem der Ausgang aktiv sein soll und ein Bereich (Range) oberhalb des Schwellwertes. Ein Bereich von 0 aktiviert den Ausgang bei allen Werten ab dem Schwellwert (einschließlich), ein Bereich von 1 aktiviert den Ausgang bei nur genau dem Wert des Schwellwertes. Ist ein Bereich größer 1 angegeben, dann wird der Ausgang aktiv, wenn der Wert größer/gleich dem Schwellwert und kleiner als Schwellwert+Bereich ist. Auch hierbei ist die umgekehrte Funktion des Ausgangs möglich.

Die Belegung der Matrix kann mit Druckvorschau auch als Liste angezeigt werden. Diese Liste kann dann ausgedruckt werden.