###############################################################################
#                                                                       #
# RCBgp-20.zip:  GroundProximityWarningSystem gauge for FS2004 aircraft #
#                                                                       #
#   By Rob Barendregt                 Release 2.0         10 febr 2005   #
#                                                                       #
#########################################################################


Introduction
===========-
This freeware GroundProximityWarningSystem (GPWS) gauge for FS2004 can be added
to any aircraft that has RETRACTABLE gear and flaps, and offers the following
main features:
- Clickable switch, with Test/Inhibit function and warning light.
- 8 different warning modes, with all the usual aural warnings, like "Pullup",
  "Sinkrate", "TerrainTerrain", "Windshear" and normal Altitude callouts.
- All modes can be deactivated individually, or even be permanently disabled.
- Fully customiseable per aircraft type, by just editing the gauge with Notepad.

The reason I developed this gauge, is because I was not able to find a freeware
gauge for FS2004 that did the job. Either because of:
- Too limited functionality.
- Not adaptable for a specific aircraft.
  E.g. the "flaps landing configuration" or "max. descent rate" DO depend on
  the aircraft type. 
- Simply doesnot work correct in FS2004.
  Like a gauge that is continuously screaming "Pullup" when I'm trying to land
  with the correct landing configuration.

Based on various information about GPWS systems I found on the Internet, and 
Doug Dawson's great XMLsound gauge (included), I created this gauge in XML, 
which you can fully customise to your own preference.
I don't pretend that this gauge is perfect and 100% realistic as well: it
remains a simplification of a real-life, intelligent GPWS system which
probably is programmed with 10000+ lines of software code.
But you judge for yourself :-)

PLEASE, read this manual carefully, before asking questions or making comments.


Installation
============
1. Extract all files to the MAIN FS2004 folder, using the "Use folder names"
option. This will place each file in it's correct location. 

2. Edit the panel.cfg file of your aircraft(s), to include the gauges.
Under [Window00] (which usually is the main panel window), add:

gauge**=GPWS_Sound!dsd_xml_sound3, 0,0,,, ./sound/GPWS/Sound.ini
gauge**=rcb-gauges!GPWS2_Default, HOR,VERT,82,31

In this definition above, replace the strings:
- "**" by the next free number.
- "HOR" by the Horizontal position of a free spot in the panel.
- "VERT" by the Vertical position of a free spot in the panel.

EXAMPLE: (for the default Boeing747-400)

gauge58=GPWS_Sound!dsd_xml_sound3, 0,0,,, ./sound/GPWS/Sound.ini
gauge59=rcb-gauges!GPWS2_Default, 40,60,62,24    //Reduced size


TIP-1: Use Windows Notepad to edit the panel.cfg files.
       MAKE A BACKUP FIRST !!!
TIP-2: Use the Windows Copy&Paste to avoid typing errors


Functionality
=============
The GPWS gauge has three main states:
- Off.
  When Off (light Red), all other lights/switches are make disabled and made
  invisible. By clicking this Master switch, the gauge state becomes Test.
- Test.
  - The gauge is tested (Test state, light Green), and a testsound is played 
    (WhoopWhoopGlideslope).
  - When finished, the state is set to On (light Off)
  - The Mode switches/lights are made visible, according to their state defined
    in the parameter list in the .xml file (Default: all On).
- On.
  - The GPWS Modes (see below) become active.
  - When the Master switch is clicked again, the gauge is set Off agaun.
  - Red: when Off.

(NOTE: all thresholds and Mode states are easily customiseable in the gauge)

1. Excessive descent rate.
- When VerticalSpeed < 3000 ft/min:  "WhoopWhoopPullup"
- VerticalSpeed between -2000 and -3000 ft/min: "Sinkrate"

2. Excessive terrain closure rate.
- Only entered when gear is up and flaps not in landing position.
- RadioAltitude decreasing: "TerrainTerrain"
- RadioAltitude < 250 ft AND decreasing:  "WhoopWhoopPullup"

3. Loss of altitude after takeoff
- RadioAltitude decreasing AND V/S > 0 ft/min: "TerrainTerrain"
- VerticalSpeed < 0 ft/min: "DontSink"

4. Insufficient terrain clearance.
- Gear is up AND flaps not in landing position: "TooLowTerrain"
- Gear is down AND flaps not in landing position: "TooLowFlaps"
- Gear is up AND flaps in landing position: "TooLowGear"

