search

vranki / ExtPlane

Plugin for X-Plane flight simulator which allows reading and writing simulation properties
138 stars 44 forks source link

readme

ExtPlane

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!)

Supported simulators

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.

Features

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.

Transformer

ExtPlane-Transformer is an application that works as ExtPlane server and can transform output from other simulators to ExtPlane protocol.

License:

Articles and guides

Downloads

ExtPlane Plugin

Installing

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.

Building

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:

Docker

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.

Debian/Ubuntu Linux

# 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

OS X

# 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.

Windows

# 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

After the build

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

Cross-compile to Windows from Linux

This is possible using mxe cross-compilation tool. See file scripts/cross-compile-win64-from-lin.sh for instructions.

Test Session

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

Protocol Input

The protocol uses a simple TCP socket connection to port 51000. Commands and replies are sent as text strings as defined below.

Datarefs

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]

High-performance UDP output

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.

MQTT output

ExtPlane has experimental MQTT protocol support using Mosquitto library.

See this file for details.

Keys and Buttons

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.

Commands

Command identifiers are strings that look like datarefs.

Situations

FMC

Other

Supported settings are:

Protocol Output

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.

Int/Float/Double Datarefs

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

Int/Float Array Datarefs

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

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"

Console Output

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.

Custom Datarefs

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.

Client Libraries

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.

Coding Guidelines

Headers

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.

Platform-Dependent Code

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.

Creating new data sources to support simulators

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.

Contact / Feedback

Original Author:

Contributors:

Use GitHub's issue tracker to report bugs or feature requests.

Contributions welcome!