Merge branch 'torsten/proplist' into next

[flightgear.git] / docs-mini / README.protocol

diff --git a/docs-mini/README.protocol b/docs-mini/README.protocol
index 7e66858ba1ade9e73eb2058d6798e773d13974cd..ef9c39a2e1d8bd39a7a64e2f5d2cfde4826511a2 100644 (file)
--- a/docs-mini/README.protocol
+++ b/docs-mini/README.protocol
@@ -1,7 +1,7 @@
 The generic communication protocol for FlightGear provides a powerful way
 of adding a simple ASCII based or binary input/output protocol, just by
 defining an XML encoded configuration file and placing it in the
-$FG_ROOT/data/Protocols/ directory.
+$FG_ROOT/Protocol/ directory.
 
 
 
@@ -56,12 +56,14 @@ and data sets, as well as a list of <chunk>s. Each <chunk> defines
 a property that should be written (and how), or a variable and which
 property it should be written to.
 
+--- ASCII protocol parameters ---
+
 output only:
-  <binary_mode>     BOOL    default: false (= ASCII mode)
   <preamble>        STRING  default: ""    file header put on top of the file
   <postamble>       STRING  default: ""    file footer put at the end of the file
 
 input & output:
+  <binary_mode>            BOOL    default: false (= ASCII mode)
   <var_separator>   STRING  default: ""    field separator
   <line_separator>  STRING  default: ""    separator between data sets
 
@@ -90,6 +92,7 @@ or
   <line_separator>\r\n</line_separator>
 
 
+--- Binary protocol parameters ---
 
 To enable binary mode, simply include a <binary_mode>true</binary_mode> tag in
 your XML file. The format of the binary output is tightly packed, with 1 byte
@@ -115,35 +118,34 @@ each of which describes the properties of on variable to write/read.
   <node>        the property tree node which provides the data
   <type>        the value type (needed for formatting)
                 one of string, float, bool, int (default: int)
-  <format>      defines the actual piece of text which should be sent.
+  <format>      (ASCII protocol only, not used or needed in binary mode)
+                defines the actual piece of text which should be sent.
                 it can include "printf" style formatting options like:
                                 <type>
                         %s      string
                         %d      integer (default)
                         %f      float
-                        (not used or needed in binary mode)
 
   <factor>      an optional multiplication factor which can be used for
                 unit conversion. (for example, radians to degrees).
   <offset>      an optional offset which can be used for unit conversion.
-                (for example, degrees to radians).
+                (for example, degrees Celcius to degrees Fahrenheit).
 
 
 Chunks can also consist of a single constant <format>, like in:
-
-
+  <format>Data Section</format>
 
 
 == examples ===================================================================
 
 Writes log of this form:
 
-V=1736
-H=17647
-P=004.6
-V=1780
-H=18105
-P=006.4
+V=16
+H=3.590505
+P=3.59
+V=12
+H=3.589020
+P=3.59
 
 
 
@@ -186,7 +188,7 @@ P=006.4
 
 -- writing data in XML syntax -------------------------------------------------
 
-Assuming the file is called $FG_ROOT/Protocols/xmltest.xml, then it could be
+Assuming the file is called $FG_ROOT/Protocol/xmltest.xml, then it could be
 used as   $ fgfs --generic=file,out,1,/tmp/data.xml,xmltest
 
 
@@ -196,32 +198,53 @@ used as   $ fgfs --generic=file,out,1,/tmp/data.xml,xmltest
   <generic>
     <output>
       <binary_mode>false</binary_mode>
-      <line_separator></line_separator>
-      <var_separator></var_separator>
+      <var_separator>\n</var_separator>
+      <line_separator>\n</line_separator>
       <preamble>&lt;?xml version="1.0"?&gt;\n\n&lt;data&gt;\n</preamble>
       <postamble>&lt;/data&gt;\n</postamble>
 
       <chunk>
-        <format>\t&lt;set&gt;\n</format>
+        <format>\t&lt;set&gt;</format>
       </chunk>
 
       <chunk>
         <node>/position/altitude-ft</node>
         <type>float</type>
-        <format>\t\t&lt;altitude-ft&gt;%.8f&lt;/altitude-ft&gt;\n</format>
+        <format>\t\t&lt;altitude-ft&gt;%.8f&lt;/altitude-ft&gt;</format>
       </chunk>
 
       <chunk>
         <node>/velocities/airspeed-kt</node>
         <type>float</type>
-        <format>\t\t&lt;airspeed-kt&gt;%.8f&lt;/airspeed-kt&gt;\n</format>
+        <format>\t\t&lt;airspeed-kt&gt;%.8f&lt;/airspeed-kt&gt;</format>
       </chunk>
 
       <chunk>
-        <format>\t&lt;/set&gt;\n</format>
+        <format>\t&lt;/set&gt;</format>
       </chunk>
     </output>
   </generic>
 </PropertyList>
 
 
+-- Analyzing the resulting binary packet format -------------------------------
+
+A utility called generic-protocol-analyse can be found under
+FlightGear/utils/xmlgrep which can be used to analyze the resulting
+data packet for the binary protocol.
+
+The output would be something like:
+
+bintest.xml
+Generic binary output protocol packet description:
+
+ pos | size |  type  | factor     | description
+-----|------|--------|------------|------------------------
+   0 |    4 |    int |            | indicated speed (kt)
+   4 |    4 |  float |            | pitch att (deg)
+   8 |    4 |  float |            | magnetic heading (deg)
+  12 |    4 |    int |            | outside air temperarure (degF)
+  16 |    1 |   bool |            | autocoord
+
+total package size: 17 bytes
+