跳到主要内容

位置保持 2025.12

Betaflight 2025.12 引入了高度保持和位置保持。

两项功能同时使用时，飞行员拨动开关即可让飞行器在 Angle 模式下悬停在固定位置和恒定高度。随后可通过摇杆调整高度和位置。GPS 是必要条件，强烈建议使用磁力计（Magnetometer）。

快速开始​

  • 在固件构建中加入 ALTITUDE_HOLD 和 POSITION_HOLD。
  • 确认 GPS 工作正常。
  • 最好加入磁力计，并确认其工作正常。
  • 准确设置悬停油门值。
  • 在同一模式开关上启用高度保持和位置保持。
  • 检查飞行器在 Angle 模式悬停时不会漂移，即加速度计已正确校准。可通过摇杆在现场微调 Acc Cal。
  • 悬停四轴飞行器并谨慎测试。
  • 注意：飞行器将处于 Angle 模式，摇杆响应会与平时明显不同。

高度保持​

高度保持可独立于位置保持安装和测试。

高度保持旨在让四轴飞行器维持恒定高度，并按需自动调整油门。要稳定保持高度，油门必须置零，或位于正常悬停点两侧的死区范围内。将油门推到死区上方或下方，可上调或下调目标高度。

高度保持精度取决于多个因素，包括高度数据的准确性和稳定性、PID 值是否适合该构型，以及风力和阵风强度。在良好条件下，配合合理 PID，可期望高度稳定在约 0.5 至 1 米范围内。

若“单独”使用，即不启用位置保持，飞行器高度应保持稳定，但不会保持位置；横滚、俯仰和偏航仍按“正常”方式工作，飞行器始终处于 Angle 模式。

可靠的高度保持需要良好的高度来源。GPS 单独使用即可，但需要较多卫星，且其中部分卫星应位于较低仰角。有时启用气压计会改善高度估算，尤其在悬停时；但在阵风或大风、贴近地面、温度变化或飞行器速度变化时，也可能造成高度误差。可在 Configurator 的 Sensors 标签页检查高度估算的准确性和稳定性。默认 PID 面向纯 GPS 配置；若加入响应较快的气压计，默认值可能略偏激进。

飞行员必须在 Configurator 的 Modes 标签页配置模式开关以启用高度保持。

功能激活后，只要油门保持在正常悬停油门摇杆位置附近的死区内，飞行器应维持恒定高度。

要调高高度，应把油门推到死区上方；飞行器应以与摇杆位置成比例的速度爬升。全油门时，默认按 alt_hold_adjust_rate 以 5 m/s 爬升。油门位于死区下方时，飞行器会以恒定速率下降。但若将油门完全拉到底、置零，飞行器会悬停，既不爬升也不下降。将油门快速拉至零可视为进入“定高悬停”的一种捷径。

启动高度保持时，油门初始设为 CLI hover_throttle 值。PID 控制器随后围绕该悬停值调整油门以保持高度。若 hover_throttle 过低，启动高度保持时四轴飞行器会立刻下降；若过高，则会立刻爬升。应依据启动瞬间的响应微调该值。设置正确时，启动时不会出现高度突变。在飞场可通过 GPS Rescue OSD 子菜单调整悬停油门值。

要维持恒定高度，油门必须设为以下之一：

  • 悬停油门值两侧的死区内；或
  • 零，即油门完全拉到底。

若把高度保持作为应对快速下坠的紧急措施启用，或飞行器正在快速爬升，都会发生过冲，且常有回弹。代码无法瞬间让飞行器停下，但应在数秒内回到启动时的高度。依赖此功能前，建议先验证这类情况下的表现。

可在倒挂状态下启用高度保持；四轴飞行器会翻正，并应保持该高度。

处于高度保持时，飞行器会进入 Angle 模式。若未同时启用位置保持，横滚、俯仰和偏航仍正常工作，只有高度受控。

CLI 选项

  • hover_throttle：启动高度保持时写入油门的初始值。设得过低，每次启动高度保持都会导致飞行器下坠。
  • alt_hold_adjust_rate：油门调节高度的响应速率。该响应有意设置得偏弱；默认全油门为 +5 m/s，零油门为 -5 m/s。
  • alt_hold_deadband：悬停油门两侧自动保持恒定高度的死区。默认值为 20，即 20%。例如悬停油门为 1400 时，20% 死区表示油门在 1320 至 1520 之间的任意位置都可悬停。

位置保持​

位置保持应通过把两项功能配置到同一模式开关上，与高度保持同时启用。

两者同时启用时，四轴飞行器的高度和位置均应保持恒定。飞行器会进入 Angle 模式，快速停止，然后在停止位置悬停。

停止后，飞行器应保持在目标位置 1 至 2 米以内，具体取决于 GPS 信号精度、风力及 PID 优化程度。更激进的 PID 保位更好，但会产生更多快速小幅修正；较温和的 PID 更平顺，但响应较慢。

