PLANNED ROUTE API

The planned route API offers the ability to work with the flight planning features of Microsoft Flight Simulator 2024. These features include:

  • The ability to load the player's current flight plan route (as presently displayed on the EFB)
  • The ability to subscribe to requests from the EFB to be provided with a route from avionics systems
  • The ability to respond to such requests

 

The interface of this API is designed to be as avionics and instrument agnostic as possible, while communicating everything necessary for users to share and synchronize flight plan routes in a general way to and from the simulator.

 

The functions available for this API are as follows:

 

Function Description
fsPlannedRouteGetEfbRoute Gets the player's flight plan route, as shown on the EFB.
fsPlannedRouteRegisterForBroadcast Registers a callback which is fired when the player's route is pushed from the EFB.
fsPlannedRouteUnregisterForBroadcast Unregisters a route push callback.
fsPlannedRouteRegisterForRequest Registers a callback which is fired when the player requests the route to be sent to the EFB.
fsPlannedRouteUnregisterForRequest Unregisters a route request callback.
fsPlannedRouteRespondToRequest Responds to a player request to have the route to be sent to the EFB.

 

 

Typedefs

When using this API the following typedefs exist to help:

 

 

FsFlightAltitudeType

An enumeration that describes an altitude in the flight plan route.

typedef enum
{
  FsFlightAltitudeType_None,
  FsFlightAltitudeType_Feet,
  FsFlightAltitudeType_FlightLevel
} FsFlightAltitudeType;
  • FsFlightAltitudeType_None: The flight altitude is empty.
  • FsFlightAltitudeType_Feet: The flight altitude is in feet.
  • FsFlightAltitudeType_FlightLevel: The flight altitude is a flight level.

 

 

FsEnrouteLegType

The type of an enroute leg in the flight plan route.

typedef enum
{
  FsEnrouteLegType_Normal,
  FsEnrouteLegType_LatLon,
  FsEnrouteLegType_PointBearingDistance
} FsEnrouteLegType;
  • FsEnrouteLegType_Normal: The enroute leg is a normal leg defined by a fixed facility.
  • FsEnrouteLegType_LatLon: The enroute leg is a defined latitude and longitude point.
  • FsEnrouteLegType_PointBearingDistance: The enroute leg is defined as a distance in nautical miles at a specific bearing from a fixed reference facility.

 

 

FsRunwayIdentifierDesignator

The designator character for a runway (i.e. L, C, R) in a FsRunwayIdentifer.

typedef enum
{
  FsRunwayIdentifierDesignator_None,
  FsRunwayIdentifierDesignator_Left,
  FsRunwayIdentifierDesignator_Right,
  FsRunwayIdentifierDesignator_Center,
  FsRunwayIdentifierDesignator_Water,
  FsRunwayIdentifierDesignator_A,
  FsRunwayIdentifierDesignator_B
} FsRunwayIdentifierDesignator;

 

 

FsRunwayIdentifierNumber

The number of the runway in a FsRunwayIdentifier.

typedef enum
{
  FsRunwayIdentifierNumber_None,
  FsRunwayIdentifierNumber_1,
  FsRunwayIdentifierNumber_2,
  FsRunwayIdentifierNumber_3,
  FsRunwayIdentifierNumber_4,
  FsRunwayIdentifierNumber_5,
  FsRunwayIdentifierNumber_6,
  FsRunwayIdentifierNumber_7,
  FsRunwayIdentifierNumber_8,
  FsRunwayIdentifierNumber_9,
  FsRunwayIdentifierNumber_10,
  FsRunwayIdentifierNumber_11,
  FsRunwayIdentifierNumber_12,
  FsRunwayIdentifierNumber_13,
  FsRunwayIdentifierNumber_14,
  FsRunwayIdentifierNumber_15,
  FsRunwayIdentifierNumber_16,
  FsRunwayIdentifierNumber_17,
  FsRunwayIdentifierNumber_18,
  FsRunwayIdentifierNumber_19,
  FsRunwayIdentifierNumber_20,
  FsRunwayIdentifierNumber_21,
  FsRunwayIdentifierNumber_22,
  FsRunwayIdentifierNumber_23,
  FsRunwayIdentifierNumber_24,
  FsRunwayIdentifierNumber_25,
  FsRunwayIdentifierNumber_26,
  FsRunwayIdentifierNumber_27,
  FsRunwayIdentifierNumber_28,
  FsRunwayIdentifierNumber_29,
  FsRunwayIdentifierNumber_30,
  FsRunwayIdentifierNumber_31,
  FsRunwayIdentifierNumber_32,
  FsRunwayIdentifierNumber_33,
  FsRunwayIdentifierNumber_34,
  FsRunwayIdentifierNumber_35,
  FsRunwayIdentifierNumber_36,
  FsRunwayIdentifierNumber_North,
  FsRunwayIdentifierNumber_Northeast,
  FsRunwayIdentifierNumber_East,
  FsRunwayIdentifierNumber_Southeast,
  FsRunwayIdentifierNumber_South,
  FsRunwayIdentifierNumber_Southwest,
  FsRunwayIdentifierNumber_West,
  FsRunwayIdentifierNumber_Northwest
} FsRunwayIdentifierNumber;

 

 

