Betaflight Altitude Hold and Position Hold: setup, first hover and what changed in 2026.6

Both modes are built on the same code as GPS Rescue, so a quad with a working rescue setup is most of the way there. Two things trip people up: the official guide uses CLI names that the firmware does not accept, and 2026.6 changed how Position Hold decides whether it knows which way the quad is pointing. This guide covers both versions.

What the modes do

Altitude Hold (ALTHOLD in the Modes tab) holds the height the quad had when you switched it on. The Betaflight guide says to expect 0.5-1 m of altitude stability in good conditions. Roll, pitch and yaw stay under your control, and the quad flies in Angle mode while the hold is active. The firmware forces Angle mode on even if you were flying Acro.

Position Hold (POS HOLD) adds horizontal control. With the sticks centred, the quad tries to stay over the point where you engaged it, and the guide puts the typical drift at 1-2 m. It controls position only, not height, so the guide says to run it together with Altitude Hold on the same switch.

When the hold is active, the OSD flight mode element shows ALTH or POSH.

Neither mode replaces GPS Rescue. If GPS Rescue starts, it takes priority over both holds.

What hardware you need

• Accelerometer. The modes are refused without it, and Betaflight will not arm with an uncalibrated accelerometer if one of these modes is set up on a switch.
• GPS. Position Hold needs a 3D fix. Altitude Hold can use GPS altitude, a barometer or both. Oscar Liang confirmed in the comments under his guide that Altitude Hold works with a barometer and no GPS.
• Barometer. Optional. The guide says a barometer helps when hovering, but it is affected by wind, gusts, prop wash near the ground, temperature changes and airspeed. The default altitude PIDs are tuned for GPS only and may be too aggressive with a fast barometer.
• Magnetometer. Optional but strongly recommended by the Betaflight guide. Without one, the quad has to work out its heading from GPS movement, which comes with conditions covered below.

Oscar Liang's wiring advice: connect the GPS to a hardware UART (TX to RX, RX to TX), not SoftSerial, because SoftSerial is limited to 19200 baud. A compass connects to SDA and SCL. Mount the GPS and compass away from VTX antennas, ESCs, motors, battery leads and action cameras. He also warns against putting conformal coating on the barometer and suggests covering it with a small piece of foam.

Firmware build options

Both modes are optional parts of the firmware, so they have to be selected when you build it in the Betaflight web app (app.betaflight.com). The guide's quick start begins with exactly this: include ALTITUDE_HOLD and POSITION_HOLD in the build. Add GPS, and the magnetometer if you have one.

After flashing, go to the Configuration tab and enable the accelerometer, and the barometer and magnetometer if fitted.

Setting up the switch

The Betaflight guide recommends putting both modes on the same switch. Oscar Liang uses a three-position switch instead:

Switch position	Mode
Low	Off
Middle	ALTHOLD
High	ALTHOLD + POS HOLD

Add the Fly Mode and Home Direction elements to the OSD. The OSD article in this series shows where to find them.

Two rules from the firmware worth knowing before the field:

• You cannot arm with either mode active. Betaflight sets a dedicated arming disable flag for each (ALTHOLD and POSHOLD), so if the quad will not arm, check the switch first.
• If you arm first and then flip the switch, the hold does not start until you raise the throttle. The guide describes a takeoff this way: arm, flip the switch (OSD shows POSH), lift off, and the hold takes over at about 1 m.

Hover throttle is the key setting

Altitude Hold needs to know roughly what throttle value keeps the quad in a hover. If the value is too low, the quad drops when you engage the hold. If it is too high, the quad climbs. The guide says the error corrects itself over time, but it is better to set the number close.

The setting is called ap_hover_throttle in the 2025.12 and 2026.6 source code, with a default of 1275. The Betaflight guide refers to it as hover_throttle. That name does not exist in the firmware. Oscar Liang's readers noticed the same mismatch, and the GPS Rescue article in this series uses the same names. If a command from the guide is rejected, run get ap_ in the CLI to see the names your firmware uses.

To find your value, hover in Angle mode with a normal battery, note the throttle value in the OSD or a Blackbox log, and enter it:

set ap_hover_throttle = 1350
save

The 1350 is only an example; use what your quad shows. The guide also mentions that hover throttle can be adjusted in the GPS Rescue submenu of the OSD menu, which saves a trip to the computer.

Flying with Altitude Hold

With the hold on, the throttle stick no longer controls motor power directly. It sets the climb or descent rate:

• In the dead zone around the hover throttle position, the quad holds height.
• At zero throttle, it also holds height. This is deliberate, so you do not fall out of the sky if you lower the throttle out of habit.
• Above the dead zone it climbs, below it descends, and at full deflection the default rate is 5 m/s.

The dead zone is set with alt_hold_deadband, default 20, which is 20% of the stick travel between hover throttle and each end of the range. The guide's example: with a hover throttle of 1400 and a 20% dead zone, the throttle holds height between 1320 and 1520. The maximum climb rate is alt_hold_climb_rate, default 50, which means 5 m/s. The guide calls this setting alt_hold_adjust_rate, another name that the source code does not use.

