From 2bcf5b7fe7b9b7c6227f977137e1bd057136c049 Mon Sep 17 00:00:00 2001 From: mfranz Date: Sun, 29 Jul 2007 17:16:03 +0000 Subject: [PATCH] corrections, extensions, spelling, cleanup --- docs-mini/README.IO | 46 ++----- docs-mini/README.protocol | 266 ++++++++++++++++++++++++++++---------- 2 files changed, 213 insertions(+), 99 deletions(-) diff --git a/docs-mini/README.IO b/docs-mini/README.IO index 38607916e..19fd13933 100644 --- a/docs-mini/README.IO +++ b/docs-mini/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: @@ -155,3 +131,9 @@ HTTP Server Example When a value is displayed, you can click on it to bring up a form to assign it a new value. + + +ACMS flight data recorder playback + + fgfs --fdm=acms --generic=file,in,1,,acms + diff --git a/docs-mini/README.protocol b/docs-mini/README.protocol index 686d0299e..7e66858ba 100644 --- a/docs-mini/README.protocol +++ b/docs-mini/README.protocol @@ -1,49 +1,95 @@ The generic communication protocol for FlightGear provides a powerful way -of adding a simple ASCII based or binary protocol, just by defining an -XML encoded configuration file. - -The definition of the protocol consists of variable separators, line separators, -and chunks of text. - -Each chunk 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 - (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 Celsius to degrees Fahrenheit). +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 character. The currently supported -control characters are: -: -: -Name Character +== file layout ================================================================ -newline '\n' -tab '\t' -formfeed '\f' -carriagereturn '\r' -verticaltab '\v' +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 -any other characters 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. 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 @@ -52,44 +98,130 @@ 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 + 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 + -A simple protocol configuration file then could look something like the -following: + - + + newline + newline + false - - newline - newline - false + + speed + V=%d + /velocities/airspeed-kt + - - speed - V=%d - /velocities/airspeed-kt - + + heading (rad) + H=%.6f + float + /orientation/heading-deg + 0.0174532925199433 + - - heading - H=%02d - /orientation/heading-deg - 57.29578 - - - - pitch angle - 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 + + + + + +