磁力计 / 电子罗盘

注意

以下说明仅适用于 Betaflight 4.5 或更高版本中的磁力计。

除非已确认以下各项，否则请勿使用磁力计：

磁力计各轴方向正确
校准准确
返回的数据干净且无噪声
已在 CLI 中输入正确的本地磁偏角
磁力计返回的航向正确
加速度计（Acc）已启用、方向正确并完成校准
固件中已包含并启用 GPS，以便查看航向数据

简介

磁力计是一种三维电子罗盘，可在三个正交轴上返回磁场强度。磁力计数据用于估计四轴飞行器的“航向”，即机头与“真北”之间的夹角（以度为单位）。正确配置后，例如机头正对东方时应返回 90°，正对南方时应返回 180°，以此类推。

磁力计信息可改善 GPS Rescue 在爬升和下降阶段的表现；在这些阶段，风和漂移可能使仅依赖 GPS 的航向判断失准。它也是实现精确位置保持所必需的功能，后续版本将对此提供支持。

Configurator 会在主 Setup 页面、GPS 选项卡中以数值显示磁力计航向，并在 GPS 选项卡的地图上以图形方式显示。

摘要

使用三维电子罗盘前，请通读整篇文档。
必须自定义构建固件并包含磁力计支持。
磁力计必须与飞控同时上电。
CLI status 命令必须显示已连接的正确硬件。
磁力计方向必须正确，并且必须完成方向检查。
磁力计必须准确校准。
必须在 CLI 中设置本地磁偏角。
必须在 Configurator 中检查磁力计航向，并与手机罗盘报告的数值比较。
用户必须在测试飞行中确认仅由磁力计提供的航向正确：启用磁力计、禁用 GPS，并在 OSD 中显示航向。
启用磁力计前，必须先在不使用磁力计的情况下确认 GPS Rescue 工作正常。
随后加入磁力计时，必须谨慎测试 GPS Rescue。使用磁力计后，初始转向/爬升阶段和下降阶段的航向控制应更准确，尤其是在有风条件下。若它未改善救援效果或引发问题，请勿使用磁力计。

危险

在你绝对确认磁力计数据准确、可靠之前，若依赖 GPS Rescue，切勿启用磁力计！

什么是磁力计？

磁力计是用于检测本地磁场¹强度和方向的三轴器件。

磁力计传感器会在 X、Y、Z 三个互相垂直的轴上输出数据。通常约定 Z 轴向上、X 轴向前、Y 轴向左。常见的 QMC5883L 就遵循该约定，但部分磁力计的轴向不同。

当磁力计的任一轴与磁力线平行并指向磁场北端时，该轴会返回最大正值，其余两轴返回零。反过来，当它指向磁场南端时，同一轴会返回最大负值，其余两轴返回零。可在 Sensors 选项卡中使用 MAG_CALIB 调试模式查看这些原始值；这也是检查模块轴向的方法。

警告

四轴飞行器上磁力计的安装方向至关重要。在 Betaflight 中，磁力计数据必须按以下方向返回：

X 轴必须指向前方。
Y 轴必须指向左方。
Z 轴必须指向上方。

始终使用 Sensors 选项卡确认传感器方向正确。若使用 IST8310，其不符合该约定的 Y 轴方向必须通过自定义配置修正，即将 Y 轴旋转 180°。

Betaflight Configurator 图 1 - Betaflight 要求的磁力计轴向及其相对于飞行器的方向。

关于地球磁场

地球磁场¹并不均匀。磁力线通常会偏离地理北极数度，并在北半球向下、在南半球向上。磁场方向和强度都会因地点而异。

地球磁场通常使用 NED（北-东-下）参考坐标系表示。即地磁场 X 轴指北、Y 轴指东、Z 轴指下。此表示方式与 Betaflight 的磁力计安装方向无关，但在解读所在位置报告的磁场强度和方向时可能有用。

绝对场强以高斯或毫特斯拉为单位，1.0 高斯 = 0.1 毫特斯拉。在作者所在位置，场强约为 0.57 高斯。Betaflight Sensors 选项卡显示传感器报告的数值，该数值取决于传感器增益，增益可在规格书中查到。例如，QMC5883L 在 1 高斯场强下返回 3000；因此，在悉尼，当该传感器校准后直接对准磁场时，预期读数为 1710。

在地球某一点测量磁场时，测得的是本地磁场矢量。该矢量通常会偏离地理北极数度，并在北半球斜向地下、在南半球斜向天空。不同地球表面位置的角度偏差可能很大，尤其是向上或向下的夹角。

地球磁场相对于地理北极的横向偏差称为磁偏角（magnetic declination）。它以度为单位；正值表示磁北位于地理北的东侧。

磁场指向地表内部（或外部）的角度称为磁倾角（magnetic inclination）或磁倾（magnetic dip）。physicsmax.com²提供了直观的说明和图示。磁倾角以“指向地面”的角度计量：北半球磁场指向地下，磁倾角为正；南半球磁场指向天空，磁倾角为负。

