X-Git-Url: https://git.xandkar.net/?a=blobdiff_plain;f=README.md;h=b417370d307e93e9da7e108ead2dc5a761feed72;hb=84fa8ccb7143428a0aa49ceeb632ff45b374d8b8;hp=16c0a3d046876610a65ded6011e251fe932b054e;hpb=8892b9afe9757950420b83fb56a8df1a5a30bf7f;p=erlang-x-plane-data.git

diff --git a/README.md b/README.md
index 16c0a3d..b417370 100644
--- a/README.md
+++ b/README.md
@@ -3,70 +3,101 @@
 X-Plane UDP data parser
 =======================
 
-Example
--------
+Examples
+--------
+
+### Receive data packet
+
+```erlang
+{ok, Socket} = gen_udp:open(Port, [binary, {active, false}]),
+{ok, {_, _, <<XPlaneDataPacket/binary>>}} = 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 attempt at
+interpreting the values have been made:
 
 ```erlang
--include_lib("include/x_plane_data.hrl").
-
-main(Port) ->
-    {ok, Socket} = gen_udp:open(Port, [binary, {active, false}]),
-    {ok, {_, _, <<XPlaneDataPacket/binary>>}} = 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),
-
-    ...
+% 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,
 ```
 
-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.
+#### Named
 
+Here we identify what each of the numbered groups mean in a given X-Plane
+version. Right now only X-Plane 10 is supported and I only identified 3 groups
+so far:
+
+- index: `3` , name: `speeds`
+- index: `17`, name: `pitch_roll_heading`
+- index: `20`, name: `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_group_lat_lon_alt.hrl").
+-include_lib("x_plane_data_group_pitch_roll_heading.hrl").
+-include_lib("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),
+
+{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),
+```
 
 Data format references
 ----------------------