A plugin for X-Plane and other simulators that allows commanding the simulation from external programs through an easy-to-use TCP protocol.
Current version 1003 (set in tcpserver.h, if you make changes!)
NOTE: ExtPlane-transformer (support for other sims except X-Plane) is not available in github releases, as building it requires Qt 5.8 and the ci container has older one.. This will eventually be fixed.
Known users:
Note: X-Plane has UDP interface that can be used to do lot of things ExtPlane normally would do. See https://github.com/dotsha747/libXPlane-UDP-Client for a c++ client for the UDP interface.
ExtPlane-Transformer is an application that works as ExtPlane server and can transform output from other simulators to ExtPlane protocol.
License:
This is a fat plugin - just copy "extplane" directory under X-Plane/Resources/plugins.
Start X-Plane. You should see ExtPlane menu entry in plugins menu.
ExtPlane uses the Qt Framework for cross-platform compatibility. Before building you'll need to setup Qt 5 or greater to compile. You'll also need to check out the X-Plane SDK (http://www.xsquawkbox.net/xpsdk/mediawiki/Download) to the directory next to the ExtPlane directory. The X-Plane SDK can be either at ~/SDK or ../SDK or ../XPlaneSDK relative to the ExtPlane directory.
The requirements for ExtPlane are as follows:
If you have docker (should work on linux & mac) you can build linux & windows binaries.
docker build -t extplane .
docker run -it -v $PWD:/ExtPlane -w /ExtPlane extplane ./scripts/ci-build.sh
You should end up with extplane-transformer.zip and extplane-plugin.zip with both linux & windows versions inside.
# 1: Install required libraries and tools
sudo apt install git build-essential qt5-qmake qt5-default qtbase5-dev qtdeclarative5-dev
# 2: Download X-Plane SDK and ExtPlane source code from GitHub
git clone https://github.com/dankrusi/XPlaneSDK.git
git clone https://github.com/vranki/ExtPlane.git
# 3: Build project
cd ExtPlane
qmake
make
# 1: Install required libraries and tools
# Download and install X-Code and Developer Tools from http://developer.apple.com
# Download and install Qt5 from http://qt-project.org/downloads
# 2: Download source code from GitHub
git clone https://github.com/dankrusi/XPlaneSDK.git
git clone https://github.com/vranki/ExtPlane.git
# 3: Build project
cd ExtPlane
qmake
make
# Note: If qmake is not on your command path, add the Qt bin directory to your path using
# export.
# 1: Install required libraries and tools
# Download and install Qt5 from http://qt-project.org/downloads
# Download and install Git from http://git-scm.com/downloads
# 2: Download source code from GitHub
git clone https://github.com/dankrusi/XPlaneSDK.git
git clone https://github.com/vranki/ExtPlane.git
# 3: Build project
cd ExtPlane
qmake
nmake
# Note: If you do not have a C++ compiler, you can install one of the following:
# MinGW version of Qt: http://qt-project.org/downloads
# Windows 7 SDK: http://www.microsoft.com/en-us/download/confirmation.aspx?id=8279
# Windows 8 SDK: http://msdn.microsoft.com/en-us/library/windows/desktop/hh852363.aspx
# Visual Studio Express: http://www.microsoft.com/visualstudio/eng/downloads#d-2012-express
A fat plugin will be in extplane-plugin/extplane. It will contain platform specific plugins you have built. For example after building linux & windows plugins it should look like this:
/extplane
└── 64
├── lin.xpl
└── win.xpl
You can copy the whole directory to XPlane's plugin directory:
cp -R extplane /path/to/xplane/Resources/plugins
This is possible using mxe cross-compilation tool. See file scripts/cross-compile-win64-from-lin.sh for instructions.
Launch X-Plane in console and observe the output. You should see something like:
ExtPlane-Plugin: Listening on port 51000
. All console output from Ext-Plane
will start with ExtPlane-Plugin
. Open another console and run telnet localhost 51000
.
Wait until you see line EXTPLANE 1
and EXTPLANE-VERSION NNNNN
. Then try typing the following commands:
sub sim/cockpit/electrical/night_vision_on
set sim/cockpit/electrical/night_vision_on 1
set sim/cockpit/electrical/night_vision_on 0
sub sim/flightmodel/position/local_y 100
set sim/flightmodel/position/local_y 3000
key 0
key 0
set sim/flightmodel/engine/ENGN_thro [1,0]
set sim/flightmodel/engine/ENGN_thro [0,0]
get sim/aircraft/engine/acf_num_engines
disconnect
The protocol uses a simple TCP socket connection to port 51000. Commands and replies are sent as text strings as defined below.
With accuracy you can decide how much the dataref's value can change before a update is sent. Set it to as large value as possible to maximize frame rate and minimize network traffic. For data datarefs, the accuracy represents the update interval in milliseconds.
Modifiers is a comma-separated list of strings that can modify behavior of dataref. See example on data dataref.
List of datarefs can be found at: http://www.xsquawkbox.net/xpsdk/docs/DataRefs.txt
For example, to subscribe to the indicated heading with an accuracy of 10 degrees, send
sub sim/flightmodel/misc/h_ind 10.0
If you want to set a dataref which supports writing, you can send the following:
set sim/flightmodel/misc/h_ind 267.32
Array datarefs can be set the same way. You can give less values than the dataref holds or skip some values. For example this sets full throttle for engines 1 & 2:
set sim/flightmodel/engine/ENGN_thro [1,1]
This sets full throttle to engine 2:
set sim/flightmodel/engine/ENGN_thro [,1]
Note: subscribe to array datarefs with full ref name without indices:
sub sim/flightmodel/engine/ENGN_thro
WRONG: sub sim/flightmodel/engine/ENGN_thro[1]
ExtPlane supports tight UDP protocol for basic dataref types (int, float, double) from simulator to client. Add modifier udp to ref name to request it in UDP. UDP datarefs are sent every flight loop using lightweight protocol.
See this file for details.
ExtPlane has experimental MQTT protocol support using Mosquitto library.
See this file for details.
List of key and button id's can be found at: http://www.xsquawkbox.net/xpsdk/mediawiki/XPLMUtilities Note that the key and button id's are numbers, not names. X-Plane does not provide a way to lookup keys or buttons by name.
Command identifiers are strings that look like datarefs.
Supported settings are:
i
(int), f
(float), d
(double), ia
(int array), fa
(float array), or b
(data).The value for EXTPLANE-VERSION is defined in extplane-server/tcpserver.h. It is an integer and should be incremented each time new features are added or bugs are fixed. The client is then able to check if the version is new enough, and can warn the user if the plugin is out of date.
Example output:
ui sim/aircraft/engine/acf_num_engines 2
uf sim/cockpit2/gauges/indicators/slip_deg -0.023
ud sim/flightmodel/misc/h_ind 267.32
Example output (a float array, size 4):
ufa sim/flightmodel/position/q [0.84599,-0.00730657,0.00933933,0.533067]
uia sim/cockpit2/engine/indicators/N1_percent [99,97]
Data datarefs output data in base64:
ub sim/aircraft/view/acf_descrip RXh0UGxhbmUgU2ltdWxhdGVkIENvbm5lY3Rpb24=
Use modifier "string" to output data as text (make sure it's really printable):
sub sim/aircraft/view/acf_descrip:string
->
ub sim/aircraft/view/acf_descrip:string "Boeing 737-800"
Currently only string data datarefs can be set. Remember to use quotes to set values:
set sim/aircraft/view/acf_descrip:string "This is an example"
ExtPlane plugin outputs some log to stdout, so if you have problems with the
plugin, start X-Plane in console and look for any output starting with ExtPlane-Plugin
.
ExtPlane can provide custom datarefs which simplify some common tasks or create a wrapper for X-Plane SDK API calls which cannot be accessed through datarefs.
ID:TYPE:LAT:LON:LOCALX:LOCALZ:HEIGHT:FREQ:HEAD:NAME
.KSEA:1:47.4475:-122.308:14461.6:-211.06:131.978:0:0:Seattle Tacoma Intl
Client libraries can be found in the client
directory. Currently only a Qt client
library is provided. Creating a client for ExtPlane is pretty easy. If you create one, please
add it to the client
directory.
Always group headers in a meaningful format (ie all Qt headers should be grouped together,
and all ExtPlane headers grouped together). In addition, make sure that headers
are always fully relative (ie use ../util/header.h
instead of util/header.h
).
This is required to build across all platforms.
When writing code which uses new features currently not implemented, always make
sure to first try to use Qt cross-platform classes and libraries. When using
platform dependent code, make sure to #ifdef
the sections of code which will
only work on a specific platform. You can use standard Qt defines, or additional
defines such as TERMIOS_AVAIALABLE
to help with this.
Look at class DataSource. You'll need to subclass it and implement any virtual functions missing. The functions are documented in the source. You'll need to do a conversion between X-Plane dataref and the simulator's own value presentations. Usually they area easy to do but complex stuff such as navigation may be impossible to do with common API.
When you have an implementation of a DataSource, add it to ExtPlaneTransformer class implementation. Then it should be available in the GUI.
To create a custom GUI for the source, create a QML file named datasources/DataSource[sourcename].qml. This is not mandatory.
See the existing datasources for examples. Thanks for contributing and make a github pull request when you're ready.
Original Author:
Contributors:
Use GitHub's issue tracker to report bugs or feature requests.
Contributions welcome!