]> git.mxchange.org Git - flightgear.git/blob - docs-mini/README.protocol
Simplify fgValidatePath + minor fix (requires simgear update)
[flightgear.git] / 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