bde90daa71
Provide templates for various aircraft components or complete aircraft types. Better to have this stuff available/adaptable than hard-coded somewhere inside fgfs.
292 lines
11 KiB
Text
292 lines
11 KiB
Text
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:
|
|
|
|
<sim>
|
|
|
|
<!-- ... -->
|
|
|
|
<flight-recorder>
|
|
<replay-config type="int">0</replay-config>
|
|
<config n="0" include="/Aircraft/Generic/flightrecorder/generic-piston-propeller-1.xml">
|
|
<name type="string">My Aircraft's Flight Recorder</name>
|
|
<!-- Custom properties -->
|
|
<signal>
|
|
<type>float</type>
|
|
<property type="string">/controls/gear/nosegear-steering-cmd-norm</property>
|
|
<interpolation>linear</interpolation>
|
|
</signal>
|
|
<!-- More custom signals here -->
|
|
</config>
|
|
</flight-recorder>
|
|
|
|
<!-- ... -->
|
|
|
|
</sim>
|
|
|
|
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:
|
|
<signals include="/Aircraft/Generic/flightrecorder/components/engine-jet.xml">
|
|
<count>4</count>
|
|
</signals>
|
|
|
|
* /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":
|
|
<signals include="/Aircraft/Generic/flightrecorder/components/rotor.xml">
|
|
<prefix type="string">/rotors/main</prefix>
|
|
</signals>
|
|
|
|
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:
|
|
<sim>
|
|
<flight-recorder>
|
|
<config n="0" include="/Aircraft/Generic/flightrecorder/generic-piston-propeller-1.xml">
|
|
<!-- Add custom properties here -->
|
|
<signal>
|
|
<type>float</type>
|
|
<property type="string">/controls/gear/nosegear-steering-cmd-norm</property>
|
|
</signal>
|
|
<signal>
|
|
<type>double</type>
|
|
<interpolation>rotational-deg</interpolation>
|
|
<property type="string">/ai/model/carrier/alpha-angle-deg</property>
|
|
</signal>
|
|
<signal>
|
|
<type>bool</type>
|
|
<property type="string">/controls/panel/custom-switch</property>
|
|
</signal>
|
|
</config>
|
|
</flight-recorder>
|
|
</sim>
|
|
|
|
|
|
Signal Configuration
|
|
--------------------
|
|
Template:
|
|
<signal>
|
|
<type>bool</type>
|
|
<interpolation>angular-deg</interpolation>
|
|
<property type="string">/controls/panel/custom-switch</property>
|
|
</signal>
|
|
|
|
* 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 "<config n=..>" 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__
|
|
|