可通过 NOAA³ 等在线来源，或 magnetic-declination.com⁴ 等提供可点击地图的网站，查询本地磁偏角和磁倾角。

以澳大利亚悉尼（151°E、34°S）为例，地磁场位于地理北以东 13°，并以 65° 的陡峭角度向上离开地面。也就是说，磁偏角为 13°，磁倾角为 -65°。若磁力计方向正确，当四轴飞行器机头指向北偏东 13°、向上 65° 时，磁力计 X 轴应获得最大正值，Y、Z 轴接近零。

在 CLI 中设置本地磁偏角

Betaflight 4.5 引入 CLI 变量 mag_declination，用于修正磁偏角偏移。正确设置后，Betaflight 将返回“真北”而非“磁北”；GPS 对地航向同样返回真北。

磁偏角值应以十分之一度输入。在上述示例中，set mag_declination = 130 可修正 13° 的正磁偏角，set mag_declination = 34 可修正 3.4° 的正磁偏角。若本地磁偏角为负，例如 -3°，应输入 set mag_declination = 3570（即 3600 - 30）。

备注

在 2025.12 固件中，磁偏角范围改为 30 度。 13° 仍设置为 130，但 -3° 必须初始化为 -30。

mag_declination 表示真北与磁北之间的角度差。有人居住区域的磁偏角处于 +- 30 度范围内。该限制应避免将磁偏角用于其他用途。

安装磁力计

若将磁力计物理安装在与飞控相同的平面上（例如均平贴机架），修正方向问题会容易得多。

大多数独立磁力计模块（如 GY-271）的传感器焊在电路板顶部，通常 Z 轴向上、X 轴向前（箭头方向）。这类板通常不需要“翻转”（flip）方向。最佳安装方式为：

位于中心位置。
与飞控处于同一平面，通常两者均“平贴机架”。
尽量远离电机、其他金属物体和大电流导线。
X 轴直接指向四轴飞行器机头，Y 轴向左，Z 轴向上。

大多数 GPS 模块中的传感器是倒装的，Z 轴指向下方，需要使用**“翻转”**方向。

许多 GPS 模块安装时会带有前俯角。这会使磁力计产生前俯角，导致常规方向修正无效；此时需在 CLI 中设置自定义磁力计方向。若磁力计位于 GPS 内，将 GPS 平装并与飞控保持同一平面会容易得多。

请注意，传感器可能以 X 轴向前、向后、向左或向右的方式焊接在 GPS 或独立模块上；模块本身也可能正向、侧向或反向安装在四轴飞行器上。因此，X 轴常常无法相对机头指向正确方向。这正是使用磁力计前始终应检查 X 轴方向的原因。

应使用 Betaflight 地面站中的“磁力计朝向”设置（命令行中的 align_mag）修正方向。常见安装错误可使用标准修正（例如 CW90 表示将轴顺时针旋转 90°）。若模块后仰或处于非常规角度，则需要 custom 方向修正。详情见下文“磁力计方向”一节。

硬件与连接

必须在 Betaflight 构建系统的云构建下拉菜单中包含“磁力计”，或在本地构建中加入 -DUSE_MAG；否则固件没有磁力计支持。该构建选项会包含所有受支持磁力计的驱动程序。

无论是否使用 GPS，构建时还应包含 GPS 固件支持。

Betaflight 为下列磁力计提供驱动，但在本文编写时，并非全部均已验证可在 Betaflight 4.5 中正常工作：

QMC5883L⁵：常见且低价的 GY-271 模块和许多 GPS 单元均使用 QMC5883L。它提供 200Hz 数据更新率、8 倍采样平均和 3000 LSB/高斯灵敏度，轴向为标准方向，默认 I2C 地址为 13。若你的构建可以选择它，建议使用该磁力计：其性能已在测试中验证，已知工作良好。该型号于 2025 年停产，由下方的 QMC5883P 替代。
QMC5883P⁶：上述 QMC5883L 的后继型号。其规格有所升级，例如量程增大至 30 高斯（与地磁场无关）且灵敏度更高。与 QMC5883L 一样，具备内置温度补偿、最高 200 Hz 数据输出率和最高 8 倍过采样。相较 QMC5883L，QMC5883P 增加了下采样滤波器以改善噪声表现。
IST8310⁷：该磁力计的轴向非常特殊。当 X 向前、Z 向上时，Y 指向右侧。IST8310 始终需要在 CLI 中设置自定义轴向。其数据更新率为 160Hz，使用 16 倍采样平均，灵敏度为 330 LSB/高斯。IST8310 还可使用四种 I2C 地址之一，取决于飞控制造商的接线方式。地址设为 14 时，Betaflight 驱动会自动连接；若未自动连接，请将 mag_i2c_address 依次设为 12、13 或 15，其中之一应可工作。
STM 的 LIS3MDL⁸：该磁力计集成在 STM 的陀螺仪、加速度计和磁力计“九轴”组合芯片中，轴向标准。该型号已淘汰，替代型号为下方的 LIS2MDL。
LIS2MDL⁹：STM 的另一款磁力计。请注意，Betaflight 驱动会反转 X 轴，以适配常见的传感器轴向并与上述 LIS3MDL 方向一致。因此，若按照芯片标记本应设置为顺时针 180°，则应使用顺时针 0°，反之亦然。正交方向同理：按芯片标记本应为顺时针 90° 时，应改为顺时针 270°，反之亦然。
HMC5883L¹⁰：ODR 为 75Hz，灵敏度为 1090 LSB/高斯；已停产，由 QMC6883L 替代。轴向标准，已验证。
已弃用：AK8963¹¹ 和 AK8975¹²（均已停产；部分版本 Z 轴向上，另一些向下，但在 X 轴向前安装时均返回标准轴向）。

