README.md

   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 =======================
   5
   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
  19 {ok, {64=Index, GroupsRaw}=DataRaw} = x_plane_data_raw:of_bin(XPlaneDataPacket),
  20 ```
  21
  22 ### Access parsed data
  23
  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
  29 ```erlang
  30 % Speeds are in group 3
  31 {3, Speeds} = lists:keyfind(3, 1, GroupsRaw),
  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
  43 {17, PitchRollHeadings} = lists:keyfind(17, 1, GroupsRaw),
  44 { PitchDeg
  45 , RollDeg
  46 , HdingTrue
  47 , HdingMag
  48 , _
  49 , _
  50 , _
  51 , _
  52 } = PitchRollHeadings,
  53 ```
  54
  55 #### Named
  56
  57 Here we identify what each of the numbered groups mean in a given X-Plane
  58 version. Right now only X-Plane 10 (packet index 64) is supported and I only
  59 identified 3 groups so far:
  60
  61 | packet index | group index | group name           |
  62 |--------------|-------------|----------------------|
  63 | 64           | 3           | `speeds`             |
  64 | 64           | 17          | `pitch_roll_heading` |
  65 | 64           | 20          | `lat_lon_alt`        |
  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
  78 -include_lib("x_plane_data_group_lat_lon_alt.hrl").
  79 -include_lib("x_plane_data_group_pitch_roll_heading.hrl").
  80 -include_lib("x_plane_data_group_speeds.hrl").
  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
 104 Data format references
 105 ----------------------
 106
 107 - http://b58.svglobe.com/data.html
 108 - http://www.nuclearprojects.com/xplane/xplaneref.html