Commit | Line | Data |
---|---|---|
0ff52c47 | 1 | [![Build Status](https://travis-ci.org/xandkar/erlang-x-plane-data.svg?branch=master)](https://travis-ci.org/xandkar/erlang-x-plane-data) |
3549a33a SK |
2 | |
3 | X-Plane UDP data parser | |
4 | ======================= | |
d014d93e | 5 | |
ca0b3fd4 SK |
6 | ![Data output in the cockpit](screenshot.png) |
7 | ||
25c95554 SK |
8 | Examples |
9 | -------- | |
10 | ||
11 | ### Receive data packet | |
12 | ||
13 | ```erlang | |
14 | {ok, Socket} = gen_udp:open(Port, [binary, {active, false}]), | |
15 | {ok, {_, _, <<XPlaneDataPacket/binary>>}} = gen_udp:recv(Socket, 0), | |
16 | ``` | |
17 | ||
18 | ### Parse data packet | |
19 | ||
20 | ```erlang | |
84fa8ccb | 21 | {ok, {64=Index, GroupsRaw}=DataRaw} = x_plane_data_raw:of_bin(XPlaneDataPacket), |
25c95554 SK |
22 | ``` |
23 | ||
24 | ### Access parsed data | |
64c0d81f | 25 | |
84fa8ccb SK |
26 | #### Raw |
27 | ||
04508b6c | 28 | At this stage, only the structure of the packet was parsed. No attempts at |
84fa8ccb SK |
29 | interpreting the values have been made: |
30 | ||
64c0d81f | 31 | ```erlang |
25c95554 | 32 | % Speeds are in group 3 |
84fa8ccb | 33 | {3, Speeds} = lists:keyfind(3, 1, GroupsRaw), |
25c95554 SK |
34 | { VindKias |
35 | , VindKeas | |
36 | , VtrueKtas | |
37 | , VtrueKtgs | |
38 | , _ | |
39 | , VindMph | |
40 | , VtrueMphas | |
41 | , VtrueMphgs | |
42 | } = Speeds, | |
43 | ||
44 | % Pitch roll and headings values are in group 17 | |
84fa8ccb | 45 | {17, PitchRollHeadings} = lists:keyfind(17, 1, GroupsRaw), |
25c95554 SK |
46 | { PitchDeg |
47 | , RollDeg | |
48 | , HdingTrue | |
49 | , HdingMag | |
50 | , _ | |
51 | , _ | |
52 | , _ | |
53 | , _ | |
54 | } = PitchRollHeadings, | |
64c0d81f SK |
55 | ``` |
56 | ||
84fa8ccb SK |
57 | #### Named |
58 | ||
59 | Here we identify what each of the numbered groups mean in a given X-Plane | |
3f512f37 SK |
60 | version. Right now only X-Plane 10 (packet index 64) is supported and I only |
61 | identified 3 groups so far: | |
84fa8ccb | 62 | |
924626bc SK |
63 | | packet index | group index | group name | |
64 | |--------------|-------------|----------------------| | |
65 | | 64 | 3 | `speeds` | | |
66 | | 64 | 17 | `pitch_roll_heading` | | |
67 | | 64 | 20 | `lat_lon_alt` | | |
84fa8ccb SK |
68 | |
69 | Unidentified groups (with index other than what is listed above) will be | |
70 | absent from the list of named groups (think of `x_plane_data_named:of_raw/1` as | |
71 | a filter), so you'll have to access their raw version, if needed. | |
72 | ||
73 | ##### Identify | |
74 | ```erlang | |
75 | {ok, {x_plane_data_v10, GroupsNamed}} = x_plane_data_named:of_raw(DataRaw), | |
76 | ``` | |
77 | ||
78 | ##### Access | |
79 | ```erlang | |
c80f9c88 | 80 | -include_lib("x_plane_data/include/x_plane_data_group_speeds.hrl"). |
84fa8ccb SK |
81 | {speeds, #x_plane_data_group_speeds |
82 | { vind_kias = VindKias | |
83 | , vind_keas = VindKeas | |
84 | , vtrue_ktas = VtrueKtas | |
85 | , vtrue_ktgs = VtrueKtgs | |
86 | , vind_mph = VindMph | |
87 | , vtrue_mphas = VtrueMphas | |
88 | , vtrue_mphgs = VtrueMphgs | |
89 | } | |
90 | } = lists:keyfind(speeds, 1, GroupsNamed), | |
91 | ||
859f8f9a SK |
92 | ... |
93 | ||
94 | -include_lib("x_plane_data/include/x_plane_data_group_pitch_roll_heading.hrl"). | |
84fa8ccb SK |
95 | {pitch_roll_heading, #x_plane_data_group_pitch_roll_heading |
96 | { pitch_deg = PitchDeg | |
97 | , roll_deg = RollDeg | |
98 | , hding_true = HdingTrue | |
99 | , hding_mag = HdingMag | |
100 | } | |
101 | } = lists:keyfind(pitch_roll_heading, 1, GroupsNamed), | |
3217de21 SK |
102 | |
103 | ... | |
104 | ||
105 | -include_lib("x_plane_data/include/x_plane_data_group_lat_lon_alt.hrl"). | |
106 | {lat_lon_alt, #x_plane_data_group_lat_lon_alt | |
107 | { lat_deg = LatDeg | |
108 | , lon_deg = LonDeg | |
109 | , alt_ftmsl = AltFtmsl | |
110 | , alt_ftagl = AltFtagl | |
111 | , on_runwy = OnRunwy | |
112 | , alt_ind = AltInd | |
113 | , lat_south = LatSouth | |
114 | , lon_west = LonWest | |
115 | } | |
116 | } = lists:keyfind(lat_lon_alt, 1, GroupsNamed), | |
84fa8ccb SK |
117 | ``` |
118 | ||
4698884e SK |
119 | Packet structure |
120 | ---------------- | |
d014d93e | 121 | |
4698884e SK |
122 | ```erlang |
123 | <<"DATA", PacketIndex:8/integer, Groups/binary>>, | |
124 | << GroupIndex:32/little-integer | |
125 | , GroupValue1:32/little-float | |
126 | , GroupValue2:32/little-float | |
127 | , GroupValue3:32/little-float | |
128 | , GroupValue4:32/little-float | |
129 | , GroupValue5:32/little-float | |
130 | , GroupValue6:32/little-float | |
131 | , GroupValue7:32/little-float | |
132 | , GroupValue8:32/little-float | |
133 | , GroupsRest/binary | |
134 | >> = Groups, | |
135 | ``` | |
136 | ||
137 | Where `PacketIndex` indicates something like a schema version, i.e. what each | |
138 | of the numbered groups means. For example, in X-Plane 10, packet index is 64 | |
139 | (character `"@"`) and group 3 contains speed data, in which the 8 group values | |
140 | are: | |
141 | ||
142 | | Location | Label | Description | | |
143 | |----------|---------------|-------------| | |
144 | | 1 | `vind_kias` | Velocity indicated, in knots indicated airspeed. | | |
145 | | 2 | `vind_keas` | Velocity indicated, in knots equivalent airspeed (the calibrated airspeed corrected for adiabatic compressible flow at the craft's current altitude). | | |
146 | | 3 | `vtrue_ktas` | Velocity true (the speed of the craft relative to undisturbed air), in knots true airspeed. | | |
147 | | 4 | `vtrue_ktgs` | Velocity true, in knots true ground speed. | | |
148 | | 5 | | Unused. Contains a dummy value. | | |
149 | | 6 | `vind_mph` | Velocity indicated, in miles per hour. | | |
150 | | 7 | `vtrue_mphas` | Velocity true, in miles per hour airspeed. | | |
151 | | 8 | `vtrue_mphgs` | Velocity true, in miles per hour ground speed. | | |
152 | ||
153 | ||
154 | References | |
155 | ---------- | |
156 | ||
157 | - `X-Plane_10_manual.pdf` (distributed with X-Plane 10) | |
d014d93e SK |
158 | - http://b58.svglobe.com/data.html |
159 | - http://www.nuclearprojects.com/xplane/xplaneref.html |