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><?xml version="1.0"?>\n\n<data>\n</preamble> 204 <postamble></data>\n</postamble> 205 206 <chunk> 207 <format>\t<set></format> 208 </chunk> 209 210 <chunk> 211 <node>/position/altitude-ft</node> 212 <type>float</type> 213 <format>\t\t<altitude-ft>%.8f</altitude-ft></format> 214 </chunk> 215 216 <chunk> 217 <node>/velocities/airspeed-kt</node> 218 <type>float</type> 219 <format>\t\t<airspeed-kt>%.8f</airspeed-kt></format> 220 </chunk> 221 222 <chunk> 223 <format>\t</set></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