*** ExtPlane ***
X-Plane plugin that allows commanding X-Plane from external programs using an easy
TCP protocol.
* Features *
- Multiple concurrent connections
- Set and get datarefs
- Dataref types supported: int, float, double, int[], float[]
- Simulate key and button presses
- Supports both X-Plane 9 and 10
- Free & Open Source under GPLv3
- Client classes for Qt included
Known users:
ExtPlane-Panel - a panel application @ https://github.com/vranki/ExtPlane-Panel
GNU GPLv3, (c) Ville Ranki <ville.ranki@iki.fi>
Contributors:
Bob Gates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Downloading *
Some binaries for various platforms are available in binaries/ directory. Just
download a suitable binary and copy it to X-Plane/Resources/plugins/extplane.xpl.
If a binary for your favorite platform is missing, please build it and
send it to authors!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Common build requirements *
Copy X-Plane SDK to home directory, so that the headers can be found
at ~/SDK/CHeaders/XPLM (or edit the .pro file).
You'll need Qt development libraries installed.
* To build on Mac & Linux *
$ qmake
$ make
Mac notes:
Warning! If you see any error or warning like :
ld: in /opt/local/lib/libxslt.1.dylib, file was built for unsupported file format which is not the architecture being linked (i386)
You need to rebuild libxslt with the +universal variant on MacPort otherwise the plugin cannot be loaded by X-Plane !
You should get the same for qt4-mac also.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Test session *
Launch X-Plane in console and observe the output. You should see something like:
TcpServer::TcpServer(QObject*, DataRefProvider*) Listening on port 51000
Open another console and run 'telnet localhost 51000'
Wait until you see line 'EXTPLANE 1'
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]
disconnect
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Command reference *
Datarefs:
sub <dataref> [accuracy] - Subscribe to dataref, with optional accuracy.
unsub <dataref> - Unsubscribe dataref.
set <dataref> <value> - Set dataref to value. Dataref must be subscribed first.
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.
List of datarefs can be found at:
http://www.xsquawkbox.net/xpsdk/docs/DataRefs.txt
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.
Other:
disconnect - Disconnect the TCP socket.
extplane-set <setting> <value> - Set ExtPlane setting
Settings are:
update_interval <value> - How often ExtPlane should update its data from X-Plane, in seconds.
Use as high value as possible here for best performance. For example 0.16
would mean 60Hz, 0.33 = 30Hz, 0.1 = 10Hz etc.. Must be a positive float.
Default is 0.33.
* Plugin output *
EXTPLANE <version> - Sent when connected. Version number is currently 1.
u<type> <dataref> <value> - Update of dataref
Array datarefs output data like this (a float array, size 4):
ufa sim/flightmodel/position/q [0.84599,-0.00730657,0.00933933,0.533067]
Set array datarefs the same way. You can give less values than the dataref
holds. For example this sets full throttle to engines 1 & 2
set sim/flightmodel/engine/ENGN_thro [1,1]
ExtPlane plugin outputs some log to stdout, so if you have problems with the
plugin, start X-Plane in console and read the output.
* Client library *
See directory "client" for client code. Currently there is only client code for Qt.
If you write client code for other environments (Python, Java..) please add them
here.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Comments and bug reports to ville.ranki@iki.fi
Official git repo at https://github.com/vranki/ExtPlane
Contributions welcome!