FsApproachProcedureType

The type of procedure in a flight plan route's procedure identifier. Specifying FsApproachProcedureType_None indicates no approach procedure has been selected.

typedef enum
{
  FsApproachProcedureType_None,
  FsApproachProcedureType_Gps,
  FsApproachProcedureType_Vor,
  FsApproachProcedureType_Ndb,
  FsApproachProcedureType_Ils,
  FsApproachProcedureType_Localizer,
  FsApproachProcedureType_Sdf,
  FsApproachProcedureType_Lda,
  FsApproachProcedureType_VorDme,
  FsApproachProcedureType_NdbDme,
  FsApproachProcedureType_Rnav,
  FsApproachProcedureType_Localizer_Backcourse
} FsApproachProcedureType;

 

 

FsRouteIcao

A struct that represents a MSFS ICAO facility identifier.

typedef struct {
  char type;
  char region[3];
  char airport[9];
  char ident[9];
} FsRouteIcao;
  • type: The one character type of the facility. Valid types are:
    • \0 - Null character, representing an empty identifier
    • V - VOR Facilities
    • W - Waypoint Facilities
    • N - NDB Facilities
    • A - Airport Facilities
    • R - Runway Facilities
    • U - User identifier that is not a MSFS facility
  • region: The null-terminated two character string representing the ICAO region code in which this facility resides.
  • airport: The ident of the corresponding airport, for terminal facilities or runways.
  • ident: The ident of the facility.

 

Examples

For the JOT VOR near Chicago, Illinois, US:

FsRouteIcao icao = {};
icao.type = 'V';
strcpy(icao.region, "K6");
strcpy(icao.ident, "JOT");

Or runway 27L at Heathrow:

FsRouteIcao icao = {};
icao.type = 'R';
strcpy(icao.region, "EG");
strcpy(icao.airport, "EGLL");
strcpy(icao.ident, "RW27L");

 

 

FsRunwayIdentifier

A structure that identifies a runway at an airport.

typedef struct
{
  FsRunwayIdentifierNumber number;
  FsRunwayIdentifierDesignator designator;
} FsRunwayIdentifier;

 

 

FsVisualPattern

A structure that describes a visual departure or approach pattern selected on the EFB.

typedef struct FsVisualPattern
{
  int pattern;
  bool isLeftTraffic;
  float distance;
  float altitude;
} FsVisualPattern;
  • pattern: An integer that identifies the type of pattern that was selected. The valid numbers will differ between departure patterns and approach patterns:
    • Departure Patterns:
      1. 0: No pattern was selected
      2. 1: A straight-out departure pattern was selected
      3. 2: A single-turn departure pattern was selected
      4. 3: A turn into downwind pattern was selected
      5. 4: An overhead field departure pattern was selected
      6. 5: An initial climb pattern was selected
      7. 6: A direct to downwind pattern was selected
      8. 7: A direct to base pattern was selected
      9. 8: A base into circuit pattern was selected
    • Approach Patterns:
      • 0: No pattern was selected
      • 1: A downwind inside pattern was selected
      • 2: A plain downwind pattern was selected
      • 3: A downwind with close side 45 entry pattern was selected
      • 4: A downwind the far side 45 entry pattern was selected
      • 5: A direct to base pattern was selected
      • 6: A straight into final pattern was selected
      • 7: A straight into long final pattern was selected
      • 8: An over field teardrop into circuit pattern was selected
      • 9: A reverse over field teardrop into circuit pattern was selected
  • isLeftTraffic: True if the pattern is left traffic, false if right traffic.
  • distance: The downwind circuit leg distance.
  • altitude: The pattern altitude.

 

 

FsApproachIdentifier

A structure that identifies a selected approach procedure.

typedef struct
{
  FsApproachProcedureType type;
  FsRunwayIdentifier runway;
  char suffix[2];
} FsApproachIdentifier;
  • type: The type of the approach procedure.
  • runway: The runway associated with the procedure.
  • suffix: The single character null-terminated string representing any approach suffix.

Examples

For a selected approach of RNAV 27L Z:

