-The generic communication protocol for FlightGear provides a powerfull way
-of adding a simple ASCII based or binary protocol, just by defining an
-XML encoded configuration file.
+The generic communication protocol for FlightGear provides a powerful way
+of adding a simple ASCII based or binary input/output protocol, just by
+defining an XML encoded configuration file and placing it in the
+$FG_ROOT/Protocol/ directory.
-The definition of the protocol consists of variable separators, line separators,
-and chuncks of text.
-Each chunck defines:
-<name> for ease of use
-<node> the property tree node which provides the data
-<type> the value type (needed for formatting)
-<format> defines the actual piece of text which should be sent.
- it can include formatting options like:
- <type>
- %s string
- %i integer (default)
- %f float
- (not used or needed in binary mode)
-<factor> an optional multiplication factor which can be used for
- unit conversion. (for example, radians to degrees).
-<offset> an optional offset which can be used for unit conversion.
- (for example, degrees Celsius to degrees Fahrenheit).
+== file layout ================================================================
+A protocol file can contain either or both of <input> and <output>
+definition blocks. Which one is used depends on how the protocol
+is called (e.g. --generic=file,out,1,/tmp/data.xml,myproto would
+only use the <output> definitions block).
-The output section also could define the variable separator and line separator.
+ <?xml version="1.0"?>
+ <PropertyList>
+ <generic>
-The separators can be either a control character such as a tab or newline, or a
-user specified string or other single charachter. The currently supported
-control charachters are:
+ <output>
+ <binary_mode>false</binary_mode>
+ <line_separator></line_separator>
+ <var_separator></var_separator>
+ <preamble></preamble>
+ <postamble></postamble>
-<var_separator>:
-<line_separator>:
-Name Charachter
+ <chunk>
+ ... first chunk spec ...
+ </chunk>
-newline '\n'
-tab '\t'
-formfeed '\f'
-carriagereturn '\r'
-verticaltab '\v'
+ <chunk>
+ ... another chunk etc. ...
+ </chunk>
+ </output>
-any other charachters just need to be added to "Network/generic.cxx"
+ <input>
+ <line_separator></line_separator>
+ <var_separator></var_separator>
-The var_separator is placed between each variable, while the line_separator is
-placed at the end of each lot of variables.
+ <chunk>
+ ... chunk spec ...
+ </chunk>
+ </input>
+
+ </generic>
+ </PropertyList>
+
+
+
+
+== input/output parameters ====================================================
+
+Both <output> and <input> blocks can contain information about
+the data mode (ascii/binary) and about separators between fields
+and data sets, as well as a list of <chunk>s. Each <chunk> defines
+a property that should be written (and how), or a variable and which
+property it should be written to.
+
+--- ASCII protocol parameters ---
+
+output only:
+ <preamble> STRING default: "" file header put on top of the file
+ <postamble> STRING default: "" file footer put at the end of the file
+
+input & output:
+ <binary_mode> BOOL default: false (= ASCII mode)
+ <var_separator> STRING default: "" field separator
+ <line_separator> STRING default: "" separator between data sets
+
+
+<var_separator> are put between every two output properties, while
+<line_separator> is put at the end of each data set. Both can contain
+arbitrary strings or one of the following keywords:
+
+ Name Character
+
+ newline '\n'
+ tab '\t'
+ formfeed '\f'
+ carriagereturn '\r'
+ verticaltab '\v'
+
+
+Typical use could be:
+
+ <var_separator>tab</var_separator>
+ <line_separator>newline</var_separator>
+
+or
+
+ <var_separator>\t</var_separator>
+ <line_separator>\r\n</line_separator>
+
+
+--- Binary protocol parameters ---
To enable binary mode, simply include a <binary_mode>true</binary_mode> tag in
your XML file. The format of the binary output is tightly packed, with 1 byte
output can be added using the <binary_footer> tag. Options include the length
of the packet, a magic number to simplify decoding. Examples:
- <binary_footer>magic,0x12345678</binary_footer>
- <binary_footer>length</binary_footer>
- <binary_footer>none</binary_footer> <!-- default -->
+ <binary_footer>magic,0x12345678</binary_footer>
+ <binary_footer>length</binary_footer>
+ <binary_footer>none</binary_footer> <!-- default -->
+
+
+
+
+== variable parameters (chunk spec) ===========================================
+
+Both <input> and <output> block can contain a list of <chunk> specs,
+each of which describes the properties of on variable to write/read.
+
+
+ <name> for ease of use (not tranferred)
+ <node> the property tree node which provides the data
+ <type> the value type (needed for formatting)
+ one of string, float, bool, int (default: int)
+ <format> (ASCII protocol only, not used or needed in binary mode)
+ defines the actual piece of text which should be sent.
+ it can include "printf" style formatting options like:
+ <type>
+ %s string
+ %d integer (default)
+ %f float
+
+ <factor> an optional multiplication factor which can be used for
+ unit conversion. (for example, radians to degrees).
+ <offset> an optional offset which can be used for unit conversion.
+ (for example, degrees Celcius to degrees Fahrenheit).
+
+For input chunks there exist some more options:
+
+ <rel> optional boolean parameter to enable handling of incoming values
+ as relative changes (default: false)
+ (Can be eg. used to realise up/down buttons by just sending 1 or
+ -1 respectively)
+
+ <min> an optional minimum limit for the value to be clamped to. This
+ limit is always specified as absolute value, also with relative
+ changes enabled. (default: 0)
+ <max> an optional upper limit for the input value to be clamped to. If
+ <min> equals <max> no limit is applied. (default: 0)
+ <wrap> instead of clamping to minimum and maximum limits, wrap values
+ around. Values will be in [min, max[ (default: false)
+ (Usefull for eg. heading selector to start again with 1 for
+ values higher than 360)
+
+<rel>, <min>, <max> and <wrap> are only used for numeric data types. <rel> can
+additionally be used with type 'bool', where it toggles the value, if the received
+value evaluates to 'true', otherwise the value is left unchanged.
+
+Chunks can also consist of a single constant <format>, like in:
+ <format>Data Section</format>
+
+
+== examples ===================================================================
+
+Writes log of this form:
-A simple protocol configuration file then could look something like the
-following:
+V=16
+H=3.590505
+P=3.59
+V=12
+H=3.589020
+P=3.59
+
+
+
+<?xml version="1.0"?>
+
+<PropertyList>
+ <generic>
+
+ <output>
+ <line_separator>newline</line_separator>
+ <var_separator>newline</var_separator>
+ <binary_mode>false</binary_mode>
+
+ <chunk>
+ <name>speed</name>
+ <format>V=%d</format>
+ <node>/velocities/airspeed-kt</node>
+ </chunk>
+
+ <chunk>
+ <name>heading (rad)</name>
+ <format>H=%.6f</format>
+ <type>float</type>
+ <node>/orientation/heading-deg</node>
+ <factor>0.0174532925199433</factor> <!-- degrees to radians -->
+ </chunk>
+
+ <chunk>
+ <name>pitch angle (deg)</name>
+ <format>P=%03.2f</format>
+ <node>/orientation/pitch-deg</node>
+ </chunk>
+ </output>
+
+ </generic>
+</PropertyList>
+
+
+Control the heading bug by sending relative changes separated by newlines:
<?xml version="1.0"?>
<PropertyList>
+ <generic>
+
+ <input>
+ <line_separator>newline</line_separator>
- <generic>
-
- <output>
- <line_separator>newline</line_separator>
- <var_separator>newline</var_separator>
- <binary_mode>false</binary_mode>
-
- <chunk>
- <name>speed</name>
- <format>V=%d</format>
- <node>/velocities/airspeed-kt</node>
- </chunk>
-
- <chunk>
- <name>heading</name>
- <format>H=%02d</format>
- <node>/orientation/heading-deg</node>
- <factor>57.29578</factor> <!-- radians to degrees -->
- </chunk>
-
- <chunk>
- <name>pitch angle</name>
- <format>P=%05.1f</format>
- <type>float</type>
- <node>/orientation/pitch-deg</node>
- </chunk>
+ <chunk>
+ <name>heading bug</name>
+ <type>int</type>
+ <node>/autopilot/settings/heading-bug-deg</node>
+ <relative>true</relative>
+ <min>1</min>
+ <max>360</max>
+ <wrap>true</wrap>
+ </chunk>
+
+ </input>
</generic>
+</PropertyList>
+-- writing data in XML syntax -------------------------------------------------
+
+Assuming the file is called $FG_ROOT/Protocol/xmltest.xml, then it could be
+used as $ fgfs --generic=file,out,1,/tmp/data.xml,xmltest
+
+
+<?xml version="1.0"?>
+
+<PropertyList>
+ <generic>
+ <output>
+ <binary_mode>false</binary_mode>
+ <var_separator>\n</var_separator>
+ <line_separator>\n</line_separator>
+ <preamble><?xml version="1.0"?>\n\n<data>\n</preamble>
+ <postamble></data>\n</postamble>
+
+ <chunk>
+ <format>\t<set></format>
+ </chunk>
+
+ <chunk>
+ <node>/position/altitude-ft</node>
+ <type>float</type>
+ <format>\t\t<altitude-ft>%.8f</altitude-ft></format>
+ </chunk>
+
+ <chunk>
+ <node>/velocities/airspeed-kt</node>
+ <type>float</type>
+ <format>\t\t<airspeed-kt>%.8f</airspeed-kt></format>
+ </chunk>
+
+ <chunk>
+ <format>\t</set></format>
+ </chunk>
+ </output>
+ </generic>
</PropertyList>
+
+
+-- Analyzing the resulting binary packet format -------------------------------
+
+A utility called generic-protocol-analyse can be found under
+FlightGear/utils/xmlgrep which can be used to analyze the resulting
+data packet for the binary protocol.
+
+The output would be something like:
+
+bintest.xml
+Generic binary output protocol packet description:
+
+ pos | size | type | factor | description
+-----|------|--------|------------|------------------------
+ 0 | 4 | int | | indicated speed (kt)
+ 4 | 4 | float | | pitch att (deg)
+ 8 | 4 | float | | magnetic heading (deg)
+ 12 | 4 | int | | outside air temperarure (degF)
+ 16 | 1 | bool | | autocoord
+
+total package size: 17 bytes
+
projects / flightgear.git / blobdiff