Ground proximity warning system
Ground Proximity Warning System (GPWS) is a system designed to alert pilots if their aircraft is in immediate danger of flying into the ground or an obstacle. Another common name for such a system is Ground-Collision Warning System (GCWS). More advanced systems, providing additional protection based on GPS position and a terrain database, are known as Enhanced Ground Proximity Warning Systems (EGPWS).
The EGPWS provided by FlightGear emulates the MK VIII made by Honeywell Inc. It provides all inputs and outputs of the original hardware. Also the configuration categories and their encodings are modeled to match the original equipment.
Since FG2018.1 the simulation was extended with optional support for Airbus-specific callouts, which would normally not be supported by the real-world MK VIII hardware unit (which is not intended to be installed on Airbus aircraft).
Features
Warnings
The module provides warnings for different alerting modes:
- Mode 1: Excessive Descent Rate
- Provides 'Sink rate!' and 'Pull up!' alerts based on descent rate at low radio altitudes (below 2500').
- Mode 2: Excessive Terrain Closure Rate
- Provides 'Pull up!' and 'Terrain!' callouts around rising terrain.
- Mode 3: Altitude Loss After Takeoff
- Provides alerts against altitude loss after takeoff (or a go-around). Losing altitude triggers a 'Don't sink!' alert.
- Mode 4: Unsafe Terrain Clearance
- Provides alerts against insufficient clearance, based upon the aircraft configuration and flight phase (takeoff, cruise, approach), and independent of terrain closure rate (i.e situations that modes 1 & 2 would not alert). Alerts include 'Too low - terrain!', 'Too low - gear!' and 'Too low - flaps!'. Also protects against a gear-up landing or approach without flaps in the landing configuration.
- Mode 5: Excessive Deviation Below Glideslope
- Provides 'Glideslope!' alerts when deviating below a glideslope while established on a localizer.
- Mode 6: Advisory Callouts
- Provides callouts based on the specified decision-height and radio altitude. This includes a 'Minimums' alert based upon the decision-height, and callouts while descending through various radio altitudes (1000', 500', 200', 100', 50', 40', 30', 20' and 10'). Also provides a 'Bank angle' alert based upon excessive aircraft roll.
- Mode 7: Windshear Protection
- Windshear protection is currently not implemented.
Other
- Self-test
- Triggers all warnings enabled for the specific plane one by one.
- Status display
- Shows module configuration and status.
Add to an Aircraft
Instrument List
Add the device to your plane by adding it to the sim/instrumentation section (usually in a separate instrumentation.xml file).
Example:
<PropertyList>
<sim>
<instrumentation>
<mk-viii>
<name>mk-viii</name>
<number>0</number>
</mk-viii>
</instrumentation>
</sim>
</PropertyList>
Usually planes only have a single GPWS installed - so using multiple instances wouldn't be too common.
<Plane>-set.xml file
Configuration parameters are stored in a different section. Add the following XML template to the instrumentation section of the plane's ...-set.xml file. Do not mix up this section with the one above (section above was within the <sim> tag, this section is outside the <sim> tag).
Notes:
- The values in the <configuration-module> section (below) list the module's default. You can omit specific <category-n> lines unless you need to change the default.
- All configuration categories require valid settings. If you do explicitly configure a category to change the default, you must provide a valid value. See sections below for valid options.
- Do not omit the <serviceable>true</serviceable> part...
XML Template
<PropertyList> <!-- here: other data from ...-set.xml --> <instrumentation> <mk-viii> <!-- http://wiki.flightgear.org/index.php/GPWS --> <serviceable>true</serviceable> <!-- EGPWS_ENABLE --> <configuration-module> <category-1> 0 </category-1> <!-- AIRCRAFT_MODE_TYPE_SELECT --> <category-3> 2 </category-3> <!-- POSITION_INPUT_SELECT --> <category-4> 13 </category-4> <!-- ALTITUDE_CALLOUTS --> <category-5> 0 </category-5> <!-- AUDIO_MENU_SELECT --> <category-6> 1 </category-6> <!-- TERRAIN_DISPLAY_SELECT --> <category-7> 124 </category-7> <!-- OPTIONS_SELECT_GROUP_1 --> <category-8> 2 </category-8> <!-- RADIO_ALTITUDE_INPUT_SELECT --> <category-9> 3 </category-9> <!-- NAVIGATION_INPUT_SELECT --> <category-10> 6 </category-10> <!-- ATTITUDE_INPUT_SELECT --> <category-13> 7 </category-13> <!-- INPUT_OUTPUT_DISCRETE_TYPE_SELECT --> <category-14> 0 </category-14> <!-- AUDIO_OUTPUT_LEVEL --> </configuration-module> <inputs> <!-- Module I/O --> <arinc429> <decision-height-ncd> false </decision-height-ncd> <decision-height> 200 </decision-height> </arinc429> </inputs> <speaker> <!-- Speaker Configuration --> <max-dist> 2 </max-dist> <!-- Max. distance where speaker is heard --> <reference-dist> 1 </reference-dist> <!-- Distance to pilot --> <volume> 0.4 </volume> <!-- Volume at reference distance --> </speaker> <voice> <file-prefix type="string">Sounds/mk-viii/</file-prefix> <!-- sound file path and prefix --> </voice> </mk-viii> </instrumentation> </PropertyList>
The example above provides the decision height as a fixed value. Since this value is an input, you can also provide this value at run-time instead - e.g. depending on whether an ILS or visual approach is flown.
Unimplemented Categories
Some configuration categories are currently not implemented. The following elements are therefore omitted in the XML template:
<category-2> 1 </category-2> <!-- AIR_DATA_INPUT_SELECT --> <category-11> 2 </category-11> <!-- HEADING_INPUT_SELECT --> <category-12> 0 </category-12> <!-- WINDSHEAR_INPUT_SELECT --> <category-15> 0 </category-15> <!-- UNDEFINED_INPUT_SELECT_1 --> <category-16> 0 </category-16> <!-- UNDEFINED_INPUT_SELECT_2 --> <category-17> 0 </category-17> <!-- UNDEFINED_INPUT_SELECT_3 -->
Electric Power
The mk-viii module needs (virtual) electric power. The module also simulates the behavior of the original hardware device when applying over or under voltage - i.e. it withstands short periods of too low or high voltage (within certain limits). Supply a nominal value of 28 volts. Usually you'll provide power via Nasal by connecting the module to the electrical bus simulation. If you're plane doesn't provide such a simulation you can also configure a fixed value (i.e. 28) to the following property:
/systems/electrical/outputs/<name>[<num>]
where <name> and <num> match the values you specified in the instrument list, e.g. for <name>=mk-viii and <num>=0
/systems/electrical/outputs/mk-viii[0]
Configuration
Hints
- Trigger the self-test to check if the EGPWS is enabled and to check which callouts are enabled for this airplane. Set the property /instrumentation/mk-viii/inputs/discretes/self-test to true to trigger the self-test. Enabling this input for 2 seconds triggers short self-test, enabling it for at least 5 seconds triggers a full self-test. The plane must be on ground and stopped, otherwise the self-test is inhibited.
- You can test EGPWS configuration without restarting FlightGear by modifying the configuration values in the Property Browser manually and then forcing the EGPWS to reload the configuration by toggling the plane's electrical power (OFF-ON).
Configuration Categories
Aircraft Mode Select
<category-1> 0 </category-1> <!-- AIRCRAFT_MODE_TYPE_SELECT -->
This is the device's main configuration setting. It selects the envelops for allowed speeds and minimum heights for all EGPWS modes. The envelops are configured by selecting an entire set of configuration values. This simplifies the configuration, however, new airplane types may require to modify the mk-viii sources in order to support an appropriate configuration set.
| category-1 | Aircraft Type Description | Type | Gear down at 500ft
when slower than |
Flaps down at | Max airspeed
flaps/gear down* |
Min Runway Length |
|---|---|---|---|---|---|---|
| (default) 0 | Fast turboprop, normal flap deployment | T6 | 178 knots | 170 ft / 150 knots | 250 / 290 knots | 2000m |
| 1 | Fast turboprop, delayed flap deployment | T8 | 178 knots | 150 ft / 148 knots | 250 / 290 knots | 2000m |
| 2 | Fast turboprop (old GPWS emulation) | T5 | 178 knots | 200 ft / 148 knots | 250 / 290 knots | 2000m |
| 3 | Slow turboprop, normal flap deployment | T7 | 148 knots | 170 ft / 120 knots | 180 / 200 knots | 2000m |
| 4 | Slow turboprop, delayed flap deployment | T9 | 148 knots | 150 ft / 118 knots | 180 / 200 knots | 2000m |
| 254 | Fast, heavy turbofans (jets), requiring 3500m runways | T1 | 190 knots | 245 ft / 159 knots | 250 / 290 knots | 3500m |
| 255 | Fast turbofans (jets), requiring 2000m runways | T1 | 190 knots | 200 ft / 159 knots | 250 / 290 knots | 2000m |
* When maximum gear down/flaps down airspeeds are exceeded for at least 60 seconds the EGPWS triggers a fault and assumes the gear down / flaps down inputs to be invalid.
Position Input Select
<category-3> 2 </category-3> <!-- POSITION_INPUT_SELECT -->
Some warning modes require the plane's GPS position, e.g. in order to find the nearest runway in its internal database to provide correct height callouts.
- 1: GPS data is supplied to the inputs externally (e.g. NASAL script). You need to provide input to
- /instrumentation/mk-viii/inputs/arinc429/gps-altitude
- /instrumentation/mk-viii/inputs/arinc429/gps-latitude
- /instrumentation/mk-viii/inputs/arinc429/gps-longitude
- /instrumentation/mk-viii/inputs/arinc429/gps-vertical-figure-of-merit
- 2 (default): GPS data uses internal source (enables a hard-wired connection within the simulator)
Altitude Callouts
<category-4> 13 </category-4> <!-- ALTITUDE_CALLOUTS -->
Select a set of callouts for the approach phase.
| category-4 | Callouts |
|---|---|
| 0 | Minimums, SMART_500, 200, 100, 50, 40, 30, 20, 10. "SMART_500" limits the 500ft callout to non-precision approaches (when no glideslope is captured or g/s is at least 2 dots above/below). |
| 1 | Minimums, SMART_500, 200 |
| 2 | Minimums, SMART_500, 100, 50, 40, 30, 20, 10 |
| 3 | Minimums, SMART_500 |
| 4 | Minimums, 200, 100, 50, 40, 30, 20, 10 |
| 5 | Minimums, 200 |
| 6 | Minimums, 100, 50, 40, 30, 20, 10 |
| 7 | All call-outs disabled. |
| 8 | Minimums. All altitude callouts disabled. |
| 9 | Minimums, 500, 200, 100, 50, 40, 30, 20, 10 |
| 10 | Minimums, 500, 200 |
| 11 | Minimums, 500, 100, 50, 40, 30, 20, 10 |
| 12 | Minimums, 500 |
| (default) 13 | Minimums, 1000, 500, 400, 300, 200, 100, 50, 40, 30, 20, 10 (This option should match Boeing and most other airliners, except Airbus.) |
| 14 | Minimums, 100 |
| 15 | Minimums, 200, 100 |
| 100 | FIELD_500. Provides “500” callout at an altitude 500ft above the actual runway altitude. |
| 101 | FIELD_500_ABOVE. Provides “500 above” callout at an altitude 500ft above the actual runway altitude. |
| The options below are not available with the original mk-viii hardware unit. They were added for the FlightGear simulation (with FG 2018.1 and newer) to support typical GPWS callouts of Airbus aircraft. | |
| 1000 | Above_100, Minimums, 2500, 1000, 500, 400, 300, 200, 100, 50, 40, 30, 20, 10, Retard (This option should match most Airbus aircraft.) |
| 1001 | Minimums, 2500, 1000, 500, 400, 300, 200, 100, 50, 40, 30, 20, 10, Retard |
| 1002 | Minimums, 2500, 1000, 500, 400, 300, 200, 100, 50, 40, 30, 20, 10 |
| 1010 | Above_100, Minimums, 1000, 500, 400, 300, 200, 100, 50, 40, 30, 20, 10, Retard |
| 1011 | Minimums, 1000, 500, 400, 300, 200, 100, 50, 40, 30, 20, 10, Retard |
The 500ft callout is available in four options:
- "SMART_500" limits the 500ft callout to non-precision approaches (when no glideslope is captured or g/s is at least 2 dots above/below).
- "FIELD_500" configures the 500ft callout to consider the altitude above the actual runway altitude (instead of the current radio altitude).
- "FIELD_500_ABOVE" is like "FIELD_500", but triggers a "500 above" callout (instead of "500").
- "500" enables the standard callout, i.e. triggers whenever the radio altimeter reports a current altitude of 500ft.
Audio Menu Select
<category-5> 0 </category-5> <!-- AUDIO_MENU_SELECT -->
Configure retractable or fixed gear aircraft.
- 0 (default): Configured for retractable gear aircraft. „Too low - gear!“ and „Too low - flaps!“ callouts enabled.
- 2: Configured for fixed gear aircraft. „Too low, flaps!“ callout enabled.
Terrain Collision Warning
<category-6> 1 </category-6> <!-- TERRAIN_DISPLAY_SELECT -->
Enable/disable terrain collision warnings.
- 1 (default): Terrain collision warnings enabled.
- 2: Terrain collision warnings disabled.
Options Select
<category-7> 124 </category-7> <!-- OPTIONS_SELECT_GROUP_1 -->
Enable/disable bank angle and steep approach warnings and select flap type.
- bit 0: not implemented
- bit 1: flap reversal.
- 0 = normal logic (default)
- 2 = invert logic when detecting extended/retracted flaps
- bit 2: bank angle alert
- 0 = bank angle alert disabled
- 4 = enabled (default)
- bit 3-5: not implemented but enabled by default
- bit 6: steep approach
- 0 = steep approach warning disabled
- 64 = steep approach warning enabled (default)
- bit 7: not implemented
Example: Value 68 (= 64+ 4) enables bank angle, steep approach alert and normal flap logic.
Note: Default is 124. This also enables additional feature bits (which are currently unsupported).
Radio Altitude Input Select
<category-8> 2 </category-8> <!-- RADIO_ALTITUDE_INPUT_SELECT -->
Select radio altimeter input source.
- 2 (default): Altitude source is property "/position/altitude-agl-ft". Works for all FDMs - but this is not precise enough to drive useful 20ft and 10ft callouts (see below).
- 3: Altitude source is "/position/gear-agl-ft". Very precise altitude of gear-above-ground - but only available for planes with YASim FDM (so far).
- 4: Altitude source is "/instrumentation/radar-altimeter/radar-altitude-ft". A radar altimeter instrument must be installed.
Hint: Most simulator altitude properties refer to the plane's center (of gravity) - but not to the altitude of the main gear. A radar altimeter on a real plane is always calibrated to the gear, hence provides precise information (yes, only within a certain degree of the angle of attack...). Without a precise altitude source the final callouts before touch down, especially 20ft and 10ft, make no sense or may not even work - very annoying, since most aircraft require a final nose up flare at about 20ft. So precise callouts are very welcome. Using a radar altimeter instrument is recommended since this is most realistic - and it can (and should) be calibrated to the main gear. See ...(TODO)... for a configuration example.
Note: This configuration category is supported beginning with FlightGear 2.2.
<category-9> 3 </category-9> <!-- NAVIGATION_INPUT_SELECT -->
Enable/disable glideslope warnings.
- 0: localizer input disabled (disables glideslope warnings)
- 3 (default): localizer input enabled (enables glideslope warning)
- Note: By default, the module is hard-wired to the NAV0 receiver for glideslope warnings, i.e. in order to use the NAV1 receiver you need to update the inputs externally through nasal, etc (see Module I/O).
Attitude Input Select
<category-10> 6 </category-10> <!-- ATTITUDE_INPUT_SELECT -->
Select attitude input source.
Note: This configuration category is implemented for the latest FlightGear version only (GIT sources as of '2010-07-30' or newer).
- 2: Read data from attitude instrument (requires vacuum system to work).
- 6 (default): Read data from hard-wired connection within simulator.
Input and Output Configuration
<category-13> 7 </category-13> <!-- INPUT_OUTPUT_DISCRETE_TYPE_SELECT -->
This configuration value configures the behavior of the module's outputs, usually connected to warning lamps in the cockpit, and enables inputs, which should be connected to cockpit switches.
| Output Lamp Configuration | Input Switch Configuration
When enabled, appropriate inputs are supplied to the module (e.g. inputs should be connected to cockpit switches). | ||||
| category-13 | Output
Format * |
Lamp
Flashing ** |
GPWS Inhibit
Switch Enabled |
Momentary Flap
Override Switch Enabled |
Alternate Steep
Approach Switch Enabled |
| 0 | warning | steady | x | x | |
| 1 | alert | steady | x | x | |
| 2 | warning | steady | x | x | x |
| 3 | alert | steady | x | x | x |
| 4 | warning | flashing | x | x | x |
| 5 | alert | flashing | x | x | x |
| 6 | warning | steady | x | x | |
| (default) 7 | alert | steady | x | x | |
| 254 | warning | steady | x | x | |
| 255 | warning | steady | x | x | |
* Output Format: 'alert': caution conditions trigger the alert output lamp, otherwise caution conditions triggers warning output.
** Lamp Flashing: Selects whether output lamps should flash or be lit steadily when warning/alert/caution is triggered.
Audio Output Level
<category-14> 0 </category-14> <!-- AUDIO_OUTPUT_LEVEL -->
Basic audio configuration.
| category-14 | Audio Relative
Volume |
|---|---|
| (default) 0 | 0 dB |
| 1 | -6 dB |
| 2 | -12 dB |
| 3 | -18 dB |
| 4 | -24 dB |
Speaker Configuration
The audio speaker can be configured by modifying the properties beneath /instrumentation/mk-viii/speaker. These properties match the xmlsound properties.
For additional information, check out $FG_ROOT/Docs/README.xmlsound.
Voice Configuration
The GPWS uses a fixed default voice. The voice can be changed by providing custom voice samples and providing a different path and filename prefix.
<voice>
<file-prefix type="string">Sounds/mk-viii/</file-prefix>
<!-- sound file path and prefix -->
</voice>
Note:
- The voice configuration option is supported by FlightGear 2.3.0 and newer.
Advanced
This section lists some advanced configuration and integration options.
Example
You may want to check the FG implementation of the Boeing 777-200 aircraft for an extensive example of GPWS integration. This plane provides a Nasal GPWS wrapper for the mk-viii module and implements all standard (Boeing) buttons and displays, i.e.:
- Self-test push button
- Glide-slope warning disable button (e.g. to silence warnings during a visual approach)
- Flap and gear override buttons (e.g. to silence flap/gear warnings in emergency situations, like stuck gear etc).
- Terrain/GPWS disable buttons
- GPWS connection to master-warning light.
- GPWS connection to PFD (to display "PULL UP").
Module I/O
- The inputs and outputs match those of the real device and are made available through the FlightGear property tree.
- Input monitoring is implemented. The loss of inputs required for a particular function is annunciated through the GPWS INOP and/or TERR FAIL lamps.
- The "Present Status" function, which enumerates current faults and lists other device details, is implemented.
- Connect outputs to cockpit instruments, e.g. the EGPWS alert and glideslope outputs to the appropriate warning lamps.
- Connect the /instrumentation/mk-viii/inputs/discretes/self-test property to the GPWS self-test button in your cockpit. Testing GPWS operation may be part of the preflight check-list.
- To assist the aircraft designer with the installation of the EGPWS, most inputs are connected to standard FlightGear properties by default. When an input feeder (...-ncd property) is set to true, the input it is associated with is automatically updated, using a standard FlightGear property. When the ...-ncd property it is set to false, its associated input must be manually updated every frame, using a Nasal script or some other mechanism.
- The aircraft's decision height needs to be configured when the 'Minimums' warning is enabled. You can provide the decision height as fixed input value to /instruments/mk-viii/inputs/arinc429/decision-height:
<arinc429> <decision-height-ncd> false </decision-height-ncd> <decision-height> 200 </decision-height> </arinc429>
Module Status
The original MK VIII supports an RS232 interface to read the module status. Since FlightGear does not support RS232 interfaces, all data is printed to the standard output. Trigger /instrumentation/mk-viii/inputs/discretes/rs-232/present-status to print the current module configuration and status:
EGPWC CONFIGURATION
PART NUMBER: 965-1220-000
MOD STATUS: N/A
SERIAL NUMBER: N/A
APPLICATION S/W VERSION: 2.0.0
TERRAIN DATABASE VERSION: 2.0.0
ENVELOPE MOD DATABASE VERSION: N/A
BOOT CODE VERSION: 2.0.0
CURRENT FAULTS
NO FAULTS
CONFIGURATION:
AIRCRAFT TYPE = 0
AIR DATA TYPE = 1
POSITION INPUT TYPE = 2
CALLOUTS OPTION TYPE = 13
AUDIO MENU TYPE = 0
TERRAIN DISPLAY TYPE = 1
OPTIONS 1 TYPE = 124
RADIO ALTITUDE TYPE = 2
NAVIGATION INPUT TYPE = 3
ATTITUDE TYPE = 6
MAGNETIC HEADING TYPE = 2
WINDSHEAR INPUT TYPE = 0
IO DISCRETE TYPE = 7
VOLUME SELECT = 0