nasa / xplaneconnect

The X-Plane Communications Toolbox is a research tool used to interact with the X-Plane flight simulator

X-Plane Connect

The X-Plane Connect (XPC) Toolbox is an open source research tool used to interact with the commercial flight simulator software X-Plane. XPC allows users to control aircraft and receive state information from aircraft simulated in X-Plane using functions written in C, C++, Java, MATLAB, or Python in real time over the network. This research tool has been used to visualize flight paths, test control algorithms, simulate an active airspace, or generate out-the-window visuals for in-house flight simulation software. Possible applications include active control of an XPlane simulation, flight visualization, recording states during a flight, or interacting with a mission over UDP.

Architecture

XPC includes an X-Plane plugin (xpcPlugin) and clients written in several languages that interact with the plugin.

Quick Start

To get started using X-Plane Connect, do the following.

1. Purchase and install X-Plane 9, 10 or 11.
2. Download the XPlaneConnect.zip file from the latest release on the releases page.
3. Copy the contents of the .zip archive to the plugin directory ([X-Plane Directory]/Resources/plugins/)
4. Write some code using one of the clients to manipulate X-Plane data.

Each client is located in a top-level directory of the repository named for the client's language. The client directories generally include a src folder containing the client source code, and an Examples folder containing sample code demonstrating how to use the client.

Additional Information

For detailed information about XPC and how to use the XPC clients, refer to the XPC Wiki.

Capabilities

The XPC Toolbox allows the user to manipulate the internal state of X-Plane by reading and setting DataRefs, a complete list of which can be found on the X-Plane SDK wiki.

In addition, several convenience functions are provided, which allow the user to efficiently execute common commands. These functions include the ability to set the position and control surfaces of both player and multiplayer aircraft. In addition, the pause function allows users to easily pause and un-pause X-Plane's physics simulation engine.

Compatibility

XPC has been tested with the following software versions:

• Windows: Vista, 7, & 8
• Mac OSX: 10.8-10.14
• Linux: Tested on Red Hat Enterprise Linux Workstation release 6.6
• X-Plane: 9, 10 & 11

Contributing

All contributions are welcome! If you are having problems with the plugin, please open an issue on GitHub or email Chris Teubert. If you would like to contribute directly, please feel free to open a pull request against the "develop" branch. Pull requests will be evaluated and integrated into the next official release.

Notices

Copyright ©2013-2018 United States Government as represented by the Administrator of the National Aeronautics and Space Administration. All Rights Reserved.

No Warranty: THE SUBJECT SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY OF ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL BE ERROR FREE, OR ANY WARRANTY THAT DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE SUBJECT SOFTWARE. THIS AGREEMENT DOES NOT, IN ANY MANNER, CONSTITUTE AN ENDORSEMENT BY GOVERNMENT AGENCY OR ANY PRIOR RECIPIENT OF ANY RESULTS, RESULTING DESIGNS, HARDWARE, SOFTWARE PRODUCTS OR ANY OTHER APPLICATIONS RESULTING FROM USE OF THE SUBJECT SOFTWARE. FURTHER, GOVERNMENT AGENCY DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING THIRD-PARTY SOFTWARE, IF PRESENT IN THE ORIGINAL SOFTWARE, AND DISTRIBUTES IT "AS IS."

Waiver and Indemnity: RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS AGAINST THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT. IF RECIPIENT'S USE OF THE SUBJECT SOFTWARE RESULTS IN ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES ARISING FROM SUCH USE, INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM, RECIPIENT'S USE OF THE SUBJECT SOFTWARE, RECIPIENT SHALL INDEMNIFY AND HOLD HARMLESS THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT, TO THE EXTENT PERMITTED BY LAW. RECIPIENT'S SOLE REMEDY FOR ANY SUCH MATTER SHALL BE THE IMMEDIATE, UNILATERAL TERMINATION OF THIS AGREEMENT.

X-Plane API

Copyright (c) 2008, Sandy Barbour and Ben Supnik All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Neither the names of the authors nor that of X-Plane or Laminar Research may be used to endorse or promote products derived from this software without specific prior written permission from the authors or Laminar Research, respectively.

X-Plane API SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

xplaneconnect's Issues

sendVIEW command does not work on Mac

The sendVIEW command doesn't seem to do anything at all on Mac.

Extra line from waypoint

