Accessing the X-Plane autopilot from datarefs

Sim/cockpit/autopilot/autopilot_state
The autopilot state dataref summarizes all state and mode information from the autopilot.

Summary of Values

The following table summarizes all bit-field values.

Bit field (Decimal)	Bit field (Hex)	Name	Axis	Notes
1	00001	Autothrottle Speed Engage	Throttle	When the pitch axis is NOT speed-by-pitch, holds airspeed or mach number by manipulating the auto-throttle servos.
2	00002	Heading Select Engage	Lateral	Flies the selected magnetic heading.
4	00004	Roll Hold Engage	Lateral	Holds the selected bank (roll) angle.
8	00008	Speed-by-pitch Engage	Vertical	Holds the selected airspeed or mach number by manipulating pitch. Does not touch the throttle to do so. Note that when altitude is armed, this will be limited in pitch to the direction the pre-selected altitude is from the current altitude. For a true speed-by-pitch regardless of altitude, altitude hold must not be armed.
16	00010	V/S Engage	Vertical	Holds the selected vertical speed.
32	00020	Altitude Hold Arm	Vertical	Before X-Plane 8.11, altitude was “always armed” – that is, setting this would engage altitude immediately. In X-Plane 9.0, altitude was always armed. In 9.20 and 9.30, this was incorrectly mapped to “altitude engage” when written to. Now this correctly maps to the arm only. Note that an aircraft might still specify “altitude is always armed” in Plane Maker.
64	00040	Flight Level Change Engage	Vertical	Speed-by-pitch in combination with altitude preselect armed.
128	00080	Pitch Hold Engage	Vertical	Holds the selected pitch angle.
256	00100	Nav Armed	Lateral	Arms tracker/coupler to track a nav source (VOR radial, localizer or GPS course).
512	00200	Nav Engaged	Lateral	Tracker/Coupler tracks a nav source. Writable with overwrite – see below.
1024	00400	Glideslope Armed	Vertical	Arms vertical track of a nav source (ILS glide slope or GPS glide path).
2048	00800	Glideslope Engaged	Vertical	Tracks a vertical nav source (ILS glide slope or GPS glide path). Writable with overwrite – see below.
4096	01000	VNAV Speed Armed	Vertical	Speed-by-pitch mode to achieve FMS-selected speed to climb or descend to VNAV altitude or MCP altitude, whichever is more restrictive. Armed below 400ft.
8192	02000	VNAV Speed Engaged	Vertical	Speed-by-pitch mode to achieve FMS-selected speed to climb or descend to VNAV altitude or MCP altitude, whichever is more restrictive. Writable with overwrite – see below.
16384	04000	Altitude Hold Engaged	Vertical	Starting with X-Plane 9.40, you can directly engage the autopilot in this mode. See below.
32768	08000	TO/GA	Lateral	Since X-Plane 9.30. Holds wings level in take-off or go-around phase.
65536	10000	TO/GA	Vertical	Since X-Plane 9.30. Holds pre-determined pitch in take-off or go-around phase.
131072	20000	VNAV Path Armed	Vertical	Since X-Plane 9.40. Arms geometric descent. Use in conjunction with G1000 providing descent cues.
262144	40000	VNAV Path Engaged	Vertical	Since X-Plane 9.40. Flies geometric descent. Use in conjunction with G1000 providing descent cues. Writable with overwrite – see below.
524288	80000	GPSS Engaged	Lateral	Since X-Plane 11.10. Tracks GPSS regardless of HSI selected nav source. Use this to fly in LNAV mode while being able to arm Nav mode for localizer interception.
1048576	100000	Heading Hold Engaged	Lateral	Since X-Plane 11.10. Holds Heading at the time of engagement, ignores heading bug.
2097152	200000	Turn Rate Engaged	Lateral	Since X-Plane 11.30. Holds turn rate (as indicated by turn coordinator) instead of bank angle.
4194304	400000	Track Engaged	Lateral	Since X-Plane 11.30. Holds magnetic ground track corrected for wind.
8388608	800000	Flight Path Angle Engaged	Vertical	Since X-Plane 11.30. Holds flight path angle.

Axis Exclusivity

The above table lists various “axes”. Basically the internal autopilot can be in only one mode per axis. Those modes are:

