XPLMNavigation

To use:

import xp

The XPLMNavigation APIs give you some access to the navigation databases inside X-Plane. X-Plane stores all navigation information in RAM, so by using these APIs you can gain access to most information without having to go to disk or parse the files yourself. See Navaid Functions.

You can also use this API to program the FMS. You must use the navigation APIs to find the navaids you want to program into the FMS, since the FMS is powered internally by X-Plane’s navigation database. See Flight Management Flight Plans.

Navaid Functions

• Iterate through the navaid database:

  • getFirstNavAid(), getNextNavAid()

• Search database based on location, type, partials names:

  • findFirstNavAidOfType(), findLastNavAidOfType()

  • findNavAid()

• Get information about the navaid:

  • getNavAidInfo()

Warning

The values retrieved using these functions generally match the format described in the Navigation Database document (e.g., XP-NAV1150-Spec.pdf) For example, the heading value for Glideslopes is defined as:

Associated localizer bearing in true degrees prefixed by glideslope angle times 100,000. E.g., Glideslope of 3.00 degrees on heading of 122.53125 becomes 300122.53125.

To add to the confusion, whereas the document indicate heights are in feet, it appears the values returned via the API are in meters.

getFirstNavAid()

Returns

XPLMNavRef or NAV_NOT_FOUND

This returns integer index (XPLMNavRef) of the very first navaid in the database. Use this to traverse the entire database. Returns NAV_NOT_FOUND if the navaid database is empty.

>>> navRef = xp.getFirstNavAid()
>>> navRef
0

Official SDK XPLMGetFirstNavAid

getNextNavAid(navRef)

Param

XPLMNavRef navRef

Returns

Next XPLMNavRef navRef or NAV_NOT_FOUND

Given a navRef, this routine returns the next navRef. It returns NAV_NOT_FOUND if the navRef passed in was invalid or if was the last one in the database. Use this routine to iterate across all like-typed navaids or the entire database. (Start with getFirstNavAid().)

Note

This merely returns the next navaid in the database. This does not return the next of the same type, or same query (see findFirstNavAidOfType(), or findNavAid()). It is very fast, so one strategy is to enumerate through the full navaid database if you’re trying to do anything complicated (e.g., find all navaids with the same frequency). If you’re looking for all navaids of the same type, you can iterate between getFirstNavAidOfType() and getLastNavAidOfType(): navaids of the same type are guaranteed to be grouped together, though they are not guaranteed to be sequentially continuous.

>>> navRef = xp.getFirstNavAid()
>>> navRef = xp.getNextNavAid(navRef)
>>> navRef
1

Official SDK XPLMGetNextNavAid

findFirstNavAidOfType(navType)

Param

XPLMNavType navType for search

Returns

First XPLMNavRef navRef or NAV_NOT_FOUND

Given a navType (See XPLMNavType below), return the navRef of the first navaid of the given type in the database or NAV_NOT_FOUND if there are no navaids of that type in the database. You must pass exactly one navaid type to this routine.

>>> xp.findFirstNavAidOfType(navType=xp.Nav_DME)
18826
>>> xp.findFirstNavAidOfType(navType=xp.Nav_DME | xp.Nav_VOR)
-1

Official SDK XPLMFindFirstNavAidOfType

findLastNavAidOfType(navType)

Param

XPLMNavType navType for search

Returns

Last XPLMNavRef navRef or NAV_NOT_FOUND

Given a navType (See XPLMNavType below), return the navRef of the last navaid of the given type database or NAV_NOT_FOUND if there are no navaids of that type in the database. You must pass exactly one navaid type to this routine.

You’ll note there is no findNextNavAidOfType() function. Because all navaids of the same type are grouped together, you can iterate between findFirstNavAidOfType() and findLastNavAidOfType(). A common work around is to load all navaid information into your plugin and then search within that data structure.

>>> xp.findLastNavAidOfType(navType=xp.Nav_DME)
26189

Official SDK XPLMFindLastNavAidOfType

findNavAid(name=None, navAidID=None, lat=None, lon=None, freq=None, navType=-1)

Parameters

• name (str) – case-sensitive fragment to search

• navAidID (str) – case-sensitive fragment to search

• lat (float) – latitude near navaid

• lon (float) – longitude near navaid

• freq (int) – integer representation of frequency (see below)

• navType (XPLMNavType) – OR’d together set of XPLMNavType

Returns

XPLMNavRef of first match

This routine provides a number of searching capabilities for the navaid database. findNavAid() will search through every navaid whose type is within navType (See XPLMNavType.) Multiple types may be OR’d together, with the default being “any” (matches imply at least one of the OR’d navTypes match not all). findNavAid() returns one navRef based on the following rules:

• If lat and lon are specified, the navaid nearest to that lat/lon will be returned, otherwise the last navaid found will be returned.

• If freq is provided , then any navaids considered must match this frequency. Note that this will screen out radio beacons that do not have frequency data published (like inner markers) but not fixes and airports. Note this is an integer, frequency input is real frequency times 100 to create a integer (e.g., specify 13775 to search for 137.75).