When running the MATLAB test scripts on mac, an extra red line is coming from the waypoint immediately in front of the vehicle (see screen shot). This line goes into the ground at a steep angle.

Java user guide needed

Matlab requestDREF incomplete

Complete requestDREF

Add getPOSI and getCTRL functions

Enable setConn for MATLAB

setConn requires requestDREF to receive port number that the information will be returned on.

Expand C/C++ Unit Testing

Expand C/C++ Unit Testing to contain more checks.

Merge / cooperate with ExtPlane

Hi,

I'm the author of ExtPlane plugin I just found XPlaneConnect. Looks like the feature set and target of the project is almost identical to ExtPlane's. XPlaneConnect seems to use a bit lower level UDP approach compared to ExtPlane's TCP socket, but still they do the same thing.

Would you be interested in merging the two projects into a single X-Plane comms plugin? I think it's a waste of effort to implement practically the same thing twice.

Plugin does not detect multiple connections on Windows reliably

2790f55 makes changes to the Java client specifically designed to ensure that each instance of the XPlaneConnect class is recognized as a new connection by the plugin. This works as expected on Mac, but does not appear to work on Windows. On Windows, all requests are logged by the plugin as coming from connection 1.

Need to do some legwork to establish whether this bug affects the C and MATLAB clients as well, and find the root cause of the bug.

Add "switch" option to SIMU command

Length byte overflows for some messages

Summary

Some messages are longer than 255 bytes, causing the length field in the GETD command to overflow.

Description

When requesting several DREFs with the GETD command, it is relatively easy to create a message which is longer than 255 bytes. This currently produces inconsistent behavior depending on which client is used. The Java client throws an exception without attempting to send the command, while the C and MATLAB clients send the command with an undefined value in the length field.

The plugin currently draws length information primarily from the return value of the recvfrom function. At least in the case of the GETD command, the length field seems to be entirely ignored. As a result, the plugin deals with these long messages without issue.

This may present a problem if the plugin ever receives a partial message or multiple messages squashed together. The former is relatively easy to fix, but the latter would be problematic.

Proposed Solution

If someone can provide information indicating that recvfrom will never return multiple UDP datagrams in a single call, then we can simply remove the length check from the Java client and explicitly ignore the length field in the future. In this case, partial datagrams will be seen as invalid during the parsing phase and discarded.

Otherwise, the length field needs to be expanded to 2 bytes, raising the max message length from 255 to 65535. This should be more than enough room for any command.

Bugfix for sendDREFs example code

There are a number of bugs in the example code for the sendDREFs() function:

• char* drefs[] should be const char* drefs[]
• semicolon missing after malloc(4)
• sendDREFs() requires a fifth input parameter: int count, which represents the number of datarefs being sent
• The second instance of values[0][0] should be values[1][0] to refer to the value for the second dataref.

I have incorporated the above bugfixes into a new, expanded example, included below. Feel free to pare it down if desired and use it on the XPC website. Note that the datarefs being set have been changed to the taxi and beacon lights.

const char* XPlane_IP = "127.0.0.1"; //IP address of PC running X-Plane
XPCSocket sock = openUDP(XPlane_IP);

int err;    //holds return code
const char* drefs[] = { "sim/cockpit2/switches/landing_lights_on", "sim/cockpit2/switches/beacon_on" };
float* values[2]; //A multidimensional array of values representing the data to set.

for (int i = 0; i < 2; ++i)
{
    values[i] = (float*)malloc(4);
}
//The following may be used in place of the FOR loop above if desired
//values[0] = (float*)malloc(1 * sizeof(float));
//values[1] = (float*)malloc(1 * sizeof(float));

//Note: with XPC, everything is sent as floats, even if X-Plane wants an int.
values[0][0] = 0.0F; //turn off landing lights (1.0F = ON)
values[1][0] = 0.0F; //turn off beacon (1.0F = ON)
int sizes[] = { 1, 1 }; // The number of items in each row of "values"
int count = 2; //The number of datarefs being sent

err = sendDREFs(sock, drefs, values, sizes, count);

switch (err)  //interpret return value (error code)
{
case -1:
    std::cout << "\nERROR: Length of dref is greater than 255 characters." << "\n";
    break;
case -2:
    std::cout << "\nERROR: There are more than 255 items in \"value\"." << "\n";
    break;
case -3:
    std::cout << "\nERROR: XPC client unable to send command." << "\n";
    break;
case 0:
    std::cout << "\nSUCCESS: XPC sent the specified datarefs." << "\n\n";
}

