Property Tree/Sockets

Property Tree
Intro Explained PropertyList XML Files Servers Sockets Reference Property Tree C++ API

Native Socket

Before we interface with FlightGear on a socket, consider this demonstration using the native protocol. TODO: explain native protocol

 --native=socket,direction,hz,machine,port,type
   direction = in, out or bi
   hz = number of times per second
   machine = machine name or ip address if client (leave empty if server)
   port = port, leave empty to let system choose
   type = tcp or udp
eg
 --native=socket,out,10,,5444,udp
                        ^ no machine so binds to localhost
 --native=socket,in,1,192.5.22.33 ,6789,tcp
 //**Important**. space = fail    ^                                 

An example of slaving two instances of flight gear together on seperate machines

   fgfs1:  --native=socket,out,30,seattle.com,5500,udp
   fgfs2:  --native=socket,in,30,tolouse.net,5500,udp --fdm=external

   This instructs the first copy of fgfs to send UDP packets in the
   native format to a machine called seattle.com on port 5500.

   The second copy of fgfs will accept UDP packets (from anywhere) on port 5500.  
   Note the additional --fdm=external option.  This tells the second copy of fgfs to not run 
   the normal flight model, but instead set the FDM values based on an external source, the network in this case.

Generic Protocol

FlightGear has an inbuilt "generic" protocol to push and pull data. (todo)

To interface with FlightGear on a socket for example, the following steps need to be taken.

1. Establish which "properties" you want to appear "on the wire"
2. Create a my_protocol.xml file containing those properties
3. Start flight gear on a socket using my_protocol.

For this simple example say were interested in heading and altitude, and we want to "listen" ie output to a socket at port 6789, udp and receiving 10 times a second in the format:

alt\thead\n 
// ie altitude - tab - heading - newline

The first step is establishing the nodes, in this example

/position/altitude-agl-ft  eg (22.4713923)
/orientation/heading-deg  eg (297.966325)

Next create a file my_protocol.xml. This needs to be located at

$FG_ROOT/Protocol/my_protocol.xml

The XML looks like this:

<?xml version="1.0"?>
<PropertyList>
<generic>
   <output>
       <line_separator>newline</line_separator>
       <var_separator>tab</var_separator>

       <chunk>
          <node>/position/altitude-agl-ft</node>
          <name>altitude to go</name>
          <type>float</type>
          <format>%03.2f</format>
        </chunk>

       <chunk>
          <node>/orientation/heading-deg</node>
          <name>Heading</name>
          <type>float</type>
          <format>%03.3f</format>
        </chunk>

   </output>
 </generic>
</PropertyList>

• The output tag indicates the protocol for output. The same "protocol" file can contain an "input" section, absent in this example (more later).
• line_seperator - the end of line (todo ? is this \r\n??)
• var_seperator - the delimiter for the properties, this could be "|", "###", any string.
• The two chunk blocks contain our data. Note that these appear in the order presented within the xml file.
  • node - the node of data we want
  • name - it there for a reference, its not transmitted and note necessary (like a note)
  • type - the way this xml is to interpret the value. This is quite important tag. For example if its not there or a string, then "floats" go wild and end up being a string of 32 characters with two decimal places!
  • format - same syntax as printf
  • There's more that can be done {todo - link to a full blown example/reference}

We can now start FlightGear and listen with:

fgfs --generic=socket,out,10,localhost,6789,udp,my_protocol

[todo] - link here to the tutorial