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