Lateral – this mode controls the heading of the airplane.
Vertical – this mode controls the pitch of the airplane. Note that speed-via pitch is a vertical mode, because the plane’s vertical path will change as necessary to hit a target airspeed.
Autothrottle – this mode controls how the AP interacts with throttles – currently it is effectively boolean (autothrottle is “on” and will try to maintain target airspeed via thrust, or it is “off”). – For more modes, see sim/cockpit2/autopilot/autothrottle_enabled
FMS – the FMS mode is a hack: basically the FMS mode tells whether the FMS will copy current FMS target altitudes into the autopilot windows. No real-world airplane works like this, but X-Plane has had this ability as a poor-man’s way to fly a flight plan since X-Plane 6. Discontinued in X-Plane 12.

Note that back-course is not an axis – use the dataref sim/cockpit/autopilot2/backcourse_on or the command sim/autopilot/back_course.

Changing Dataref Values

Starting in X-Plane 740, this dataref can be written.
To change a dataref value, follow these rules:

Write ONLY the bit you want to toggle! If you want to toggle altitude hold arm, write only “32” to the dataref.
If you want to change modes in a certain sequence, write to the dataref multiple times. If you write a combined set of bits, the order that the commands are “executed” may not be predictable. For example, engaging heading mode normally clears localizer arm. So to set up for an approach, you want to first set only heading mode, then set only localizer arm. Otherwise, when setting both, there is a chance that the implementation could arm the localizer first, then set heading mode, which would clear the localizer arm.
Some modes will cancel other modes automatically. In particular, the sim must maintain exactly one lateral and vertical mode. So for example, engaging heading mode will clear out any of: wing leveler, HNAV. So in order to sanely write to the autopilot, you need to understand the “operational” meaning of each change, not just what lights you want to light up. (See below on overrides for more info.)

If you are not using overrides to completely replace the AP logic, you can accomplish the same effect as any bit-set by using the command system – see XPLMUtilities for more info. We strongly recommend all 2.0 plugins use the command system for maximum compatibility. If you are trying to simulate the pilot pressing a button, use the command system!

Starting in X-Plane 940, it is possible to set the “engage” bits directly – see Overriding the Autopilot Mode below.

Arm Vs. Engage

Some autopilot modes can be “armed”. In armed mode, when the AP mode changes are not overridden (see below) the AP will remain in its old mode, but will be “armed” – that is, listening for a chance to change modes later.

The most typical example is the localizer. When you arm HNAV mode to join a localizer, your lateral mode does not change. (That is, you are still flying via wing leveler or heading.) At a later time, when the localizer signal becomes available to the nav receiver that the AP is listening to, the AP will automatically engage HNAV mode, which naturally replaces the old lateral mode.

Arming state is not a mode on an axis, so arming is not mutually exclusive with other AP functions. You can arm everything at once if you want. Arming is permission for X-Plane to change modes later under certain conditions.

Altitude hold arm will engage altitude hold when the plane reaches the target altitude dialed into the AP dash.
NAV arm will engage when the AP crosses the lateral path we are going to follow (a localizer, GPS course line, etc).
Glideslope arm will engage when we cross the glide slope or GPS glide path from below with signal.
VNAV arm will engage when the AP crosses the vertical path we are going to follow (a geometric descent as part of a STAR for example).

Arm Vs. Engage For Altitude Hold

Unlike most other “arm” functions, it is actually possible to either arm or directly engage altitude hold mode, via two different commands (or bits in this dataref). Here is the difference in their operation:

Altitude hold engage: when altitude hold is engaged and we are not currently in altitude hold mode the autopilot will automatically stop climbing/descending and set the altitude-to-hold to the current altitude. Think of this as a “stop now” button.
- A plane-maker setting will cause X-Plane to optionally reset the altitude hold window on the AP dash to the current altitude.
Altitude hold arm: this simply arms altitude hold but does not engage altitude hold mode. The current altitude in the AP dashboard window is not changed.
- Plane-Maker has an option to always engage pitch-hold mode when altitude arm is commanded.
- Plane-Maker has an option to re-arm altitude hold mode in a wide variety of situations. Real G1000 planes are like this: you can’t turn off altitude arm unless you are on a glide slope or GPS vertical approach. This can be thought of as a safety feature: because alt-hold is always armed, the airplane can never climb or descend in an unbounded manner – there is always a set “stop point”.

