Generic protocol: Difference between revisions

Jump to navigation Jump to search

Generic protocol (view source)

Revision as of 08:42, 10 October 2013

1,013 bytes added ,  10 October 2013
Syntax highlighting, tables and formatting
(Syntax highlighting, tables and formatting)
Line 22: Line 22:


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.
<syntaxhighlight lang="text">
  --generic=file,out,1,/tmp/data.xml,myproto
  --generic=file,out,1,/tmp/data.xml,myproto
</syntaxhighlight>


If you're using a serial port under Windows, you must use a special escape sequence for COM port numbers higher than COM9.   
If you're using a serial port under Windows, you must use a special escape sequence for COM port numbers higher than COM9.   
Line 32: Line 34:
Overview of the XML file
Overview of the XML file


<syntaxhighlight lang="xml">
  <?xml version="1.0"?>
  <?xml version="1.0"?>
  <PropertyList>
  <PropertyList>
Line 44: Line 47:
   
   
             <chunk>
             <chunk>
                 ... first chunk spec ...
                 <!-- First output chunk definition -->
             </chunk>
             </chunk>
   
   
             <chunk>
             <chunk>
                 ... another chunk etc. ...
                 <!-- Next output chunk definition etc... -->
             </chunk>
             </chunk>
         </output>
         </output>
Line 57: Line 60:
   
   
             <chunk>
             <chunk>
                 ... chunk spec ...
                 <!-- First input chunk definition -->
            </chunk>
            <chunk>
                <!-- Next input chunk definition etc... -->
             </chunk>
             </chunk>
         </input>
         </input>
Line 63: Line 70:
     </generic>
     </generic>
  </PropertyList>
  </PropertyList>
</syntaxhighlight>


== Input/Output Parameters ==
== Input/Output Parameters ==
Line 69: Line 77:


==== ASCII protocol parameters ====
==== ASCII protocol parameters ====
Note that some parameters only can be used for output.


Output only:
{| class="wikitable"
<preamble>       STRING  default: ""   file header put on top of the file
! Parameter tag !! Out !! In !! Type !! Default !! Purpose
<postamble>       STRING  default: ""   file footer put at the end of the file
|-
| <tt>&lt;preamble&gt;</tt> || x || || String || "" || File header put on top of the file
|-
| <tt>&lt;postamble&gt;</tt> || x || || String || "" || File footer put at the end of the file
|-
| <tt>&lt;binary_mode&gt;</tt> || x || x || Boolean || False || Indicates if binary mode is to be used instead of ASCII
|-
| <tt>&lt;var_separator&gt;</tt> || x || x || String || "" || Field separator
|-
| <tt>&lt;line_separator&gt;</tt> || x || x || String || "" || Separator between data sets
|}


Input & Output:
* '''<var_separator>''' is put between each of the properties.
<binary_mode>     BOOL    default: false (= ASCII mode)
<var_separator>  STRING  default: ""    field separator
<line_separator>  STRING  default: ""    separator between data sets
 
* '''<var_separator>''' is put between every two output properties
* '''<line_separator>''' is put at the end of each data set.  
* '''<line_separator>''' is put at the end of each data set.  
Both can contain arbitrary strings or one of the following keywords:
Both can contain arbitrary strings or one of the following keywords:


  Name            Character
{| class="wikitable"
------------------------------
! Keyword !! Special character
  newline         '\n'
|-
  tab             '\t'
| newline || <tt>\n</tt>
  formfeed         '\f'
|-
  carriagereturn   '\r'
| tab || <tt>\t</tt>
  verticaltab     '\v'
|-
| formfeed || <tt>\f</tt>
|-
| carriagereturn || <tt>\r</tt>
|-
| verticaltab || <tt>\v</tt>
|}


Typical use could be:
Typical use could be:
<syntaxhighlight lang="xml">
  <var_separator>tab</var_separator>
  <var_separator>tab</var_separator>
  <line_separator>newline</var_separator>
  <line_separator>newline</var_separator>
</syntaxhighlight>
or
or
<syntaxhighlight lang="xml">
  <var_separator>\t</var_separator>
  <var_separator>\t</var_separator>
  <line_separator>\r\n</line_separator>
  <line_separator>\r\n</line_separator>
 
</syntaxhighlight>


