diff --git a/Docs/README.commands b/Docs/README.commands new file mode 100644 index 000000000..e9ed009f0 --- /dev/null +++ b/Docs/README.commands @@ -0,0 +1,249 @@ +FlightGear Commands Mini-HOWTO + +David Megginson +Started: 2002-10-25 +Last revised: 2003-01-20 + + +In FlightGear, a *command* represents an action, while a *property* +represents a state. The trigger for a command can be any kind of user +input, including the keyboard, mouse, joystick, GUI, instrument panel, +or a remote network client. + + +XML Command Binding Markup +-------------------------- + +Most of the command-binding in FlightGear is handled through static +XML configuration files such as $FG_ROOT/keyboard.xml for the +keyboard, $FG_ROOT/mice.xml for the mouse, and +$FG_ROOT/gui/menubar.xml for the menubar. In all of these files, you +reference a command through a binding. This binding advances the +first throttle by 1%, up to a maximum value of 1.0: + + + property-adjust + /controls/throttle[0] + 0.01 + 1.0 + + +A command binding always consists of the XML 'binding' element, with +one subelement named 'command' containing the command name (such as +'property-adjust'). All other subelements are named parameters to the +command: in this case, the parameters are 'property', 'step', and +'max'. Here is a simpler binding, with no parameters: + + + exit + + +Bindings always appear inside some other kind of markup, depending on +the input type. For example, here is the binding from keyboard.xml +that links the ESC key to the 'exit' command: + + + ESC + Prompt and quit FlightGear. + + exit + + + +Usually, more than one binding is allowed for a single input trigger, +and bindings are executed in order from first to last. + + +Built-in Commands +----------------- + +As of the last revision date, the following commands were available +from inside FlightGear; the most commonly-used ones are the commands +that operate on property values (FlightGear's internal state): + + +null - do nothing + +script - execute a PSL script + script: the PSL script to execute + +exit - prompt and quit FlightGear + +load - load properties from an XML file + file: the name of the file to load, relative to the current + directory (defaults to "fgfs.sav") + +save - save properties to an XML file + file: the name of the file to save, relative to the current + directory (defaults to "fgfs.sav"). + +panel-load - (re)load the 2D instrument panel + path: the path of the XML panel file, relative to $FG_ROOT (defaults + to the value of /sim/panel/path if specified, or + "Panels/Default/default.xml" as a last resort. + +panel-mouse-click - pass a mouse click to the instrument panel + button: the number of the mouse button (0-based) + is-down: true if the button is down, false if it is up + x-pos: the x position of the mouse click + y-pos: the y position of the mouse click + +preferences-load - (re)load preferences + path: the file name to load preferences from, relative to $FG_ROOT. + Defaults to "preferences.xml". + +view-cycle - cycle to the next viewpoint + +screen-capture - capture the screen to a file + +tile-cache-reload - reload the scenery tile cache + +lighting-update - update FlightGear's lighting + +property-toggle - swap a property value between true and false + property: the name of the property to toggle + +property-assign - assign a value to a property + property[0]: the name of the property that will get the new value. + value: the new value for the property; or + property[1]: the name of the property holding the new value. + +property-adjust - adjust the value of a property + property: the name of the property to increment or decrement + step: the amount of the increment or decrement (defaults to 0) + offset: input offset distance (used for the mouse; multiplied by + factor) + factor: factor for multiplying offset distance (used for the mouse; + defaults to 1) + min: the minimum allowed value (default: no minimum) + max: the maximum allowed value (default: no maximum) + mask: 'integer' to apply only to the left of the decimal point; + 'decimal' to apply only to the right of the decimal point; 'all' + to apply to the full value (defaults to 'all') + wrap: true if the value should be wrapped when it passes min or max; + both min and max must be specified (defaults to false) + +property-multiply - multiply the value of a property + property: the name of the property to multiply + factor: the amount by which to multiply (defaults to 1.0) + min: the minimum allowed value (default: no minimum) + max: the maximum allowed value (default: no maximum) + mask: 'integer' to apply only to the left of the decimal point; + 'decimal' to apply only to the right of the decimal point; 'all' + to apply to the full value (defaults to 'all') + wrap: true if the value should be wrapped when it passes min or max; + both min and max must be specified (defaults to false) + +property-swap - swap the values of two properties + property[0]: the name of the first property + property[1]: the name of the second property + +property-scale - set the value of a property based on an axis + property: the name of the property to set + setting: the current input setting (usually a joystick axis from -1 + or 0 to 1) + offset: the offset to shift by, before applying the factor (defaults + to 0) + factor: the factor to multiply by (use negative to reverse; defaults + to 1.0) + +property-cycle - cycle a property through a set of values + property: the name of the property to cycle + value[*]: all of the allowed values + +dialog-show - show an XML-configured dialog box + dialog-name - the name of the dialog to show + +dialog-close - close the active dialog box + +dialog-update - copy values from FlightGear to the active dialog box + object-name: the name of the GUI object to update (defaults to all + objects) + +dialog-apply - copy values from the active dialog box to FlightGear + object-name: the name of the GUI object to apply (defaults to all + objects) + +presets-commit - commit preset values from /sim/presets + + +The following commands are temporary, and will soon disappear or be +renamed; do NOT rely on them: + +old-save-dialog - offer to save a flight + +old-load-dialog - offer to load a flight + +old-reinit-dialog - offer to reinit FlightGear + +old-hires-snapshot-dialog - save a hires screen shot + +old-snapshot-dialog - save a screenshot + +old-print-dialog - print the screen (Windows only) + +old-pilot-offset-dialog - set pilot offsets graphically + +old-hud-alpha-dialog - set the alpha value for the HUD + +old-properties-dialog - display the property browser + +old-preset-airport-dialog - set the default airport + +old-preset-runway-dialog - set the default runway + +old-preset-offset-distance-dialog - set the default offset distance + +old-preset-altitude-dialog - set the default altitude + +old-preset-glidescope-dialog - set the default glidescope + +old-preset-airspeed-dialog - set the default airspeed + +old-preset-commit-dialog - commit preset values + +old-ap-add-waypoint-dialog - add a waypoint to the current route + +old-ap-pop-waypoint-dialog - remove a waypoint from the current route + +old-ap-clear-dialog - clear the current route + +old-ap-adjust-dialog - adjust the autopilot settings + +old-lat-lon-format-dialog - toggle the lat/lon format in the HUD + +old-help-dialog - offer online help + + +Adding New Commands in C++ +-------------------------- + + +To add a new command to FlightGear, you first need to create a +function that takes a single SGPropertyNode const pointer as an +argument: + + void + do_something (SGPropertyNode * arg) + { + something(); + } + +Next, you need to register it with the command manager: + + globals->get_commands()->addCommand("something", do_something); + +Now, the command "something" is available to any mouse, joystick, +panel, or keyboard bindings. If the bindings pass any arguments, they +will be children of the SGPropertyNode passed in: + + void + do_something (const SGPropertyNode * arg) + { + something(arg->getStringValue("foo"), arg->getDoubleValue("bar")); + } + +That's pretty-much it. Apologies in advance for not making things any +more complicated. + + diff --git a/Docs/README.conditions b/Docs/README.conditions new file mode 100644 index 000000000..10d9d040b --- /dev/null +++ b/Docs/README.conditions @@ -0,0 +1,206 @@ +CONDITIONS IN FLIGHTGEAR PROPERTY FILES + +Written by David Megginson, david@megginson.com +Last modified: $Date$ + +This document is in the Public Domain and comes with NO WARRANTY! + + +1. Introduction +--------------- + +Some FlightGear property files contain conditions, affecting whether +bindings or animations are applied. For example, the following +binding will apply only when the /sim/input/selected/engine[0] +property is true: + + + + /sim/input/selected/engine[0] + + property-assign + /controls/starter[0] + true + + +Conditions always occur within a property subtree named "condition", +which is equivalent to an "and" condition. + + +2. Comparison Operators +----------------------- + +The simplest condition is "property". It resolves as true when the +specified property has a boolean value of true (i.e. non-zero, etc.) +and false otherwise. Here is an example: + + + /sim/input/selected/engine[0] + + +For more sophisticated tests, you can use the "less-than", +"less-than-equals", "greater-than", "greater-than-equals", "equals", +and "not-equals" comparison operators. These all take two operands, +either two "property" operands or one "property" and one "value" +operand, and return true or false depending on the result of the +comparison. The value of the second operand is always forced to the +type of the first; for example, if you compare a string and a double, +the double will be forced to a string and lexically compared. If one +of the operands is a property, it is always assumed to be first. Here +is an example of a comparison that is true only if the RPM of the +engine is less than 1500: + + + + /engines/engine[0]/rpm + 1500 + + + + +3. Boolean Operators +-------------------- + +Finally, there are the regular boolean operators "and", "or", and +"not". Each one surrounds a group of other conditions, and these can +be nested to arbitrary depths. Here is an example: + + + + + + /engines/engine[0]/rpm + 1500 + + + /engines/engine[0]/rpm + 2500 + + + /engines/engine[0]/running + + + +The top-level "condition" is an implicit "and". + + +4. Approximating if...else +-------------------------- + +There is no equivalent to the regular programming 'else' statement in +FlightGear conditions; instead, each condition separately must take +the others into account. For example, the equivalent of + + if (x == 3) ... else if (y == 5) ... else ... + +in FlightGear conditions is + + + + /x + 3 + + + + /y + 5 + + + +and then + + + + /y + 5 + + + + /x + 3 + + + +and then + + + + + /x + 3 + + + + + /y + 5 + + + +It's verbose, but it works nicely within existing property-based +formats and provides a lot of flexiblity. + + +5. Syntax Summary +----------------- + +Here's a quick syntax summary: + +* ... + + Contains one or more subconditions, all of which must be true. + +* ... + + The top-level container for conditions, equivalent to an "and" group + +* ... + + Contains two properties or a property and value, and is true if the + properties have equivalent values. + +* ... + + Contains two properties or a property and a value, and is true if + the second property or the value has a value greater than the first + property. + +* ... + + Contains two properties or a property and a value, and is true if + the second property or the value has a value greater than or equal + to the first property. + +* ... + + Contains two properties or a property and a value, and is true if + the second property or the value has a value less than the first + property. + +* ... + + Contains two properties or a property and a value, and is true if + the second property or the value has a value less than or equal + to the first property. + +* ... + + Contains one subcondition, which must not be true. + +* ... + + Contains two properties or a property and value, and is true if the + properties do not have equivalent values. + +* ... + + Contains one or more subconditions, at least one of which must be + true. + +* ... + + The name of a property to test. + +* ... + + A literal value in a comparison. diff --git a/Docs/README.electrical b/Docs/README.electrical new file mode 100644 index 000000000..968f7967f --- /dev/null +++ b/Docs/README.electrical @@ -0,0 +1,170 @@ +Specifying and Configuring and Aircraft Electrical System +========================================================= + +Written by Curtis L. Olson + +February 3, 2003 - Initial revision. + + +Introduction +============ + +The FlightGear electrical system model is an approximation. We don't +model down to the level of individual electrons, but we do try to +model a rich enough subset of components so that a realistic (from the +pilot's perspective) electrical system may be implemented. We try to +model enough of the general flow so that typical electrical system +failures can be implimented and so that the pilot can practice +realistic troubleshooting techniques and learn the basic structure and +relationships of the real aircraft electrical system. + +An electrical system can be built from 4 major components: suppliers, +buses, outputs, and connectors. Suppliers are things like batteries +and generators. Buses collect input from multiple suppliers and feed +multiple outputs. Outputs are not strictly necessary, but are +included so we can name generic output types and provide a consistent +naming scheme to other FlightGear subsystems. Finally connectors +connect a supplier to a bus, or a bus to an output, and optionally can +specify a switch property (either a physical switch or a circuit +breaker.) + +At run time, the structure specified in the electrical system config +file is parsed and a directional graph (in the computer science sense) +is built. Each frame, the current is propagated through the system, +starting at the suppliers, flowing through the buses, and finally to +the outputs. The system follows the path of connectors laid out in +the config file and honors the state of any connector switch. + + +Suppliers +========= + +A supplier entry could look like the following: + + + Battery 1 + /systems/electrical/suppliers/battery[0] + battery + 24 + 60 + + + can be anything you choose to call this entry. + is the name of a property that will be updated with the state + of this supplier. + can be "battery", "alternator", or "external". + specifies the volts of the source + specifies the amps of the source + +Currently and are not really modeled in detail. This +is more of a place holder for the future. + +For alternators, you must additionally specify: + + /engines/engine[0]/rpm + +The value of the rpm source determines if the generator is able to +produce power or not. + + +Buses +===== + +A bus entry could look like the following: + + + Essential/Cross Feed Bus + /systems/electrical/outputs/bus-essential + /systems/electrical/outputs/annunciators + /systems/electrical/outputs/master-switch + + + is whatever you choose to call this bus + +You can have an arbitrary number of entries. Each entry is the +name of a property that will be updated with the value of the current +at that bus. This allows you to wire devices directly to the bus but +does not allow you to insert a switch or circuit breaker in between. +See "Outputs" and "Connectors" if you want to do that. + + +Outputs +======= + +An output entry could look like the following: + + + Starter 1 Power + /systems/electrical/outputs/starter[0] + + +An output isn't entirely unlike a bus, but it's nice conceptually to +have a separate entity type. This enables us to specify a common set +of output property names so that other subsystems can automatically +work with any electrical system that follows the same conventions. An +output lives on the other side of a switch, so this is how you can +wire in cockpit switches to model things like fuel pump power, +avionics master switch, or any other switch on the panel. + + is whatever you choose to call this bus + +You can have an arbitrary number of entries. Each entry is the +name of a property that will be updated with the value of the current +at that bus. This allows you to wire devices directly to the bus but +does not allow you to insert a switch or circuit breaker in between. +See "Outputs" and "Connectors" if you want to do that. + +Other FlightGear subsystems can monitor the property name associated +with the various outputs to decide how to render an instrument, +whether to run the fuel pump, whether to spin a gyro, or any other +subsystem that cares about electrical power. + + +Connectors +========== + +An connector entry could look like the following: + + + Alternator 1 + Virtual Bus 1 + /controls/switches/master-alt + off + + +A connector specifies and input, and output, and any number of +switches that are wired in series. In other words, all switches need +to be true/on in order for current to get from the input to the output +of the connector. + + specifies the of the input. Typically you would +specify a "supplier" or a "bus". + + specifies the of the output. Typically you would +specify a bus or an output. + +You can have an arbitrary number of entries. The switches +are wired in series so all of them need to be on (i.e. true) in order +for current to pass to the output. + +Note: by default the system forces any listed switches to be true. +The assumption is that not every aircraft or cockpit may impliment +every available switch, so rather than having systems be switched off, +with no way to turn them on, we default to switched on. + +This is a problem however with the starter switch which we want to be +initialized to "off". To solve this problem you can specify +off or +on Switches default to on, so you +really only need to specify this tag if you want the connector's +switch to default to off. + + +Summary +======= + +The electrical system has a lot of power and flexibility to model a +variety of electrical systems. However, it is not yet perfect or +finished. One major weakness is that it doesn't yet model degraded +battery or generator power, and it doesn't model the "charge" of the +batteries in case of a generator failure. diff --git a/Docs/README.gui b/Docs/README.gui new file mode 100644 index 000000000..4b7691728 --- /dev/null +++ b/Docs/README.gui @@ -0,0 +1,362 @@ +FlightGear GUI Mini-HOWTO + +David Megginson +Started: 2003-01-20 +Last revised: 2003-01-20 + + +FlightGear creates its drop-down menubar and dialog boxes from XML +configuration files under $FG_ROOT/gui. This document gives a quick +explanation of how to create or modify the menubar and dialogs. The +toolkit for the FlightGear GUI is PUI, which is part of plib. + +All of the XML files use the standard FlightGear PropertyList format. + + +MENUBAR +------- + +FlightGear reads the configuration for its menubar from +$FG_ROOT/gui/menubar.xml. The file consists of a series of top-level +elements named "menu", each of which defines on of the drop-down +menus, from left to right. Each menu contains a series of items, +representing the actual items a user can select from the menu, and +each item has a series of bindings that FlightGear will activate when +the user selects the item. + +Here's a simplified grammar: + + [menubar] : menu* + + menu : label, item* + + item : label, binding* + +The bindings are standard FlightGear bindings, the same as the ones +used for the keyboard, mouse, joysticks, and the instrument panel. +Any commands allowed in those bindings are allowed here as well. + +Here's an example of a simple menubar with a "File" drop-down menu and +a single "Quit" item: + + + + + + + + + + exit + + + + + +PUI menus do not allow advanced features like submenus or checkmarks. +The most common command to include in a menu item binding is the +'dialog-show' command, which will open a user-defined dialog box as +described in the next section. + + +DIALOGS +------- + +The configuration files for XML dialogs use a nested structure to set +up dialog boxes. The top-level always describes a dialog box, and the +lower levels describe the groups and widgets that make it up. Here is +a simple, "hello world" dialog: + + + + hello + + 150 + 100 + false + + + 10 + 50 + + + + + + + +The dialog contains two sub-objects: a text field and a button. The +button contains one binding, which closes the active dialog when the +user clicks on the button. + +Coordinates are pseudo-pixels. The screen is always assumed to be +1024x768, no matter what the actual resolution is. The origin is the +bottom left corner of the screen (or parent dialog or group); x goes +from left to right, and y goes from bottom to top. + +All objects, including the top-level dialog, accept the following +properties, though they will ignore any that are not relevant: + + x - the X position of the bottom left corner of the object, in + pseudo-pixels. The default is to center the dialog. + + y - the Y position of the bottom left corner of the object, in + pseudo-pixels. The default is to center the dialog. + + width - the width of the object, in pseudo-pixels. The default is + the width of the parent container. + + height - the height of the object, in pseudo-pixels. The default is + the width of the parent container. + + legend - the text legend to display in the object. + + label - the text label to display near the object. + + property - the name of the FlightGear property whose value will + be displayed in the object (and possibly modified through it). + + binding - a FlightGear command binding that will be fired when the + user activates this object (more than one allowed). + + default - true if this is the default object for when the user + presses the [RETURN] key. + +Objects may appear nested within the top-level dialog or a "group" +object. Here are all the object types allowed, with their special +properties: + + +dialog +------ + +The top-level dialog box; the name does not actually appear in the +file, since the root element is named PropertyList. + + name - (REQUIRED) the unique name of the dialog for use with the + "dialog-show" command. + + modal - true if the dialog is modal (it blocks the rest of the + program), false otherwise. The default is false. + +Example: + + + + sample + 500 + 210 + false + + + ... + + + + + + + +group +----- + +A group of subobjects. This object does not draw anything on the +screen, but all of its children specify their coordinates relative to +the group; using groups makes it easy to move parts of a dialog +around. + +Example: + + + 0 + 50 + + + ... + + + + ... + + + + + + + +input +----- + +A simple editable text field. + +Example: + + + 10 + 60 + 200 + 25 + + /environment/temperature-sea-level-degc + + + +text +---- + +A non-editable text label. + +Example: + + + 10 + 200 + + + + +checkbox +-------- + +A checkbox, useful for linking to boolean properties. + +Example: + + + 150 + 200 + 12 + 12 + /autopilot/locks/heading + + + + +button +------ + +A push button, useful for firing command bindings. + + one-shot - true if the button should pop up again after it is + pushed, false otherwise. The default is true. + + + + + +combo +----- + +A pop-up list of selections. + + value - one of the selections available for the combo. There may be + any number of "value" fields. + +Example: + + + 10 + 50 + 200 + 25 + /environment/clouds/layer[0]/type + clear + mostly-sunny + mostly-cloudy + overcast + cirrus + + + + +select +------ + +A scrollable list of selections. + + selection - a path in the property tree which holds the selectable items. + +Example: + + + + + +slider +------ + +A horizontal or vertical slider for setting a value. + + vertical - true if the slider should be vertical, false if it should + be horizontal. The default is false. + + min - the minimum value for the slider. The default is 0.0. + + max - the maximum value for the slider. The default is 1.0. + +Example: + + + 10 + 50 + 200 + /environment/visibility-m + 5 + 50000 + + + +dial +---- + +A circular dial for choosing a direction. + + wrap - true if the dial should wrap around, false otherwise. The + default is true. + + min - the minimum value for the dial. The default is 0.0. + + max - the maximum value for the dial. The default is 1.0. + +Example: + + + 10 + 50 + 20 + /environment/wind-from-direction-deg + 0 + 360 + + + +__end__ diff --git a/Docs/README.introduction b/Docs/README.introduction new file mode 100644 index 000000000..8d4d8aab3 --- /dev/null +++ b/Docs/README.introduction @@ -0,0 +1,88 @@ + +Internals +--------- + +The core of FlightGear is the property system. This is a tree like internal +representation of global variables. The property system is explained more +in detail later on. + +FlightGear' way of doing things is breaking it up into small pieces. There is +(for example) animation code that reacts on property changes. There is also a +Flight Dynamics model (FDM) that (amongst other things) updates properties. +There is a menu system that can display and alter properties. Then we have +sound code that plays sound based on ... properties. + +Maybe you see a pattern evolve by now. + +All subsystems are almost self containing. Most of the time they only read the +values of some properties, and sometimes they alter other properties. This is +the basic way of communicating between subsystems. + + +Property System +--------------- + +The property system is best described as an in-memory LDAP database which holds +the state of global variables. The system has a tree like hierarchy (like a +file system) and has a root node, sub nodes (like subdirectories) and end-nodes +(variables). + +All variables are kept internally as raw values and can be converted to any +other supported type (boolean, int, float double and string). + +Like a file system, every node can be accessed relative to the current node, or +absolute to the root node. + +The property system also allows aliasing nodes to other nodes (like symbolic +linking files or directories to other files or directories) and may be assigned +read-only or read-write. + +If necessary it would be possible for parts of the program to hold it's own +property tree, which is inaccessible from the global property tree, by keeping +track of it's own root-node. + +Property I/O code allows one to easily read the tree from, or write the tree to +an XML file. + + +Subsystems +---------- + +To add a new subsystem you would have to create a derived class from +SGSubsystem and define at least a small set of functions: + + class FGFX : public SGSubsystem + { + public: + + FGFX (); + virtual ~FGFX (); + + virtual void init (); + virtual void reinit (); + virtual void bind (); + virtual void unbind (); + virtual void update (double dt); + } + +The init() functions should make sure everything is set and ready so the +update() function can be run by the main loop. The reinit() function handles +everything in case of a reset by the user. + +The bind() and unbind() functions can be used to tie and untie properties. + +After that you can register this class at the subsystem manager: + + globals->add_subsystem("fx", new FGFX); + +Now the subsystem manager calls the update() function of this class every +frame. dt is the time (in seconds) elapsed since the last call. + + +Scripting +--------- + +The scripting langage Nasal can also read and modify properties but it can also +be incorporated into the menu system. The documentation for Nasal can be found +here: http://www.plausible.org/nasal/flightgear.html + diff --git a/Docs/README.jsclient b/Docs/README.jsclient new file mode 100644 index 000000000..619588ae7 --- /dev/null +++ b/Docs/README.jsclient @@ -0,0 +1,12 @@ +Start flightgear with +fgfs --jsclient=socket,in,,,,udp --prop:/jsclient/axis[i]="/property/you/want/to/control" --prop:/jsclient/axis[i+1]="/another/property/you/want/to/control" ... +eg: +# fgfs --aircraft=yf23-yasim --airport=KEMT --jsclient=socket,in,5,,16759,udp --prop:/jsclient/axis[0]="/controls/flight/spoilers" --prop:/jsclient/axis[1]="/radios/comm/volume" + + +Start the server on the machine with the remote gameport: +JsServer +eg: +# JsServer 192.168.1.1 16759 + +(JsServer can be started before or after fgfs) \ No newline at end of file diff --git a/Docs/README.logging b/Docs/README.logging new file mode 100644 index 000000000..6321d39fc --- /dev/null +++ b/Docs/README.logging @@ -0,0 +1,86 @@ +Logging in FlightGear +--------------------- + +[Note: JSBSim also has its own independent logging facilities, which +are not discussed here.] + +FlightGear can log any property values at any interval to one or more +CSV files (which can be read and graphed using spreadsheets like +Gnumeric or Excel). Logging is defined in the '/logging' subbranch of +the main property tree; under '/logging', each '/log' subbranch +defines a separate log with its own output file and interval. Here is +a simple example that logs the rudder and aileron settings every +second (1000ms) to the file steering.csv, using a comma (the default, +anyway) as the field delimiter: + + + + true + steering.csv + 1000 + , + + true + Rudder + /controls/rudder + + + true + Ailerons + /controls/aileron + + + + +Each 'log' subbranch contains a required 'enabled' property, an +optional 'filename' property (defaults to "fg_log.csv"), an optional +'delimiter' property (defaults to a comma), an optional 'interval-ms' +property (defaults to 0, which logs every frame), and a series of +'entry' subbranches. The 'delimiter' property uses only the first +character of the property value as the delimiter. Note that the +logger does no escaping, so you must choose a delimiter that will not +appear in the property values (that's not hard, since most of the +values are numeric, but watch for commas in the titles). + +Each 'entry' subbranch contains a required 'enabled' property, a +'property' property specifying the name of the property to be logged, +and an optional 'title' property specifying the title to use in the +CSV file (defaults to the full path of the property). The elapsed +time in milliseconds since the start of the simulation is always +included as the first entry with the title "Time", so there is no need +to include it explicitly. + +Here's a sample of the logging output for the above log: + + Time,Rudder,Ailerons + 6522,0.000000,0.000000 + 7668,-0.000000,0.000000 + 8702,-0.000000,0.000000 + 9705,-0.000000,0.000000 + 10784,-0.000000,0.000000 + 11792,-0.000000,0.000000 + 12808,-0.000000,-0.210000 + 13826,-0.000000,-0.344000 + 14881,-0.000000,-0.066000 + 15901,-0.000000,-0.806000 + 16943,-0.000000,-0.936000 + 17965,-0.000000,-0.534000 + 19013,-0.000000,-0.294000 + 20044,-0.000000,0.270000 + 21090,-0.000000,-1.000000 + 22097,-0.000000,-0.168000 + +Note that the requested interval is only a minimum; most of the time, +the actual interval is slightly longer than the requested one. + +The easiest way for an end-user to define logs is to put the log in a +separate XML file (usually under the user's home directory), then +refer to it using the --config option, like this: + + fgfs --config=log-config.xml + +The output log files are always relative to the current directory. + +-- + +David Megginson, last updated 2002-02-01 diff --git a/Docs/README.properties b/Docs/README.properties new file mode 100644 index 000000000..18ff23f3e --- /dev/null +++ b/Docs/README.properties @@ -0,0 +1,235 @@ +================================================================================ +CONTROLS +================================================================================ + +Flight Controls +--------------- +/controls/flight/aileron +/controls/flight/aileron-trim +/controls/flight/elevator +/controls/flight/elevator-trim +/controls/flight/rudder +/controls/flight/rudder-trim +/controls/flight/flaps +/controls/flight/slats +/controls/flight/BLC // Boundary Layer Control +/controls/flight/spoilers +/controls/flight/speedbrake +/controls/flight/wing-sweep +/controls/flight/wing-fold +/controls/flight/drag-chute + +Engines +------- +/controls/engines/throttle_idle +/controls/engines/engine[%d]/throttle +/controls/engines/engine[%d]/starter +/controls/engines/engine[%d]/fuel-pump +/controls/engines/engine[%d]/fire-switch +/controls/engines/engine[%d]/fire-bottle-discharge +/controls/engines/engine[%d]/cutoff +/controls/engines/engine[%d]/mixture +/controls/engines/engine[%d]/propeller-pitch +/controls/engines/engine[%d]/magnetos +/controls/engines/engine[%d]/boost +/controls/engines/engine[%d]/WEP +/controls/engines/engine[%d]/cowl-flaps-norm +/controls/engines/engine[%d]/feather +/controls/engines/engine[%d]/ignition +/controls/engines/engine[%d]/augmentation +/controls/engines/engine[%d]/afterburner +/controls/engines/engine[%d]/reverser +/controls/engines/engine[%d]/water-injection +/controls/engines/engine[%d]/condition + +Fuel +---- +/controls/fuel/dump-valve +/controls/fuel/tank[%d]/fuel_selector +/controls/fuel/tank[%d]/to_engine +/controls/fuel/tank[%d]/to_tank +/controls/fuel/tank[%d]/boost-pump[%d] + +Gear +---- +/controls/gear/brake-left +/controls/gear/brake-right +/controls/gear/brake-parking +/controls/gear/steering +/controls/gear/gear-down +/controls/gear/antiskid +/controls/gear/tailhook +/controls/gear/tailwheel-lock +/controls/gear/wheel[%d]/alternate-extension + +Anti-Ice +-------- +/controls/anti-ice/wing-heat +/controls/anti-ice/pitot-heat +/controls/anti-ice/wiper +/controls/anti-ice/window-heat +/controls/anti-ice/engine[%d]/carb-heat +/controls/anti-ice/engine[%d]/inlet-heat + +Hydraulics +---------- +/controls/hydraulic/system[%d]/engine-pump +/controls/hydraulic/system[%d]/electric-pump + +Electric +-------- +/controls/electric/battery-switch +/controls/electric/external-power +/controls/electric/APU-generator +/controls/electric/engine[%d]/generator +/controls/electric/engine[%d]/bus-tie + +Pneumatic +--------- +/controls/pneumatic/APU-bleed +/controls/pneumatic/engine[%d]/bleed + +Pressurization +-------------- +/controls/pressurization/mode +/controls/pressurization/dump +/controls/pressurization/outflow-valve +/controls/pressurization/pack[%d]/pack-on + +Lights +------ +/controls/lighting/landing-lights +/controls/lighting/turn-off-lights +/controls/lighting/formation-lights +/controls/lighting/taxi-light +/controls/lighting/logo-lights +/controls/lighting/nav-lights +/controls/lighting/beacon +/controls/lighting/strobe +/controls/lighting/panel-norm +/controls/lighting/instruments-norm +/controls/lighting/dome-norm + +Armament +-------- +/controls/armament/master-arm +/controls/armament/station-select +/controls/armament/release-all +/controls/armament/station[%d]/stick-size +/controls/armament/station[%d]/release-stick +/controls/armament/station[%d]/release-all +/controls/armament/station[%d]/jettison-all + +Seat +---- +/controls/seat/vertical-adjust +/controls/seat/fore-aft-adjust +/controls/seat/cmd_selector_valve +/controls/seat/eject[%d]/initiate +/controls/seat/eject[%d]/status + +APU +--- +/controls/APU/off-start-run +/controls/APU/fire-switch + +Autoflight +---------- +/controls/autoflight/autopilot[%d]/engage +/controls/autoflight/autothrottle-arm +/controls/autoflight/autothrottle-engage +/controls/autoflight/heading-select +/controls/autoflight/altitude-select +/controls/autoflight/bank-angle-select +/controls/autoflight/vertical-speed-select +/controls/autoflight/speed-select +/controls/autoflight/mach-select +/controls/autoflight/vertical-mode +/controls/autoflight/lateral-mode + +================================================================================ +FDM (Aircraft settings) +================================================================================ + +Position +--------------- +/position/latitude-deg +/position/longitude-deg +/position/altitude-ft + +Orientation +----------- +/orientation/roll-deg +/orientation/pitch-deg +/orientation/heading-deg + +/orientation/roll-rate-degps +/orientation/pitch-rate-degps +/orientation/yaw-rate-degps + +/orientation/side-slip-rad +/orientation/side-slip-deg +/orientation/alpha-deg + +Velocities +---------- +/velocities/airspeed-kt +/velocities/mach +/velocities/speed-north-fps +/velocities/speed-east-fps +/velocities/speed-down-fps + +/velocities/uBody-fps +/velocities/vBody-fps +/velocities/wBody-fps + +/velocities/vertical-speed-fps +/velocities/glideslope + +Acceleration +------------ +/accelerations/nlf + +/accelerations/ned/north-accel-fps_sec +/accelerations/ned/east-accel-fps_sec +/accelerations/ned/down-accel-fps_sec + +/accelerations/pilot/x-accel-fps_sec +/accelerations/pilot/y-accel-fps_sec +/accelerations/pilot/z-accel-fps_sec + +Engines +------- + +common: +/engines/engine[%d]/fuel-flow-gph +/engines/engine[%d]/fuel-flow_pph +/engines/engine[%d]/thrust_lb +/engines/engine[%d]/running +/engines/engine[%d]/starter +/engines/engine[%d]/cranking + +piston: +/engines/engine[%d]/mp-osi +/engines/engine[%d]/egt-degf +/engines/engine[%d]/oil-temperature-degf +/engines/engine[%d]/oil-pressure-psi +/engines/engine[%d]/cht-degf +/engines/engine[%d]/rpm + +turbine: +/engines/engine[%d]/n1 +/engines/engine[%d]/n2 +/engines/engine[%d]/epr +/engines/engine[%d]/augmentation +/engines/engine[%d]/water-injection +/engines/engine[%d]/ignition +/engines/engine[%d]/nozzle-pos-norm +/engines/engine[%d]/inlet-pos-norm +/engines/engine[%d]/reversed +/engines/engine[%d]/cutoff + +propeller: +/engines/engine[%d]/rpm +/engines/engine[%d]/pitch +/engines/engine[%d]/torque diff --git a/Docs/README.protocol b/Docs/README.protocol new file mode 100644 index 000000000..96c4aa55b --- /dev/null +++ b/Docs/README.protocol @@ -0,0 +1,81 @@ +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 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: + + + + + + + newline + newline + + + speed + V=%d + /velocities/airspeed-kt + + + + heading (rad) + H=%02d + /orientation/heading-deg + 57.29578 + + + + pitch angle (deg) + P=%05.1f + float + /orientation/pitch-deg + + + +