• If name is provided, only navaids that contain the fragment in their name will be returned. (Search on name is case-sensitive, so “Oakland” will find Metropolitan Oakland Intl (KOAK), but “OAKLAND” will not.

• If navAidID is provided, only navaids that contain the fragment in their IDs will be returned.

This routine provides a simple way to do a number of useful searches:

Find the nearest navaid on this frequency. Find the nearest airport. Find the VOR whose ID is “KBOS”. Find the nearest airport whose name contains “Chicago”.

>>> xp.findNavAid(name="Chicago", navType=xp.Nav_Airport | xp.Nav_DME)
16813190
>>> xp.findNavAid(name="OAK")
16800138
>>> xp.findNavAid(name="OAK", lat=35, lon=-122)
33705283

Warning

This function may lead you astray. You might think search for navAidID="EDDF", navType=xp.Nav_Airport might retrieve Frankfurt Airport (EDDF). But instead it will retrieve the first match which is the airport Karlstadt Saupurzel (XEDDF). Check your results!

Official SDK XPLMFindNavAid

getNavAidInfo(navRef)

Param

XPLMNavRef integer retrieved from e.g., findNavAid()

Returns

NavAidInfo or None

See information about returned NavAidInfo data structure below.

This routine returns information about a navaid indicated by its navRef. Fields are filled out with information if it is available. For example, Airports have neither frequency nor heading, so they will always be zero. Fixes (Nav_Fix) do not have height, frequency or heading. There is no way to distinguish between true values of zero and missing values.

Frequencies are in the nav.dat convention as described in the X-Plane nav database FAQ: NDB frequencies are exact, all others are multiplied by 100.

The reg field tells if the navaid is within the local “region” of loaded DSFs. (This information may not be particularly useful to plugins.) (Unlike C API, for python, this parameter is a single byte value 1 for true or 0 for false, not a string.):

>>> navRef = xp.findNavAid(name="OAK", lat=35, lon=-122, navType=xp.Nav_Airport)
>>> navRef
16793550
>>> navInfo = xp.getNavAidInfo(navRef)
>>> navInfo
<xppython3.NavAidInfo object at 0x7f84a16a3220>
>>> navInfo.name
'LIVE OAK CO'

Flight Management Flight Plans

X-Plane 12.1 allows you to specific which flight plan you want to interact with. These routines replace similar routines from previous versions of X-Plane which provide access only to the main “pilot” flight plan. In general, you can replace calls using the older interface with calls to 12.1 interface by including the parameter specifying the Fpl_Pilot_Primary flight plan. Full set of flight plan types are listed XPLMNavFlightPlan.

Note: the FMS works based on an array of entries. Indices into the array are zero-based. Each entry is a nav-aid plus an altitude. The FMS tracks the currently displayed entry and the entry that it is flying to (“destination entry”).

The FMS must be programmed with contiguous entries, so clearing an entry at the end shortens the effective flight plan. There is a max of 100 waypoints in the flight plan.

• Manipulate entry status in FMS

  • countFMSFlightPlanEntries()

  • getDisplayedFMSFlightPlanEntry(), setDisplayedFMSFlightPlanEntry()

  • getDestinationFMSFlightPlanEntry(), setDestinationFMSFlightPlanEntry()

  • setDirectToFMSFlightPlanEntry()

• Manipulate a particular FMS entry

  • getFMSFlightPlanEntryInfo(), setFMSFlightPlanEntryInfo(), setFMSFlightPlanEntryLatLon(), setFMSFlightPlanEntryLatLonWithId()

  • clearFMSFlightPlanEntry()

• Load and Save a flight plan loadFMSFlightPlan(), saveFMSFlightPlan()

For most of our examples below, we’ll be using the flight plan described in X-Plane’s Airbus MCDU Manual. In there, they describe inputting a flight plan for the route:

EDDS25 ETAS4B T163 SPESA SPES3B ILS25L

We’ll input that same route programmatically.

Functions

loadFMSFlightPlan(device, plan)

Parameters

• device (int) – 0= pilot side, 1= co-pilot side

• plan (str) – X-Plane 11+ formatted flight plan

Returns

Loads specially formatted string as the flight plan for the selected device

The format of the flight plan is X-Plane specific, and is described in Flightplan files - v11 .fms file format.

Assume the file edds-eddf.fms with contents:

I
1100 Version
CYCLE 2306
ADEP EDDS
DEPRWY RW25
SID ETAS4B
ADES EDDF
DESRWY RW25L
STAR SPES4B
APP I25L
APPTRANS CHA
NUMENR 6
1 EDDS ADEP 1272.000000 48.689877 9.221964
11 XINLA T163 0.000000 49.283646 9.141608
11 SUKON T163 0.000000 49.659721 9.195556
11 SUPIX T163 0.000000 49.727779 9.305278
11 SPESA T163 0.000000 49.862240 9.348325
1 EDDF ADES 354.000000 50.033306 8.570456

You can load that file directly into the pilot’s primary FMS using:

>>> with open("edds-eddf.fms", "r") as fp:
...    plan = fp.read()
>>> xp.loadFMSFlightPlan(0, plan)
>>> xp.countFMSFlightPlanEntries(xp.Fpl_Pilot_Primary)
22

(Your results may differ, as this is dependent on the current X-Plane navigation database).

Official SDK XPLMLoadFMSFlightPlan

saveFMSFlightPlan(device)

Parameters

device (int) – 0= pilot side, 1= co-pilot side

Return str

X-Plane 11+ formatted flight plan

Returns a string representing flight plan for selected device

The format of the flight plan is X-Plane specific, and is described in Flightplan files - v11 .fms file format.

>>> print(xp.saveFMSFlightPlan(0))
I
1100 Version
CYCLE 2306
ADEP EDDS
DEPRWY RW25
SID ETAS4B
ADES EDDF
DESRWY RW25L
STAR SPES4B
APP I25L
APPTRANS CHA
NUMENR 6
1 EDDS ADEP 1270.000000 48.689877 9.221964
11 XINLA T163 0.000000 49.283646 9.141608
11 SUKON T163 0.000000 49.659721 9.195556
11 SUPIX T163 0.000000 49.727779 9.305278
11 SPESA T163 0.000000 49.862240 9.348325
1 EDDF ADES 354.000000 50.033306 8.570456

You are responsible for saving it to a file, if that’s desired.

Official SDK XPLMSaveFMSFlightPlan

countFMSFlightPlanEntries(flightPlan)

Parameters

flightPlan (XPLMNavFlightPlan) – selected flight plan

Return int

number of entries in flight plan.

Also returns 0 if given flightPlan is not supported. (There is no way to determine if a particular flight plan is supported by the aircraft except, I suppose, by setting a value and attempting to read it back.)

Note that load/save use a simple integer for Pilot/Copilot flight plan. Most of the remain API use XPLMNavFlightPlan which can manipulate primary, approach, and temporary flight plans.:

>>> xp.countFMSFlightPlanEntries(xp.Fpl_Pilot_Primary)
22

Official SDK XPLMCountFMSFlightPlanEntries

getFMSFlightPlanEntryInfo(flightPlan, index)

Returns information about a single entry in the given flight plan.

Parameters

• flightPlan (XPLMNavFlightPlan) – selected flight plan

• index (int) – existing 0-based index to retrieve

Return FMSEntryInfo

Instance of FMSEntryInfo

>>> for i in range(xp.countFMSFlightPlanEntries(xp.Fpl_Pilot_Primary)):
...    print(str(xp.getFMSFlightPlanEntryInfo(xp.Fpl_Pilot_Primary, i)))
...
Airport:   [16804176]   EDDS, (48.690, 9.222) @1270'
LatLon:                 RW25, (48.694, 9.244) @1181'
Unknown:              (1700), (48.690, 9.220) @1700'
Fix:       [33625103]  DS050, (48.671, 9.122) @0'
Fix:       [33625093]  DS040, (48.690, 9.067) @0'
Fix:       [33625096]  DS043, (48.801, 9.010) @0'
Fix:       [33615290]  KOVAN, (48.882, 9.084) @0'
Fix:       [33613188]  ETASA, (49.191, 9.128) @0'
Fix:       [33622147]  XINLA, (49.284, 9.142) @0'
Fix:       [33619153]  SUKON, (49.660, 9.196) @0'
Fix:       [33619188]  SUPIX, (49.728, 9.305) @0'
Fix:       [33619099]  SPESA, (49.862, 9.348) @0'
VOR:       [    5076]    CHA, (49.921, 9.040) @0'
Fix:       [33624044]  DF606, (49.945, 8.912) @0'
Fix:       [33624046]  DF610, (50.029, 8.917) @0'
Fix:       [33624047]  DF611, (50.043, 8.973) @0'
Fix:       [33624048]  DF612, (50.066, 9.071) @0'
Fix:       [33624049]  DF613, (50.088, 9.168) @0'
Fix:       [33624050]  DF614, (50.111, 9.266) @0'
Fix:       [33624051]  DF615, (50.134, 9.363) @0'
Fix:       [33624052]  DF616, (50.156, 9.461) @0'
Unknown:              VECTOR, (52.509, 26.156) @0'
Fix:       [33624060]  DF626, (50.235, 9.417) @0'
Airport:   [16787750]   EDDF, (50.033, 8.570) @354'

Note that loading the same flight plan into a different aircraft may results in a different set of entries. The above entries were for the Airbus, the following entries are from the Cessan 172 G1000

>>> for i in range(xp.countFMSFlightPlanEntries(xp.Fpl_Pilot_Primary)):
...    print(str(xp.getFMSFlightPlanEntryInfo(xp.Fpl_Pilot_Primary, i)))
...
Airport:   [16804176]   EDDS, (48.690, 9.222) @1270'
LatLon:                 RW25, (48.694, 9.244) @1181'
Unknown:              (1700), (48.690, 9.220) @1700'
Fix:       [33625103]  DS050, (48.671, 9.122) @0'
Fix:       [33625093]  DS040, (48.690, 9.067) @0'
Fix:       [33625096]  DS043, (48.801, 9.010) @0'
Fix:       [33615290]  KOVAN, (48.882, 9.084) @0'
Fix:       [33613188]  ETASA, (49.191, 9.128) @0'
Fix:       [33622147]  XINLA, (49.284, 9.142) @0'
Fix:       [33619153]  SUKON, (49.660, 9.196) @0'
Fix:       [33619188]  SUPIX, (49.728, 9.305) @0'
Fix:       [33619099]  SPESA, (49.862, 9.348) @0'
VOR:       [    5076]    CHA, (49.921, 9.040) @0'
Fix:       [33624044]  DF606, (49.945, 8.912) @0'
Fix:       [33624046]  DF610, (50.029, 8.917) @0'
Fix:       [33624047]  DF611, (50.043, 8.973) @0'
Fix:       [33624048]  DF612, (50.066, 9.071) @0'
Fix:       [33624049]  DF613, (50.088, 9.168) @0'
Fix:       [33624050]  DF614, (50.111, 9.266) @0'
Fix:       [33624051]  DF615, (50.134, 9.363) @0'
Fix:       [33624052]  DF616, (50.156, 9.461) @0'
Unknown:              VECTOR, (52.509, 26.156) @0'
Fix:       [33624060]  DF626, (50.235, 9.417) @0'
Airport:   [16787750]   EDDF, (50.033, 8.570) @354'

Note the use of VECTOR here, which is a lat/lon a few hundred miles away in the direction one is suppose to fly. Not something to actually over-fly.

And… because G1000 has a separate Approach plan, don’t forget:

>>> for i in range(xp.countFMSFlightPlanEntries(xp.Fpl_Pilot_Approach)):
...    print(str(xp.getFMSFlightPlanEntryInfo(xp.Fpl_Pilot_Approach, i)))
...
VOR:       [    5353]    CHA, (49.921, 9.040) @0'
Fix:       [33621703]  D338K, (50.095, 8.942) @0'
Fix:       [33621910]  LEDKI, (50.104, 8.856) @0'
Fix:       [33621902]  FF25L, (50.081, 8.759) @0'
LatLon:                RW25L, (50.040, 8.587) @411'
Fix:       [33621697]  D247E, (50.021, 8.505) @0'
Fix:       [33621696]  D241H, (49.993, 8.453) @0'
Unknown:              (5000), (49.925, 8.232) @4999'
VOR:       [    5353]    CHA, (49.921, 9.040) @0'

Official SDK XPLMGetFMSFlightPlanEntryInfo

setFMSFlightPlanEntryInfo(flightPlan, index, navRef, altitude=0)

setFMSFlightPlanEntryLatLon(flightPlan, index, lat, lon, altitude=0)

setFMSFlightPlanEntryLatLonWithId(flightPlan, index, lat, lon, altitude=0, ID=None)

Sets entry in FMS at the given index.

Parameters

• flightPlan (XPLMNavFlightPlan) – selected flight plan

• index (int) – 0-based index to set

• navRef (XPLMNavRef) – XPLMNavRef integer from findNavAid()

• lat (float) –

• lon (float) – Latitude / Longitude. To be used when navRef is not appropriate

• altitude (int) – Altitude of fix in feet.

• ID (str) – Optional string used (with LatLon) to be displayed with entry

Returns

None

These three functions all do the same thing, but using slightly different data as input. If a navRef is provided, its latitude, longitude and display name will used. If no navRef is provided, latitude and longitude must be provided.

The index you provide must be for either an existing entry, or one more than the last entry, otherwise it is ignored. That is, if you only have three entries, setting entry index #10 will do nothing.

To match our example EDDS-EDDF flight plan, one could use the SDK to create it as:

>>> xp.setFMSFlightPlanEntryInfo(0, 0, 16803968, 1271)
>>> xp.setFMSFlightPlanEntryLatLonWithId(0, 1, 48.694, 9.244, 1180, "RW25")
>>> xp.setFMSFlightPlanEntryLatLonWithId(0, 2, 48.690, 9.220, 1699, "(1700)")
>>> xp.setFMSFlightPlanEntryInfo(0, 3, 33622837, 0)
>>> xp.setFMSFlightPlanEntryInfo(0, 4, 33622827, 0)
>>> xp.setFMSFlightPlanEntryInfo(0, 5, 33622830, 0)
>>> xp.setFMSFlightPlanEntryInfo(0, 6, 33613119, 19999)
>>> xp.setFMSFlightPlanEntryInfo(0, 7, 33611008, 19035)
>>> xp.setFMSFlightPlanEntryInfo(0, 8, 33620051, 0)
>>> xp.setFMSFlightPlanEntryInfo(0, 9, 33617115, 0)
>>> xp.setFMSFlightPlanEntryInfo(0, 10, 33617153, 0)
>>> xp.setFMSFlightPlanEntryInfo(0, 11, 33617059, 0)
>>> xp.setFMSFlightPlanEntryInfo(0, 12, 5353, 0)
>>> xp.setFMSFlightPlanEntryLatLonWithId(0, 13, 50.095, 8.942, 0, "D338K")
>>> xp.setFMSFlightPlanEntryInfo(0, 14, 33621910, 0)
>>> xp.setFMSFlightPlanEntryLatLonWithId(0, 15, 50.081, 8.759, 0, "FF25L")
>>> xp.setFMSFlightPlanEntryLatLonWithId(0, 16, 50.040, 8.587, 411, "RW25L")
>>> xp.setFMSFlightPlanEntryLatLonWithId(0, 17, 50.021, 8.505, 0, "D247E")
>>> xp.setFMSFlightPlanEntryLatLonWithId(0, 18, 49.993, 8.453, 0, "D241H")
>>> xp.setFMSFlightPlanEntryLatLonWithId(0, 19, 49.925, 8.232, 4999, "5000")
>>> xp.setFMSFlightPlanEntryInfo(0, 20, 5353, 0)
>>> xp.setFMSFlightPlanEntryInfo(0, 21, 16787675, 353)

The resulting formatted flight plan looks like:

I
1100 Version
CYCLE 2112
DEP EDDS
DES EDDF
NUMENR 22
1 EDDS DRCT 1272.000000 48.689877 9.221964
28 RW25 DRCT 0.000000 48.694000 9.244000
28 (1700 DRCT 0.000000 48.689999 9.220000
11 DS050 DRCT 0.000000 48.670815 9.122375
11 DS040 DRCT 0.000000 48.689812 9.067369
11 DS043 DRCT 0.000000 48.800713 9.009992
11 KOVAN DRCT 0.000000 48.882385 9.084291
11 ETASA DRCT 0.000000 49.190796 9.128403
11 XINLA DRCT 0.000000 49.283646 9.141608
11 SUKON DRCT 0.000000 49.659721 9.195556
11 SUPIX DRCT 0.000000 49.727779 9.305278
11 SPESA DRCT 0.000000 49.862240 9.348325
3 CHA DRCT 0.000000 49.921104 9.039817
28 D338K DRCT 0.000000 50.095001 8.942000
11 LEDKI DRCT 0.000000 50.104099 8.855891
28 FF25L DRCT 0.000000 50.081001 8.759000
28 RW25L DRCT 0.000000 50.040001 8.587000
28 D247E DRCT 0.000000 50.021000 8.505000
28 D241H DRCT 0.000000 49.993000 8.453000
28 5000 DRCT 0.000000 49.924999 8.232000
3 CHA DRCT 0.000000 49.921104 9.039817
1 EDDF DRCT 354.000000 50.033306 8.570456

You’ll note this formatted flight plan is different from the formatted flight plan created by manually entering the data to the MCDU (See edds_eddf.fms above). You’ll lose explicit departure and destination block information with named SID and STAR. At present (XP 12.1) there is no way to provide such information through the SDK. Nor can you indicate that your route should use a particular airway, as you can by using MCDU. Fortunately waypoints and altitudes are all the same.

Note

Regarding altitude: Due to internal conversion from integer feet to floating point to meters and back again, the altitude you set may be slightly different from the altitude you observe on the FMS device and/or the altitude you get programmatically. The different is likely to be only a foot or so.

Official SDK XPLMSetFMSFlightPlanEntryInfo

Official SDK XPLMSetFMSFlightPlanEntryLatLon

Official SDK XPLMSetFMSFlightPlanEntryLatLonWithId

clearFMSFlightPlanEntry(flightPlan, index)

Removes indicated flight plan entry

Parameters

• flightPlan (XPLMNavFlightPlan) – selected flight plan

• index (int) – 0-based index entry to be removed

Returns

None

The entry will be removed and the result flight plan with either be shortened, or a discontinuity may result. Attempting to clear an index which does not exist is ignored.

Continuing with our flight plan example, if we delete the single entry in position 15:

>>> xp.clearFMSFlightPlanEntry(0, 15)

We’ll still have 22 entries, but the entry #15 will now be a discontinuity.

┏━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃Entry┃       Before delete #15 "FF25L"                  ┃     After delete note DISCON at #15               ┃
┠━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┃
┃ [0] ┃Airport: [16803968]  EDDS, (48.690, 9.222) @1271' ┃  Airport: [16803968]  EDDS, (48.690, 9.222) @1271'┃
┃ [1] ┃LatLon:              RW25, (48.694, 9.244) @1180' ┃  LatLon:              RW25, (48.694, 9.244) @1180'┃
┃ [2] ┃Unknown:           (1700), (48.690, 9.220) @1699' ┃  Unknown:           (1700), (0.000, 0.000) @0'    ┃
┃ [3] ┃Fix:     [33622837] DS050, (48.671, 9.122) @0'    ┃  Fix:     [33622837] DS050, (48.671, 9.122) @0'   ┃
┃ [4] ┃Fix:     [33622827] DS040, (48.690, 9.067) @0'    ┃  Fix:     [33622827] DS040, (48.690, 9.067) @0'   ┃
┃ [5] ┃Fix:     [33622830] DS043, (48.801, 9.010) @0'    ┃  Fix:     [33622830] DS043, (48.801, 9.010) @0'   ┃
┃ [6] ┃Fix:     [33613119] KOVAN, (48.882, 9.084) @19999'┃  Fix:     [33613119] KOVAN, (48.882, 9.084) @0'   ┃
┃ [7] ┃Fix:     [33611008] ETASA, (49.191, 9.128) @19035'┃  Fix:     [33611008] ETASA, (49.191, 9.128) @0'   ┃
┃ [8] ┃Fix:     [33620051] XINLA, (49.284, 9.142) @0'    ┃  Fix:     [33620051] XINLA, (49.284, 9.142) @0'   ┃
┃ [9] ┃Fix:     [33617115] SUKON, (49.660, 9.196) @0'    ┃  Fix:     [33617115] SUKON, (49.660, 9.196) @0'   ┃
┃[10] ┃Fix:     [33617153] SUPIX, (49.728, 9.305) @0'    ┃  Fix:     [33617153] SUPIX, (49.728, 9.305) @0'   ┃
┃[11] ┃Fix:     [33617059] SPESA, (49.862, 9.348) @0'    ┃  Fix:     [33617059] SPESA, (49.862, 9.348) @0'   ┃
┃[12] ┃VOR:     [    5353]   CHA, (49.921, 9.040) @0'    ┃  VOR:     [    5353]   CHA, (49.921, 9.040) @0'   ┃
┃[13] ┃Fix:     [33621703] D338K, (50.095, 8.942) @0'    ┃  Fix:     [33621703] D338K, (50.095, 8.942) @0'   ┃
┃[14] ┃Fix:     [33621910] LEDKI, (50.104, 8.856) @0'    ┃  Fix:     [33621910] LEDKI, (50.104, 8.856) @0'   ┃
┃[15] ┃Fix:     [33621902] FF25L, (50.081, 8.759) @0'    ┃  Unknown:           DISCON, (50.072, 8.721) @0'   ┃
┃[16] ┃LatLon:             RW25L, (50.040, 8.587) @411'  ┃  LatLon:             RW25L, (50.040, 8.587) @411' ┃
┃[17] ┃Fix:     [33621697] D247E, (50.021, 8.505) @0'    ┃  Fix:     [33621697] D247E, (50.021, 8.505) @0'   ┃
┃[18] ┃Fix:     [33621696] D241H, (49.993, 8.453) @0'    ┃  Fix:     [33621696] D241H, (49.993, 8.453) @0'   ┃
┃[19] ┃Unknown:           (5000), (49.925, 8.232) @4999' ┃  Unknown:           (5000), (49.925, 8.232) @4999'┃
┃[20] ┃VOR:     [    5353]   CHA, (49.921, 9.040) @0'    ┃  VOR:     [    5353]   CHA, (49.921, 9.040) @0'   ┃
┃[21] ┃Airport: [16787675]  EDDF, (50.033, 8.570) @353'  ┃  Airport: [16787675]  EDDF, (50.033, 8.570) @353' ┃
┗━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Official SDK XPLMClearFMSFlightPlanEntry

getDestinationFMSFlightPlanEntry(flightPlan)

Parameters

flightPlan (XPLMNavFlightPlan) – selected flight plan

Return int

Return 0-based index number of the entry the FMS is flying to.

If the flightPlan is not valid for the aircraft, 0 is returned. There is no way to distinguish between a valid and invalid response.

>>> xp.getDestinationFMSFlightPlanEntry(xp.Fpl_Pilot_Primary)
0

Official SDK XPLMGetDestinationFMSFlightPlanEntry

setDestinationFMSFlightPlanEntry(flightPlan, index)

Parameters

• flightPlan (XPLMNavFlightPlan) – selected flight plan

• index (int) – existing 0-based index to become new destination

Returns

None

The flight track is from the location immediately before the index to the index entry. (Compare with setDirectToFMSFlightPlanEntry().) If the index is not valid, the command is ignored.

Changing destination from KDEN to WITNE:

>>> xp.setDestinationFMSFlightPlanEntry(xp.Nav_Pilot_Primary, 1)

Official SDK XPLMSetDestinationFMSFlightPlanEntry

setDirectToFMSFlightPlanEntry(flightPlan, index)

Parameters

• flightPlan (XPLMNavFlightPlan) – selected flight plan

• index (int) – existing 0-based index to become new direct-to destination

Returns

Return

The flight track is changed to be the current aircraft position to the indicated destination, ignoring flight plan entries before the index value.

Compare setDestinationFMSFlightPlanEntry() (left) versus setDirectToFMSFlightPlanEntry() (right) for a plan where the aircraft is currently at KDEN and we set the entry to index #3 GLD:

Official SDK XPLMSetDirectToFMSFlightPlanEntry

getDisplayedFMSFlightPlanEntry(flightPlan)

Parameters

flightPlan (XPLMNavFlightPlan) – selected flight plan

Return int

Return 0-based index number of the currently displayed flight plan entry

Some aircraft are able to step through the flight plan. For example, the Airbus can be set to “PLAN” and each leg displayed for review.

This function retrieves the currently displayed entry index.

Official SDK XPLMGetDisplayedFMSFlightPlanEntry

setDisplayedFMSFlightPlanEntry(flightPlan, index)

Parameters

• flightPlan (XPLMNavFlightPlan) – selected flight plan

• index (int) – existing 0-based index to be displayed

Returns

None

Change the entry being displayed on ND (Navigation Display), where applicable.

For example, on the Airbus:

To cycle through each leg:

>>> xp.setDisplayedFMSFlightPlanEntry(0, 1)
>>> xp.setDisplayedFMSFlightPlanEntry(0, 2)
>>> xp.setDisplayedFMSFlightPlanEntry(0, 3)

Note that, for the Airbus, if the MCDU is set on “F-PLN” the display will not update. Select any other MCDU button and the views will update.

Note also that G1000 MFD can be made to view each leg of the flight plan by manually moving the on-screen cursor, but does not respond to these Get/SetDisplay functions.

Official SDK XPLMSetDisplayedFMSFlightPlanEntry

Flight Management Computer: Pre-XP12.1 Style

X-Plane 12.1 introduced a new way of interacting with Flight Management computers, allowing you to select which flight plan you want to work with. See Flight Management Flight Plans. You should be using that method for new development.

Some aircraft have a Flight Management System which responds to these commands. Some do not. sigh. The Laminar G530 and G1000 work.

Note: the FMS works based on an array of entries. Indices into the array are zero-based. Each entry is a nav-aid plus an altitude. The FMS tracks the currently displayed entry and the entry that it is flying to.

The FMS must be programmed with contiguous entries, so clearing an entry at the end shortens the effective flight plan. There is a max of 100 waypoints in the flight plan.

• Manipulate entry status in FMS

  • countFMSEntries()

  • getDisplayedFMSEntry(), setDisplayedFMSEntry()

  • getDestinationFMSEntry(), setDestinationFMSEntry()

  • getGPSDestinationType(), getGPSDestination()

• Manipulate a particular FMS entry

  • getFMSEntryInfo(), setFMSEntryInfo(), setFMSEntryLatLon()

  • clearFMSEntry()

Functions

countFMSEntries()

Returns the number of entries in the FMS.

>>> xp.countFMSEntries()
6

Official SDK XPLMCountFMSEntries

getDisplayedFMSEntry()

Return the index of the entry the pilot is viewing. (For XP 11.55, this appears to always return 0. This has been acknowledged by Laminar Research as bug XPD-11386. The X-Plane 10 737 works correctly, but the 737 which comes with X-Plane 11 does not.

Practically speaking, assume this does not work.

>>> xp.getDisplayedFMSEntry()
0

Official SDK XPLMGetDisplayedFMSEntry

getDestinationFMSEntry()

Return the index of the entry the FMS is flying to. (The “destination” refers to the active leg.) This is an index into the FMS, not into the navaid database.

>>> xp.getDestinationFMSEntry()
0

Official SDK XPLMGetDestinationFMSEntry

setDisplayedFMSEntry(index)

Change which entry the FMS is showing to the integer index specified. (For X-Plane 11.55, this does not appear to do anything. This has been acknowledged by Laminar Research as bug XPD-11386. Like getDisplayedFMSEntry(), this appears to work in X-Plane 11 only for older X-Plane 10 version of the 737 aircraft.)

>>> xp.setDestinationFMSEntry(3)

Official SDK XPLMSetDisplayedFMSEntry

setDestinationFMSEntry(index)

Change which entry the FMS is flying the aircraft toward.

>>> xp.getDestinationFMSEntry()
0
>>> xp.setDestinationFMSEntry(3)
>>> xp.getDestinationFMSEntry()
3

Official SDK XPLMSetDestinationFMSEntry

getFMSEntryInfo(index)

Returns information about the zero-based index entry in the FMS. Value returned is an object (see below).

A reference to a navaid can be returned allowing you to find additional information (such as a frequency, ILS heading, name, etc.). Some information is available immediately. For a lat/lon entry, the lat/lon is returned by this routine but the navaid cannot be looked up (and the reference will be XPLM_NAV_NOT_FOUND.

Note

X-Plane C SDK function takes many parameters, where the data is returned. The XPPython3 function takes a single parameter (Index) and returns all the values in an FMSEntryInfo object.

Object returned by getFMSEntryInfo() containing information about an entry. It has the following attributes:

setFMSEntryInfo(index, navRef, altitude=0)

This routine changes an entry at index in the FMS to have the destination navaid specified by navRef (as returned by findNavAid()) at altitude (in feet) specified. Use this only for airports, fixes, and radio-beacon navaids. Currently for radio beacons, the FMS can only support VORs, NDBs, and TACANS.

Use the setFMSEntryLatLon() fly to a lat/lon.

>>> navRef = xp.findNavAid(navType=xp.Nav_VOR)
>>> xp.setFMSEntryInfo(3, navRef, 1000)
>>> print(xp.getFMSEntryInfo(3))
VOR: [9469] ZDA, (44.095, 15.364) @1000'

Official SDK XPLMSetFMSEntryInfo

setFMSEntryLatLon(index, lat, lon, altitude=0)

This routine changes an entry at index in the FMS to have the destination specified by lat, lon at altitude (in feet) specified.

>>> xp.setFMSEntryLatLon(3, 34, -122.5, 1000)
>>> print(xp.getFMSEntryInfo(3))
LatLon: (34.000, -122.5) @1000'

Official SDK XPLMSetFMSEntryLatLon

clearFMSEntry(index)

Clears the given entry, potentially shortening the flight plan.

Official SDK clearFMSEntry

GPS Receiver

getGPSDestinationType()

Return the XPLMNavType of the current GPS destination.

Returns

XPLMNavType

>>> xp.getGPSDestinationType()
512

Official SDK XPLMGetGPSDestinationType

getGPSDestination()

Return the XPLMNavRef of current GPS destination.

: return: XPLMNavRef

>>> xp.getGPSDestination()
33706498
>>> print(xp.getNavAidInfo(xp.getGPSDestination()))
LUCOS (LUCOS) Fix (41.638, -70.768) ---

Official SDK XPLMGetGPSDestination

Constants

XPLMNavFlightPlan

These enumerations define the type of flight plan used with Flight Management Flight Plans routines. Not all are available on all aircraft. For convenience, I’ve included at least one aircraft which has the named flight plan. This is not a complete list of aircraft.

Fpl_Pilot_Primary	=0	Cessna 172 G1000, GNS530, Airbus MCDU
Fpl_CoPilot_Primary	=1	Cessna 172 GNS430, Airbus MCDU
Fpl_Pilot_Approach	=2	GNS530, G1000
Fpl_CoPilot_Approach	=3	GNS430
Fpl_Pilot_Temporary	=4	Airbus MCDU
Fpl_CoPilot_Temporary	=5	Airbus MCDU

XPLMNavType

These enumerations define the different types of navaids. They are each defined with a separate bit so that they may be bit-wise added together to form sets of nav-aid types.

Nav_Unknown	=0
Nav_Airport	=1
Nav_NDB	=2
Nav_VOR	=4
Nav_ILS	=8
Nav_Localizer	=16
Nav_GlideSlope	=32
Nav_OuterMarker	=64
Nav_MiddleMarker	=128
Nav_InnerMarker	=256
Nav_Fix	=512
Nav_DME	=1024
Nav_LatLon	=2048
Nav_TACAN	=4096

Note

Nav_LatLon is a specific lat-lon coordinate entered into the FMS. It will not exist in the database, and cannot be programmed into the FMS. Querying the FMS for navaids will return it. Use setFMSEntryLatLon() to set a lat/lon waypoint.

Official SDK XPLMNavType

XPLMNavRef

XPLMNavRef is an iterator into the navigation database. The navigation database is essentially an array, but it is not necessarily densely populated. The only assumption you can safely make is that like-typed nav-aids are grouped together.

Use XPLMNavRef to refer to a nav-aid.

NAV_NOT_FOUND = -1

NAV_NOT_FOUND is returned by functions that return an XPLMNavRef when the iterator must be invalid.

Official SDK XPLMNavRef

FMSEntryInfo

Data structure returned by getFMSFlightPlanEntryInfo() and py:func:getFMSEntryInfo.

type	XPLMNavType or XPLM_NAV_NOT_FOUND if this is a lat/lon entry
navAidID	str or None if this is a lat/lon entry
ref	XPLMNavRef or None
altitude	int (in feet)
lat	float latitude
lon	float longitude

Conveniently, it also has a str() representation

>>> info = xp.getFMSEntryInfo(0)
>>> info
<xppython3.FMSEntryInfo object at 0x7ff38c0a5040>
>>> info.navAidID
'LUCOS'
>>> info.ref
337064980
>>> print(info)
Fix: [337064980] LUCOS, (41.638, -70.768) @0'
>>> print(xp.getNavAidInfo(info.ref))
LUCOS (LUCOS) Fix (41.638, -70.768) ---

Official SDK XPLMGetFMSEntryInfo

NavAidInfo

Data structure returned by getNavAidInfo().

type	XPLMNavType
latitude	float
longitude	float
height	float (in meters)
frequency	int. For NDB, frequency is exact. Otherwise, divide by 100 to get actual.
heading	float
name	str
navAidID	str
reg	int 1= navaid is within the local “region” of loaded DSFs.

Conveniently, it also has a str() representation

>>> navRef = xp.findNavAid(name="OAK", lat=35, lon=-122, navType=xp.Nav_Airport)
>>> navRef
16793550
>>> navInfo = xp.getNavAidInfo(navRef)
>>> navInfo
<xppython3.NavAidInfo object at 0x7f84a16a3220>
>>> navInfo.name
'LIVE OAK CO'
>>> navInfo.navAidID
'8T6'
>>> navInfo.latitude
28.36280
>>> print(navInfo)
LIVE OAK CO (8T6) (28.363, -98.116) ---

Official SDK XPLMGetNavAidInfo