X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=docs-mini%2FREADME.protocol;h=80a7163c68f6119bc43c53885f75224b85a881c8;hb=575f576aa90d8d22a857ccbb5e9f2c2e79a0db50;hp=7e66858ba1ade9e73eb2058d6798e773d13974cd;hpb=2bcf5b7fe7b9b7c6227f977137e1bd057136c049;p=flightgear.git

diff --git a/docs-mini/README.protocol b/docs-mini/README.protocol
index 7e66858ba..80a7163c6 100644
--- 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,54 @@ 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).
 
+For input chunks there exist some more options:
 
-Chunks can also consist of a single constant <format>, like in:
+  <rel>         optional boolean parameter to enable handling of incoming values
+                as relative changes (default: false)
+                (Can be eg. used to realise up/down buttons by just sending 1 or
+                -1 respectively)
+
+  <min>         an optional minimum limit for the value to be clamped to. This
+                limit is always specified as absolute value, also with relative
+                changes enabled. (default: 0)
+  <max>         an optional upper limit for the input value to be clamped to. If
+                <min> equals <max> no limit is applied. (default: 0)
+  <wrap>        instead of clamping to minimum and maximum limits, wrap values
+                around. Values will be in [min, max[ (default: false)
+                (Usefull for eg. heading selector to start again with 1 for
+                values higher than 360)
 
+<rel>, <min>, <max> and <wrap> are only used for numeric data types. <rel> can
+additionally be used with type 'bool', where it toggles the value, if the received
+value evaluates to 'true', otherwise the value is left unchanged.
 
+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
 
 
 
@@ -182,11 +204,34 @@ P=006.4
 </PropertyList>
 
 
+Control the heading bug by sending relative changes separated by newlines:
+
+<?xml version="1.0"?>
+
+<PropertyList>
+  <generic>
+
+    <input>
+      <line_separator>newline</line_separator>
 
+       <chunk>
+         <name>heading bug</name>
+         <type>int</type>
+         <node>/autopilot/settings/heading-bug-deg</node>
+         <relative>true</relative>
+         <min>1</min>
+         <max>360</max>
+         <wrap>true</wrap>
+     </chunk>
+
+   </input>
+
+ </generic>
+</PropertyList>
 
 -- 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 +241,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
+