警告

AK8963 和 AK8975 驱动代码已在 Betaflight 4.5 中弃用，未来某个版本将移除。这些磁力计可能可以、也可能无法在 Betaflight 4.5 中工作。开发者没有这些设备，因而无法测试。使用这些磁力计搭配 4.5 时请格外谨慎。请确认磁力计任务不会对其他 I2C 设备造成问题，并确认这些设备的数据可用。强烈建议使用 QMC5883L 之类仍在使用的磁力计。

用户应在 CLI 中保留默认值 set mag_hardware = AUTO，让 Betaflight 自动识别磁力计并选择正确驱动。

注意

磁力计会在上电时检测。务必确保磁力计与飞控同时上电。

磁力计通常通过 I2C 连接。所有受支持磁力计的规格最高只支持 400Hz“快速模式”。将模块的 SCL、SDA 引脚分别连接至飞控同名引脚，并按模块要求使用 5V 或 3.3V 供电。

通过 I2C 连接时，以下 CLI 设置通常可用：

set mag_bustype = I2C
set mag_i2c_address = 0（从已连接的磁力计自动确定）
set mag_i2c_device = 1（取决于飞控引出的 I2C 总线；若板级配置正确，通常会自动设置）

若未检测到磁力计：

飞控可能使用 I2C 设备 2 而非设备 1 来连接外部 I2C 磁力计或气压计芯片。请检查飞控数据手册；可尝试 set mag_i2c_device = 2 观察是否能连接。
IST8310 可能未连接在默认地址 14。若设置 set mag_i2c_address = 0 后仍未检测到，请尝试将 mag_i2c_address 设置为 12、13 或 15。

当固件包含磁力计支持、加速度计已启用，且受支持的磁力计已正确接线时，可在 Betaflight 地面站的“传感器”选项卡中启用并保存磁力计。此后：

顶部的磁力计硬件图标（N 上方带三角形）会点亮。
“配置”选项卡右上角会提供“磁力计朝向”设置。
在“传感器”选项卡顶部启用“磁力计”后，会显示当前 X、Y、Z 磁力计数值。
CLI 的 status 命令会显示检测到的磁力计硬件。

提示

使用磁力计时必须始终启用加速度计，以修正俯仰或横滚变化对航向估计的影响！

磁力计方向

无论磁力计如何安装，在使用前都必须确认其方向正确！

提示

当磁力计方向（对齐）正确时，Configurator 首页上的“四轴图标”应会随飞行器的偏航、俯仰和横滚平滑、正确地移动。请注意，当飞行器姿态变化非常快时，航向会先根据陀螺仪和加速度计数据快速响应，再在之后约半秒内按磁力计数据调整。若磁力计数据轴方向错误或校准不当，“四轴图标”起初会正确转动，随后迅速跳到错误航向。这是危险信号；需要修正方向并重新校准。

若可从电路板上的方向标记确认方向正确，即 Z 向上、X 向前，且模块未倒置；或者通过对照磁力计规格书中芯片的小圆点确认了方向，则默认或 CW0 对齐应当正确。

若磁力计正装但 X 轴向右旋转 90°，请选择 CW90，其余情况类推。

若磁力计倒装，请逐一选择“翻转”选项，直到找到正确项。

若磁力计处于自定义角度，请选择 CUSTOM 方向，并在 CLI 中输入以十分之一度为单位的修正值（见下文）。

请注意，“翻转”在功能上是围绕 Y 轴将磁力计旋转 180°。必须逐一尝试所有可能方向并检查，直至找到有效设置。对于 HMC5883L/QMC5883L，若能看到芯片本身，此帖¹³中的速查表可能有帮助。

使用 Configurator 的 Sensors 选项卡检查磁力计方向

备注

在使用 Sensors 选项卡检查磁力计方向前，请务必在 Configurator 的 Blackbox 选项卡将 Debug Mode 设置为 MAG_CALIB。

即使四轴飞行器没有 Blackbox Flash 或 SD 存储器，也可启用该调试模式。若没有闪存，请临时将 Blackbox Logging Device 设为 serial，无需配置端口。

