Cyriel Notteboom Menno Hochstenbach

Data connection between

MATLAB/Simulink & X-Plane using
UDP
Background
A lot has already been written about using the User Datagram Protocol (UDP) to communicate with
X-Plane, but it hasn’t been clearly pointed out yet how we can use Simulink (MATLAB) to send and
receive this data. It works with X-Plane v10.25, but also older versions I think. I spent a lot of time
finding out how to make it work, so I hope it’s helpful.

The UDP occurs over a network (i.e. 2 computers connected through Ethernet cable), but the
following can also be applied to a single computer. It is recommended though to use 2 separate
computers, to divide the calculation load.

I will explain the bare minimum in simple words to set the connection up, assuming you are an
average computer user. A basic understanding of MATLAB, Simulink and X-Plane is required. This is
written for an airplane in X-Plane, but it is extendable for any aircraft (helicopter, multicopter, …).

If you want to dig deeper, I greatly recommend Jeff’s website. (See resources)

X-Plane and UDP

To learn what UDP is all about, what the structure is and how to set up X-Plane, I recommend reading
Nuclear Project’s website, who wrote it in very clear language. Just ignore the C++ he’s talking about,
we’ll be using Simulink.

http://www.nuclearprojects.com/xplane/info.shtml

Simulink and UDP

If you search for “UDP” in the Simulink library, you will find several toolboxes containing relevant
blocks. We will only use the DSP System toolbox. Simulink has to do two things at the same time,
sending and receiving. We will cover them separately. The highest level can look like this. You can see
the input on the left, the sending block, and the receiving block on the right, that outputs any X-Plane
data. You can use this to feed a controller and build a feedback control loop, or anything else.
Cyriel Notteboom Menno Hochstenbach

Sending UDP datagrams

Input
You can use almost anything as input, i.e. a USB RC controller, a game console controller, … Simulink
can read their signals with the “Pilot joystick” block. UDP inputs override direct inputs, but disable
the joystick in X-Plane to be sure (Settings -> Joystick & equipment)

Whatever the source is, make sure the inputs scale between -1 and 1 (roll, pitch, yaw), or 0 and 1
(thrust). To do this you may need to add a calibration block, like I did.

Encoding and sending

Next thing you need to do is prepare the input to be sent to X-Plane. This consists of the following
steps:

1) Convert your signal to single precision floating point numbers.

2) Convert them to unsigned integers of 8 bits, (data type uint8). You can use the block “Byte
pack”, and put single as input data type. It converts every incoming single precision floating
point number to an 8 bit representation.
Cyriel Notteboom Menno Hochstenbach

3) Construct a datagram that X-Plane understands. There are several ways to do this, if you
know something about C++ programming and building S-blocks, you can do that, but I chose
for a simple yet effective method; writing a MATLAB function. This is possible with the
“MATLAB Function” block. The only thing that needs to be done here is make a string of
numbers using the uint8 data from earlier. I suggest reading Nuclear Project’s website to
understand the construction of the datagram.

function UDP = UDP_encode(roll_single, pitch_single, yaw_single,

throttle_single)

DATA = [68 65 84 65 48];

NULL = [0 192 121 196];

UDP_flightcon = [11 0 0 0 pitch_single' roll_single' yaw_single' NULL

NULL NULL NULL NULL];

UDP_throttle = [25 0 0 0 throttle_single' NULL NULL NULL NULL NULL NULL

NULL];

UDP = [DATA UDP_flightcon UDP_throttle]';

end

The marked numbers refer to the “data number”, I call it the channel, in X-Plane. You can
find them in X-Plane in the Data Set tab, found under the Data Input & Output menu option.
In my case, I only sent channel #11, which are the flight controls, and #25, the throttle signal.
If you want to control for example a quad rotor (which has 4 throttles), the code would look
like this:

function UDP = UDP_encode(throttle_1, throttle_2, throttle_3, throttle_4)

DATA = [68 65 84 65 48];

NULL = [0 192 121 196];

UDP_throttle = [25 0 0 0 throttle_1' throttle_2' throttle_3' throttle_4'

NULL NULL NULL NULL];

UDP = [DATA UDP_throttle]';

end
Cyriel Notteboom Menno Hochstenbach

Each channel consists of maximum 8 entries. For example channel 11 has 3 entries, aileron,
elevator and rudder. Be sure to check these channel numbers, as they change with different
versions of X-Plane.

Channel 11

Channel 18,
entry 2

4) Finally send the datagram to X-Plane through UDP, using the DSP System toolbox block “UDP
Send”. This block needs to know where it needs to send the datagram, so you need to fill in
the right address, IP-address and port number. X-Plane receives on port 49000 on default.
You can check this in X-Plane in Settings -> Net Connections, on the last tab, UDP Port.
Cyriel Notteboom Menno Hochstenbach

If you are running both X-Plane and Simulink on the same computer, you use the localhost IP-
adress, ‘127.0.0.1’. If not, you can find the “X-Plane computer’s” IP address with the ipconfig
command in command window. Look for the IPv4 address in the Ethernet section.

