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.
9 == file layout ================================================================
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).
21 <binary_mode>false</binary_mode>
22 <line_separator></line_separator>
23 <var_separator></var_separator>
25 <postamble></postamble>
28 ... first chunk spec ...
32 ... another chunk etc. ...
37 <line_separator></line_separator>
38 <var_separator></var_separator>
51 == input/output parameters ====================================================
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.
59 --- ASCII protocol parameters ---
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
66 <binary_mode> BOOL default: false (= ASCII mode)
67 <var_separator> STRING default: "" field separator
68 <line_separator> STRING default: "" separator between data sets
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:
86 <var_separator>tab</var_separator>
87 <line_separator>newline</var_separator>
91 <var_separator>\t</var_separator>
92 <line_separator>\r\n</line_separator>
95 --- Binary protocol parameters ---
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:
104 <binary_footer>magic,0x12345678</binary_footer>
105 <binary_footer>length</binary_footer>
106 <binary_footer>none</binary_footer> <!-- default -->
111 == variable parameters (chunk spec) ===========================================
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.
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:
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).
135 Chunks can also consist of a single constant <format>, like in:
136 <format>Data Section</format>
139 == examples ===================================================================
141 Writes log of this form:
152 <?xml version="1.0"?>
158 <line_separator>newline</line_separator>
159 <var_separator>newline</var_separator>
160 <binary_mode>false</binary_mode>
164 <format>V=%d</format>
165 <node>/velocities/airspeed-kt</node>
169 <name>heading (rad)</name>
170 <format>H=%.6f</format>
172 <node>/orientation/heading-deg</node>
173 <factor>0.0174532925199433</factor> <!-- degrees to radians -->
177 <name>pitch angle (deg)</name>
178 <format>P=%03.2f</format>
179 <node>/orientation/pitch-deg</node>
189 -- writing data in XML syntax -------------------------------------------------
191 Assuming the file is called $FG_ROOT/Protocol/xmltest.xml, then it could be
192 used as $ fgfs --generic=file,out,1,/tmp/data.xml,xmltest
195 <?xml version="1.0"?>
200 <binary_mode>false</binary_mode>
201 <var_separator>\n</var_separator>
202 <line_separator>\n</line_separator>
203 <preamble><?xml version="1.0"?>\n\n<data>\n</preamble>
204 <postamble></data>\n</postamble>
207 <format>\t<set></format>
211 <node>/position/altitude-ft</node>
213 <format>\t\t<altitude-ft>%.8f</altitude-ft></format>
217 <node>/velocities/airspeed-kt</node>
219 <format>\t\t<airspeed-kt>%.8f</airspeed-kt></format>
223 <format>\t</set></format>
230 -- Analyzing the resulting binary packet format -------------------------------
232 A utility called generic-protocol-analyse can be found under
233 FlightGear/utils/xmlgrep which can be used to analyze the resulting
234 data packet for the binary protocol.
236 The output would be something like:
239 Generic binary output protocol packet description:
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
249 total package size: 17 bytes