然后在 Sensors 选项卡勾选屏幕顶部的 Debug。此时将实时看到磁力计实时数据和校准值。

顶部三个面板显示当前原始 X、Y、Z 磁场强度值，它们基于当前方向和校准值由传感器检测而得。这些信息可用于确认方向并监控校准过程。

此外，校准期间，下方面板会显示正在重新计算的校准值。校准过程刚开始时，这些值会出现尖峰。屏幕底部的 lambda 值会在校准完成时接近 2000，完成后降至零。校准完成后，可在此处查看 X、Y、Z 校准值。

备注

检查方向前，必须先对传感器进行一次“快速”校准！初始校准不必完美，但必须完成。

当某一轴与本地磁场完美对准时，另外两轴会显示零或接近零。若显示为明显正值（通常至少为 1000-2000），该轴指向磁场北端；若为明显负值，则该轴指向相反方向，即南方。

可利用这一点检查磁力计固定到四轴飞行器后的方向。最好远离大型含铁金属物体，例如在开阔场地进行。

测试前，需要大致了解本地地磁场的“北”方向。

首先取出手机，打开罗盘设置并设为返回 True North（而非“magnetic” North）。然后打开罗盘应用，在工作台或地面上标出一条指向真北/真南的线。此时请再次检查 Declination 值是否正确设置（见上文）。

然后查找本地的磁倾角值。

若处于北半球，在测试传感器 X 轴时，应使四轴飞行器机头沿南北磁力线，以该角度朝地面向下指。

若处于南半球，则应以该角度向天空向上指。

接着将四轴飞行器连接至 Configurator，按上述方式设置 Debug，打开 Sensors 选项卡，并尽可能让机头指向磁场方向。

若一切正确，X 轴应显示较大的正值，Y、Z 轴应显示较小且接近零的数值。稍微调整飞行器角度，应能使 Y、Z 轴非常接近零。若机头看起来指向北方、与地平线的角度正确，且 X 明显是最大值，则 X 轴方向正确！

将四轴飞行器偏航 180°，使机尾指向北方，X 轴应显示很大的负数，其他轴值较低。

至此，你已确认 X 轴方向正确！

接着将四轴飞行器向右转 90°，使飞行器“左侧”（即 Y 轴）直接指向磁北。若一切正常，Y 轴数据应为大数值，X、Z 轴接近零。

最后，使飞行器顶部直接指向磁场矢量。此时你应已清楚该方向。Z 轴应显示明显正值，X、Y 轴接近零。

尽管过程看似复杂，但这是 100% 确认磁力计方向正确的唯一方法。

若未获得预期结果，则需要对磁力计方向进行软件修正。持续尝试直至它正确工作。

请记住，若磁力计芯片倒置（大多数 GPS 模块中均如此），需要使用“翻转”方向。应从一开始就设好此项。

非常规磁力计方向的软件修正

要正确设置这些修正，必须了解测试环境中的磁力线方向。在修正方向前，磁力计必须已在某个阶段完成校准。

目标是在 Sensors 选项卡中取得以下结果：当指定的飞行器部位与磁力线平行时：

与磁力线平行的机架部位	X 轴	Y 轴	Z 轴
机头	最大	0	0
左侧	0	最大	0
顶部	0	0	最大

通常最好先在磁力计平装、与机架垂直方正且位于预定安装位置时进行初步测试。若磁力计在 GPS 内且计划让 GPS 略微后仰，先不处理倾斜；暂时保持平装，但务必选择 flip 方向。

一个好办法是先检查 Z 轴。确认当飞行器顶部直接指向本地磁力线“北端”时，它返回明显正值。若得到明显负值，传感器即为倒装。此时应应用 CW0_DEG_FLIP 修正，再继续检查 X、Y 轴。

检查 X 轴时，移动飞行器直到 X 出现正值，然后细调至 X 最大、Y 和 Z 为零。假设这发生在飞行器右侧与磁力线平行时，说明 X 轴指向飞行器右侧，即传感器顺时针旋转了 90°。假设 Z 轴向上，适当修正为 CW90；若 Z 轴向下，则应使用 CW90_FLIP。

每次尝试不同的软件方向后，都要重新测试：使机头指向磁力线，寻找 X 最大值；然后确认左侧与磁力线平行时 Y 最大；最后确认顶部与磁力线平行时 Z 最大。满足这些条件即完成，除非还计划让磁力计略微倾斜。

若磁力计是独立模块，若可能，最简单的方法必然是将其平贴安装在飞行器上，使 X 向前、Z 向上。

若磁力计位于 GPS 内，且希望让 GPS 以例如 30° 后仰，则还需额外进行 30° 修正，使磁力计也后仰 30°。

遗憾的是，这意味着不能使用简单的标准 CW0 类修正。必须在 CLI 中通过 set align_mag = custom 启用自定义磁力计对齐。然后为每个需要修正的轴输入数值，例如 set mag_align_pitch = 300，可补偿 30° 的俯仰方向问题。