Alternatively, you can see the IP-address in X-Plane under Settings -> Net Connections ->Data.

Now is the time to test, run both the Simulink simulation and X-Plane and you should see a
message like the one on the screen-shot. Yay, it’s working! Now for the receiving part…

Receiving UDP datagrams

To receive any data from X-Plane, you must make sure it is sending the right data to the right
address. To do this, again go to X-Plane -> Settings -> Net Connections -> Data. There you can mark
the first option, and fill in either the IPv4 address of the Simulink computer, or again the local host IP
address. Since ports 49000, 49001 and 49002 are already taken, take port 49003.
Cyriel Notteboom Menno Hochstenbach

It is also very important to note which data X-Plane is sending, as shown in Settings -> Data input &
output. In the same window you can change the rate at which X-Plane throws out data. I just put it to
maximum, 99.9 UDP/sec. Lower values may be more efficient, I encourage the motivated reader to
experiment.

1) UDP data is captured with “UDP Receive” from

the DSP System toolbox. Properties are as
follows:
X-Plane sends on port 49003. Depending on
how many channels you want to send, the
maximum length for message must be high
enough. (see later)
2) These datagrams have the same structure as
the one we sent earlier. Again, refer to Nuclear
Project’s website.
To decode these datagrams, I wrote again a
Matlab function block.
Cyriel Notteboom Menno Hochstenbach

% X-Plane: Channels 11, 17, 20

%--------------------------------------------------------------------------
% flight_con = [elev ailrn ruddr]; % flight controls
% attitude = [pitch roll hding_true hding_mag]; % pitch, roll, yaw
% location = [lat lon alt_msl alt_agl]; % latitude,
longitude, altitude [deg],[ftmsl],[ftagl] (mean sea level, actual ground
level)
%--------------------------------------------------------------------------

function [elev, ailrn, ruddr, pitch, roll, hding_true, hding_mag, lat, lon,
alt_msl, alt_agl] = UDP_decode(UDP)

% We don't need the DATA header, which are the first 5 bytes
UDP = UDP(6:end);

% We cut the datagram in channels, each containing 36 bytes, 4 for the

channel number, and 4 for each of the 8 entries.
CH11 = UDP(1:36);
CH17 = UDP(37:72);
CH20 = UDP(73:108);

%-------------------------
% At last we extract each entry from their channel and output them.
elev = Channel_to_single(CH11,1);
ailrn = Channel_to_single(CH11,2);
ruddr = Channel_to_single(CH11,3);

pitch = Channel_to_single(CH17,1);
roll = Channel_to_single(CH17,2);
hding_true = Channel_to_single(CH17,3);
hding_mag = Channel_to_single(CH17,4);

lat = Channel_to_single(CH20,1);
lon = Channel_to_single(CH20,2);
alt_msl = Channel_to_single(CH20,3);
alt_agl = Channel_to_single(CH20,4);

%---------------------------------
end

function [single] = Channel_to_single(CH, data_pos)

start_byte = 1 + 4*data_pos;
stop_byte = start_byte + 3;
single = CH(start_byte:stop_byte);

end

3) Now we have all data entries extracted from the

datagram. Don’t forget these are still uint8 types, so
we need to unpack the bytes to real life numbers.
Use “Byte Unpack”. Go in properties, and create as
much outputs as needed. (One for each entry). I
have 11 entries.
Cyriel Notteboom Menno Hochstenbach

4) Now is another good time to test. For exmple the elevator output from X-Plane. We see a
sampled output, but we only need the envelope of it. So I wrote a block that remembers the
last nonzero sample until a new one is received. And there you have it!

Raw samples

After Envelope block

5) The only thing that’s left to do, is to group the entries again in channels for clarity. Now you
can start adding your own blocks. Good luck!
Cyriel Notteboom Menno Hochstenbach

Resources
Ernst, D. (2007). Development of research platform for unmanned vehicle controller design ,
evaluation , and implementation system : From MATLAB to hardware based embedded
system.

Ernst, D., Valavanis, K., Garcia, R., & Craighead, J. (2007). Unmanned Vehicle Controller
Design, Evaluation and Implementation: From MATLAB to Printed Circuit Board.
Journal of Intelligent and Robotic Systems, 49(1), 85–108. doi:10.1007/s10846-007-
9130-4

Garcia, R., & Barnes, L. (2009). Multi-UAV Simulator Utilizing X-Plane. Journal of
Intelligent and Robotic Systems, 57(1-4), 393–406. doi:10.1007/s10846-009-9372-4

Ribeiro, L. R., & Oliveira, N. M. F. (2010). UAV autopilot controllers test platform using
Matlab/Simulink and X-Plane. 2010 IEEE Frontiers in Education Conference (FIE),
S2H–1–S2H–6. doi:10.1109/FIE.2010.5673378

Ronaldo, S., Maria, N., & Oliveira, F. De. (2011). EXPERIMENTAL FRAMEWORK FOR
EVALUATION OF GUIDANCE.

http://www.jefflewis.net/XPlaneUDP_9.html

http://www.nuclearprojects.com/xplane/

http://en.wikipedia.org/wiki/User_Datagram_Protocol