Runway Awareness and Advisory System

Runway Awareness and Advisory System

Started in	08/2014
Description	System to give advisories about runways
Contributor(s)	onox
Status	Under active development as of 08/2014
Subforum	http://forum.flightgear.org/viewtopic.php?f=66&t=21266

Features

The Runway Advisory and Awareness System can give a number of advisories:

Feature	RAAS
On runway and alignment < 20 degrees
On short runway, announcing remaining distance
On runway (reminder)	Not done
Approaching runway (on ground) when groundspeed < 40 knots
Approaching runway (airborne) when distance < 3 nm, alignment < 20 degrees, AFE is 300 - 750 ft
Approaching runway (airborne), announcing available distance
Distance remaining (during landing) when AGL < 100 feet and groundspeed > 40 knots
Distance remaining after rejected takeoff, past 50 % of runway and 7 knots below maximum groundspeed
Runway end when distance remaininig < 100 feet or 30 meters and groundspeed < 40 knots
Taxiway takeoff when groundspeed > 40 knots while not on runway	Not done

https://www.youtube.com/watch?feature=player_detailpage&v=59ymnKUi49A#t=117

https://www.youtube.com/watch?feature=player_detailpage&v=0jkRhIMZAZo#t=171

Aircraft

Currently RAAS is only used in the 747-8i.

Tip  Ask the developer of your favorite aircraft if you want it to support RAAS.

TODO

Use *.groundnet.xml to detect when the aircraft is near a holding point to more accurately emit "approaching-runway" signal	Not done
Allow remaining-distance to be emitted while aircraft is not on ground	Not done
Allow to choose between 450 - 550 ft or 350 - 450 ft suppression of approaching-runway (in air)	Not done
Require climb rate to be < 450 ft/min for remaining-distance	Not done
Require the presence of a mk-viii (GPWS) module	Not done

Signals

In order to give these advisories, callbacks for a number of signals can be registered to two announcers. Depending on the current mode of each announcer they will emit certain signals:

Takeoff announcer

Mode	Emitted signals
taxi-and-takeoff	approaching-runway, on-runway, on-short-runway
takeoff	on-runway, on-short-runway
approach	approaching-runway, approaching-short-runway

Landing announcer

Mode	Emitted signals
takeoff	remaining-distance, vacated-runway
landing	remaining-distance, landed-runway, vacated-runway, landed-outside-runway

Installation

In case logger.nas and runway_announcer.nas have not been added to FlightGear's fgdata project yet, add the following to the beginning of the <nasal> element in your aircraft's -set.xml file:

<logger>
    <file>Aircraft/$YOUR_AIRCRAFT_FOLDER/Nasal/logger.nas</file>
</logger>
<runway>
    <file>Aircraft/$YOUR_AIRCRAFT_FOLDER/Nasal/runway_announcer.nas</file>
</runway>

Add the following to the <nasal> element below the previous two:

<file>Aircraft/$YOUR_AIRCRAFT_FOLDER/Nasal/runway.nas</file>

Add the file runway.nas to your aircraft's Nasal folder. This file is aircraft specific and needs to be constructed using the steps below.

Nasal/runway.nas

The following example listens to /gear/on-ground and overrides a number of properties of the takeoff_config object so that it can be used for large airliners.

Step 1 of 3: Functions

First, create a number of functions to format and print messages:

# Copyright (C) 2014  onox
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.

var copilot_say = func (message) {
    setprop("/sim/messages/copilot", message);
    logger.info(sprintf("Announcing '%s'", message));
};

var on_short_runway_format = func {
    var distance = getprop("/sim/runway-announcer/short-runway-distance");
    return sprintf("On runway %%s, %d %s remaining", distance, takeoff_config.distances_unit);
};

var approaching_short_runway_format = func {
    var distance = takeoff_announcer.get_short_runway_distance();
    return sprintf("Approaching runway %%s, %d %s available", distance, takeoff_config.distances_unit);
};

var remaining_distance_format = func {
    return sprintf("%%d %s remaining", landing_config.distances_unit);
};

Tip  You might want to replace copilot_say().

Step 2 of 3: Announcers

Second, create configuration objects, override some of their parameters, create the announcers, and then connect the various signals to callbacks:

var takeoff_config = { parents: [runway.TakeoffRunwayAnnounceConfig] };

# You can modify this setting from a GUI during runtime
takeoff_config.distances_unit = "meter";

# Will cause the announcer to emit the "on-runway" signal if the
# aircraft is at most 15 meters from the center line of the runway
takeoff_config.distance_center_line_m = 15;

# Let the announcer emit the "approaching-runway" signal if the
# nose of the aircraft comes within 120 meters of the runway
takeoff_config.distance_edge_max_m = 150;

var landing_config = { parents: [runway.LandingRunwayAnnounceConfig] };
landing_config.distance_center_nose_m = 30;

# You can modify this setting from a GUI during runtime
landing_config.distances_unit = "meter";