最好按以下步骤进行：

先确定模块平贴机架时有效的标准修正。
将其转换为各轴以度为单位的一组自定义修正。
确定为修正模块俯仰偏移所需的最终调整。

示例如下：

若模块不需要修正，即在平装、CW0 或默认方向下 X 向前、Z 向上且工作正常，随后将其后仰 30°，使用 set align_mag = custom 和 set mag_align_pitch = 300 应可修正。

若模块平装时需要 CW90 修正，则使用 set align_mag = custom、set mag_align_yaw = 900 和 set mag_align_roll = -300 的组合，可修正模块后仰 90° 的情况。由于传感器在逻辑上旋转了 90°，需在横滚轴上修正。

若模块需要 CW90FLIP 修正且再后仰 30°，则需使用 set align_mag = custom、set mag_align_pitch = 1800、set mag_align_yaw = 900 和 set mag_align_roll = 300。

请注意，若电路板旋转了 90°，俯仰修正必须通过横滚轴完成。

磁力计校准

要获得准确航向，准确校准不可或缺。可在飞场或连接 Configurator 时完成。若接收机和磁力计均由 USB 供电，飞场可使用便携式 USB 电源而非 LiPo。

校准会“归零”四轴飞行器附近含铁物体（如附近的电路板元件）产生的本地磁场，以及传感器固有偏移。

连接 Betaflight 地面站后，可在“设置”选项卡点击“校准磁力计”按钮启动校准，也可通过摇杆命令启动。飞行器必须处于未解锁状态。

某一轴的“中心”或“校准”值，是该轴检测到的最小值和最大值之间的中点。随后会从该轴每个读数中减去该“校准”值，使所有读数以零为中心。应用校准值后，每个轴报告的最大正值与最大负值在数值上应大致相等、符号相反。

校准值会保存到 CLI 参数 mag_calibration，并可编辑。例如 set mag_calibration = 35,-130,-75 会使航向代码从每个 X 读数减去 35、向每个 Y 读数加 130、向每个 Z 读数加 75。

为获得最准确的校准结果：

在预定飞行地点或附近校准四轴飞行器。
校准时远离外部金属或磁性物体。
多次执行，并确认每次校准值一致。
（仅限专家）验证每轴的绝对最小和最大读数相等。
考虑拆除电机。

备注

附近电机的磁干扰会严重影响校准。

若缓慢转动电机时，地面站“设置”选项卡的飞行器图标抖动、磁力计航向值显著变化，或“传感器”选项卡中的磁力计数据抖动，则可能存在问题。飞行时这些偏移应会平均掉，但校准时不会。因此，无论多么谨慎地重复测试，都可能得到奇怪且不同的校准值。多次校准结果的平均值可能最准确。电机距离越远、磁力计相对于电机平面越高或越低，问题越小。

一旦获取，在本地范围内通常无需频繁修改校准值。若远离常用飞行地点，可能需要更新或检查。

启动校准

重新校准前，最好记录之前的校准值，特别是此前值正确时。可通过 Preset>Save 命令或在 CLI 中执行 get mag_calibration 记录。若飞行器从未校准，值为 0,0,0。

校准时飞行器必须未解锁。

15 秒延迟使你有时间用摇杆启动校准、放下遥控器、拿起飞行器；准备好后晃动飞行器，即可开始采集数据。

有两种方式可启动校准过程：

在地面站中点击“校准磁力计”按钮，并保持通过长 USB 线连接；或者
在 Mode 2 遥控器上使用摇杆命令（务必确认飞行器未解锁！）：
- 右摇杆直下（俯仰最低，横滚居中）。
- 左摇杆推至右上角（油门最高，偏航完全向右）。

若有蜂鸣器，将发出两声短鸣，确认已启动校准过程。

随后有 15 秒准备时间。准备好后，以超过 350 度/秒的速度晃动机架，开始采集校准过程本身的数据。

达到运动阈值后，飞控 LED 常亮，蜂鸣器播放快速 7 声提示。随后在 30 秒内以三维方式移动四轴飞行器，以采集球面分布的数据。

若未达到运动阈值，飞控 LED 会继续规律闪烁；15 秒后将发出“两声长鸣”的失败提示。

校准过程完成时，即达到运动阈值 30 秒后，飞控 LED 恢复正常闪烁，蜂鸣器播放 3 声中等长度提示，旧校准值被新值替代。

下表概括蜂鸣器行为：

状态	蜂鸣器	使用音调	说明
启动	2 声短鸣	ACC_CALIBRATION	必须在 15 秒内移动
失败	2 声长鸣	ACC_CALIBRATION_FAIL	15 秒内未移动
检测到运动	快速 7 声提示	READY	开始移动所有轴；LED 常亮
校准完成	3 声中等长度提示	GYRO CALIBRATED	30 秒结束，LED 正常闪烁；检查结果