Aliasing of Flight-Level Change With Speed Change

Starting with X-Plane 860, speed via pitch (vertical speed mode) and flight level change are no longer the same dataref. There is only one mode (“speed” mode) and the flight level change bits are aliased for compatibility. For the rest of this paragraph, we will refer to speed via pitch mode as “FLCHG” mode.
FLCHG mode interacts with the auto-throttle in the following ways:

For legacy aircraft, When FLCHG is engaged, if the autothrottle is enabled, power is increased to 100% throttle (climb) or 0% throttle (descent). This is a throttle position – FLCHG does not target an N1 or other engine output metric. Autothrottle is disabled.
For aircraft with the “Airliner” type autopilot selected in Plane Maker, When FLCHG is engaged, if the autothrottle is in speed mode, autothrottle goes to REF mode (climb) or RETARD (descent).
When altitude arm moves to engage, if FLCHG had been engaged, the autothrottle was disabled or in REF or RETARD for the FLCHG mode, the autothrottle speed hold is resumed.

Overriding the Autopilot Mode

You can use the dataref sim/operation/override/override_autopilot to disable X-Plane’s ability to spontaneously change autopilot modes.

When the override is set, the sim will still change AP modes in response to plugins and user-induced commands. However, the sim will not change modes automatically in response to reaching target altitudes, arm states, etc. These must be done manually by your plugin.

Additionally, starting in X-Plane 940, if this override is set, you can write the following engage modes directly into X-Plane:

512 (engage HNAV mode)
2048 (engage glide slope mode)
262144 (engage VNAV mode)

Note that engaging a mode when the sim is not ready for this mode (e.g. engaging the glide slope when there is no signal) will have unpredictable consequences.

Overriding the Autopilot Nav Heading

In X-Plane 940 you can override the heading the airplane flies in “NAV” mode with sim/operation/override/override_nav_heading
When this override is set you can:

Write to sim/cockpit/autopilot/nav_steer_deg_mag to control which way the plane flies.
Write “512” (engage HNAV) directly into the AP state. NAV mode will go from ARM to engage immediately to fly your heading.

IMPORTANT: There is a “gotcha” about overriding only the AP nav heading: when the autopilot mode is not overridden (see above) then the sim will automatically change from “hnav engaged” to “wing leveler” when there is no signal on the current receiver as selected by the CDI.
So if you are trying to override HNAV to fly a heading while the CDI is selecting NAV1 or NAV2 radios, and those radios have no signal, your write of “512” to engage HNAV will immediately be counteracted by X-plane, which will disengage HNAV completely due to no signal.
The solution is to override both the autopilot nav heading AND the entire autopilot mode states.

Avoiding Infinite Loops

Writing to this dataref works by issuing a sim command in most cases.

This means that if you write this dataref from a command-handler that is overriding an autopilot command, there is a good chance that you will put the sim into an infinite loop, like this.

User presses AP button.
Panel code issues AP command.
Plugin receives “first chance” at the command.
Plugin writes to autopilot_state dataref.
Dataref write handler issues an AP command. (Go back to step 3.)

To avoid infinite loops:

Trigger commands when possible, rather than writing this dataref. This will at least make it clear when there is an infinite loop risk.
To re-trigger the “default behavior” (e.g. user hits “hdg”, you change data, then you want X-Plane to really arm hdg) simply use the return value from the command handler to indicate that x-plane should receive. See XPLMUtilities for the command API.
If you need to cross-call a different AP mode (e.g. user hits “HNAV” but you want to go into “HDG” mode) be sure to set a recursion-check flag if your plugin can recurse back into the original command handler code! The sim will not detect this infinite loop, it will simply hang.

Deprecated Datarefs

These are the enum mappings for the older datarefs. Please avoid using them whenever possible; they will be discontinued!
sim/cockpit/autopilot/airspeed_mode sim/cockpit/autopilot/heading_mode sim/cockpit/autopilot/altitude_mode sim/cockpit/autopilot/mode_hnav sim/cockpit/autopilot/altitude_gls