GPS 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.

GPS internals

Introduction

Although the code is named 'GPS', it is intended to be used to support a wide range of related devices, such as INS or FMS systems. A generic name such as 'navigation computer' might be better, but renaming the properties and code at this point would be awkward.

The core GPS code attempts to provide simple, building block functions that can be easily composed in Nasal or XML to model the behaviour of particular real world instruments. This page should be read in conjunction with the route manager internals page.

It is assumed the reader is familiar with using the GPS in flight, as detailed in the user's manual.

The GPS is a work in progress - if you have problems with a feature, or think functionality is missing, don't work around the problem yourself, get in touch. It's far better to support a feature used by 50% of real-world devices, in the core code, than to duplicate it many times over. (Of course, if the feature is only found in one real world device, it may not be added to the core code)

Concepts

The code computes basic positional information, derived from FG's knowledge of the aircraft position (i.e the /position properties). There is no attempt made to accurately simulate GPS position calculation - in the future an error function will be used (optionally) to reduce the accuracy of the GPS indicated position.

From the indicated position, many other values are derived - ground track, speed, vertical speed, odometer and so on. All these values can be seen in the basic /gps property tree, and are hopefully self-explanatory.

Active waypoints

The active waypoint is available as gps/wp/wp[1], for historical reasons. Various interesting values are computed for the active waypoint, such as distance, bearing and so on.

gps/wp/wp[0] contains another waypoint, which varies depending on mode. For DTO and OBS modes, it is the position at the point the mode was entered; for LEG mode it is the previous waypoint in the route. In general the GPS is navigating from wp0, and towards wp1.

Due to unfortunate history, the route-manager also tracks a 'wp0' and 'wp1', but they do not correspond to the GPS labelling - the route-manager's wp0 is the active (current) waypoint, which corresponds to the GPS's wp1. (The route-manager's wp1 is the next waypoint, if one exists - the GPS code doesn't treat the next waypoint specially, for the moment) Changing either convention is judged to be too risky for existing aircraft, so they have been left as-is.

In the future, when other kinds of leg exist, the active waypoint may not have a defined position; for example if the active leg is a hold, DME arc or procedure turn.

Commands and the scratch

The GPS has a simple command system - it expects the properties under instrumentation/gps/scratch to be populated with some parameters, and then a command property to be set under instrumentation/gps/command. Information is also returned via the instrumentation/gps/scratch properties. For example, to go direct to a waypoint, it is loaded into the scratch, and a 'direct' command executed. To find the nearest VOR, set .../scratch/type to vor and execute a nearest command (to execute a command set the command name as a string at the command property instrumentation/gps/command). The scratch will be updated with information about the result (if one was found) - and then a 'direct' or 'obs' command can be executed to use the waypoint.

Command List

More commands can be added! Let James know what you want (and why) and it can probably be done.

leg

Enter leg mode. Only possible if the route-manager route is active. The active waypoint becomes the current route manager waypoint

obs

Enter OBS mode. The active waypoint is loaded from the scratch, if valid - otherwise the current active waypoint is retained.

direct

Enter DTO mode. The active waypoint is loaded from the scratch, and a course calculated. If the scratch is invalid, the current active waypoint is used.

nearest

load the nearest waypoint (of a type) into the scratch. The following parameters are supported:

type - a type string (any, airport, vor, ndb, fix, wpt). 'any', 'all' or an empty value mean all types

max-results - maximum number of nearby waypoints to load. Default is 1, larger values are supported, but there may be noticeable delays if this is set to 100 or similar - testing is needed in this area.

search

load waypoints by matching ident. The following parameters are supported:

type - as for 'nearest'

query - the string to search on

order-by-range - a flag indicating if matches should be returned sorted by distance (the default) or alphabetically

exact - a flag indicated if matches must be exact (true) or partial (false).

search-names

load waypoints by matching name. Parameters are exactly the same as for regular search, including partial searches and result ordering controls.

load-route-wpt

loads the active route waypoint into the scratch (and allows other route points to be accessed via next & prev)

next

load the next result (for nearest/search/load-route-wpt)

previous

load the previous search result

define-user-waypoint

create a user waypoint based on the current scratch.

route-insert-before

insert the current scratch data into the route, before the waypoint at the supplied index.

index - the route index to insert before. If this is negative, the waypoint will be appended to the route.

route-insert-after

insert the current scratch data into the route, after the waypoint at the supplied index.

index - the route index to after before. If this is negative, the waypoint will be appended to the route.

route-delete

delete the route waypoint at the specified index

index - the route index to delete

Configuration

Various properties exist under gps/config to control behaviour. They can be adjusted at any time, and depend partly on the real-world insturment being modelled, and partly on installed aircraft performance (eg, turn rate). The default values are generally acceptable.

linear-deflection-nm

If positive, the cross-track error (in nm) that corresponds to full-scale CDI deflection output. Internally, this value is used to scale the cdi-deflection property, so that at its maximum value (+/- 10), it corresponds to this deviation in nm. Some receivers (such as the KLN-89) modify this value dynamically based on flight phase mode, to increase precision during approaches.

If this value is negative, the GPS reports angular CDI deflection (like a VOR receiver), in degrees, directly.

min-runway-length-ft

If positive, the minimum runway length (in feet) suitable for this aircraft. This is used to filters (and airports) from search / nearest results, so that 'nearest airport' does not list close, but unusable, airports.

hard-surface-runways-only

Flag to indicate if the GPS should consider hard-surfaced or all types of runway. Set this flag for aircraft which cannot land on soft surfaces such as grass or gravel. As above, this is used to filter search results.

turn-rate-deg-sec

turn rate in degrees per second. Default value is 3.0, meaning a 180 degree turn takes one minute, which corresponds to a standard rate turn. This value is needed to compute turn anticipation correctly.

drive-autopilot

Indicates if the GPS should automatically update /autopilot/target-altitude-ft and /autopilot/target-heading-deg whenever the active waypoint changes. This property is true in the default GPS installation, but should be disabled in any real-world instrument, since it is entirely unrealistic! It exists for compatibility with older versions of the GPS and route-manager code.

Positional Source

The GPS code is entirely agnostic to how the primary position is obtained; hence calling the code a GPS is inaccurate, but convenient. 'Navigation computer' is a better name. In simple GPS mode, the position value is read directly from the /position properties, i.e the actual simulation position of the aircraft.

In realistic mode, GPS position is calculated using an error filter that approximates the errors observed in real GPS receiver equipment. Config properties allow the simulation of selective availability (SA) and various augmentation systems such as WAAS and D-GPS to increase or decrease precision.

In INS mode, position is supplied by a simulated inertial reference platform, which integrates acceleration values over time to compute velocity and hence position change. As in real life, the INS system will accumulate errors (drift) over time due to numerical and technical limits. Drift rate and other parameters can be configured to control simulated INS accuracy.

In combined modes, position is calculated using multiple methods above. For example, GPS may be used to establish baseline position, and reset drift in an INS platform. Another possibility is to use INS for baseline position, and then use radio triangulation to correct for drift - this is the behaviour of the air navigation computers in the Boeing 757 and 767, for example.