注意

请格外注意，切勿意外启动磁力计校准！

若误启动，请不要触碰机架，等待 15 秒超时。旧校准值将会保留。

若启动磁力计校准后让机架以超过 350 度/秒的速度移动，但接下来的 30 秒内没有正确旋转飞行器，旧校准值将被“垃圾”校准值替换，磁力计数据将不可用！

校准操作方法

只要在 30 秒窗口内进行一系列运动，使某一轴在三维空间中描绘出一个球面，三个轴就都会描绘出球面，应可得到良好结果。

一种覆盖全部可能角度的方法：

用电池抓住四轴飞行器。
以大圆方式挥动手臂，例如向前 -> 向上 -> 越过头顶 -> 向后 -> 向下，或以“8”字形挥动，并持续如此摆动。
同时随机向左、向右偏航飞行器。
在执行上述动作时，以小步缓慢绕垂直轴转动身体，使 30 秒内完成完整的 360 度转身。

每 1.5-2 秒完成一次完整手臂旋转效果良好，但请记住，只有 30 秒可将身体完全转一圈。

另一种方法：

使飞行器顶部向下、机头向后，手臂垂在身体一侧；将手臂向上摆动 180°，使飞行器顶部直指天空。
将飞行器偏航 90°，再将手臂完全放下。
身体转动约 30°，重复上举、偏航和放下的动作。
持续操作，直至在 30 秒内多次重复且身体完全转过一圈。

每次运行后检查 mag_calibration CLI 数值，确认得到一致的值。

若每次的数值差异在 20-30 个场强单位内，可以认为结果相当可靠。

可通过以下方式确认校准：

在 Sensors 选项卡使用 Mag_Calib 调试，确认每个轴的最小值和最大值大致相等。
在 Sensors 选项卡使用 Mag_Calib 调试，确认归一化的“MagADC 长度”值在各个角度下相当稳定。
将飞行器报告的航向（Configurator 的 GPS 选项卡或 Setup 页面）与手机罗盘读数比较。
根据手机罗盘将飞行器指向真北，检查 GPS 选项卡地图中的箭头图标是否直指上方（地图始终以北为上）。

单轴校准

可以“一次一个轴”进行“手动”校准。这不是常规或推荐方法，但可用于检查某一轴的校准值。

首先设置 Mag_Calib 调试，以便查看原始传感器数据。

校准前，使机头指向磁北场矢量，并在该大致方向上较快、随机地“晃动”。在 Configurator 的 Sensors 选项卡中仔细观察 X 轴值；很快就能找出 X 最大时的位置。目标是建立对北方位置的“肌肉记忆”和视觉感觉。

然后启动校准，快速移动飞行器以开始数据采集。密切观察 X 的原始磁力计值；确认已获得良好峰值后，将飞行器旋转 180°，使机尾直接指向磁场，并持续移动，直至 30 秒结束。

现在，X 的校准值会显示在第五条调试曲线中；若在 CLI 中执行 get mag_calibration，应看到与 X,Y,Z 中第一个值相同的数值。记下该数值。此时 Y、Z 校准值不会正确。

可重复几次以确认 X 的校准值一致，并选择最一致的值。

随后对 Y 轴重复操作。仍应尝试得到最大的最大值和最小值，并重复几次。Y 校准值位于第 7 条调试曲线以及 CLI 的 Y 值中。

最后对 Z 重复操作。

可使用 set mag_calibration X,Y,Z 在 CLI 中手动输入得到的三个校准值。

通常，挥动手臂并转动身体的方法效果很好，一次校准即可返回三个轴的校准值。手动方法也可能十分有效。

使用手机验证航向

航向值可与手机比较。确保手机设置为显示真北而不是磁北，并确认已在 CLI 中输入本地磁偏角值。使用手机确定北方后，使四轴飞行器正对北方。Configurator 首页或眼镜中的航向值在正对北方时应接近 0 / 360。

在 Sensors 选项卡中微调校准

对于校准良好的磁力计，当另外两轴值接近零时，任一单轴的最高值和最低值在数值上应相等。

使用 Sensors 选项卡检查每轴最大值和最小值，也可在新的飞行地点验证现有校准的准确性。当另外两轴为零时，若最大值和最小值非常接近，则无需重新校准。

客户端校准（2025.12+ 固件）

备注

本节描述的客户端校准方法需要 Betaflight 2025.12 或更高固件（MSP API >= 1.47）。固件提供 CLI-over-MSP 支持，地面站据此读取和写入 mag_calibration 偏移。在旧固件上，仅可使用上述基于固件的校准方法。

从 Betaflight 地面站 2026.6 开始，可以在客户端侧执行磁力计校准：即地面站本身采集原始磁力计样本，使用最小二乘球面拟合算法计算校准偏移，并通过 CLI set mag_calibration 命令将结果写入飞控。这与上述基于固件的校准根本不同：后者由飞控固件内部采集样本并计算偏移。客户端校准提供实时三维球面可视化、质量评估，以及何时接受或丢弃结果的完整控制。

