docs-mini/README.IO

   1 This document describes how to invoke FlightGear's generic IO subsystem.
   2
   3 FlightGear has a fairly flexible generic IO subsystem that allows you
   4 to "speak" any supported protocol over any supported medium.  The IO
   5 options are configured at runtime via command line options.  You can
   6 specify multiple entries if you like, one per command line option.
   7
   8 The general form of the command line option is as follows:
   9
  10     --protocol=medium,direction,hz,medium_options,...
  11
  12     protocol = { native, nmea, garmin, fgfs, rul, pve, ray, etc. }
  13     medium = { serial, socket, file, etc. }
  14     direction = { in, out, bi }
  15     hz = number of times to process channel per second (floating
  16          point values are ok.
  17
  18 Generic Communction:
  19
  20     --generic=params
  21
  22     With this option it is possible to output a pre-configured
  23     ASCII string using a predefined seperator. The configuration is
  24     defined in an XML file located in the Protocol directiory of
  25     the base package.
  26
  27     params can be:
  28     serial port communication:    serial,dir,hz,device,baud,protocol
  29     socket communication:         socket,dir,hz,machine,port,style,protocol
  30     output to a file:             file,dir,hz,filename,,protocol
  31
  32
  33     The confinfiguration file is defined as follows:
  34
  35     <?xml version="1.0"?>
  36     <PropertyList>
  37
  38      <generic>
  39       <output>
  40        <seperator>\n</seperator>
  41
  42         <chunk>
  43          <name>speed</name>               <!-- for readabillity              -->
  44          <type>int</type>                 <!-- one of: bool,int,float,string -->
  45          <format>V=%d</format>            <!-- output format string          -->
  46          <node>/velocities/speed</node>   <!-- location of the value         -->
  47          <offset>0.0</offset>             <!-- add this to the value         -->
  48          <factor>1.0</factor>             <!-- multiply by this value        -->
  49        </chunk>
  50
  51        <chunk>
  52         ...
  53        </chunk>
  54
  55        ...
  56
  57       </output>
  58      </generic>
  59     </PropertyList>
  60
  61
  62 Serial Port Communication:
  63
  64     --nmea=serial,dir,hz,device,baud
  65
  66     device = OS device name of serial line to be open()'ed
  67     baud = {300, 1200, 2400, ..., 230400}
  68
  69     example to pretend we are a real gps and output to a moving map application:
  70
  71     --nmea=serial,out,0.5,COM1,4800
  72
  73     Note that for unix varients you might use a device name like "/dev/ttyS0"
  74
  75 Socket Communication:
  76
  77     --native=socket,dir,hz,machine,port,style
  78
  79     machine = machine name or ip address if client (leave empty if server)
  80     port = port, leave empty to let system choose
  81     style = tcp or udp
  82
  83     example to slave one copy of fgfs to another
  84
  85     fgfs1:  --native=socket,out,30,fgfs2,5500,udp
  86     fgfs2:  --native=socket,in,30,,5500,udp --fdm=external
  87
  88     This instructs the first copy of fgfs to send UDP packets in the
  89     native format to a machine called fgfs2 on port 5500.
  90
  91     The second copy of fgfs will accept UDP packets (from anywhere) on
  92     port 5500.  Note the additional --fdm=external option.  This tells
  93     the second copy of fgfs to not run the normal flight model, but
  94     instead set the FDM values based on an external source (the
  95     network in this case.)
  96
  97
  98 File I/O:
  99
 100     --garmin=file,dir,hz,filename
 101
 102     filename = file system file name
 103
 104     example to record a flight path at 10 hz:
 105
 106     --native=file,out,10,flight1.fgfs
 107
 108     example to replay your flight
 109
 110     --native=file,in,10,flight1.fgfs --fdm=external
 111
 112
 113 Moving Map Example:
 114
 115     Per Liedman has developed a moving map program called Atlas
 116     (atlas.sourceforge.net) The initial inspiration and much code came
 117     from Alexei Novikov.
 118
 119     The moving map supports NMEA format input either via network or
 120     via serial port.  Either way will work, but this example
 121     demonstrates the use of a socket connection.
 122
 123     Start up fgfs with:
 124
 125         fgfs --nmea=socket,out,0.5,atas-host-name,5500,udp
 126
 127     Start up the Atlas program with:
 128
 129         Atlas --udp=5500 --fgroot=path-to-fg-root --glutfonts
 130
 131     Once both programs are running, the Atlas program should display
 132     your current location.  Atlas is a really nifty program with many
 133     neat options such as the ability to generate and use background
 134     bitmaps that show the terrain, cities, lakes, oceans, rivers, etc.
 135
 136
 137 HTTP Server Example
 138
 139     You can now interact with a running copy of FlightGear using your
 140     web browser.  You can view all the key internal variables and even
 141     change the ones that are writable.  If you have support in your
 142     favorite [scripting] language for interacting with an http server,
 143     you should be able to use this as a mechanism to interface your
 144     script with FlightGear.
 145
 146     Start up fgfs with the --httpd=<port#> option:
 147
 148     For example:
 149
 150         fgfs --httpd=5500
 151
 152     Now point your web browser to:
 153
 154         http://host.domain.name:5500/
 155
 156     When a value is displayed, you can click on it to bring up a form
 157     to assign it a new value.