Determine java architecture

MATLAB Unit Testing Script

Create Matlab Unit Testing Script

Documentation correction: sendCTRL throttle range should be [0,1]

In the documentation for sendCTRL, the throttle range is given as [-1,1]. The correct range is [0,1], as per the X-Plane dataref list: http://www.xsquawkbox.net/xpsdk/docs/DataRefs.html

In testing with the latest beta (10.40r1), X-plane will happily accept out-of-range values, however, the throttle lever will then move out of its normal track in the 3D cockpit view. :)

Cheers!

Linux build does not work on all systems

We can successfully build the plugin for 64 bit Linux, but when run, an error is produced in the X-Plane log stating that the symbol Hash_bytes is not defined. This causes the plugin to fail to load.

The 32 bit Linux build works as expected.

Add Visualization Demo

One of the use cases of XPC is as a tool for assisting in using X-Plane as a graphical visualization of another flight simulation's data. It would be nice to have an example that shows how this might be accomplished.

When #21 is implemented, this could simply read a playback file on the client side and feed points in to the plugin manually.

Matlab readData Bug

Hi it seems that in Matlab the readDATA function is not working properly. I always get the multiple clients issue although the global clients variable has only one entry. This can be fixed by changing:
assert(istrue(... -> assert(isequal(...
Further Matlab wants to call socket.readDATA() although the function should be readData().
But still with this fixes, the code does not run and there seems to be a problem for me with the buffer when reading out the data. This seems to be within the java code.

Determine Python Architecture

Add Text to Screen

Add the ability to write text to the screen within X-Plane

Add example for Python client

C Unit Testing

Create C Unit Testing Executable

Add Waypoints

Add waypoint generation feature- high priority

Extend DREF command to support sending multiple datarefs in a single command

Extend sendCTRL for multiplayer aircraft

Linux Executable Needed

Error when using "interpreted MATLAB Fcn" block in Simulink

An error occurred while running the simulation and the simulation was terminated

Error due to multiple causes.

Java exception occurred:
java.net.SocketException: No buffer space available (maximum connections reached?): Cannot bind
at java.net.DualStackPlainDatagramSocketImpl.socketBind(Native Method)
at java.net.DualStackPlainDatagramSocketImpl.bind0(Unknown Source)
at java.net.AbstractPlainDatagramSocketImpl.bind(Unknown Source)
at java.net.DatagramSocket.bind(Unknown Source)
at java.net.DatagramSocket.(Unknown Source)
at java.net.DatagramSocket.(Unknown Source)
at java.net.DatagramSocket.(Unknown Source)
at gov.nasa.xpc.XPlaneConnect.(XPlaneConnect.java:152)
at gov.nasa.xpc.XPlaneConnect.(XPlaneConnect.java:136)

Or

An error occurred while running the simulation and the simulation was terminated

Error due to multiple causes.

Java exception occurred:
java.io.IOException: No response received.
at gov.nasa.xpc.XPlaneConnect.getDREFs(XPlaneConnect.java:299)

Java Example

Add "Status Monitor" Example

Would like to have an example that demonstrates how to use the client in a continuous mode to compliment the current example that just runs a sequence of commands and exits.

Create github Wiki for ease of Use

I got this error when I used matlab :Error using XPlaneConnect.getDREFs (line 27) [getDREFs] ERROR: Multiple clients open. You must specify which client to use.

POSI: Alpha/Beta

@teubert This was in xpcPlugin.cpp. I'm removing the (mostly out of date) TODO list there, and putting the outstanding items in here.

Not sure what exactly this one entails. Could you elaborate?

Add datarefs for multiplayer global position

Add connection verification to beginning of examples

The example (for all languages) currently sends quite a lot of data without reading anything. As a result, it can appear that the example mostly works when X-Plane isn't even running.

It would probably be better to read a DREF or send another simple command that requires a response from the plugin. If this operation fails, we can immediately tell the user that something is wrong. This would be especially helpful for new users who have misplaced the plugin files.

New Feature: Faster getting and setting of DREFs

Related to the discussion on #51, I think it might be useful to facilitate more efficient getting and setting of data refs. I'm envisioning the following new commands:

Get DREF Pointer: Takes a dataref string, and returns the internal pointer used by the X-Plane API. This would allow users to cache pointers to frequently used datarefs and only send those pointers rather than sending the full dref string each time they need to get or set a value. The plugin already caches these pointers internally, but having clients send pointers over the network could significantly cut down on the amount of data that the plugin needs to process in order to retrieve the right pointer.

Get DREF(s) (pointer): Identical to the existing GetDREF(s) command, but pass pointers instead of the dref names.

Set DREF (pointer): Identical to the existing SetDREF command, but pass a pointer instead of the dref name.

Playback Executable

Create an executable to run a playback file. This executable will read a playback file and set the aircraft position/orientation as indicated in the playback file.

Example Operation:
./runPlayback pb1.xpc

Example Playback File pb1.xpc:
Time, Aircraft, Lat, Lon, Alt, Roll, Pitch, Yaw
0, 1, 34.5, 67.2, 500, 0, 0, 0
0.1, 1, 34.5001, 67.2, 500, 0, 0, 0

Add detailed information on the internal plugin APIs to the wiki

All of the relevant information is already in the source, just need to copy it over to the wiki.

New Feature: Set and Hold Values

Related to the discussion on #51, I think it might be useful to add the ability to set a "sticky" value for a dataref, that the plugin will try to reset on every simulation frame.

This functionality could be supported by adding an optional flag to the existing DREF command.

Internally, the plugin would need to maintain a list of drefs and values, and register a callback to set each dref after each iteration of the flight simulation loop.

Dead Code in XPCFlightLoopCallback

The cyclesToClear variable in XPCPlugin.cpp is never updated after initialization. As a result, the final if block in the XPCFlightLoopCallback function will never execute.

Proposed fix: Remove cyclesToClear all together, and instead clear the buffer any time the plugin processes OPS_PER_CYCLE requests in a single frame. This would allow the plugin to clear large backlogs caused by events such as loading a new part of the world more reliably than simply clearing the buffer at a fixed interval.

Added "Autopilot" Example

An example that takes a series of GPS RNAV points and flies a plane along the route would provide an example of how XPC interacts with a non-trivial client program.

parseRequest incorrectly copying data

I'm looking at the following snippet on line 580 of xplaneConnect.c:

    for (j=0; j< arraySizes[i]; j++)
    {
        memcpy(&tmp,&my_message[place+1],sizeof(float));
        data[j] = tmp;
    }

It seems to me that this code is either missing a dependency on j in the memcpy (probably) or just terribly inefficient. If the code is working as intended, I believe we could at the very least move the memcpy out of the inner loop.

P.S. I took a look at the tests, and this code path is covered by requestDREFTest, but it doesn't look to me like that test verifies that the result is correct.

Plugin does not correctly terminate strings sent by the TEXT command.

Sending a new message that is shorter than the previous message will correctly overwrite the beginning of the message, but the remainder of the old message continues to display as well.

Add network data format information to wiki

Add speedbrakes to CTRL command

Determine Simulink Architecture

Add VIEW command

Add the ability to change the current camera view via a client command.

The relevant dref is sim/graphics/view/view_type, but it's not writable. The SDK docs point to this function and indicates that the enum values on the dref page can be used in conjunction with it.

Memory leak in parseRequest

Summary

The parseRequest function creates multiple potential memory leaks.

Description

parseRequestcurrently unconditionally allocates new memory and stores the resulting pointers in resultArray, overwriting any pointers already stored there. This can leak memory in two ways. First, the allocation may overwrite a pointer without freeing it. This was previously handled by freeing non-null pointers in resultArray, but parseRequest is sometimes called with a stack allocated two dimensional array, which causes free to segfault on Windows 8. Second, the responsibility for eventually freeing the newly allocated memory falls to the caller. Since there is no way to enforce this contract, it is inevitable that callers will forget to free memory.

Sending CONF messages in response to CONN command causes X-Plane to crash

Per 66b074d, sending CONF messages after handling a CONN command causes X-Plane to crash on Windows 8 if multiple CONN commands are sent.

Initial investigation suggests that the CONF messages are somehow ending up in the plugin message buffer, but it's not immediately clear why that would be happening.

Uninitialized variable causes error in xpcExample

In main.cpp from xpcExample (found in: XPlaneConnect-master\C\xpcExample\xpcExample\src), the variable int tSize is uninitialized. This causes the following error to be returned in the console:

The following error is also returned by visual studio:

This bug can be fixed by initializing the variable as follows:

int tSize=1;

Cheers!

Could use developers guide