5. Excessive glideslope deviation.
- Only when gear is down, and flaps in landing position.
- Glideslope (in NAV1) is valid AND more then 1.5 dots below GS: "Glideslope"

6. Excessive banking.
- When the aircraft banks more then 35 degrees: "Bankangle"

7. Windshear.
- The longitudinal windspeed suddenly changes more then 15 knots:
  "WindshearWindshearWindshear"

8. Altitude callouts.
- RadioAltitude decreasing AND RadioAltitude passes heigth (x + y).
  - "x": R-ALT is: 10,20,30,40,50,100,200,300,400,500,1000,2500 or "Minimums".
  - "y": The basic R-ALT of the aircraft when on the ground (default: 18 feet)
  - "Minimums" callout:
    - If the gauge parameter set to 0: uses the FS9-set value for DecisionHeight
      as threshold (default: appr. 330 feet RadioAltitude).
    - If the gauge parameter is NOT 0: use this parameter value as threshold.

Notes:
- Modes 2,3,4,5,7 are only enabled when RadioAltitude is less then parameter
  "GPWS_UpperRALT" (default:900 ft).
  "RadioAltitude" as used in this gauge, is defined as the distance beween the
  earth surface and the gear in lowered position. 
- Modes 1,2,3,4,5,6 remain active while the condition remains.
  While active, the warning sounds of these modes are repeated every 4 sec.
  Also, only one of these modes will give an aural warning at the same time,
  with a priority from mode-1 (highest) to mode-6 (lowest).
  Note that the mode-7 and mode-8 aural warnings are independant of these !!
- When On, the gauge can be in TOGA mode or not:
  - TOGA mode is set (light Amber) when:
    - The aircrafts lifts off the ground at Takeoff or Touch&Go.
    - The gear is being raised when the aircraft is below "GPWS_UpperRALT"
      RadioAltitude (i.e. the GPWS assumes a GoAround).
    When set, modes 1,2,4,5 are disabled.
  - TOGA mode is reset when the aircraft is above "GPWS_UpperRALT"
    When reset, mode 2 is disabled.
  Besides this, the TOGA mode can be toggled manually by clicking the switch/light.
- If your panel allready includes a gauge that partly overlaps with the 
  functionality of this gauge (like: altitude callouts): each one of the modes
  can be deactivated (= made permanentally invisible) individually by editing
  the startup state of that mode in the .xml file.
- This gauge can only be used in 2D-cockpit mode, since the VirtualCockpit
  is defined in the aircraft's .mdl file. Of course you can add it to a [VCockpit]
  window (e.g. with size 1,1), but then you won't be able to see/click the bitmap.
- When added to a 2D-Cockpit panel window, the gauge doesnot function before
  you have made that window visible at least ONCE after loading the aircraft.
- A note about sound volume: the callout sounds are played externally from the
  FS2004 soundsystem, so they are independant of SoundSetting in FS. If you find
  these aural warning way too soft/loud, you can decrease/increase all Sound volumes
  in FS (so these aural warnings become relatively more/less loud).

Each of the GPWS modes has its own state and switch/light. See tooltips on the row
of eight switches/lights. 
These Mode states are:
0: Disabled. (= mode permanently invisible and inoperative)
1: Off (light Red).
   When clicked, the Mode state becomes On (state 4)
2: On/NoSound (light Off, with Red borders)
   The Mode is operational, but without aural warnings.
   When clicked, the sound is set On again (state 4)
3: On/NoSound/Active (light Amber, with Red borders).
   The Mode conditions are true, and the amber warning light is set.
   When clicked, the sound is set On again (state 5).
4: On (light Off).
   The Mode is operational, with aural warnings.
   When clicked, the sound is set off (state 2)
5: On/Active (light Amber).
   The Mode conditions are true, the warning light is set and the aural warning is given.
   When clicked, the sound is set off (state 3)

When the Mode switch is clicked in state4/5, and you KEEP the mousebutton depressed
(for about 0.5 sec), it changes to state2/3 and then immediately to state 1 (Off).
   

