CDI instrument

Request for Comments:

FlightGear Run Levels SGModule - standalone SGSubsystems An Integrated AI Traffic System Autopilot Enhancements Backwards Compatibility Initiative CDI instrument Decoupling the AI Traffic System Multiplayer Enhancements Modularizing, parallelizing and distributing FlightGear FDM engine feature standardization FlightGear Headless FlightGear Sessions Keyboard function priority list Next Generation Scenery Property Tree Reorganization Recommended Property Tree Enhancements Recommended Project Policies Redesigning the Replay System Remote Properties Simplifying Aircraft Deployment

Collection of information relating to creating a formal CDI instrument in FG, to alleviate confusion and bugs due to overloading the existing navradio code and properties. Throughout this page, the terms CDI and HSI are used interchangeably to describe a instrument providing lateral guidance based on a moving indicator, from some navigation source. Depending on the panel, multiple instruments of this type might be presented on a single cockpit display (eg, a G1000 map display).

Current Situation and Issues

• NavRadio defines a boolean flag, slaved-to-gps, which causes most of the NavRadio outputs (especially, CDI deflection and GS deflection) to be driven from the GPS/FMS module instead of the VOR receiver. This functionality was originally created to make the generic GPS useful in all the existing aircraft that had no real GPS instrument, but is also used by aircraft with an FMS function (eg, the 777 and B1900d) to provide some drive to the autopilot The flag is exposed in the default GPS dialog, but also toggled by, for example., the B1900's 'FMS/NAV' switch on the panel, and by the 777's AFDS scripts when 'LNAV' is selected on the MCP.

Due to lack of documentation of the feature, and its intended role, all current uses in aircraft should probably be considered broken, and prime candidates for improvements as proposed further in this page.

• NavRadio computes some intercept data for the autopilot, using unrealistic values including true heading and ground track.

• The GPS/FMS course is derived from the navradio radials/selected-radial property, and the FMS updates this property when the desired GPS course changes - for example when passing a waypoint. Some real world FMS devices can specify the desired course to the HSI/CDI instrument in this way, but some others cannot - for example the KLN89B requires the pilot to manually adjust the CDI course to match the desired course indicated on the GPS display.

• The GPS/FMS uses radials/selected-radial as the default external course selector (though this can be changed), particular when operating in OBS mode for a KLN89-type device. This is highly convenient in that the existing default radios dialog, panel-instrument CRS/OBS selector knobs, and so on, all work to set the GPS course automatically.

• Many aircraft overload 'course' to always mean NavRadio course - for example the MCPs on the large jets (777, 737) implicitly set the navradio course when changing the panel knob or via a custom autopilot dialog. Since they are typically using slaved-to-gps to model the FMS drive to the autopilot, this works in practice, but makes it impossible to use the nav1 vor receiver independently while following an FMS course - which is obviously highly desirable. It also means the nav1 course is being over-written by the FMS course, again complicating things when switching from FMS to VOR/LOC navigation during an approach.

Goals

(Note some of these are conflicting, or are long-term goals that will only be possibly six or twelve months after the initial work takes place)

• Keep compatability with existing aircraft, whilst providing a migration strategy for aircraft that wish to take advantage of the CDI features. Crucially, this means the current properties on NavRadio must continue to work and exist as before, for GUI dialogs, panel instruments, autopilot configurations and so on.

• Ensure the system is a clear upgrade path, i.e that an aircraft author can choose to opt-in to a new design or scheme, and have things work a particular, well defined way.

• Ensure the complexity (in Nasal, particular) of an aircraft installation is proportional to the real system complexity. I.e it's acceptable to require Nasal scripting and complex inter-dependencies between instruments in a Boeing, Airbus or G1000-equipped aircraft, since those system do have complex dataflows in real-life. It is not acceptable to need (or have) such complexities in a Super Cub with a simple VOR receiver. The middle case - a Cessna with a KLN89 installed - presumably lies somewhere in between.

• Return NavRadio to being a pure, physical VOR receiver, with no overload for GPS support, autopilot intercept calculation, or so on

• Allow FMS/GPS/advanced HSI development without further complicating the NavRadio code

• Clarify the meaning of various GUI and command-line switches which set 'radials' or 'courses', or follow 'nav1 course'

• Give the option to have the GPS/FMS and NavRadio course, CDI deflection and so on be entirely independent, so that FMS / glass-cockpit installations can work more realistically.

Non-goals

• Allow hybrid aircraft which partially use the old and new design - i.e an aircraft should be converted over to whatever new instruments / properties are defined, or not - but there should not be an expectation that aircraft can be partially converted and still work sensibly.

Use-cases

Aircraft which use the generic autopilot config, autopilot dialog and instruments configuration

