docs-mini/README.protocol

   1 The generic communication protocol for FlightGear provides a powerfull way
   2 of adding a simple ASCII based output only protocol, just by defining an
   3 XML encoded configuration file and placing it in the $FG_ROOT/data/Protocols
   4 directory.
   5
   6 The definition of the protocol consists of variable separators, line separators,
   7 and chuncks of text.
   8
   9 Each chunck defines:
  10
  11 <name>          for ease of use
  12 <node>          the property tree node which provides the data
  13 <type>          the value type (needed for formatting)
  14 <format>        defines the actual piece of text which should be sent.
  15                 it can include formatting options like:
  16                                 <type>
  17                         %s      string
  18                         %i      integer (default)
  19                         %f      float
  20
  21 <factor>        an optionale multiplication factor which can be used for
  22                 unit conversion. (for example, radians to degrees).
  23 <offset>        an optional offset which can be used for unit conversion.
  24                 (for example, degrees Celsius to degrees Fahrenheit).
  25
  26
  27 The output section also could define the variable separator and line separator.
  28
  29 The separators can be either a control character such as a tab or newline, or a
  30 user specified string or other single charachter. The currently supported
  31 control charachters are:
  32
  33 <var_separator>:
  34 <line_separator>:
  35 Name            Charachter
  36
  37 newline         '\n'
  38 tab             '\t'
  39 formfeed        '\f'
  40 carriagereturn  '\r'
  41 verticaltab     '\v'
  42
  43 any other charachters just need to be added to "Network/generic.cxx"
  44
  45 The var_separator is placed between each variable, while the line_separator is
  46 placed at the end of each lot of variables.
  47
  48
  49 A simple protocol configuration file then could look something like the
  50 following:
  51
  52 <?xml version="1.0"?>
  53
  54 <PropertyList>
  55  <output>
  56
  57    <line_separator>newline</line_separator>
  58    <var_separator>newline</var_separator>
  59
  60    <chunk>
  61     <name>speed</name>
  62     <format>V=%d</format>
  63     <node>/velocities/airspeed-kt</node>
  64    </chunk>
  65
  66    <chunk>
  67     <name>heading (rad)</name>
  68     <format>H=%02d</format>
  69     <node>/orientation/heading-deg</node>
  70     <factor>57.29578</factor>  <!-- degrees to radians -->
  71    </chunk>
  72
  73    <chunk>
  74     <name>pitch angle (deg)</name>
  75     <format>P=%05.1f</format>
  76     <type>float</type>
  77     <node>/orientation/pitch-deg</node>
  78    </chunk>
  79
  80  </output>
  81 </PropertyList>