所有客户端校准功能均可在传感器选项卡的磁力计部分访问。

磁偏角自动检测

校准前，可点击“磁偏角度”字段旁的检测按钮，自动检测本地磁偏角、磁倾角和场强。该功能会根据 GPS 或浏览器位置从在线地磁模型获取数值。磁偏角会写入 mag_declination CLI 参数；磁倾角和场强仅供参考，并用于三维可视化显示本地磁场方向。

对齐自动检测

“磁力计朝向”下拉菜单旁的检测按钮可自动确定磁力计安装方向。它会在你缓慢旋转四轴飞行器时采集样本，分析传感器数据，并给出最可能的朝向（例如 CW90、CW180FLIP），同时显示置信度。你可应用或舍弃该结果。

此功能取代了逐轴相对磁场方向进行手动测试的过程。

校准值编辑器

三个可编辑的数值字段显示当前 mag_calibration 偏移（X、Y、Z）。可手动输入数值，然后点击保存数值将它们写入飞控。这些数值通过 CLI set mag_calibration 命令保存，独立于全局的保存并重启操作。

检查模式

点击检查按钮（眼睛图标）进入检查模式。这会打开三维球面可视化，并使用当前校准值将实时磁力计读数绘制为点。检查模式不会触发校准，也不会修改任何值。

三维可视化显示的内容：

罗盘环：位于水平面，带 N、S、E、W 方位标签。
轴线：红色（南-北）、绿色（东-西）和蓝色（下-上），穿过原点并绘制到天球边缘。
橙色磁场参考箭头：显示本地磁场方向和磁倾角，箭头尖端带小型“N”和“S”标签，并显示磁倾角。
四轴飞行器图标：显示飞行器当前姿态，前桨为绿色，后桨为红色。
机体坐标系轴向量：附着在飞行器图标上的红色 X、绿色 Y、蓝色 Z 向量，显示每轴测得的实时场强。各轴正方向伸出的向量较粗，负方向较细。
白色机头方向线：从飞行器机头延伸至白色实时样本点。
白点：位于飞行器 X 轴末端，距离等于总场强，并缩放至适配天球内部。
累积样本点：旋转飞行器时形成球面；颜色由蓝色（最旧）渐变至红色（最新）。
绿点：显示当前固件校准偏移位置。
灰点：显示计算得到的球心（样本足够进行球面拟合时）。

检查模式的使用方法：

打开检查模式，将四轴飞行器平放在工作台上。
使机头指向已知罗盘方向（使用设为真北的手机罗盘）。
确认三维显示中各点出现在预期位置：若机头指北，点应接近“N”标签。
缓慢将飞行器旋转到所有姿态，以形成一球面点集。
校准良好的磁力计会生成以原点 (0,0,0) 为中心的球形点集。
若球面明显偏离中心，则需要重新校准。
若点出现在完全错误的位置，磁力计方向很可能不正确。

检查模式还可用于检测磁干扰：若缓慢转动电机时点发生跳变或散乱，说明磁力计过于靠近电机磁场。

客户端校准（引导式）

引导式校准模式会在 60 秒窗口内引导你完成 6 个姿态，每 10 秒自动推进一次提示。这是大多数用户推荐的校准方法。

启动方式：点击校准，或在下拉菜单中选择客户端校准（引导）。

6 个姿态步骤：

步骤	提示	目的
1/6	平放，偏航 360°	赤道环
2/6	倒置，偏航 360°	对侧赤道环
3/6	机头垂直向上，偏航 360°	北极区域
4/6	机头垂直向下，偏航 360°	南极区域
5/6	左侧向上，偏航 360°	中纬度填充（左侧）
6/6	右侧向上，偏航 360°	中纬度填充（右侧）

校准期间：

倒计时计时器显示剩余时间。
提示每 10 秒自动推进；步骤之间不要暂停，应持续移动飞行器。
三维可视化会显示逐渐形成球面的累积点。
每收集 10 个样本执行一次球面拟合，更新计算出的偏移和质量评分。
质量会显示为 Good、Fair 或 Poor；百分比评分由拟合准确度（60%）和角度覆盖均匀性（40%）组成。

60 秒后：

数据采集停止，并显示“Data collection complete -- review and save”。
检查球面可视化，确认覆盖良好且没有大面积空缺。
检查计算出的偏移和质量评分。
点击保存校准将偏移写入飞控。
点击取消舍弃结果。

良好引导式校准的提示：

平稳、持续地旋转，姿态之间不要停顿。
每个“yaw 360°”步骤中至少完成一次完整旋转。
远离金属物体和电机磁铁。
若使用 USB 供电，请使用长线或便携式 USB 电池。

客户端校准（自由式）

自由式校准与引导式校准相似，但没有定时提示。你可按自己的节奏在所有方向上自由旋转飞行器，直至覆盖充分。