This is a common category, and there is an expectation that the default navradio dialog, default GPS dialog and default autopilot work sanely together, to allow a VOR OBS to be followed, or a GPS course.

Aircraft with no real-world GPS, and a non-CDI panel display of the NavRadio

(eg, the current default C172). Ideally aircraft in this case would not need a CDI instrument created - they would continue using the existing properties on navradio as always, and their autopilot function and GUI dialogs would need no changes.

Aircraft which model a real-world GA GPS device (eg, a KLN89 or KLN90B installation in a Cessna or similar)

(note there are no current examples of this case, but it is an important one to support) The KLN89B installation manual provides some good hints about how such setups are configured - notable that there will be a physical panel switch to select the CDI source (NAV1 or GPS), and that the GPS can and does read the course selection from the CDI knob, but that it has no way to change the CDI course - it relies on the pilot to do this on its behalf. Presumably there are more complex CDI instruments available which might allow the course to be set via an external data source such as the GPS.

Aircraft which use slaved-to-gps to provide FMS functionality (eg, the B1900d)

This is the category where intensive work is likely required, to upgrade aircraft to use a real CDI. It includes all the large, modern aircraft with complete panels or integrated FMS systems.

Proposed Approach

CDI instrument

Create a new C++ instrument, which can be specified in instruments.xml, which models a generic CDI. This would have the following configuration, most of which are optional depending on the air-data computers or similar on the airciraft.

true-heading-source

a GPS (or similar) derived true heading

magnetic-heading-source

a magnetic heading, presumably derived from a compass or heading gyro

true-track-source

GPS/FMS derived true ground track property

magnetic-track-source

GPS/FMS/AHRS-derived magnetic ground track property

deviation-peg-value

a value corresponding to needle position when no input data is valid

gs-peg-value

a value corresponding to gs needle position when no input data is valid

input[n]/deviation-source

a property providing a deflection value

input[n]/deviation-scale

a value to scale the input deviation by

input[n]/deviation-valid

a condtion group specifiying when the deviation data is valid (eg, in-range flag for a nav radio, data-valid property for a GPS)

input[n]/selected-course-input

a property where the CDI should write its current course selection. This would be the selected radial for a nav-radio, or the course input property for an FMS/GPS. Note that at least some real-world FMS devices ignore this value, i.e it could left undefined.

input[n]/selected-flag-prop

a property location for the CDI to indicate to a source that is it currently selected. Some sources may need to listen to this property to update internal state, for example if they can only read the selected course input when selected.

input[n]/gs-deviation-source

property providing a GS deviation value

input[n]/gs-deviation-valid

a condition group specifying when the gs-deviation data is valid

input[n]/gs-deviation-scale

a value to scale the GS deviation by.

And the following properties:

selected-course-deg

a course value corresponding to the 'knob' on a mechanical CDI, or the course selector on a MCP

selected-input

an integer corresponding to a defined input sub-tree

desired-course-deg

the desired course of the selected input

deviation

the scaled output deviation from the current input, or the peg value

deviation-valid

flag indicating the deviation output is valid

gs-deviation

the scaled output GS deviation from the current input, or the peg value

gs-deviation-valid

flag indicating of the GS deviation output is valid

input[n]/desired-course-deg

the desired course value for the input. For a VOR, this is the selected radial (for a LOC, it will be the localizer heading). For a GPS, it would be the desired leg course, direct-to route or similar.

The theory of operation is that an input[n] configuration block would be created for each CDI input source, and that the the CDI would output whichever deviation value is selected, scaled as necessary - or the 'peg' value if no input is selected, or the select input has no valid data, such as an untuned nav radio.

Nav Radio

• Document slaved-to-gps as only for use by the default GPS dialog, and ideally warn about any other use in aircraft or panels.

• Mmark accesses to crosstrack-heading-error-deg and target-auto-hdg-deg as deprecated. The former is not currently used by any aircraft in Git; the latter is used by five aircraft in Git - in each case as part of a flight-director script.

Depending on community feedback, the timescales for removing these properties (and associated code) from nav-radio might be as short as six months, but are likely to be considerably longer - in practice the code is ugly, but is not doing major harm, other than causing confusion to new aircraft developers.

Default GPS

• Add a GPS course selection dial or spinbox to the GUI dialog, to allow the GPS course to be controlled directly.

• Remove the GPS's external-course coupling features. This eliminates several bugs, and implicitly requires use of a CDI instrument (or equivalent, in Nasal) to enforce whatever CDI/FMS/nav-radio course-coupling is desired.

• Retain the 'NAV slave' checkbox in the default GPS dialog, but provide some means to hide it when a CDI is active - probably a global /sim/gui/dialogs property when the CDI instrument sets when created.

Autopilot

• In the default autopilot dialog, add feedback when true heading is being generated by the GPS/route-manager code, to make it clear to the user where the heading is being generated from.