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