启动方式：在“校准”下拉菜单中选择客户端校准（自由）。

使用方法：

拿起四轴飞行器，开始向所有方向旋转。
观察三维可视化，目标是以点均匀填满球面。
随着覆盖改善，质量指示器会实时更新。
持续操作，直至质量达到“Good”且球面没有明显空缺。
点击保存校准接受结果，或点击取消舍弃。

自由模式没有时间限制。可根据需要花足够时间获得良好覆盖。若要在不离开校准模式的情况下重新开始，清除按钮会重置已收集的样本。

何时应使用自由式而非引导式：

已有经验且能从视觉上判断覆盖情况时。
希望花更多时间填补特定空缺时。
飞行器的安装方式导致某些引导姿态难以完成时。

固件校准（旧版）

旧版固件校准模式与上文启动校准一节所述的基于固件的校准相同。它通过 MSP_MAG_CALIBRATION 触发固件内置的 30 秒校准。固件会计算并自动保存偏移。

从“传感器”选项卡启动时，三维可视化会与固件的 30 秒倒计时一并显示，因此可以实时观察球面点集形成。不过，偏移由固件而非地面站计算和保存。

提供该模式是为了向后兼容。推荐使用客户端侧方法（引导式或自由式），因为它们提供视觉反馈、质量评估以及保存前审查结果的能力。

使用检查模式验证校准

使用任意方法校准后，请使用检查模式验证结果：

点击检查，以新的校准值进入检查模式。
缓慢将飞行器向所有方向旋转。
点应形成以原点为中心的球面。
绿点（固件偏移）应靠近原点。
若球面明显偏离中心，可能需要以更好的角度覆盖重新校准。

也可手动调整“校准数值”字段并点击保存数值，然后重新进入检查模式查看变化效果。

校准方法比较

功能	固件校准（旧版）	客户端校准（引导式）	客户端校准（自由式）
固件版本	全部	2025.12+	2025.12+
时长	30 秒（固定）	60 秒（倒计时）	无限制
姿态引导	无	6 条自动推进的提示	无
三维可视化	是（仅查看）	是	是
由谁计算偏移	固件	地面站（球面拟合）	地面站（球面拟合）
自动保存	是	否（手动保存）	否（手动保存）
质量反馈	无	Good/Fair/Poor + 百分比	Good/Fair/Poor + 百分比
可在保存前审查	否	是	是
是否需要物理敲击/晃动	是（15 秒窗口）	否	否

在哪里显示航向信息？

航向信息由 GPS 单元（对地航向）、IMU（快速转向时的陀螺仪信息）和磁力计单元提供。IMU 代码使用“传感器融合”方法，将可用数据整合为飞行器最终的“姿态”或“航向”值。

当前航向显示在 Configurator 主页面飞行器图标区域的左上方。若磁力计已启用，显示的航向反映磁力计数据，并返回飞行器机头相对北方的角度。没有磁力计时，航向值始终从 0° 或 359° 开始，仅会因陀螺仪数据积分可指示解锁后偏航的相对变化而改变。

若代码构建时包含 GPS 支持，Configurator 的 GPS 选项卡会显示当前磁力计航向和 GPS 对地航向。

在 OSD 中，可将航向显示为以度为单位的数值，或以图形方式显示。

提示

若一切工作正常，启用磁力计后，Configurator 主页面显示的飞行器图标应平滑移动而不会突然跳变。快速移动后的突然跳变通常意味着方向不正确。

若 GPS 工作正常，且在 Failsafe 选项卡中启用了 GPS Rescue，可在 GPS_RESCUE_HEADING 调试的 Debug 4 中记录磁力计航向信息。

MagADC X、Y、Z 值始终会记录到 Blackbox。首次飞行后应检查它们，确认噪声并不严重；噪声应远小于信号。若噪声明显存在问题，请将磁力计安装得离电机和大电流导线更远，确保传感器到成对电机的距离相等，并检查磁力计模块电源是否有足够滤波。

由 ctzsnooze 于 2023-09 为 Betaflight 4.5 起草。特别感谢 ledvinap 和 pichim 提供的帮助与指导。

简介​

摘要​

什么是磁力计？​

关于地球磁场​

在 CLI 中设置本地磁偏角​

安装磁力计​

硬件与连接​

磁力计方向​

使用 Configurator 的 Sensors 选项卡检查磁力计方向​

非常规磁力计方向的软件修正​

磁力计校准​

启动校准​

校准操作方法​

单轴校准​

使用手机验证航向​

在 Sensors 选项卡中微调校准​

客户端校准（2025.12+ 固件）​

磁偏角自动检测​

对齐自动检测​

校准值编辑器​

检查模式​

客户端校准（引导式）​

客户端校准（自由式）​

固件校准（旧版）​

使用检查模式验证校准​

校准方法比较​

在哪里显示航向信息？​

外部链接​

Footnotes​

简介

摘要