X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=docs-mini%2FREADME.protocol;h=80a7163c68f6119bc43c53885f75224b85a881c8;hb=575f576aa90d8d22a857ccbb5e9f2c2e79a0db50;hp=cd2159f44dd20ca696321674b6e1f15f082b172a;hpb=5594b110e3ac4fd3eca3903b3597aae50c0b50da;p=flightgear.git diff --git a/docs-mini/README.protocol b/docs-mini/README.protocol index cd2159f44..80a7163c6 100644 --- a/docs-mini/README.protocol +++ b/docs-mini/README.protocol @@ -1,49 +1,98 @@ -The generic communication protocol for FlightGear provides a powerfull way -of adding a simple ASCII based or binary protocol, just by defining an -XML encoded configuration file. +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/Protocol/ 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 - (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). +== 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). -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: + + false + + + + -: -: -Name Charachter + + ... first chunk spec ... + -newline '\n' -tab '\t' -formfeed '\f' -carriagereturn '\r' -verticaltab '\v' + + ... another chunk etc. ... + + -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. + + ... 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. + +--- ASCII protocol parameters --- + +output only: + STRING default: "" file header put on top of the file + STRING default: "" file footer put at the end of the file + +input & output: + BOOL default: false (= ASCII mode) + 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 + + +--- Binary protocol parameters --- 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 +101,193 @@ 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) + (ASCII protocol only, not used or needed in binary mode) + 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 + + 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 Celcius to degrees Fahrenheit). + +For input chunks there exist some more options: + + optional boolean parameter to enable handling of incoming values + as relative changes (default: false) + (Can be eg. used to realise up/down buttons by just sending 1 or + -1 respectively) + + an optional minimum limit for the value to be clamped to. This + limit is always specified as absolute value, also with relative + changes enabled. (default: 0) + an optional upper limit for the input value to be clamped to. If + equals no limit is applied. (default: 0) + instead of clamping to minimum and maximum limits, wrap values + around. Values will be in [min, max[ (default: false) + (Usefull for eg. heading selector to start again with 1 for + values higher than 360) + +, , and are only used for numeric data types. can +additionally be used with type 'bool', where it toggles the value, if the received +value evaluates to 'true', otherwise the value is left unchanged. + +Chunks can also consist of a single constant , like in: + Data Section + + +== examples =================================================================== + +Writes log of this form: -A simple protocol configuration file then could look something like the -following: +V=16 +H=3.590505 +P=3.59 +V=12 +H=3.589020 +P=3.59 + + + + + + + + + + newline + newline + false + + + speed + V=%d + /velocities/airspeed-kt + + + + heading (rad) + H=%.6f + float + /orientation/heading-deg + 0.0174532925199433 + + + + pitch angle (deg) + P=%03.2f + /orientation/pitch-deg + + + + + + + +Control the heading bug by sending relative changes separated by newlines: + + + + newline - - - - newline - newline - false - - - speed - V=%d - /velocities/airspeed-kt - - - - heading - H=%02d - /orientation/heading-deg - 57.29578 - - - - pitch angle - P=%05.1f - float - /orientation/pitch-deg - + + heading bug + int + /autopilot/settings/heading-bug-deg + true + 1 + 360 + true + + + + +-- writing data in XML syntax ------------------------------------------------- + +Assuming the file is called $FG_ROOT/Protocol/xmltest.xml, then it could be +used as $ fgfs --generic=file,out,1,/tmp/data.xml,xmltest + + + + + + + + false + \n + \n + <?xml version="1.0"?>\n\n<data>\n + </data>\n + + + \t<set> + + + + /position/altitude-ft + float + \t\t<altitude-ft>%.8f</altitude-ft> + + + + /velocities/airspeed-kt + float + \t\t<airspeed-kt>%.8f</airspeed-kt> + + + + \t</set> + + + + + +-- Analyzing the resulting binary packet format ------------------------------- + +A utility called generic-protocol-analyse can be found under +FlightGear/utils/xmlgrep which can be used to analyze the resulting +data packet for the binary protocol. + +The output would be something like: + +bintest.xml +Generic binary output protocol packet description: + + pos | size | type | factor | description +-----|------|--------|------------|------------------------ + 0 | 4 | int | | indicated speed (kt) + 4 | 4 | float | | pitch att (deg) + 8 | 4 | float | | magnetic heading (deg) + 12 | 4 | int | | outside air temperarure (degF) + 16 | 1 | bool | | autocoord + +total package size: 17 bytes +