位置保持要求良好的 GPS 信号；启用经过准确校准且工作正常的磁力计时效果最佳。

有磁力计时，起飞后即可立即获得准确的位置保持。

相反，没有磁力计时，飞行器必须以前倾姿态、合理速度直线飞行至少数秒，位置保持才会工作。在此之前，OSD 会显示警告 POSHOLD FAIL。

警告

若磁力计提供错误航向，或 GPS 航向数据已混乱，启用位置保持可能使飞行器大幅倾斜、绕圈，甚至高速飞离！

备注

有关磁力计设置，请参阅 Betaflight.com wiki。

在位置保持中，可通过超过 pos_hold_deadband 的横滚和俯仰输入调整目标位置。此时可使用摇杆移动甚至飞行四轴飞行器，感觉有些类似普通 Angle 模式，尤其是死区设得较小时。可在 CLI 中使用 pos_hold_deadband 调整死区；其单位是摇杆相对中心位置的百分比。若将 pos_hold_deadband 设为零，俯仰和横滚输入会被完全忽略，四轴飞行器的位置会锁定，直至切回模式开关。

摇杆响应会明显低于普通 Angle 模式。飞行员可指令的最大角度为 autopilot_max_angle 的一半，该值默认是 50 度。

摇杆回中时，飞行器的制停会比较猛烈，尤其在高速移动时。例如，四轴飞行器以 10 至 15 m/s 前进时，飞行器可能施加默认最大 50 度的后仰来刹住前速。为获得更平顺的减速，应在摇杆回中前先使用摇杆让飞行器减速。

若需要更激进的飞行行为，可将 autopilot_max_angle 提高到 70 度。

若位置保持和高度保持均正常工作，且 failsafe 设为 landing mode，四轴飞行器会在当前位置进入受控下降阶段，不会漂移或直接坠落。这比旧方法好得多。对于 failsafe，GPS Rescue 仍优先于 landing mode，并覆盖位置保持。

用户 CLI 选项​

  • pos_hold_without_mag = on：允许不使用磁力计的位置保持。
  • pos_hold_deadband：中心摇杆位置周围的死区，默认 5%。设为零时将忽略摇杆。较小死区更便于调整位置或飞行。
  • autopilot_max_angle：自动驾驶代码在急停时可施加给飞行器的最大角度。默认 50 度、最大 70 度。飞行员可指令的最大角度是该值一半。
  • autopilot_position_P：位置保持的 P 值。另有 PID D、I 和 A 值，其中 A 为“加速度”（Acceleration）。默认均为 30。数值过高会振荡，过低则控制松散。调整时务必谨慎，每次仅调整一项以了解其作用。
  • autopilot_position_cutoff：施加于 PID D 和 A 值的平滑滤波器。默认 80，即 0.8 Hz；该值下仍会有些抖动。50 会平顺很多，但位置控制会变得模糊；200 则非常抖。请按需求选择。
  • gyro_filter_debug_axis：选择将俯仰或横滚距离及 PID 记录到 autopilot_position Debug。

起飞前检查​

  • 若使用磁力计，请在 Configurator 主界面仔细验证航向。将航向值与手机指南针对照：机头朝北时 Mag 应接近 0，朝东接近 90，朝南接近 180，依此类推。不必完美，但误差应小于 20 度。还应确认其在俯仰 +/- 60 度时仍保持准确。
  • 在 Angle 模式悬停，确认 Acc 已校准且悬停稳定。可通过摇杆微调到理想悬停。
  • 先单独测试高度保持，确认启用瞬间不会立即掉高或爬升。调整 hover_throttle，直至启用高度保持时高度不突变；练习用油门上下调整高度。
  • 随后在同一模式开关上启用位置保持。确保 GPS 卫星数量充足。
  • 飞行器没有 Mag 时，必须以合理速度直线前飞至少 50 至 100 米，有时更远，且不输入横滚或偏航；直至直接朝 Home 点飞行时 Home Arrow 笔直向上。这会将飞行器航向“校准”到 GPS 航向信息。未完成此步骤，位置保持不可用也不会工作。
  • 飞行器有 Mag 时，无需担心前飞校准；起飞瞬间即可使用位置保持。
  • 准备测试位置保持时，在离地数米处以 LOS 悬停，同时启用高度保持和位置保持。准备随时关闭位置保持开关或立即上锁。飞行器应保持原位，可能在约 1 米半径内漂移。
  • 若飞行器立刻以异常角度飞走或无规律绕圈，说明 Mag 或 GPS 的航向信息错误。无 Mag 时，请再次以合理速度直线飞行 50 至 100 米，且不输入横滚或偏航。
  • 若抖动严重或发生振荡，PID 过高。
  • 确认可用横滚和俯仰摇杆调整位置。请谨慎、轻柔操作，它不会有“正常”手感。要减速时应平顺操作，或在摇杆回中前反向俯仰输入手动消除速度；否则高速急停会造成突兀俯仰变化，因为飞行器会尽可能快速地制动。
  • 在 FPV 使用前，先通过 LOS 飞行充分熟悉位置保持的“控制感”。

