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/data/Protocols/ 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 output only:
  60   <binary_mode>     BOOL    default: false (= ASCII mode)
  61   <preamble>        STRING  default: ""    file header put on top of the file
  62   <postamble>       STRING  default: ""    file footer put at the end of the file
  63
  64 input & output:
  65   <var_separator>   STRING  default: ""    field separator
  66   <line_separator>  STRING  default: ""    separator between data sets
  67
  68
  69 <var_separator> are put between every two output properties, while
  70 <line_separator> is put at the end of each data set. Both can contain
  71 arbitrary strings or one of the following keywords:
  72
  73   Name             Character
  74
  75   newline          '\n'
  76   tab              '\t'
  77   formfeed         '\f'
  78   carriagereturn   '\r'
  79   verticaltab      '\v'
  80
  81
  82 Typical use could be:
  83
  84   <var_separator>tab</var_separator>
  85   <line_separator>newline</var_separator>
  86
  87 or
  88
  89   <var_separator>\t</var_separator>
  90   <line_separator>\r\n</line_separator>
  91
  92
  93
  94 To enable binary mode, simply include a <binary_mode>true</binary_mode> tag in
  95 your XML file. The format of the binary output is tightly packed, with 1 byte
  96 for bool, 4 bytes for int, and 8 bytes for double. At this time, strings are not
  97 supported. A configurable footer at the end of each "line" or packet of binary
  98 output can be added using the <binary_footer> tag. Options include the length
  99 of the packet, a magic number to simplify decoding. Examples:
 100
 101   <binary_footer>magic,0x12345678</binary_footer>
 102   <binary_footer>length</binary_footer>
 103   <binary_footer>none</binary_footer>                 <!-- default -->
 104
 105
 106
 107
 108 == variable parameters (chunk spec) ===========================================
 109
 110 Both <input> and <output> block can contain a list of <chunk> specs,
 111 each of which describes the properties of on variable to write/read.
 112
 113
 114   <name>        for ease of use (not tranferred)
 115   <node>        the property tree node which provides the data
 116   <type>        the value type (needed for formatting)
 117                 one of string, float, bool, int (default: int)
 118   <format>      defines the actual piece of text which should be sent.
 119                 it can include "printf" style formatting options like:
 120                                 <type>
 121                         %s      string
 122                         %d      integer (default)
 123                         %f      float
 124                         (not used or needed in binary mode)
 125
 126   <factor>      an optional multiplication factor which can be used for
 127                 unit conversion. (for example, radians to degrees).
 128   <offset>      an optional offset which can be used for unit conversion.
 129                 (for example, degrees to radians).
 130
 131
 132 Chunks can also consist of a single constant <format>, like in:
 133
 134
 135
 136
 137 == examples ===================================================================
 138
 139 Writes log of this form:
 140
 141 V=16
 142 H=3.590505
 143 P=3.59
 144 V=12
 145 H=3.589020
 146 P=3.59
 147
 148
 149
 150 <?xml version="1.0"?>
 151
 152 <PropertyList>
 153   <generic>
 154
 155     <output>
 156       <line_separator>newline</line_separator>
 157       <var_separator>newline</var_separator>
 158       <binary_mode>false</binary_mode>
 159
 160       <chunk>
 161         <name>speed</name>
 162         <format>V=%d</format>
 163         <node>/velocities/airspeed-kt</node>
 164       </chunk>
 165
 166       <chunk>
 167         <name>heading (rad)</name>
 168         <format>H=%.6f</format>
 169         <type>float</type>
 170         <node>/orientation/heading-deg</node>
 171         <factor>0.0174532925199433</factor>  <!-- degrees to radians -->
 172       </chunk>
 173
 174       <chunk>
 175         <name>pitch angle (deg)</name>
 176         <format>P=%03.2f</format>
 177         <node>/orientation/pitch-deg</node>
 178       </chunk>
 179    </output>
 180
 181  </generic>
 182 </PropertyList>
 183
 184
 185
 186
 187 -- writing data in XML syntax -------------------------------------------------
 188
 189 Assuming the file is called $FG_ROOT/Protocols/xmltest.xml, then it could be
 190 used as   $ fgfs --generic=file,out,1,/tmp/data.xml,xmltest
 191
 192
 193 <?xml version="1.0"?>
 194
 195 <PropertyList>
 196   <generic>
 197     <output>
 198       <binary_mode>false</binary_mode>
 199       <var_separator>\n</var_separator>
 200       <line_separator>\n</line_separator>
 201       <preamble>&lt;?xml version="1.0"?&gt;\n\n&lt;data&gt;\n</preamble>
 202       <postamble>&lt;/data&gt;\n</postamble>
 203
 204       <chunk>
 205         <format>\t&lt;set&gt;</format>
 206       </chunk>
 207
 208       <chunk>
 209         <node>/position/altitude-ft</node>
 210         <type>float</type>
 211         <format>\t\t&lt;altitude-ft&gt;%.8f&lt;/altitude-ft&gt;</format>
 212       </chunk>
 213
 214       <chunk>
 215         <node>/velocities/airspeed-kt</node>
 216         <type>float</type>
 217         <format>\t\t&lt;airspeed-kt&gt;%.8f&lt;/airspeed-kt&gt;</format>
 218       </chunk>
 219
 220       <chunk>
 221         <format>\t&lt;/set&gt;</format>
 222       </chunk>
 223     </output>
 224   </generic>
 225 </PropertyList>
 226
 227