diff --git a/Docs/README.IO b/Docs/README.IO index fc3bcbaeb..19fd13933 100644 --- a/Docs/README.IO +++ b/Docs/README.IO @@ -5,6 +5,7 @@ to "speak" any supported protocol over any supported medium. The IO options are configured at runtime via command line options. You can specify multiple entries if you like, one per command line option. + The general form of the command line option is as follows: --protocol=medium,direction,hz,medium_options,... @@ -15,13 +16,14 @@ The general form of the command line option is as follows: hz = number of times to process channel per second (floating point values are ok. -Generic Communction: + +Generic Communication: --generic=params With this option it is possible to output a pre-configured - ASCII string using a predefined seperator. The configuration is - defined in an XML file located in the Protocol directiory of + ASCII string using a predefined separator. The configuration is + defined in an XML file located in the Protocol directory of the base package. params can be: @@ -29,34 +31,7 @@ Generic Communction: socket communication: socket,dir,hz,machine,port,style,protocol output to a file: file,dir,hz,filename,protocol - - The confinfiguration file is defined as follows: - - - - - - - \n - - - speed - int - V=%d - /velocities/speed - 0.0 - 1.0 - - - - ... - - - ... - - - - + See README.protocol for how to define a generic protocol. Serial Port Communication: @@ -70,7 +45,8 @@ Serial Port Communication: --nmea=serial,out,0.5,COM1,4800 - Note that for unix varients you might use a device name like "/dev/ttyS0" + Note that for unix variants you might use a device name like "/dev/ttyS0" + Socket Communication: @@ -160,3 +136,4 @@ HTTP Server Example ACMS flight data recorder playback fgfs --fdm=acms --generic=file,in,1,,acms + diff --git a/Docs/README.protocol b/Docs/README.protocol index 96c4aa55b..7e66858ba 100644 --- a/Docs/README.protocol +++ b/Docs/README.protocol @@ -1,81 +1,227 @@ -The generic communication protocol for FlightGear provides a powerfull way -of adding a simple ASCII based output only protocol, just by defining an -XML encoded configuration file and placing it in the $FG_ROOT/data/Protocols -directory. - -The definition of the protocol consists of variable separators, line separators, -and chuncks of text. - -Each chunck defines: - - for ease of use - the property tree node which provides the data - the value type (needed for formatting) - defines the actual piece of text which should be sent. - it can include formatting options like: - - %s string - %i integer (default) - %f float - - an optionale multiplication factor which can be used for - unit conversion. (for example, radians to degrees). - an optional offset which can be used for unit conversion. - (for example, degrees Celsius to degrees Fahrenheit). +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/data/Protocols/ directory. -The output section also could define the variable separator and line separator. - -The separators can be either a control character such as a tab or newline, or a -user specified string or other single charachter. The currently supported -control charachters are: - -: -: -Name Charachter - -newline '\n' -tab '\t' -formfeed '\f' -carriagereturn '\r' -verticaltab '\v' - -any other charachters just need to be added to "Network/generic.cxx" - -The var_separator is placed between each variable, while the line_separator is -placed at the end of each lot of variables. -A simple protocol configuration file then could look something like the -following: +== file layout ================================================================ + +A protocol file can contain either or both of and +definition blocks. Which one is used depends on how the protocol +is called (e.g. --generic=file,out,1,/tmp/data.xml,myproto would +only use the definitions block). + + + + + + + false + + + + + + + ... first chunk spec ... + + + + ... another chunk etc. ... + + + + + + + + + ... chunk spec ... + + + + + + + + + +== input/output parameters ==================================================== + +Both and blocks can contain information about +the data mode (ascii/binary) and about separators between fields +and data sets, as well as a list of s. Each defines +a property that should be written (and how), or a variable and which +property it should be written to. + +output only: + BOOL default: false (= ASCII mode) + STRING default: "" file header put on top of the file + STRING default: "" file footer put at the end of the file + +input & output: + STRING default: "" field separator + STRING default: "" separator between data sets + + + are put between every two output properties, while + is put at the end of each data set. Both can contain +arbitrary strings or one of the following keywords: + + Name Character + + newline '\n' + tab '\t' + formfeed '\f' + carriagereturn '\r' + verticaltab '\v' + + +Typical use could be: + + tab + newline + +or + + \t + \r\n + + + +To enable binary mode, simply include a true 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 tag. Options include the length +of the packet, a magic number to simplify decoding. Examples: + + magic,0x12345678 + length + none + + + + +== variable parameters (chunk spec) =========================================== + +Both and block can contain a list of specs, +each of which describes the properties of on variable to write/read. + + + for ease of use (not tranferred) + the property tree node which provides the data + the value type (needed for formatting) + one of string, float, bool, int (default: int) + defines the actual piece of text which should be sent. + it can include "printf" style formatting options like: + + %s string + %d integer (default) + %f float + (not used or needed in binary mode) + + an optional multiplication factor which can be used for + unit conversion. (for example, radians to degrees). + an optional offset which can be used for unit conversion. + (for example, degrees to radians). + + +Chunks can also consist of a single constant , like in: + + + + +== examples =================================================================== + +Writes log of this form: + +V=1736 +H=17647 +P=004.6 +V=1780 +H=18105 +P=006.4 + + - + - newline - newline + + newline + newline + false - - speed - V=%d - /velocities/airspeed-kt - + + speed + V=%d + /velocities/airspeed-kt + - - heading (rad) - H=%02d - /orientation/heading-deg - 57.29578 - + + heading (rad) + H=%.6f + float + /orientation/heading-deg + 0.0174532925199433 + - - pitch angle (deg) - P=%05.1f - float - /orientation/pitch-deg - + + pitch angle (deg) + P=%03.2f + /orientation/pitch-deg + + - + + + + + +-- writing data in XML syntax ------------------------------------------------- + +Assuming the file is called $FG_ROOT/Protocols/xmltest.xml, then it could be +used as $ fgfs --generic=file,out,1,/tmp/data.xml,xmltest + + + + + + + + false + + + <?xml version="1.0"?>\n\n<data>\n + </data>\n + + + \t<set>\n + + + + /position/altitude-ft + float + \t\t<altitude-ft>%.8f</altitude-ft>\n + + + + /velocities/airspeed-kt + float + \t\t<airspeed-kt>%.8f</airspeed-kt>\n + + + + \t</set>\n + + + + + +