==== 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:
<syntaxhighlight lang="xml">
   <binary_footer>magic,0x12345678</binary_footer>
   <binary_footer>magic,0x12345678</binary_footer>
   <binary_footer>length</binary_footer>
   <binary_footer>length</binary_footer>
   <binary_footer>none</binary_footer>                <!-- default -->
   <binary_footer>none</binary_footer>                <!-- default -->
</syntaxhighlight>


In addition, you can specify endianess of the data sent. This is done with the <byte_order> flag. The two options are network (big endian) and host.
In addition, you can specify endianess of the data sent. This is done with the <byte_order> flag. The two options are network (big endian) and host.
<syntaxhighlight lang="xml">
   <byte_order>host</byte_order>
   <byte_order>host</byte_order>
   <byte_order>network</byte_order>        <!-- default -->
   <byte_order>network</byte_order>        <!-- default -->
</syntaxhighlight>


== Variable Parameters - <chunk> spec ==
== Variable Parameters - <chunk> spec ==
Line 124: Line 151:
===== <format> =====
===== <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:
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
{| class="wikitable"
    %d     integer (default)
! Formatting option !! Type
    %f     float
|-
| <tt>%s</tt> || String
|-
| <tt>%d</tt> || Integer (default)
|-
| <tt>%f</tt> || Float
|}


Note: the type attribute tells the property tree how to store a value internally, using the most appropriate data type saves memory and reduces conversion overhead (bool, int, float, double, string).  
Note: the type attribute tells the property tree how to store a value internally, using the most appropriate data type saves memory and reduces conversion overhead (bool, int, float, double, string).  
Line 144: Line 177:
==== <format> ====
==== <format> ====
Chunks can also consist of a single constant <format>, like in:
Chunks can also consist of a single constant <format>, like in:
<syntaxhighlight lang="xml">
  <format>Data Section</format>
  <format>Data Section</format>
 
</syntaxhighlight>


== Examples ==
== Examples ==
==== Example 1 ====
==== Example 1 ====
Writes log of this form:
Writes log of this form:
V=16
<pre>
H=3.590505
V=16
P=3.59
H=3.590505
V=12
P=3.59
H=3.589020
V=12
P=3.59
H=3.589020
 
P=3.59
</pre>


<syntaxhighlight lang="xml">
  <?xml version="1.0"?>  
  <?xml version="1.0"?>  
  <PropertyList>
  <PropertyList>
Line 190: Line 226:
  </generic>
  </generic>
  </PropertyList>
  </PropertyList>
</syntaxhighlight>


===Writing data in XML format===
===Writing data in XML format===
Line 195: Line 232:
  fgfs --generic=file,out,1,/tmp/data.xml,xmltest
  fgfs --generic=file,out,1,/tmp/data.xml,xmltest


 
<syntaxhighlight lang="xml">
  <?xml version="1.0"?>
  <?xml version="1.0"?>
  <PropertyList>
  <PropertyList>
Line 215: Line 252:
         <format>\t\t&lt;altitude-ft&gt;%.8f&lt;/altitude-ft&gt;</format>
         <format>\t\t&lt;altitude-ft&gt;%.8f&lt;/altitude-ft&gt;</format>
       </chunk>
       </chunk>
</syntaxhighlight>
   
   
For more examples, see [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg37892.html].
For more examples, see [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg37892.html].
<syntaxhighlight lang="xml">
       <chunk>
       <chunk>
         <node>/velocities/airspeed-kt</node>
         <node>/velocities/airspeed-kt</node>
Line 229: Line 268:
  </generic>
  </generic>
  </PropertyList>
  </PropertyList>
</syntaxhighlight>


== Analyzing the resulting binary packet format ==
== Analyzing the resulting binary packet format ==
Line 267: Line 307:


The XML looks like this:
The XML looks like this:
<syntaxhighlight lang="xml">
  <?xml version="1.0"?>
  <?xml version="1.0"?>
  <PropertyList>
  <PropertyList>
Line 291: Line 332:
   </generic>
   </generic>
  </PropertyList>
  </PropertyList>
</syntaxhighlight>


* The '''output''' tag indicates the protocol for output. The same "protocol" file can contain an "input" section, absent in this example (more later).
* The '''output''' tag indicates the protocol for output. The same "protocol" file can contain an "input" section, absent in this example (more later).
Line 306: Line 348:


[todo] - link here to the tutorial
[todo] - link here to the tutorial


== External links ==
== External links ==
Retrieved from "https://wiki.flightgear.org/Special:MobileDiff/63260"

Navigation menu