The first step is figuring out how X-Plane communicates with external programs. Never having interfaced with any other software before, I figured this would be a good challenge for me.
After doing a lot of research and reading everything I could find on the subject, it seems that there are a couple ways of going about this. The first way, would be by writing a plug-in. The second option, is communicating with X-Plane using UDP, or User Datagram Protocol. From Wikipedia:
I've chosen to go the UDP route. Although this is designed to work over a "network", I'll being doing it all on a single computer. For a very good explination of how all this works, check out Jeff Lewis's site. I found it the most helpful while trying to make heads or tales of everything.
My "simplified" (and probably over-simplified) version of how it all works goes like this: UDP communication occurs over a network, typically with more than one computer. Computers all have addresses in the form of an IP address. Well, each computer also has a localhost address or "home" address, typically 127.0.0.1, for loopback network connections. Basically, any software on your computer that is connected to the localhost can send/receive data from each other. Ports are used to tie into the network. Any software that wants to send/receive data on the localhost must open or bind to a port, and ports can not be shared.
Jeff had a good analogy: If you think of the localhost (127.0.0.1) as being the apartment building, ports are like the individual apartment numbers. Another way to think of it is to think of the localhost as being the power wires running through your home. If you want to to access it, you must do so through an outlet (or port). You can't plug-in more than one device per outlet plug (same goes for ports).
I will not get into all the details of how it works, as Jeff does an excellent job of that already, so be sure to check out his site above!
Data sent using UDP are sent in the form of a string of bytes, called datagrams. X-Plane has many options for the sending of this data, such as what data it sends and how often it is sent. Here is a screen-shot from the Data Set tab, found under the Data Input & Output menu option:
For each data element, you can select to have it sent via UDP, you can output the data to a text file (Data.txt), which will be very helpful for the development of the C# software. Also, you may have it display on-screen while the simulation is running. With the options set as shown in the above screen-shot, here's the on-screen disply:
Before I jump into the C# of this, here's how to get X-Plane all setup for UDP. In the previously shown options screen, in the bottom-right corner there is a box for setting UDP rate. This tells X-Plane how many times per second to send a datagram. For initial testing, anything from 1 to 10/sec works.
Next step is to tell X-Plane what our localhost IP is and what port we want the information to be sent to. These settings can be found under Settings -> Net Connections. Clicking on the last tab, UDP Port, I can see the actual port numbers that X-Plane uses:
X-Plane binds to port 49000 for receiving data, 49001 for sending, and 49002 for iPad devices. Since there is no reason to change these values, I'll not touch them. But, it does tell me that ports 49000 to 49002 are already taken, so for receiving any data in my C# application, I know I'll need to use a port other than those, such as 49003.
Now that the ports are known, I can click on one tab to the left, the Advanced tab. Here, I can put in my localhost IP, 127.0.0.1, and the "receiving" port I anticipate using in my C# application, 49003.
Understanding the format of X-Planes UDP sentences is very important, obviously. So I'll review them here.
Here is a raw data string sent from X-Plane:
68 65 84 65 60 18 0 0 0 171 103 81 191 187 243 46 190 103 246 45 67 156 246 26 67 47 231 26 67 0 192 121 196 0 192 121 196 85 254 151 193
Now, here I've color-coded it and put some commas in to help read it better:
68,65,84,65,60, 18,0,0,0, 171,103,81 191, 187,243,46,190, 103,246,45,67, 156,246,26,67, 47,231,26,67, 0,192,121,196, 0,192,121,196, 85,254,151,193
|
Lets break it down:
68,65,84,65,60 = D,A,T,A,'' : These are CHAR's. The 5th byte we don't care about, so when sending any data sentences to X-Plane, a 0 (zero) should be placed there. 18,0,0,0 = 18 : This is an index number that corresponds to a specific data set in X-Plane. In this example string, we're looking at the data set, "18: pitch, roll, headings". The only byte we need out of these 4 is the fist one. The other 3 will always be zero. The first byte doesn't need any calculations, use as an integer. 171,103,....,151,193 : These 32 bytes make up the 8 single-precision floating point numbers that will need to be calculated. This is EASY to do with a single C# function, BitConverter.ToSingle... I'll get to this shortly. |
There are well over 100 different UDP sentences available through the Data Set panel in X-Plane. Each of them is unique and constains up to 8 floating-point values. Luckily there's an easy way to view the data order of any of those sentences.
In X-Plane, back under the Data Input & Output -> Data Set tab, the 2nd check-box next to all the data sets, sets that particular data set to be logged in a .txt file, called Data.txt. This is stored inside the X-Plane root folder. For any sentence you wish to view the data order of, simply check the Disk File 'data.text' option, select how many times per second you want to log the data, then run the sim for a few seconds. Once you know some data has been written (X-Plane will display a message that it's writing to the data file), go back to your Data Set option, un-check the data box (so it doesn't keep logging data), then go to your X-Plane root folder and view the data.txt file.
As an example, this is the #20 data set, "lat, lon, altitude". In this sentence, all 8 values are used:
__lat,__deg | __lon,__deg | __alt,ftmsl | __alt,ftagl | ___on,runwy | __alt,__ind | __lat,south | __lon,_west |
------------|---------------|---------------|---------------|---------------|---------------|---------------|---------------|
47.50037 | -122.21684 | 4.87364 | 0.35146 | 1.00000 | 4.87439 | 46.00000 | -124.00000 |
That was a fairly quick run-down of "how it works", but if you'd like to read some more "background" information, see Jeff's tutorial here,
or to view X-Plane's own documentation on the subject, see this page: X-Plane UDP Reference.
Now, lets start working on some C#! Click here to continue...
