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

• X-Plane 9, 10 & 11 - native support. X-Plane 11 currently only tested.
• Condor soaring simulator 1 and 2
• FlightGear - basic support via Transformer (see later)

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

• Multiple concurrent connections
• Set and get datarefs
• Support for different dataref types: int, float, double, int[], float[], data
• Simulate key and button presses
• Execute commands
• Load situations
• High-performance UDP option
• MQTT protocol for easy integration to external systems such as Node Red
• Free & open source under GPLv3
• Client libraries available for Qt (c++), Java and C#

Known users:

• ExtPlane-Panel
  • A fully-featured interface for ExtPlane with tons of flight instruments and more
  • https://github.com/vranki/ExtPlane-Panel
• Copilot X
  • Voice command app for Android
  • https://play.google.com/store/apps/details?id=com.appropel.xplanevoice
• XPlaneCDU
  • A remote control interface for the Control Display Unit (CDU) for Android.
  • https://play.google.com/store/apps/details?id=net.waynepiekarski.xplanecdu&hl=en
  • https://github.com/waynepiekarski/XPlaneCDU
• X-Plane Voice Control
  • Simple to use Voice control made for Zibo's awesome 738X (most likely will work for 739 Ultimate)
  • https://github.com/Najsr/X-Plane-Voice-Control

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:

• GNU GPLv3

Articles and guides

• Ville Ranki's blog: ExtPlane-panel (English, 2010)
  • http://coshacks.blogspot.fi/2010/12/extplane-panel-for-x-plane.html
• Nicolas Montarnal's blog: Simulateur de vol: cockpit pour Xplane (French, 2015)
  • http://nicolasmontarnal.blogspot.fr/2015/10/x-plane-mise-en-place-dinstruments-de.html

Downloads

ExtPlane Plugin

• Up to date Linux & windows versions
  • GitHub releases page: https://github.com/vranki/ExtPlane/releases/
• Older version: Linux, Windows, OS-X (32bit & 64bit), 8MB
  • https://github.com/dankrusi/ExtPlane-Panel/releases/tag/v0.1

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:

• C++ Toolchain
• Qt Framework 5+
• X-Plane SDK 3.0+

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

• sub {dataref}:[modifiers] [accuracy] Subscribe to dataref, with optional accuracy.
• unsub {dataref} Unsubscribe dataref.
• set {dataref} {value} Set dataref to value. Dataref must be subscribed first.
• get {dataref} Get dataref value once, then unsubscribe.

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

• key {key id} Create a command key press.
• but {button id} Press down an button.
• rel {button id} Release button pressed using "but" command.

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

• ** cmd once {command} ** Execute command. It begins and ends immediately.
• ** cmd begin {command} ** Begin execution of command. Then it will be "held down".
• ** cmd end {command} ** Stop execution of command, that was started before.

Command identifiers are strings that look like datarefs.

Situations

• sit "{situationFileLocation}" situation file location relative to XPlane root folder <br /> (e.g., sit "Output/situations/SampleSit.sit" )

FMC

• fms_wpt_entry id,latitude,longitude,altitude Inserts waypoint to FMC. (e.g., "fms_wpt_entry 1,50.0267,8.51,32000") <br />
• **fms_cl