FsApproachIdentifier approachId = {};
approachId.type = FsApproachProcedureType_Rnav;
approachId.runway.number = FsRunwayIdentifierNumber_27;
approachId.runway.designator = FsRunwayIdentifierDesignator_Left;
strcpy(approachId.suffix, "Z");

 

 

FsFlightAltitude

Defines an altitude in a flight plan route. Altitudes are expressed in feet. If an altitude is a flight level, the altitude will be the three numbers representing the flight level.

typedef struct
{
  FsFlightAltitudeType type;
  int altitude;
} FsFlightAltitude;

 

 

FsEnrouteLeg

A leg in the enroute portion of the flight plan route.

typedef struct
{
  FsEnrouteLegType type;
  FsRouteIcao fixIcao;
  char via[9];
  char* name;
  FsFlightAltitude altitude;
  double lat;
  double lon;
  FsRouteIcao pbdReferenceIcao;
  double bearing;
  double distance;
} FsEnrouteLeg;
  • type: The type of leg, whether it be a normal fixed facility leg, a lat/lon leg, or a relative point/bearing/distance leg.
  • fixIcao: The ICAO identifier of the fixed facility for the terminator of this leg.
  • via: An eight-character maximum null-terminated string containing the name of the airway via which this leg fix is reached. If used, this leg should be where the airway is exited. The airway legs that connect the previous leg (airway entry) and this leg will be automatically handled by consumers and must not be included in the route.
  • name: A pointer to a null-terminated string representing a human readable name for this leg, if any. This is mostly used to identify user waypoints with POI names.
  • altitude: The altitude at which this leg should be reached, if applicable. A FsFlightAltitudeType_None altitude indicates no altitude target.
  • lat: The latitude of the leg terminator, if a lat/lon leg.
  • lon: The longitude of the leg terminator, if a lat/lon leg.
  • pbdReferenceIcao: The ICAO identifier of the relative reference for a point/bearing/distance leg.
  • bearing: The bearing away from the reference facility with which a point/bearing/distance leg is defined, in degrees true north from [0-360).
  • distance: The distance away from the reference facility with which a point/bearing/distance leg is defined, in nautical miles.

 

 

FsPlannedRoute

A standardized flight plan route definining airports, procedures, and enroute legs.

typedef struct
{
  FsRouteIcao departureAirport;
  FsRunwayIdentifier departureRunway;
  char departure[9];
  char departureTransition[9];
  FsVisualPattern departureVisualPattern;
  FsRouteIcao destinationAirport;
  FsRunwayIdentifier destinationRunway;
  char arrival[9];
  char arrivalTransition[9];
  FsApproachIdentifier approach;
  char approachTransition[9];
  FsVisualPattern approachVisualPattern;
  FsFlightAltitude cruiseAltitude;
  bool isVfr;
  int numEnrouteLegs;
  FsEnrouteLeg* enrouteLegs;
} FsPlannedRoute;
  • departureAirport: The airport at which this flight plan route departs, if any.
  • departure: The eight-character null terminated string that is the name of the departure procedure, if one is selected.
  • departureTransition: The eight-character null terminated string that is the name of the departure to enroute transition, if one is selected.
  • departureVisualPattern: The selected departure visual pattern, if any.
  • destinationAirport: The airport at which this flight plan terminates, if any.
  • arrival: The eight-character null terminated string that is the name of the arrival procedure, if one is selected.
  • arrivalTransition: The eight-character null terminated string that is the name of the enroute to arrival transition, if one is selected.
  • approach: The identifier of the selected approach procedure, if any.
  • approachTransition: The eight-character null terminated string that is the name of the approach transition, if one is selected.
  • approachVisualPattern: The selected approach visual pattern, if any.
  • cruiseAltitude: The filed cruise altitude for the route.
  • isVfr: True if the filed route is filed as a VFR route, false if filed as an IFR route.
  • numEnrouteLegs: The number of enroute legs in the route.
  • enrouteLegs: A pointer to an array of FsEnrouteLeg defining the enroute legs of the planned route.

 

 

FsRouteRequestId

An alias for a route request identifier from the EFB.

typedef long FsRouteRequestId;

 

 

fsPlannedRouteBroadcastCallback

A callback signature for receiving routes sent from the EFB.

typedef void (*fsPlannedRouteBroadcastCallback)(const FsPlannedRoute* route, void* ctx);

 

 

fsPlannedRouteRequestCallback

A callback signature for receiving a route request from the EFB.

typedef void (*fsPlannedRouteRequestCallback) (FsRouteRequestId id, void* ctx);

 

 

 

 

 

 

 

Related Topics

  1. WebAssembly
  2. Platform Toolset
  3. Debugging WASM Gauges