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/data/Protocols/ directory.
+$FG_ROOT/Protocol/ directory.
a property that should be written (and how), or a variable and which
property it should be written to.
+--- ASCII protocol parameters ---
+
output only:
- <binary_mode> BOOL default: false (= ASCII mode)
<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
<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
<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> defines the actual piece of text which should be sent.
+ <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
- (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 to radians).
+ (for example, degrees Celcius to degrees Fahrenheit).
+For input chunks there exist some more options:
-Chunks can also consist of a single constant <format>, like in:
+ <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:
-V=1736
-H=17647
-P=004.6
-V=1780
-H=18105
-P=006.4
+V=16
+H=3.590505
+P=3.59
+V=12
+H=3.589020
+P=3.59
</PropertyList>
+Control the heading bug by sending relative changes separated by newlines:
+
+<?xml version="1.0"?>
+
+<PropertyList>
+ <generic>
+
+ <input>
+ <line_separator>newline</line_separator>
+ <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/Protocols/xmltest.xml, then it could be
+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
<generic>
<output>
<binary_mode>false</binary_mode>
- <line_separator></line_separator>
- <var_separator></var_separator>
+ <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>\n</format>
+ <format>\t<set></format>
</chunk>
<chunk>
<node>/position/altitude-ft</node>
<type>float</type>
- <format>\t\t<altitude-ft>%.8f</altitude-ft>\n</format>
+ <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>\n</format>
+ <format>\t\t<airspeed-kt>%.8f</airspeed-kt></format>
</chunk>
<chunk>
- <format>\t</set>\n</format>
+ <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
+