Route Manager internals

Note  Whenever possible, please refrain from modeling complex systems, like an FDM, autopilot or Route Manager with Nasal. This is primarily to help reduce Nasal overhead (especially GC overhead). It will also help to unify duplicated code. The FlightGear/SimGear code base already contains fairly generic and efficient systems and helpers, implemented in C++, that merely need to be better generalized and exposed to Nasal so that they can be used elsewhere. For example, this would enable Scripted AI Objects to use full FDM implementations and/or built-in route manager systems. Technically, this is also the correct approach, as it allows us to easily reuse existing code that is known to be stable and working correctly, . For details on exposing these C++ systems to Nasal, please refer to Nasal/CppBind. If in doubt, please get in touch via the mailing list or the forum first.

Internal documentation for people wanting to work with the route manger. This page should be read in conjunction with the equivalent GPS internals page.

The major change in the route manager is that waypoints are no longer popped when they are sequenced. Instead, the current waypoint index is incremented. This change is necessary to allow the route manager to function as the flight plan backend of real-world GPS and navigation devices, which, for example, show previous waypoints and route on a moving map display.

Since most real navigation systems deal in legs, not waypoints, the active leg is defined as that between waypoints[currentWpt - 1] and waypoints[currentWpt]. This is why current waypoint property is initialised to '1' on activating a route, and why activating a route adds the current location (usually the departure runway) as waypoint 0 - taken together, the user and GPS see the expected first leg from the runway to the first waypoint they entered.

Also see, Nasal Flightplan

Activation

Activating a route currently validates any supplied data, and fills out missing data (where possible). There is the potential to hook into Nasal callbacks in this area, if people request that as a feature. As the route-manager evolves into a general flight-plan manager, activation will probably be associated with other functions as well - most importantly, with filing a flight plan with ATC system, and hence making it available over the multi-player network to human or AI ATC providers.

Sequencing

The route-manager expect an external navigation system (i.e, the GPS instrument, in practice) to control sequencing, since various control modes affect precisely when sequencing occurs. In particular, turn anticipation and overflight waypoints change the behaviour in this area. To avoid duplicate or complicating the code, the route manager delegates all policy to the GPS.

When the route-manager is commanded to sequence, it emits signals as necessary (see below), updates the current waypoint index and compatibility waypoint data, and generally performs any internal house-keeping it requires.

Properties

current-waypoint

Index of the current (active) waypoint in the route array. In an active route, this will never be zero, since there must always be valid previous ('from') waypoint. Setting this value causes a waypoint jump, eg when executing a direct-to operation from the GPS logic; in general the value should only be set under exceptional, user-directed circumstances.

Signals

Various signal properties exist at route-manager/signals. At present, they are:

sequenced

Emitted when the current waypoint increments to the next step. At present this is not emitted for 'jumps', eg when the GPS does a direct-to command.

finished

Emitted when last waypoint is reached, i.e an attempt is made to sequence when the current waypoint is the final one.

edited

Emitted when the user (via the GUI) or some other system modifies the route, eg by adding or removing waypoints. This exists to allow other places observing the route to re-synchronize their copies of any waypoint data.

Enroute data

At present, the route manager records and computes some standard data related to a 'flight' (and in the future, could generate a logbook based upon this). Notably it maintains an 'airborne' flag, and uses this to provide elapsed time enroute. Once the waypoint format is updated to store speeds better, the potential exists (in C++ or Nasal) to compute an accurate time remaining enroute value, and to estimate real progress relative to the flight plan.

(This area is very much unfinished, since there's no clear benefit to doing the computations in C++, and it depends heavily on aircraft-specific performance data)

Compatibility

To keep older aircraft and instruments work, the properties wp[0], wp[1] and wp-last are maintained, implicitly updated to refer to the current waypoint, the next waypoint and the final waypoint.