X-Git-Url: https://git.xandkar.net/?p=erlang-x-plane-data.git;a=blobdiff_plain;f=README.md;h=382c4b58d3bc85fc417e95b2213a4483770ebb31;hp=16c0a3d046876610a65ded6011e251fe932b054e;hb=HEAD;hpb=8892b9afe9757950420b83fb56a8df1a5a30bf7f diff --git a/README.md b/README.md index 16c0a3d..382c4b5 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,159 @@ -[![Build Status](https://travis-ci.org/ibnfirnas/erlang-x_plane_data.svg?branch=master)](https://travis-ci.org/ibnfirnas/erlang-x_plane_data) +[![Build Status](https://travis-ci.org/xandkar/erlang-x-plane-data.svg?branch=master)](https://travis-ci.org/xandkar/erlang-x-plane-data) X-Plane UDP data parser ======================= -Example -------- +![Data output in the cockpit](screenshot.png) + +Examples +-------- + +### Receive data packet + +```erlang +{ok, Socket} = gen_udp:open(Port, [binary, {active, false}]), +{ok, {_, _, <>}} = gen_udp:recv(Socket, 0), +``` + +### Parse data packet + +```erlang +{ok, {64=Index, GroupsRaw}=DataRaw} = x_plane_data_raw:of_bin(XPlaneDataPacket), +``` + +### Access parsed data + +#### Raw + +At this stage, only the structure of the packet was parsed. No attempts at +interpreting the values have been made: + +```erlang +% Speeds are in group 3 +{3, Speeds} = lists:keyfind(3, 1, GroupsRaw), +{ VindKias +, VindKeas +, VtrueKtas +, VtrueKtgs +, _ +, VindMph +, VtrueMphas +, VtrueMphgs +} = Speeds, + +% Pitch roll and headings values are in group 17 +{17, PitchRollHeadings} = lists:keyfind(17, 1, GroupsRaw), +{ PitchDeg +, RollDeg +, HdingTrue +, HdingMag +, _ +, _ +, _ +, _ +} = PitchRollHeadings, +``` + +#### Named + +Here we identify what each of the numbered groups mean in a given X-Plane +version. Right now only X-Plane 10 (packet index 64) is supported and I only +identified 3 groups so far: + +| packet index | group index | group name | +|--------------|-------------|----------------------| +| 64 | 3 | `speeds` | +| 64 | 17 | `pitch_roll_heading` | +| 64 | 20 | `lat_lon_alt` | + +Unidentified groups (with index other than what is listed above) will be +absent from the list of named groups (think of `x_plane_data_named:of_raw/1` as +a filter), so you'll have to access their raw version, if needed. + +##### Identify +```erlang +{ok, {x_plane_data_v10, GroupsNamed}} = x_plane_data_named:of_raw(DataRaw), +``` + +##### Access +```erlang +-include_lib("x_plane_data/include/x_plane_data_group_speeds.hrl"). +{speeds, #x_plane_data_group_speeds + { vind_kias = VindKias + , vind_keas = VindKeas + , vtrue_ktas = VtrueKtas + , vtrue_ktgs = VtrueKtgs + , vind_mph = VindMph + , vtrue_mphas = VtrueMphas + , vtrue_mphgs = VtrueMphgs + } +} = lists:keyfind(speeds, 1, GroupsNamed), + +... + +-include_lib("x_plane_data/include/x_plane_data_group_pitch_roll_heading.hrl"). +{pitch_roll_heading, #x_plane_data_group_pitch_roll_heading + { pitch_deg = PitchDeg + , roll_deg = RollDeg + , hding_true = HdingTrue + , hding_mag = HdingMag + } +} = lists:keyfind(pitch_roll_heading, 1, GroupsNamed), + +... + +-include_lib("x_plane_data/include/x_plane_data_group_lat_lon_alt.hrl"). +{lat_lon_alt, #x_plane_data_group_lat_lon_alt + { lat_deg = LatDeg + , lon_deg = LonDeg + , alt_ftmsl = AltFtmsl + , alt_ftagl = AltFtagl + , on_runwy = OnRunwy + , alt_ind = AltInd + , lat_south = LatSouth + , lon_west = LonWest + } +} = lists:keyfind(lat_lon_alt, 1, GroupsNamed), +``` + +Packet structure +---------------- ```erlang --include_lib("include/x_plane_data.hrl"). - -main(Port) -> - {ok, Socket} = gen_udp:open(Port, [binary, {active, false}]), - {ok, {_, _, <>}} = gen_udp:recv(Socket, 0), - {ok, XPlaneData} = x_plane_data:of_bin(XPlaneDataPacket), - - % Currently there're 133 possible data types sent by X-Plane 10, of which - % I've identified and labeled only some of. See x_plane_datum:t() type for - % what is currently labeled. - % The types I've not yet labeled are in the format specified by - % x_plane_datum:anonymous() and can be looked-up by their index number. - - % Find labeled data types - {some, #x_plane_datum_speeds - { vind_kias = VindKias - , vind_keas = VindKeas - , vtrue_ktas = VtrueKtas - , vtrue_ktgs = VtrueKtgs - , vind_mph = VindMph - , vtrue_mphas = VtrueMphas - , vtrue_mphgs = VtrueMphgs - }, - } = hope_kv_list:get(XPlaneData, speeds), - - {some, #x_plane_datum_pitch_roll_heading - { pitch_deg = PitchDeg - , roll_deg = RollDeg - , hding_true = HdingTrue - , hding_mag = HdingMag - }, - } = hope_kv_list:get(XPlaneData, pitch_roll_heading), - - {some, #x_plane_datum_lat_lon_alt - { lat_deg = LatDeg - , lon_deg = LonDeg - , alt_ftmsl = AltFtmsl - , alt_ftagl = AltFtagl - , on_runwy = OnRunwy - , alt_ind = AltInd - , lat_south = LatSouth - , lat_west = LatWest - }, - } = hope_kv_list:get(XPlaneData, lat_lon_alt), - - % Find an unlabled data type - {some, {10, V1, V2, V3, V4, V5, V6, V7, V8}} = hope_kv_list:get(XPlaneData, 10), - - % Attempt to find a data type that was not included in current packet - none = hope_kv_list:get(XPlaneData, 130), - none = hope_kv_list:get(XPlaneData, 67), - - ... +<<"DATA", PacketIndex:8/integer, Groups/binary>>, +<< GroupIndex:32/little-integer + , GroupValue1:32/little-float + , GroupValue2:32/little-float + , GroupValue3:32/little-float + , GroupValue4:32/little-float + , GroupValue5:32/little-float + , GroupValue6:32/little-float + , GroupValue7:32/little-float + , GroupValue8:32/little-float + , GroupsRest/binary +>> = Groups, ``` -Note: you can, of course, use any other method to search a `[{K, V}]` list -(which is how `x_plane_data:t()` is structured), such as: -`proplists:get_value/2`, `lists:keyfind/3`, etc., but I prefer the API of -`hope_kv_list`, so I used that. +Where `PacketIndex` indicates something like a schema version, i.e. what each +of the numbered groups means. For example, in X-Plane 10, packet index is 64 +(character `"@"`) and group 3 contains speed data, in which the 8 group values +are: + +| Location | Label | Description | +|----------|---------------|-------------| +| 1 | `vind_kias` | Velocity indicated, in knots indicated airspeed. | +| 2 | `vind_keas` | Velocity indicated, in knots equivalent airspeed (the calibrated airspeed corrected for adiabatic compressible flow at the craft's current altitude). | +| 3 | `vtrue_ktas` | Velocity true (the speed of the craft relative to undisturbed air), in knots true airspeed. | +| 4 | `vtrue_ktgs` | Velocity true, in knots true ground speed. | +| 5 | | Unused. Contains a dummy value. | +| 6 | `vind_mph` | Velocity indicated, in miles per hour. | +| 7 | `vtrue_mphas` | Velocity true, in miles per hour airspeed. | +| 8 | `vtrue_mphgs` | Velocity true, in miles per hour ground speed. | -Data format references ----------------------- +References +---------- +- `X-Plane_10_manual.pdf` (distributed with X-Plane 10) - http://b58.svglobe.com/data.html - http://www.nuclearprojects.com/xplane/xplaneref.html