fix spelling
[fg:toms-fgdata.git] / Protocol / README.Protocol
1 The generic communication protocol for FlightGear provides a powerful way
2 of adding a simple ASCII based or binary protocol, just by defining an
3 XML encoded configuration file.
4
5 The definition of the protocol consists of variable separators, line separators,
6 and chunks of text.
7
8 Each chunk defines:
9
10 <name>          for ease of use
11 <node>          the property tree node which provides the data
12 <type>          the value type (needed for formatting)
13 <format>        defines the actual piece of text which should be sent.
14                 it can include formatting options like:
15                                 <type>
16                         %s      string
17                         %i      integer (default)
18                         %f      float
19                 (not used or needed in binary mode)
20
21 <factor>        an optional multiplication factor which can be used for
22                 unit conversion. (for example, radians to degrees).
23 <offset>        an optional offset which can be used for unit conversion.
24                 (for example, degrees Celsius to degrees Fahrenheit).
25
26
27 The output section also could define the variable separator and line separator.
28
29 The separators can be either a control character such as a tab or newline, or a
30 user specified string or other single character. The currently supported
31 control characters are:
32
33 <var_separator>:
34 <line_separator>:
35 Name            Character
36
37 newline         '\n'
38 tab             '\t'
39 formfeed        '\f'
40 carriagereturn  '\r'
41 verticaltab     '\v'
42
43 any other characters just need to be added to "Network/generic.cxx"
44
45 The var_separator is placed between each variable, while the line_separator is
46 placed at the end of each lot of variables.
47
48 To enable binary mode, simply include a <binary_mode>true</binary_mode> tag in
49 your XML file. The format of the binary output is tightly packed, with 1 byte
50 for bool, 4 bytes for int, and 8 bytes for double. At this time, strings are not
51 supported. A configurable footer at the end of each "line" or packet of binary
52 output can be added using the <binary_footer> tag. Options include the length
53 of the packet, a magic number to simplify decoding. Examples:
54
55         <binary_footer>magic,0x12345678</binary_footer>
56         <binary_footer>length</binary_footer>
57         <binary_footer>none</binary_footer>                     <!-- default -->
58
59 A simple protocol configuration file then could look something like the
60 following:
61
62 <?xml version="1.0"?>
63
64 <PropertyList>
65
66  <generic>
67
68   <output>
69    <line_separator>newline</line_separator>
70    <var_separator>newline</var_separator>
71    <binary_mode>false</binary_mode>
72
73    <chunk>
74     <name>speed</name>
75     <format>V=%d</format>
76     <node>/velocities/airspeed-kt</node>
77    </chunk>
78
79    <chunk>
80     <name>heading</name>
81     <format>H=%02d</format>
82     <node>/orientation/heading-deg</node>
83     <factor>57.29578</factor>  <!-- radians to degrees -->
84    </chunk>
85
86    <chunk>
87     <name>pitch angle</name>
88     <format>P=%05.1f</format>
89     <type>float</type>
90     <node>/orientation/pitch-deg</node>
91    </chunk>
92
93  </generic>
94
95 </PropertyList>