Instrumentation
FlightGear's built-in Instrumentation system simulates basic instruments used in many aircraft and provide their output as Properties to be used e.g. for animating 3D instruments or Canvas instruments.
This article is meant to provide an overview over the instrumentation modules available and their configuration.
General configuration
The instrumentation modules to be available to an aircraft can be selected by the aircraft developer using an instrumentation XML configuration file. This file is called from the Aircraft-set.xml:
<sim>
<instrumentation>
<path>Systems/my-aircraft-instrumentation.xml</path>
</instrumentation>
</sim>
A generic configuration file to be copied and customised can be found in Aircraft/Generic/generic-instrumentation.xml.
Common Elements
Instrument Root Path: typically /instrumentation/name[number]/ e.g. /instrumentation/adf[1]/ for the second ADF.
Electric Power Path (where applicable): typically /systems/electrical/outputs/name[number] e.g. /systems/electrical/outputs/comm[0] for the first comm radio.
| name | typically used for the instrument's root path and, where applicable, electric power path |
| number | used to differentiate between multiple objects using the same name. |
All instruments that inherit AbstractInstrument additionally accept the following config settings:
| power-supply | custom property to be used as the electric power path |
| minimum-supply-volts | minimum electric voltage at which the instrument works |
Instrument Modules
ADF (Automatic Direction Finder)
This instrument simulates an Automatic Direction Finder used for navigating using Non-Directional Beacons.
Configuration
<adf>
<name>adf</name>
<number>0</number>
</adf>
Airspeed Indicator
Configuration
<airspeed-indicator>
<name>airspeed-indicator</name>
<number>0</number>
<total-pressure>/systems/pitot/total-pressure-inhg</total-pressure>
<static-pressure>/systems/static/pressure-inhg</static-pressure>
<has-overspeed-indicator>0</has-overspeed-indicator>
<pressure-alt-source>/instrumentation/altimeter/pressure-alt-ft</pressure-alt-source>
<ias-limit>248.0</ias-limit>
<mach-limit>0.48</mach-limit>
<alt-threshold>13200</alt-threshold>
</airspeed-indicator>
- Total Pressure: see FGproperties/Systems/Pitot
- Static Pressure: see FGproperties/Systems/static
- see also: $FG_ROOT/Docs/README.airspeed-indicator
Altimeter
Configuration
<altimeter>
<name>altimeter</name>
<number>0</number>
<static-pressure>/systems/static/pressure-inhg</static-pressure>
<quantum>0</quantum>
<tau>0</tau>
</altimeter>
- Static Pressure: see FGproperties/Systems/static
- Quantum: TODO
- Tau: TODO
Attitude Indicator (suction-powered)
Configuration
<attitude-indicator>
<name>attitude-indicator</name>
<number>0</number>
<suction>/systems/vacuum/suction-inhg</suction>
<minimum-vacuum>4.5</minimum-vacuum>
<limits>
<spin-thresh>0.8</spin-thresh> <!-- below this gyro spin, instrument will lag, depending on the pitch/roll config below -->
<max-roll-error-deg>40.</max-roll-error-deg>
<max-pitch-error-deg>12.0</max-pitch-error-deg>
</limits>
<gyro>
<spin-up-sec>180.0</spin-up-sec> <!-- ~3 minutes -->
<spin-down-sec>300.0</spin-down-sec> <!-- ~5 minutes -->
</gyro>
</attitude-indicator>
- Note, the
<minimum-vacuum>,<gyro>and<limits>sections are optional. The defaults given in c++ are for demonstration and not realistic. - Suction: see Aircraft systems#Vacuum
Attitude Indicator (Electric)
Configuration
<attitude-indicator-electric>
<name>attitude-indicator</name>
<number>0</number>
<!-- optional configs, given with defaults -->
<config>
<spin-thresh>0.8</spin-thresh> <!-- below this gyro spin, instrument will lag, depending on the pitch/roll config below -->
<max-roll-error-deg>40.</max-roll-error-deg>
<max-pitch-error-deg>12.0</max-pitch-error-deg>
</config>
</attitude-indicator-electric>
Clock
Configuration
<clock>
<name>clock</name>
<number>0</number>
</clock>
Comm Radio
Configuration
<comm-radio>
<name>comm</name>
<number>0</number>
<eight-point-three>0</eight-point-three>
</comm-radio>
- eight-point-three: Setting this to 1 (true) enables a simulation of the newer 8.33 kHz frequency raster
- see also Kx165
DCL GPS
Information (from Source Code)
// dclgps.cxx - a class to extend the operation of FG's current GPS
// code, and provide support for a KLN89-specific instrument. It
// is envisioned that eventually this file and class will be split
// up between current FG code and new KLN89-specific code and removed.
DME (Distance Measuring Equipment)
Configuration
<dme>
<name>dme</name>
<number>0</number>
</dme>
GPS (Global Positioning System)
Configuration
<gps>
<name>gps</name>
<number>0</number>
</gps>
GSDI/GSDA (Ground Speed Drift Angle Indicator)
Configuration
<gsdi>
<name>gsdi</name>
<number>0</number>
</gsdi>
This instrument configuration is not included in generic-instrumentation.xml. See the EC130 for an aircraft implementing this instrument.
Heading Indicator (Directional Gyro)
This is a realistic and highly configrable directional gyro based heading indicator. It can be either electrical or suction driven and supports the gyro based errors like precession drift and transport wander.
Configuration
By default, the instrument is electrically driven and powered by /systems/electrical/outputs/DG[number] (for backwards-compatibility reasons)
<heading-indicator-dg>
<name>heading-indicator</name>
<number>0</number>
</heading-indicator-dg>
Like with most other electrically driven instruments you can explicitely set the power source:
<heading-indicator-dg>
<name>heading-indicator</name>
<number>0</number>
<power-supply>/systems/electrical/outputs/heading-indicator</power-supply>
<minimum-supply-volts>12.0</minimum-supply-volts>
</heading-indicator-dg>
To make it vacuum driven instead:
<heading-indicator-dg>
<name>heading-indicator</name>
<number>0</number>
<suction>/systems/vacuum/suction-inhg</suction>
<minimum-vacuum>4.0</minimum-vacuum> <!-- from this inHg suction on the spin will reach 100% -->
</heading-indicator-dg>
You can optionally configure the instruments error behaviour and limits (to disable, set accordingly). The defaults given in c++ are for demonstration and not realistic so these might be better:
<limits>
<yaw-limit-rate>11.5</yaw-limit-rate> <!-- about 55° bank; +- this yaw rate (deg/s) and the gyro will accumulate errors -->
<g-limit-lower>-0.8</g-limit-lower> <!-- exceeding lower G limit makes gyro drag -->
<g-limit-upper>1.8</g-limit-upper> <!-- exceeding upper G limit makes gyro drag -->
<yaw-error-factor>0.033</yaw-error-factor> <!-- how much error out-of-limits yaw-rate (deg/s) will add -->
<g-error-factor>0.033</g-error-factor> <!-- how much error out-of-limits G-forces will add -->
<g-limit-tumble-factor>1.5</g-limit-tumble-factor> <!-- exceeding g-limit-upper/lower by this factor will make the gyro tumble -->
<g-node>/accelerations/pilot-gdamped</g-node> <!-- optionally read the g force for the limits from here -->
<g-filter-time>10.0</g-filter-time> <!-- damping value for internal g node damping. use 0 to disable -->
<yaw-rate-source>/orientation/yaw-rate-degps</yaw-rate-source> <!-- optional read the yaw-rate from here -->
</limits>
<gyro>
<minimum-spin-norm>0.8</minimum-spin-norm> <!-- min. spin to not let the gyro lag when changing heading -->
<spin-up-sec>180.0</spin-up-sec> <!-- ~3 minutes -->
<spin-down-sec>300.0</spin-down-sec> <!-- ~5 minutes -->
</gyro>
<heading-source>/orientation/heading-deg</heading-source> <!-- alternate source for the heading value -->
The instrument has a built-in damping filter for the g-node, so spikes do not trigger tumbling. If tuning this is not sufficient, you can specify a custom source property.
Runtime configuration The limits and gyro config are exposed to the instruments propoerty tree and can be changed at runtime.
The following proerties are also exposed for runtime configuration:
caged-flag
|
Make the gyro caged. Use this to quickly stop tumbling (or prevent it in the first instance). |
align-deg
|
Should be used by the instruments model to rotate the disc, countering instrument errors. |
latitude-nut-setting
|
Set to the factory setting. At the nut's latitutde (-90 to 90) the precession by earths rotation is countered by a small weight on the gimbal.
|
Heading Indicator (Electric Flux-Gate Compass)
The flux-gate heading indicator always points to magnetic north automatically.
Configuration
<heading-indicator-fg>
<name>heading-indicator-fg</name>
<number>0</number>
</heading-indicator-fg>
- Powered by /systems/electrical/outputs/heading-indicator-fg[number]
Heading Indicator (Suction-Driven)
Configuration
<heading-indicator>
<name>heading-indicator</name>
<number>0</number>
<suction>/systems/vacuum/suction-inhg</suction>
</heading-indicator>
The following proerties are also exposed for runtime configuration:
offset-deg
|
Read/write; Gyro drift is reflected in this property, and can be countered by altering the value. If not initialized at instrument init time, will be synced to "/environment/magnetic-variation-deg" automatically. |
- Note, this is an unrealistic/simple instrument. For better realism options, you should use the "Heading Indicator (Directional Gyro)", see above.
- Suction: see Aircraft systems#Vacuum
King KR 87 Digital ADF (Automatic Direction Finder)
Configuration
<KR-87>
<name>kr-87</name>
<number>0</number>
</KR-87>
Magnetic Compass
Configuration
<magnetic-compass>
<name>magnetic-compass</name>
<number>0</number>
<!-- Deviation table, matches deviation table texture -->
<deviation>
<table>
<entry>
<ind>0</ind>
<dep>1</dep>
</entry>
<entry>
<ind>30</ind>
<dep>3</dep>
</entry>
<!-- ... -->
<entry>
<ind>330</ind>
<dep>-2</dep>
</entry>
</table>
</deviation>
</magnetic-compass>
- Deviation Table: This can be used to simulate Magnetic deviation, e.g. to reflect what's written on a textured deviation card next to the compass. Can also be a property that is beeing read and dynamically calculated (
<deviation>/instrumentation/magnetic-compass/deviation-deg</deviation>), for example to implement powered avionics influencing the magnetic field.
By default the compass simulates a fixed axis compass disc pitched at 0°. A pitched compass disc has an additional reading error.
The compass property tree exposes a /instrumentation/magnetic-compass/pitch-offset-deg prop that can be set to a fixed pitch angle to simulate pitched mounts or manually pitchable compass casings. By dynamically calculating the property, you can offset the plane's /orientation-pitch-deg, essentially nulling the effect. By adding some filters you can simulate a freely pitchable compass disc for a constrained pitch angle; that is: a compass disc mounted on a pivot-pin bearing (like most modern compasses feature). For an example see the filter implementation from the C172p.
The instrument exposes pitch-deg and roll-deg properties to simulate pitching and rolling of the compass disc based on flight forces and fluid viscosity.
You can use them in your 3D-models animation configs.
The damping can be adjusted by setting it in the instrumentation.xml config:
<fluid-viscosity type="double">8.2</fluid-viscosity> (8.2 mm²/s is the value of kerosene and should be good in most cases).
Marker Beacon
Configuration
<marker-beacon>
<name>marker-beacon</name>
<number>0</number>
</marker-beacon>
MK-VIII
Configuration
<mk-viii>
<name>mk-viii</name>
<number>0</number>
</mk-viii>
For more information, see Ground proximity warning system.
Master Reference Gyro
Configuration
<master-reference-gyro>
<name>master-reference-gyro</name>
<number>0</number>
</master-reference-gyro>
for more information, see Lightning T Mk.5 Instruments PDF, p. 4f.
Configuration
<nav-radio>
<name>nav</name>
<number>0</number>
</nav-radio>
Radar Altimeter
Configuration
<radar-altimeter>
<name>radar-altimeter</name>
<number>0</number>
<update-interval-sec>0.1</update-interval-sec>
</radar-altimeter>
Slip/Skid Ball
Configuration
<slip-skid-ball>
<name>slip-skid-ball</name>
<number>0</number>
</slip-skid-ball>
TACAN
Configuration
<tacan>
<name>tacan</name>
<number>0</number>
</tacan>
TCAS
For configuration, see Traffic alert and collision avoidance system#Instrument List
Transponder
Configuration
<transponder>
<name type="string">transponder</name>
<number type="int">0</number>
<minimum-supply-volts type="double">8.0</minimum-supply-volts>
<mode type="int">1</mode>
<auto-ground type="string">/gear/gear/wow</auto-ground>
<encoder-path type="string">/instrumentation/altimeter</encoder-path>
<airspeed-path type="string">/instrumentation/airspeed-indicator/indicated-speed-kt</airspeed-path>
<mach-path type="string">/instrumentation/airspeed-indicator/indicated-mach</mach-path>
<kt70-compatibility type="bool">0</kt70-compatibility>
</transponder>
- Mode
- 0 = Mode A
- 1 = Mode C
- 2 = Mode S
- Auto-Ground: Set property to be used to detect when the ground-bit (mode-S only) should be set
- Encoder/Airspeed/Mach Path: Set instrument properties to feed the transponder
- for more information, see Transponder.
Turn Indicator
Configuration
<turn-indicator>
<name>turn-indicator</name>
<number>0</number>
<gyro>
<spin-up-sec>180.0</spin-up-sec> <!-- ~3 minutes -->
<spin-down-sec>300.0</spin-down-sec> <!-- ~5 minutes -->
</gyro>
</turn-indicator>
- Note, the
<gyro>sections are optional. The defaults given in c++ are for demonstration and not realistic.
Vertical Speed Indicator (VSI)
Configuration
<vertical-speed-indicator>
<name>vertical-speed-indicator</name>
<number>0</number>
<static-pressure>/systems/static/pressure-inhg</static-pressure>
</vertical-speed-indicator>
- Static Pressure: see FGproperties/Systems/static