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