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. Values will be in [min, max[ (default: false)
 148                 (Usefull for eg. heading selector to start again with 1 for
 149                 values higher than 360)
 150
 151 <rel>, <min>, <max> and <wrap> are only used for numeric data types. <rel> can
 152 additionally be used with type 'bool', where it toggles the value, if the received
 153 value evaluates to 'true', otherwise the value is left unchanged.
 154
 155 Chunks can also consist of a single constant <format>, like in:
 156   <format>Data Section</format>
 157
 158
 159 == examples ===================================================================
 160
 161 Writes log of this form:
 162
 163 V=16
 164 H=3.590505
 165 P=3.59
 166 V=12
 167 H=3.589020
 168 P=3.59
 169
 170
 171
 172 <?xml version="1.0"?>
 173
 174 <PropertyList>
 175   <generic>
 176
 177     <output>
 178       <line_separator>newline</line_separator>
 179       <var_separator>newline</var_separator>
 180       <binary_mode>false</binary_mode>
 181
 182       <chunk>
 183         <name>speed</name>
 184         <format>V=%d</format>
 185         <node>/velocities/airspeed-kt</node>
 186       </chunk>
 187
 188       <chunk>
 189         <name>heading (rad)</name>
 190         <format>H=%.6f</format>
 191         <type>float</type>
 192         <node>/orientation/heading-deg</node>
 193         <factor>0.0174532925199433</factor>  <!-- degrees to radians -->
 194       </chunk>
 195
 196       <chunk>
 197         <name>pitch angle (deg)</name>
 198         <format>P=%03.2f</format>
 199         <node>/orientation/pitch-deg</node>
 200       </chunk>
 201    </output>
 202
 203  </generic>
 204 </PropertyList>
 205
 206
 207 Control the heading bug by sending relative changes separated by newlines:
 208
 209 <?xml version="1.0"?>
 210
 211 <PropertyList>
 212   <generic>
 213
 214     <input>
 215       <line_separator>newline</line_separator>
 216
 217        <chunk>
 218          <name>heading bug</name>
 219          <type>int</type>
 220          <node>/autopilot/settings/heading-bug-deg</node>
 221          <relative>true</relative>
 222          <min>1</min>
 223          <max>360</max>
 224          <wrap>true</wrap>
 225      </chunk>
 226
 227    </input>
 228
 229  </generic>
 230 </PropertyList>
 231
 232 -- writing data in XML syntax -------------------------------------------------
 233
 234 Assuming the file is called $FG_ROOT/Protocol/xmltest.xml, then it could be
 235 used as   $ fgfs --generic=file,out,1,/tmp/data.xml,xmltest
 236
 237
 238 <?xml version="1.0"?>
 239
 240 <PropertyList>
 241   <generic>
 242     <output>
 243       <binary_mode>false</binary_mode>
 244       <var_separator>\n</var_separator>
 245       <line_separator>\n</line_separator>
 246       <preamble>&lt;?xml version="1.0"?&gt;\n\n&lt;data&gt;\n</preamble>
 247       <postamble>&lt;/data&gt;\n</postamble>
 248
 249       <chunk>
 250         <format>\t&lt;set&gt;</format>
 251       </chunk>
 252
 253       <chunk>
 254         <node>/position/altitude-ft</node>
 255         <type>float</type>
 256         <format>\t\t&lt;altitude-ft&gt;%.8f&lt;/altitude-ft&gt;</format>
 257       </chunk>
 258
 259       <chunk>
 260         <node>/velocities/airspeed-kt</node>
 261         <type>float</type>
 262         <format>\t\t&lt;airspeed-kt&gt;%.8f&lt;/airspeed-kt&gt;</format>
 263       </chunk>
 264
 265       <chunk>
 266         <format>\t&lt;/set&gt;</format>
 267       </chunk>
 268     </output>
 269   </generic>
 270 </PropertyList>
 271
 272
 273 -- Analyzing the resulting binary packet format -------------------------------
 274
 275 A utility called generic-protocol-analyse can be found under
 276 FlightGear/utils/xmlgrep which can be used to analyze the resulting
 277 data packet for the binary protocol.
 278
 279 The output would be something like:
 280
 281 bintest.xml
 282 Generic binary output protocol packet description:
 283
 284  pos | size |  type  | factor     | description
 285 -----|------|--------|------------|------------------------
 286    0 |    4 |    int |            | indicated speed (kt)
 287    4 |    4 |  float |            | pitch att (deg)
 288    8 |    4 |  float |            | magnetic heading (deg)
 289   12 |    4 |    int |            | outside air temperarure (degF)
 290   16 |    1 |   bool |            | autocoord
 291
 292 total package size: 17 bytes
 293