FlightGear Flight Recorder Mini-HOWTO
Thorsten Brehm
Started in August 2011
Last revised: 2011-09-26
FlightGear provides a customizable flight recorder capable of capturing
any selection of properties described via XML configuration files.
The recorder is currently used for the replay system.
Feature Brief
-------------
* Generic recording system, adaptable to any aircraft/data, provided that
data is accessible via the property tree. No hard-coded selections or
assumptions on properties to be recorded.
* Configuration read from XML files or the property tree itself.
* Interpolation method configurable per recorded/replayed signal.
* Adaptable recording resolution per signal.
* Multiple configurations supported.
Quick Start: Basic Configuration
--------------------------------
To configure and adapt the flight recorder, add a "/sim/flight-recorder"
section to your aircraft -set.xml file.
Example:
0
My Aircraft's Flight Recorder
float
/controls/gear/nosegear-steering-cmd-norm
linear
Default type for each signal is "float". Default "interpolation" method
is "linear" (for float/double). Default values may be omitted. See
configuration details below.
Generic Configuration Files
---------------------------
Select one of the default configuration files to specify the basic
properties to be recorded. It's not recommended to specify all
properties to be recorded individually.
The following generic files are provided:
* /Aircraft/Generic/flightrecorder/generic-piston-propeller-4.xml
Matches propeller aircraft with 4 piston engines, 4 tanks,
3 retractable gear.
It is the same configuration that was hard-coded for the replay system
up to FlightGear 2.4.0. To provide backward compatibility this
configuration is loaded by default, unless an aircraft provides a
specific flight recorder configuration.
* /Aircraft/Generic/flightrecorder/generic-piston-propeller-1.xml
Matches propeller aircraft with 1 piston engines, 2 tanks, 3 fixed
gear.
* /Aircraft/Generic/flightrecorder/generic-turboprop-2.xml
Matches turboprop aircraft with 2 turbines/propellers, 4 tanks,
3 retractable gear.
* /Aircraft/Generic/flightrecorder/generic-jet.xml
Matches jet aircraft with 2 jet engines, 4 tanks.
* /Aircraft/Generic/flightrecorder/generic-glider.xml
Matches gliders (no engines, no tanks, single fixed gear).
* /Aircraft/Generic/flightrecorder/generic-helicopter.xml
Matches helicopters with main and tail rotor (tested with YASim).
If none of the generic files matches your aircraft, simply use a
configuration which covers more than you need. Alternatively, copy the
contents of one of these generic files to your aircraft, and adapt as
needed (see below).
FDM experts are welcome to add more generic configuration files to
/Aircraft/Generic/flightrecorder - such as YASim-/JSBSim-specific
configurations, and configurations for other types of aircraft
(balloons, airships, ...).
Generic Components
-----------------
The generic configuration files in turn include a set of generic
components. If you copy the contents of a generic file to your aircraft,
you can adapt the components to your needs. See examples.
It is not recommended to copy the contents of the _component_ files to
an aircraft though (causes too much hassle and dependencies).
Engine Selection:
* /Aircraft/Generic/flightrecorder/components/engine-jet.xml
Records properties of a single jet engine.
For multiple jet engines, use "count". Example for 4 jets:
4
* /Aircraft/Generic/flightrecorder/components/engine-piston.xml
Records properties of a single piston engine and propeller.
For multiple piston engines, use "count" (see "jet" example).
* /Aircraft/Generic/flightrecorder/components/rotor.xml
Records properties of a single helicopter rotor (tested with YASim).
To use this, provide the base property path to the rotor as "prefix".
Example recording the rotor below "/rotors/main":
/rotors/main
Gear Selection:
* /Aircraft/Generic/flightrecorder/components/gear-fixed.xml
Records properties of a single non-retractable gear.
For multiple fixed gear, use "count" (see "jet" example).
* /Aircraft/Generic/flightrecorder/components/gear-retractable.xml
Records properties of a single retractable gear.
For multiple retractable gear, use "count" (see "jet" example).
Tanks:
* /Aircraft/Generic/flightrecorder/components/tanks.xml
Records properties of a single fuel tank.
For multiple fuel tanks, use "count" (see "jet" example).
Other:
* /Aircraft/Generic/flightrecorder/components/surfaces.xml
Records properties of flight control surfaces. Include this
for aircraft (with wings). Not useful for helicopters,
balloons, ...
* /Aircraft/Generic/flightrecorder/components/faults-engines.xml
Records fault properties of a single engine. Only include this
if your aircraft supports fault simulation.
For multiple engines, use "count" (see "jet" example). If used,
it should be compined with piston or jet engine.
* /Aircraft/Generic/flightrecorder/components/environment.xml
Records properties of environment/weather (visibility,
temperature - but _not_ cloud position...).
* /Aircraft/Generic/flightrecorder/components/position.xml
Records properties of a the aircrafts main position (latitude,
longitude, velocities, ...).
This is the most important component. Always include this.
* /Aircraft/Generic/flightrecorder/components/controls.xml
Records most important flight controls (rudder, aileron,
elevator, ...). Always include this.
Custom Properties
-----------------
When the generic or component files are not be sufficient to record or
replay aircraft-specific effects, you can add custom properties (signals
to be recorded) to the configuration.
Each signal consits of a recording type/resolution (which does _not_
need to match the actual type in the property tree!), the path to the
property and interpolation type.
Example recording some additional custom properties:
float
/controls/gear/nosegear-steering-cmd-norm
double
rotational-deg
/ai/model/carrier/alpha-angle-deg
bool
/controls/panel/custom-switch
Signal Configuration
--------------------
Template:
bool
angular-deg
/controls/panel/custom-switch
* type: The signal's type specifies the recording resolution - not the
type of the original property. The following types are supported:
- double: 8 byte/sample
- float: 4 byte/sample (default)
- int: 4 byte/sample, integer
- int16: 2 byte/sample, integer
- int8: 1 byte/sample, integer
- bool: 1 bit/sample (yes, 1 bit. 8 bools per byte).
String type is unsupported (too expensive).
* interpolation: Specifies how values are interpolated during replay, i.e.
when replay is in slow-motion mode and more frames/second are required
than recorded, or when replaying data from the medium/long term memory.
Supported methods:
- discrete: No interpolation. Default for integer/bool types.
- linear: Standard linear interpolation. Default for float/double.
- angular-rad (or angular): Angular values in radians (0-2pi).
- angular-deg: Angular values in degrees (0-360).
* property: Path to the property to be recorded.
Advanced Configuration
----------------------
- Multipe recorder configurations for a single aircraft are supported
(multiple "" sections for n=0,1,...).
Active configuration to be used for the replay system is selected via
/sim/flight-recorder/replay-config (= 0,1,...).
This can be useful for specific recorders for specific scenarios,
which should not be used by default. For example, a specific recorder
configuration could be provided which also records the position of
an aircraft carrier, of other AI aircraft, ...
This may also be useful for future use, i.e. to select another flight
recorded configuration for a different purpose, such as for the
multiplayer system.
- Flight recorder configuration can be adapted during run-time
(configuration is visible in the property browser below
/sim/flight-recorder). However it is necessary to reset (reinit) the
replay subsystem first - which also erases earlier recordings. It is
not possible to mix recordings of different configurations on to a
single "tape".
- Each configuration should be given a name. Useful for a (future)
selection GUI, when multiple configurations are available.
Optimizing Performance
----------------------
- Recording properties consumes memory and also CPU time. A few
additional properties don't matter much, but avoid execessive numbers.
Reduce the resolution (type) of signals to the minimum necessary to
save space.
- Use "bool" types where possible, they are most efficient.
- Avoid recording with "double" resolution (type "double"). Use "float"
instead - even if the original property in the property tree is a
"double" (almost all of them do). "float" precision is almost always
sufficient for recording/replay purposes, with few exceptions (like
latitude/longitude properties).
- Use int16/int8 for "small" integer values.
Recording/Replay Limits
-----------------------
- All properties can be recorded, however, only writable properties can
be replayed. Properties marked as read-only, or tied properties not
implementing the "set" method cannot be replayed.
- Replaying a property overwrites the property's value. However, other
sources may also write to the same property - such as Nasal code,
autopilot rules etc. When multiple sources "fight" over a property's
value then the last update "wins" - resulting in a dependency to an
unknown/random sequence. Hence, during deplay, try to disable other
sources writing to properties which were recorded and should be
replayed.
If the other source cannot be disabled, check if you're recording the
right property. It may be better to record the input properties of the
other source instead (i.e. the inputs processed by the Nasal or
autopilot rule).
__end__