]> git.mxchange.org Git - flightgear.git/blob - docs-mini/README.protocol
Use api's with objects instead of scalars.
[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 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/Protocol/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