Sim/cockpit/autopilot/autopilot state

From X-Plane SDK
Jump to: navigation, search

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 Engage Throttle
2 00002 Heading Hold Engage Lateral
4 00004 Wing Leveler Engage Lateral
8 00008 Airspeed Hold With Pitch Engage Vertical
16 00010 VVI Climb Engage Vertical
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.
64 00040 Flight Level Change Engage Vertical
128 00080 Pitch Sync Engage Vertical
256 00100 HNAV Armed Lateral
512 00200 HNAV Engaged Lateral Writable with overwrite - see below.
1024 00400 Glideslope Armed Vertical
2048 00800 Glideslope Engaged Vertical Writable with overwrite - see below.
New in X-Plane 8.11
4096 01000 FMS Armed FMS Before X-Plane 8.11 FMS mode was the same as glide-slope mode.
8192 02000 FMS Enaged FMS (In X-Plane 9, FMS does not have a separate arm and engage - use the "arm" choice.)
16384 04000 Altitude Hold Engaged Vertical Starting with X-Plane 9.40, you can directly engage the autopilot. See below.
New in X-Plane 9.30
32768 08000 Horizontal TOGA Engaged Lateral
65536 10000 Vertical TOGA Engaged Vertical
New in X-Plane 9.40
131072 20000 VNAV Armed Vertical
262144 40000 VNAV Engaged Vertical Writable with overwrite - see below.

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 thrusrt, or it is "off").
  • 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.

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.
  • HNAV 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 from below with signal.
  • VNAV arm will engage when the AP crosses the vertical path we are going to follow (e.g. a GPS vertical approach).

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

VNAV vs. FMS Mode

FMS mode is a legacy "mode" that copies FMS entries into the AP windows. See above; it is unrealistic, not found in real aircraft, and exists mainly for legacy compatibility.

VNAV mode is a true vertical planning mode, as found in a G1000 or FMS. However, it is not currently possible to set up and fly VNAV paths with the consumer-level sim. VNAV is only supported in conjunction with the G1000 compatibility option. (In this case a real G1000 provides vertical navigation.)

Aliasing of Flight-Level Change With Speed Change

Starting with X-Plane 860, speed via pitch (vertical speed more) 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:

  • 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.
  • When altitude arm moves to engage, if FLCHG had been engaged, the autothrottle was disabled for the FLCHG mode, the autothrottle 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.

  1. User presses AP button.
  2. Panel code issues AP command.
  3. Plugin receives "first chance" at the command.
  4. Plugin writes to autopilot_state dataref.
  5. 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!

  9 = discon
 10 = autothrottle
 13 = airspeed via pitch
  9 = discoin
 11 = heading mode
 12 = wing leveler
  9 = discon
 14 = vvi
 15 = alt mode arm
 16 = alt hold engage
 17 = fms arm
 18 = fms engage
 19 = lca
 20 = pitch sync
  9 = discon
 21 = loc arm
 22 = loc engage
  9 = discon
 23 = gls arm
 24 = gls engage