docs-mini/README.protocol

   1 The generic communication protocol for FlightGear provides a powerful way
   2 of adding a simple ASCII based or binary input/output protocol, just by
   3 defining an XML encoded configuration file and placing it in the
   4 $FG_ROOT/Protocol/ directory.
   5
   6
   7
   8
   9 == file layout ================================================================
  10
  11 A protocol file can contain either or both of <input> and <output>
  12 definition blocks. Which one is used depends on how the protocol
  13 is called  (e.g. --generic=file,out,1,/tmp/data.xml,myproto would
  14 only use the <output> definitions block).
  15
  16   <?xml version="1.0"?>
  17   <PropertyList>
  18       <generic>
  19
  20           <output>
  21               <binary_mode>false</binary_mode>
  22               <line_separator></line_separator>
  23               <var_separator></var_separator>
  24               <preamble></preamble>
  25               <postamble></postamble>
  26
  27               <chunk>
  28                       ... first chunk spec ...
  29               </chunk>
  30
  31               <chunk>
  32                       ... another chunk etc. ...
  33               </chunk>
  34           </output>
  35
  36           <input>
  37               <line_separator></line_separator>
  38               <var_separator></var_separator>
  39
  40               <chunk>
  41                       ... chunk spec ...
  42               </chunk>
  43           </input>
  44
  45       </generic>
  46   </PropertyList>
  47
  48
  49
  50
  51 == input/output parameters ====================================================
  52
  53 Both <output> and <input> blocks can contain information about
  54 the data mode (ascii/binary) and about separators between fields
  55 and data sets, as well as a list of <chunk>s. Each <chunk> defines
  56 a property that should be written (and how), or a variable and which
  57 property it should be written to.
  58
  59 --- ASCII protocol parameters ---
  60
  61 output only:
  62   <preamble>        STRING  default: ""    file header put on top of the file
  63   <postamble>       STRING  default: ""    file footer put at the end of the file
  64
  65 input & output:
  66   <binary_mode>     BOOL    default: false (= ASCII mode)
  67   <var_separator>   STRING  default: ""    field separator
  68   <line_separator>  STRING  default: ""    separator between data sets
  69
  70
  71 <var_separator> are put between every two output properties, while
  72 <line_separator> is put at the end of each data set. Both can contain
  73 arbitrary strings or one of the following keywords:
  74
  75   Name             Character
  76
  77   newline          '\n'
  78   tab              '\t'
  79   formfeed         '\f'
  80   carriagereturn   '\r'
  81   verticaltab      '\v'
  82
  83
  84 Typical use could be:
  85
  86   <var_separator>tab</var_separator>
  87   <line_separator>newline</var_separator>
  88
  89 or
  90
  91   <var_separator>\t</var_separator>
  92   <line_separator>\r\n</line_separator>
  93
  94
  95 --- Binary protocol parameters ---
  96
  97 To enable binary mode, simply include a <binary_mode>true</binary_mode> tag in
  98 your XML file. The format of the binary output is tightly packed, with 1 byte
  99 for bool, 4 bytes for int, and 8 bytes for double. At this time, strings are not
 100 supported. A configurable footer at the end of each "line" or packet of binary
 101 output can be added using the <binary_footer> tag. Options include the length
 102 of the packet, a magic number to simplify decoding. Examples:
 103
 104   <binary_footer>magic,0x12345678</binary_footer>
 105   <binary_footer>length</binary_footer>
 106   <binary_footer>none</binary_footer>                 <!-- default -->
 107
 108
 109
 110
 111 == variable parameters (chunk spec) ===========================================
 112
 113 Both <input> and <output> block can contain a list of <chunk> specs,
 114 each of which describes the properties of on variable to write/read.
 115
 116
 117   <name>        for ease of use (not tranferred)
 118   <node>        the property tree node which provides the data
 119   <type>        the value type (needed for formatting)
 120                 one of string, float, bool, int (default: int)
 121   <format>      (ASCII protocol only, not used or needed in binary mode)
 122                 defines the actual piece of text which should be sent.
 123                 it can include "printf" style formatting options like:
 124                                 <type>
 125                         %s      string
 126                         %d      integer (default)
 127                         %f      float
 128
 129   <factor>      an optional multiplication factor which can be used for
 130                 unit conversion. (for example, radians to degrees).
 131   <offset>      an optional offset which can be used for unit conversion.
 132                 (for example, degrees Celcius to degrees Fahrenheit).
 133
 134 For input chunks there exist some more options:
 135
 136   <rel>         optional boolean parameter to enable handling of incoming values
 137                 as relative changes (default: false)
 138                 (Can be eg. used to realise up/down buttons by just sending 1 or
 139                 -1 respectively)
 140
 141   <min>         an optional minimum limit for the value to be clamped to. This
 142                 limit is always specified as absolute value, also with relative
 143                 changes enabled. (default: 0)
 144   <max>         an optional upper limit for the input value to be clamped to. If
 145                 <min> equals <max> no limit is applied. (default: 0)
 146   <wrap>        instead of clamping to minimum and maximum limits, wrap values
 147                 around. (default: false)
 148                 (Usefull for eg. heading selector to start again with 1 for
 149                 values higher than 360)
 150
 151
 152 Chunks can also consist of a single constant <format>, like in:
 153   <format>Data Section</format>
 154
 155
 156 == examples ===================================================================
 157
 158 Writes log of this form:
 159
 160 V=16
 161 H=3.590505
 162 P=3.59
 163 V=12
 164 H=3.589020
 165 P=3.59
 166
 167
 168
 169 <?xml version="1.0"?>
 170
 171 <PropertyList>
 172   <generic>
 173
 174     <output>
 175       <line_separator>newline</line_separator>
 176       <var_separator>newline</var_separator>
 177       <binary_mode>false</binary_mode>
 178
 179       <chunk>
 180         <name>speed</name>
 181         <format>V=%d</format>
 182         <node>/velocities/airspeed-kt</node>
 183       </chunk>
 184
 185       <chunk>
 186         <name>heading (rad)</name>
 187         <format>H=%.6f</format>
 188         <type>float</type>
 189         <node>/orientation/heading-deg</node>
 190         <factor>0.0174532925199433</factor>  <!-- degrees to radians -->
 191       </chunk>
 192
 193       <chunk>
 194         <name>pitch angle (deg)</name>
 195         <format>P=%03.2f</format>
 196         <node>/orientation/pitch-deg</node>
 197       </chunk>
 198    </output>
 199
 200  </generic>
 201 </PropertyList>
 202
 203
 204 Control the heading bug by sending relative changes separated by newlines:
 205
 206 <?xml version="1.0"?>
 207
 208 <PropertyList>
 209   <generic>
 210
 211     <input>
 212       <line_separator>newline</line_separator>
 213
 214        <chunk>
 215          <name>heading bug</name>
 216          <type>int</type>
 217          <node>/autopilot/settings/heading-bug-deg</node>
 218          <relative>true</relative>
 219          <min>1</min>
 220          <max>360</max>
 221          <wrap>true</wrap>
 222      </chunk>
 223
 224    </input>
 225
 226  </generic>
 227 </PropertyList>
 228
 229 -- writing data in XML syntax -------------------------------------------------
 230
 231 Assuming the file is called $FG_ROOT/Protocol/xmltest.xml, then it could be
 232 used as   $ fgfs --generic=file,out,1,/tmp/data.xml,xmltest
 233
 234
 235 <?xml version="1.0"?>
 236
 237 <PropertyList>
 238   <generic>
 239     <output>
 240       <binary_mode>false</binary_mode>
 241       <var_separator>\n</var_separator>
 242       <line_separator>\n</line_separator>
 243       <preamble>&lt;?xml version="1.0"?&gt;\n\n&lt;data&gt;\n</preamble>
 244       <postamble>&lt;/data&gt;\n</postamble>
 245
 246       <chunk>
 247         <format>\t&lt;set&gt;</format>
 248       </chunk>
 249
 250       <chunk>
 251         <node>/position/altitude-ft</node>
 252         <type>float</type>
 253         <format>\t\t&lt;altitude-ft&gt;%.8f&lt;/altitude-ft&gt;</format>
 254       </chunk>
 255
 256       <chunk>
 257         <node>/velocities/airspeed-kt</node>
 258         <type>float</type>
 259         <format>\t\t&lt;airspeed-kt&gt;%.8f&lt;/airspeed-kt&gt;</format>
 260       </chunk>
 261
 262       <chunk>
 263         <format>\t&lt;/set&gt;</format>
 264       </chunk>
 265     </output>
 266   </generic>
 267 </PropertyList>
 268
 269
 270 -- Analyzing the resulting binary packet format -------------------------------
 271
 272 A utility called generic-protocol-analyse can be found under
 273 FlightGear/utils/xmlgrep which can be used to analyze the resulting
 274 data packet for the binary protocol.
 275
 276 The output would be something like:
 277
 278 bintest.xml
 279 Generic binary output protocol packet description:
 280
 281  pos | size |  type  | factor     | description
 282 -----|------|--------|------------|------------------------
 283    0 |    4 |    int |            | indicated speed (kt)
 284    4 |    4 |  float |            | pitch att (deg)
 285    8 |    4 |  float |            | magnetic heading (deg)
 286   12 |    4 |    int |            | outside air temperarure (degF)
 287   16 |    1 |   bool |            | autocoord
 288
 289 total package size: 17 bytes
 290