# Create announcers
var takeoff_announcer = runway.TakeoffRunwayAnnounceClass.new(takeoff_config);
var landing_announcer = runway.LandingRunwayAnnounceClass.new(landing_config);

var stop_announcer    = runway.make_stop_announcer_func(takeoff_announcer, landing_announcer);
var switch_to_takeoff = runway.make_switch_to_takeoff_func(takeoff_announcer, landing_announcer);

takeoff_announcer.connect("on-runway", runway.make_betty_cb(copilot_say, "On runway %s", switch_to_takeoff));
takeoff_announcer.connect("on-short-runway", runway.make_betty_cb(copilot_say, on_short_runway_format, switch_to_takeoff));
takeoff_announcer.connect("approaching-runway", runway.make_betty_cb(copilot_say, "Approaching runway %s"));
takeoff_announcer.connect("approaching-short-runway", runway.make_betty_cb(copilot_say, approaching_short_runway_format));

landing_announcer.connect("remaining-distance", runway.make_betty_cb(copilot_say, remaining_distance_format));
landing_announcer.connect("vacated-runway", runway.make_betty_cb(copilot_say, "Vacated runway %s", stop_announcer));
landing_announcer.connect("landed-runway", runway.make_betty_cb(copilot_say, "Touchdown on runway %s"));
landing_announcer.connect("landed-outside-runway", runway.make_betty_cb(nil, nil, stop_announcer));

Step 3 of 3: Listeners

Finally, set up a listener to detect when the aircraft is on the ground and when it is airborne:

# Depending on whether the aircraft is on the ground or not, it will start, stop, or change the modes of the announcers
var set_on_ground = runway.make_set_ground_func(takeoff_announcer, landing_announcer);

var init_announcers = func {
    setlistener("/gear/on-ground", func (node) {
        set_on_ground(node.getBoolValue());
    }, startup=1, runtime=0);
};

setlistener("/sim/signals/fdm-initialized", func {
    var timer = maketimer(5.0, func init_announcers());
    timer.singleShot = 1;
    timer.start();
});

Note  In this example the /gear/on-ground property is used to detect whether the aircraft is on the ground or in the air. Make sure to use a <logic> element in a <autopilot> XML file to set this to true or false depending on your gears' wow values.

Note  It is your responsibility to start and stop the announcers and to set the correct modes. Therefore it is necessary to connect to signals like landed-outside-runway and vacated-runway, even if they appear to be useless for your specific aircraft. The example of runway.nas above already does this for you.

Configuring the announcers

The configuration object takeoff_config has a number of properties with default values. These properties can be modified if you want to change when certain signals are emitted. For example, in the example of runway.nas above, distance_center_line_m and distance_edge_max_m where overridden for large airliners. The defaults are:

diff_runway_heading_deg: 20,
# Difference in heading between runway and aircraft in order to
# get an announcement that the aircraft is on the runway for takeoff
# or approaching while airborne.

diff_approach_heading_deg: 40,
# Maximum angle at which the aircraft should approach the runway.
# Must be higher than 0 and lower than 90.

distance_center_line_m: 10,
# The distance in meters from the center line of the runway

distance_edge_min_m: 20,
distance_edge_max_m: 80,
# Minimum and maximum distance in meters from the edge of the runway
# for announcing approaches.

nominal_distance_takeoff_m: 3000,
# Minimum distance in meters required for a normal takeoff. If
# remaining distance when entering the runway is less than the distance
# required for a normal takeoff, then the on-short-runway instead of
# on-runway signal will be emitted.

nominal_distance_landing_m: 2000,
# Minimum distance in meters required for a normal landing. If
# runway length when approaching the runway is less than the distance
# required for a normal landing, then the approaching-short-runway
# instead of approaching-runway signal will be emitted.

distances_unit: "meter",
# The unit to use for the remaining distance of short runways. Can
# be "meter" or "feet".

groundspeed_max_kt: 40,
# Maximum groundspeed in knots for approaching runway callouts

approach_afe_min_ft: 300,
approach_afe_max_ft: 750,
# Minimum and maximum altitude Above Field Elevation in feet. Used to
# decide whether to announce that the aircraft is approaching a runway.

approach_distance_max_nm: 3.0,
# Maximum distance in nautical miles of the aircraft to the
# approaching runway

The same applies to the configuration object landing_config:

distances_meter: [100,  300,  600,  900, 1200, 1500],

distances_feet:  [500, 1000, 2000, 3000, 4000, 5000],

distances_unit: "meter",
# The unit to use for the remaining distance. Can be "meter" or "feet"

distance_center_nose_m: 0,
# Distance from the center to the nose in meters

diff_runway_heading_deg: 20,
# Difference in heading between runway and aircraft in order to
# detect the correct runway on which the aircraft is landing.

groundspeed_min_kt: 40,
# Minimum groundspeed in knots for remaining distance callouts

agl_max_ft: 100,
# Maximum AGL in feet for remaining distance callouts