1The generic communication protocol for FlightGear provides a powerful way
2of adding a simple ASCII based or binary input/output protocol, just by
3defining an XML encoded configuration file and placing it in the
4$FG_ROOT/Protocol/ directory.
5
6
7
8
9== file layout ================================================================
10
11A protocol file can contain either or both of <input> and <output>
12definition blocks. Which one is used depends on how the protocol
13is called  (e.g. --generic=file,out,1,/tmp/data.xml,myproto would
14only 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
53Both <output> and <input> blocks can contain information about
54the data mode (ascii/binary) and about separators between fields
55and data sets, as well as a list of <chunk>s. Each <chunk> defines
56a property that should be written (and how), or a variable and which
57property it should be written to.
58
59--- ASCII protocol parameters ---
60
61output 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
65input & 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
73arbitrary 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
84Typical use could be:
85
86  <var_separator>tab</var_separator>
87  <line_separator>newline</var_separator>
88
89or
90
91  <var_separator>\t</var_separator>
92  <line_separator>\r\n</line_separator>
93
94
95--- Binary protocol parameters ---
96
97To enable binary mode, simply include a <binary_mode>true</binary_mode> tag in
98your XML file. The format of the binary output is tightly packed, with 1 byte
99for bool, 4 bytes for int, and 8 bytes for double. At this time, strings are not
100supported. A configurable footer at the end of each "line" or packet of binary
101output can be added using the <binary_footer> tag. Options include the length
102of 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
113Both <input> and <output> block can contain a list of <chunk> specs,
114each 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
135Chunks can also consist of a single constant <format>, like in:
136  <format>Data Section</format>
137
138
139== examples ===================================================================
140
141Writes log of this form:
142
143V=16
144H=3.590505
145P=3.59
146V=12
147H=3.589020
148P=3.59
149
150
151
152<?xml version="1.0"?>
153
154<PropertyList>
155  <generic>
156
157    <output>
158      <line_separator>newline</line_separator>
159      <var_separator>newline</var_separator>
160      <binary_mode>false</binary_mode>
161
162      <chunk>
163        <name>speed</name>
164        <format>V=%d</format>
165        <node>/velocities/airspeed-kt</node>
166      </chunk>
167
168      <chunk>
169        <name>heading (rad)</name>
170        <format>H=%.6f</format>
171        <type>float</type>
172        <node>/orientation/heading-deg</node>
173        <factor>0.0174532925199433</factor>  <!-- degrees to radians -->
174      </chunk>
175
176      <chunk>
177        <name>pitch angle (deg)</name>
178        <format>P=%03.2f</format>
179        <node>/orientation/pitch-deg</node>
180      </chunk>
181   </output>
182
183 </generic>
184</PropertyList>
185
186
187
188
189-- writing data in XML syntax -------------------------------------------------
190
191Assuming the file is called $FG_ROOT/Protocol/xmltest.xml, then it could be
192used as   $ fgfs --generic=file,out,1,/tmp/data.xml,xmltest
193
194
195<?xml version="1.0"?>
196
197<PropertyList>
198  <generic>
199    <output>
200      <binary_mode>false</binary_mode>
201      <var_separator>\n</var_separator>
202      <line_separator>\n</line_separator>
203      <preamble>&lt;?xml version="1.0"?&gt;\n\n&lt;data&gt;\n</preamble>
204      <postamble>&lt;/data&gt;\n</postamble>
205
206      <chunk>
207        <format>\t&lt;set&gt;</format>
208      </chunk>
209
210      <chunk>
211        <node>/position/altitude-ft</node>
212        <type>float</type>
213        <format>\t\t&lt;altitude-ft&gt;%.8f&lt;/altitude-ft&gt;</format>
214      </chunk>
215
216      <chunk>
217        <node>/velocities/airspeed-kt</node>
218        <type>float</type>
219        <format>\t\t&lt;airspeed-kt&gt;%.8f&lt;/airspeed-kt&gt;</format>
220      </chunk>
221
222      <chunk>
223        <format>\t&lt;/set&gt;</format>
224      </chunk>
225    </output>
226  </generic>
227</PropertyList>
228
229
230-- Analyzing the resulting binary packet format -------------------------------
231
232A utility called generic-protocol-analyse can be found under
233FlightGear/utils/xmlgrep which can be used to analyze the resulting
234data packet for the binary protocol.
235
236The output would be something like:
237
238bintest.xml
239Generic binary output protocol packet description:
240
241 pos | size |  type  | factor     | description
242-----|------|--------|------------|------------------------
243   0 |    4 |    int |            | indicated speed (kt)
244   4 |    4 |  float |            | pitch att (deg)
245   8 |    4 |  float |            | magnetic heading (deg)
246  12 |    4 |    int |            | outside air temperarure (degF)
247  16 |    1 |   bool |            | autocoord
248
249total package size: 17 bytes
250
251