4,400
edits
Generic protocol: Difference between revisions
Jump to navigation
Jump to search
m
Robot: Cosmetic changes
(minor formatting) |
m (Robot: Cosmetic changes) |
||
| Line 1: | Line 1: | ||
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 [[$ | 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. | ||
==XML File Layout== | == XML 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. The following example would only use the <output> definitions block. | 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. The following example would only use the <output> definitions block. | ||
| Line 40: | Line 40: | ||
</PropertyList> | </PropertyList> | ||
==Input/Output Parameters == | == Input/Output Parameters == | ||
Both '''<input>''' 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. | Both '''<input>''' 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==== | ==== ASCII protocol parameters ==== | ||
Output only: | Output only: | ||
| Line 75: | Line 75: | ||
====Binary protocol parameters==== | ==== 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 for bool, 4 bytes for int, and 8 bytes for double. At this time, strings are not supported. A configurable footer at the end of each "line" or packet of binary output can be added using the '''<binary_footer>''' tag. Options include the length of the packet, a magic number to simplify decoding. Examples: | 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 for bool, 4 bytes for int, and 8 bytes for double. At this time, strings are not supported. A configurable footer at the end of each "line" or packet of binary output can be added using the '''<binary_footer>''' tag. Options include the length of the packet, a magic number to simplify decoding. Examples: | ||
| Line 82: | Line 82: | ||
<binary_footer>none</binary_footer> <!-- default --> | <binary_footer>none</binary_footer> <!-- default --> | ||
==Variable Parameters - <chunk> spec== | == 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. | 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>===== | ===== <name> ===== | ||
For ease of use and not tranferred (like a notes tag) | For ease of use and not tranferred (like a notes tag) | ||
=====<node>===== | ===== <node> ===== | ||
The [[ | The [[Property Tree|property tree]] node which provides the data | ||
=====<type>===== | ===== <type> ===== | ||
The value type which is needed for formatting, one of string, float, bool, int (default: int). Its recommended that this tag is present otherwise spurious results can occur. | The value type which is needed for formatting, one of string, float, bool, int (default: int). Its recommended that this tag is present otherwise spurious results can occur. | ||
=====<format>===== | ===== <format> ===== | ||
ASCII protocol only, not used or needed in binary mode. Defines the actual piece of text which should be sent. | 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> | <type> | ||
%s string | %s string | ||
| Line 101: | Line 101: | ||
%f float | %f float | ||
=====<factor>===== | ===== <factor> ===== | ||
An optional multiplication factor which can be used for unit conversion, for example, radians to degrees. | An optional multiplication factor which can be used for unit conversion, for example, radians to degrees. | ||
=====<offset>===== | ===== <offset> ===== | ||
An optional offset which can be used for unit conversion, for example, degrees Celcius to degrees Fahrenheit. | An optional offset which can be used for unit conversion, for example, degrees Celcius to degrees Fahrenheit. | ||
====<format>==== | ==== <format> ==== | ||
Chunks can also consist of a single constant <format>, like in: | Chunks can also consist of a single constant <format>, like in: | ||
<format>Data Section</format> | <format>Data Section</format> | ||
==Examples== | == Examples == | ||
====Example 1==== | ==== Example 1 ==== | ||
Writes log of this form: | Writes log of this form: | ||
V=16 | V=16 | ||
| Line 157: | Line 157: | ||
===Writing data in XML format==== | ===Writing data in XML format==== | ||
Assuming the file is called [[$ | 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 | fgfs --generic=file,out,1,/tmp/data.xml,xmltest | ||
| Line 195: | Line 195: | ||
==Analyzing the resulting binary packet format== | == 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: | 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: | ||
<pre> | <pre> | ||
| Line 212: | Line 212: | ||
</pre> | </pre> | ||
==Links== | == Links == | ||
* Sourced from [http://cvs.flightgear.org/viewvc/source/docs-mini/README.protocol?view=markup source/docs-mini/README.protocol] | * Sourced from [http://cvs.flightgear.org/viewvc/source/docs-mini/README.protocol?view=markup source/docs-mini/README.protocol] | ||