HowTo customise the gauge
=========================
A lot of the gauge parameters can be adapted easily to your own preference or
specific aircraft, by editing the gauge with a simple text editor like Windows
Notepad. This specifically applies to parameters like:
- DecisionHeight ("Minimums" callout).
- The base RadioAltitude of the aircraft when on the ground.
  This is determined by the aircrafts gearheight and datum position.
  Examples: 18 ft for a Boeing747, 3 ft for a Cessna.
  This parameter is only relevant for the accuracy of low-altitude callouts.
- The "landing position" flaps-setting of the aircraft.
  Obviously this can be different for every aircraft type, and depends on the
  number of flaps positions and flaps "degrees" per position. 
  Note: this limit is static, and doesnot take airspeed/weight into account.
  In this gauge, "landing position" is defined as any position where the 
  "flap handle" percentage is equal or more than the set threshold.
  You can determine this percentage (default: 64%) as follows:
  - Determine the number of flap positions of your aircraft.
    For each flap position, the "flaps handle position" is a lineair percentage.
    Example for a B747-400:
    - Has 7 flap positions: 0 1 5 10 20 25 30 degrees
    - Which corresponds with "flaps handle": 0 17 33 50 67 83 100 %
    - So for threshold at 64%, "flaps landing position" is "flaps 20" or more.
    Example for a B737-400:
    - Has 9 flap positions: 0 1 2 5 10 15 25 30 40 degrees
    - Which corresponds with "flaps handle": 0 12 25 37 50 62 75 87 100 %
    - So for threshold at 64%, "flaps landing position" is "flaps 25" or more.
- The descent rate threshold before a "Sinkrate" warning is giving. Obviously
  this value is different for a jetfighter and a small GA aircraft :-).
- Repetition/interval time of aural warnings.
- Startup state of the gauge (On or Off) when the gauge is loaded.
- The Modes that are supported by the gauge, and their startup state. 

Here's how to do this:
- In folder \gauges\rcb-gauges\, make a COPY of the file GPWS2_Default.xml, and
  RENAME it to e.g. GPWS2_B737.xml.
- Open this new file with Notepad.
- Find the section "GPWS Parameters", and edit the values to your preference.
  Note: ONLY edit the number, nothing else !!
- Save the file.
- In panel.cfg, use the definition of the new gauge filename:
  Replace the string 
  "rcb-gauges!GPWS2_Default"
  by (for this example)
  "rcb-gauges!GPWS2_B737"

In case you are in doubt what the parameters are: compare the default values
in the .xml file with those mentioned in section "Functionality" above.
Of course there are some logical restrictions on used values. Examples:
- GWPS_UpperAlt should always be higher then GWPS_LowerAlt.
- GWPS_LowerVS should always be more negative then GWPS_UpperVS.

!! NOTE for XML-gauge designers !!
The L:Var gauge parameters are initialised only at startup of the gauge; so you 
can adjust the default values realtime, by, from another XML-gauge,  forcing the
L:vars to another value. 
Or, change parameters in-flight, based on specific flight conditions.


Copyrights and Disclaimer
============================
This package is freeware (NOT: public domain), and is available for your
personal use only.

Without my explicite permission, it may NOT be sold, re-distributed and/or 
uploaded to another website or bulletin board in ANY shape or form.
If you want to bundle this package with your (freeware) aircraft, you may ONLY
do so AFTER my explicite permission and inclusion of the documentation file.

And obviously, installing & using this package is at your own risk. 
However, if you execute the Installation instructions properly, this package
should NOT crash you PC or FS, nor should it have a substantial impact on 
performance. 
Although most of the testing was done on Windows-XP platforms, I don't expect
any problems with other Windows versions (provided FS2004 itself runs OK).


Credits
=======
- Doug Dawson, for his great gauge that allows playing sounds from an XML gauge.
  This gauge (dsd_xml_sound3.gau) is included in this package, and renamed as
  GPWS_Sound.gau to avoid possible future incompatibilities.
- Most of the callouts/warnings are existing soundfiles, but I was unable to
  establish their origin. I think they originated from the FPDA group, but if
  you recognise them as yours, please inform me so I can give you proper credit.


As with all of my gauges, I'm always open for questions, or suggestions for
improvement. But PLEASE !!, read this manual properly before mailing me.

Enjoy, and fly safe .....

Rob Barendregt, The Netherlands
Email: [email protected]


***************************** End Of Readme ********************************