Exiting the hold needs attention. A code comment in the firmware explains that there is no smooth transition from the hold back to manual throttle, so your throttle should be near the hover position when you flip the switch. One of Oscar Liang's readers crashed after leaving Altitude Hold with the throttle at zero. Treat it like a handover: set the throttle to hover, then switch.

Other behaviour the guide describes:

• If you engage the hold while the quad is dropping fast, it overshoots and bounces before settling.
• If the quad is upside down when you engage it, it flips upright first.

Flying with Position Hold

With the sticks centred, the quad leans into the wind to stay in place. Moving the roll or pitch sticks beyond a small dead zone (pos_hold_deadband, default 5%) lets you reposition the quad. When you let go, it brakes and holds the new spot.

This part differs between versions:

• 2025.12: your sticks fly the quad in Angle mode, but your maximum angle is half of ap_max_angle (default 50°, so 25°). The autopilot itself may tilt the quad up to 50° to stop. The guide gives a hard stop from 10-15 m/s as an example of when it needs that much. The setting goes up to 70°.
• 2026.6: the release notes say stick inputs now request a target velocity, so you nudge the quad around without falling out of the hold. Full stick is set by ap_max_velocity, default 500 (5 m/s), and your maximum angle is the full ap_max_angle.

The 2025.12 guide also describes a sanity check: if the quad ends up more than 10 m from where the hold started (more if it was moving fast at the time), Position Hold gives up. In both versions, the OSD shows POSHOLD FAIL when the hold is requested but cannot work.

The heading problem without a compass

Position Hold has to know which way the quad is pointing. Without a compass, it uses the GPS course, which only becomes reliable after the quad has flown in a straight line.

In 2025.12 you have to allow this explicitly:

set pos_hold_without_mag = ON
save

Before engaging the hold, fly straight forward until the home arrow in the OSD points the right way. The guide mentions 50-100 m, sometimes more. If you skip this, the guide warns that the quad may tilt, fly in circles or fly away. Oscar Liang flew his quad without a compass for about 8 minutes of holding with this setting.

In 2026.6 pos_hold_without_mag has been removed, and a saved diff containing it will be rejected when you load it. Position Hold now waits until the heading is known before it starts. A new trust_mag setting (default OFF) decides whether the compass counts as a heading source at all. The release notes say to enable it only after you have checked that the compass is correctly oriented and calibrated:

set trust_mag = ON
save

Without a trusted compass, a period of clean nose-forward flight is still needed before Position Hold or GPS Rescue can work, and the OSD shows HEADING N/A while the heading is unknown. The release notes recommend a compass on any quad where a reliable rescue matters.

If you do use a compass, the 2025.12 guide suggests a check with a phone compass: point the quad north, east, south and west and compare the heading in the OSD or Configurator. It should read about 0 for north and 90 for east, with an error under 20°, and stay accurate when the quad is pitched forward or back by up to 60°.

First test

The order from the Betaflight guide and Oscar Liang's tests, adapted into a checklist:

1. Calibrate the accelerometer on a level surface. If the quad drifts in Angle mode, trim the accelerometer in the opposite direction to the drift.
2. Wait for a good GPS fix. Oscar Liang waits for at least 8 satellites.
3. Set the hover throttle from a normal Angle mode hover.
4. Take off in calm weather over an open area, climb to a safe height and switch on Altitude Hold only. Check that the quad does not jump or sag.
5. Without a compass: fly straight forward until the home arrow is correct. With 2026.6, wait until HEADING N/A disappears.
6. Switch on Position Hold. If the quad starts circling or drifting away, switch the modes off immediately and take control.
7. Before switching off, move the throttle to hover position.

When it does not work well

• The quad drops or climbs when engaged - hover throttle is off. Adjust ap_hover_throttle.
• It bounces in height with a barometer - the default altitude PIDs are tuned for GPS. The settings are ap_altitude_p, ap_altitude_i, ap_altitude_d and ap_altitude_f. Note that the defaults changed from 15 in 2025.12 to 30 in the 2026.6 source code, after the altitude controller was rewritten.
• It circles or wanders - heading problem. Check the compass orientation and calibration, or fly further in a straight line before engaging.
• It holds, but loosely - the horizontal controller uses ap_position_p, ap_position_i and ap_position_d. In 2026.6, GPS Rescue uses the same terms, so the release notes suggest tuning them while hovering in Position Hold.
• Debugging - the 2025.12 guide recommends a Blackbox log with set debug_mode = autopilot_position. In 2026.6 this debug mode was removed in the same change that removed pos_hold_without_mag.

Failsafe: if the radio link is lost while both holds are active, the guide says the landing stage of failsafe becomes a controlled descent over the current position. That is a useful fallback, but it does not replace a properly configured GPS Rescue.