安全功能​

  • 处于位置保持或高度保持时，飞行器不能解锁。
  • 以下情况下位置保持不会工作：
    • 没有 GPS 3D 定位；
    • 没有 Mag，且由于飞行器未以足够长时间、足够速度、干净的前倾直线飞行，GPS 尚未提供可用航向；
    • 有 Mag，但 GPS 航向无法作为备用，必须使用 Mag（见上文），而 Mag 处于“不健康”状态，即损坏或从未校准。
  • 尝试位置保持时，若上述任一检查失败或合理性检查失败，OSD 会显示 POS HOLD FAIL。
  • 默认要求 Mag。只有执行 set pos_hold_without_mag = on 才允许无 Mag 的位置保持。
  • 若 pos_hold_without_mag 设为 on 且没有 Mag，起飞后不能立即使用位置保持；只有 GPS 提供有用航向后才会允许。用户必须以前倾姿态直线飞行至少数秒，不输入横滚或偏航，以便将 IMU 对准 GPS。在完成对准前，位置保持不会启动，OSD 会显示失败警告。
  • 飞行器解锁后启用位置保持，OSD 飞行模式会显示 POSH；四轴飞行器会启动 Angle 模式并等待油门抬升。油门抬升后飞行器应起飞，到离地约 1 米时位置保持会接管。
  • 若位置保持无法维持在距离起始点 10 米以内，会由简单的合理性检查终止；若启用时四轴飞行器高速移动，允许距离会提高。
  • GPS Rescue 会覆盖位置保持并正常工作。
警告

若上电后立即启用位置保持，而 GPS 定位较差，高度和位置控制都可能不稳定。稳定的高度与位置数据以及良好的 GPS 定位，对位置保持至关重要。

调试：检查 PID 等​

在 CLI 中执行 set debug_mode = autopilot_position，即可记录位置保持的目标、距离和 PID。

最简单的基本测试是让飞行器直接向北飞行，仅做俯仰调整，并使用 set gyro_debug_axis = pitch 记录俯仰值。设为 Pitch 时，日志记录南北方向（纬度）的 PID；设为 Roll 时，记录东西方向（经度）的地球坐标系轴数值。

通道说明
0到目标的绝对距离，单位 cm
1选定地球坐标系轴上到目标的距离
2选定地球坐标系轴上的 pidSum，单位 degrees*10
3请求的俯仰或横滚角，单位 degrees * 10
4选定地球坐标系轴上的 P，单位 degrees*10
5选定地球坐标系轴上的 I，单位 degrees*10
6选定地球坐标系轴上的 D，单位 degrees*10
7选定地球坐标系轴上的 A，单位 degrees*10

注意：

  • 四轴飞行器的南北和东西运动各有独立的 PID 控制器。
  • A 表示“加速度”（Acceleration），即四轴飞行器速度的变化。
  • 原始 GPS 信息也会照常记录，例如 GPS 速度、卫星数等。

位置保持的工作原理​

启动时，目标位置设为当前 GPS 位置。每次 GPS 更新四轴飞行器的位置时，系统都会以厘米精度分别计算目标点南北方向（纬度）和东西方向（经度）的“误差”距离。每个方向的误差均独立通过 PIDA 控制器处理。对两个地球坐标系轴而言，P 因子响应误差大小，D 与 A 因子抵抗速度及速度变化，I 因子响应随时间积累的误差，例如稳定风造成的偏移；由此得到纬度与经度的 pidSum 值。

这些 pidSum 会转换为一个指向目标点的矢量。四轴飞行器必须向该方向倾斜以修正当前位置偏差。为确定倾斜方式，代码会取得机头相对北方的航向角，并将其与同样在地球坐标系中、相对北方的所需修正角比较，然后施加相应的俯仰和横滚修正。飞行员偏航时，系统按需更新俯仰和横滚轴。举例而言，若四轴飞行器正顶着逆风大幅前倾，随后偏航 90 度，全部俯仰角会无缝转换为横滚。

摇杆移出死区时，控制权交给普通 Angle 模式控制器，飞行员完全以 Angle 模式飞行，手感良好。飞行期间系统会检查位置、速度和加速度值。摇杆回到死区后，位置保持会以该位置为临时目标恢复，并进入 D 值大于平常的特殊“制停”阶段；PID 随后主动停止运动。四轴飞行器最终停止时，系统会将该轴的位置重设为停止点，飞行器便保持在那里。

草案 v1.1