地磁校准
地磁校准消除随模块一起运动的磁干扰，是 9 轴模式获得可靠航向的前提。
适用场景
只用 6 轴模式，或型号不带磁传感器时，不需要校准。
满足以下三条，再使用 9 轴模式：
- 首次使用前至少完成一次地磁校准；
- 使用环境没有明显的空间磁场干扰，最好是室外空旷处；
- 模块与载体（PCB、外壳、机器人等）的相对位置保持固定，随模块运动的磁性部件不会变化。
室内和电机附近的选择见校准频率与模式选择；干扰无法通过校准消除的原因见磁干扰类型与校准边界。
运行中，MAG_AIDING 只表示磁辅助已使能，不能单独说明航向可靠。还要结合 MAG_DIST、ATT_CONV 和实际航向变化判断，位定义见 MAIN_STATUS 状态字。
上电后，MAG_DIST 为 1 表示磁航向暂不可信。原因可能是磁场受干扰，也可能是磁基准尚未确认。转动模块并保持磁环境洁净，等 MAG_DIST 清零后再使用 9 轴航向。转动后仍为 1，按故障排查流程检查磁环境。
校准频率与模式选择
校准时机：
- 首次固定安装后，校准并验证；安装没变且验证正常时，不必重复校准。
- 模块与载体的相对位置，或随模块运动的磁性部件发生变化后，重新校准。
- 恢复出厂、固件升级或更换使用环境后，先做航向旋转验证。验证正常就不必重新校准；异常时先排除磁干扰，再重新校准。见恢复出厂和固件升级。
模式选择：室外空旷处用 9 轴；室内、靠近电机或大电流线缆用 6 轴，因为钢筋、家具和电流变化造成的畸变不随模块运动，校准消除不了，选择依据见工作模式。必须在电机附近用 9 轴时，在电机停止时校准。
校准步骤
CHCenter 的「地磁校准」窗口可完成第 3–4 步：选择「3D — 手持 / 无人机」或「2D — 车载 / AGV」，窗口显示对应的旋转要领。下面按 ASCII 命令说明。使用 Modbus 时，启动和读取状态改用地磁校准寄存器，环境检查、旋转动作、状态含义和验证方法都一样。
第 1 步：切换工作模式
CONFIG ATT MODE 1保存并重启后生效，流程见配置流程与保存。重启后 LOG USRCONFIG 应返回 PROFILE=1，也可以确认 MAIN_STATUS.MAG_AIDING=1。工作模式的取值见工作模式。
切换工作模式后，姿态零点要重新设置，先 CONFIG ATT RST 5，见设置顺序。
第 2 步：检查校准环境
常见干扰源：磁铁、扬声器、磁性螺丝、铁质家具、钢制工装、车辆底盘、显示器、电机与变压器、大电流线缆、手机充电器、建筑钢筋。
| 环境等级 | 要求 |
|---|---|
| 最佳 | 室外空旷场地，远离建筑物和车辆（> 5 m） |
| 仅用于临时验证 | 室内远离钢结构、电机、大电流线缆和磁体的区域。量产验收请用室外场地，或已通过 B_total 与航向旋转验证的固定场地 |
注意
模块焊在产品 PCB 上、使用磁性外壳，或装在机器人、车辆、三脚架等导磁刚体上时，把与模块固联的整体一起旋转校准。单独校准模块再装进产品，校准会失效；模块与载体分离或重装后，需要重新校准。
第 3 步：执行校准
发送下面其中一条命令启动校准，然后按要领旋转。此处 OK 只表示命令已接受，不表示校准完成：
CONFIG MCAL START
CONFIG MCAL START 2D不带参数为 3D 校准，带 2D 为平面校准。
| 校准类型 | 适用载体 | 旋转要求 |
|---|---|---|
| 3D | 手持设备、无人机等会明显俯仰、横滚的载体；首次校准，或安装磁环境变化后 | 位置保持不动，只改变姿态。建议每个轴转 2 圈，不少于 1 圈；速度均匀，推荐 20–100 deg/s，不长时间停在同一姿态。推荐顺序：绕 X 轴 2 圈 → 绕 Y 轴 2 圈 → 绕 Z 轴 2 圈，或随机旋转 |
| 2D | 运行中基本保持水平、主要绕竖直轴旋转的载体（AGV、车辆、转台） | 保持水平，绕竖直轴旋转一周以上。车辆可原地缓慢转圈，中途不停顿 |
2D必须大写，其他写法按 3D 校准。- 速度和圈数只是操作参考，是否完成以
STAT=3和第 5 步的航向旋转验证为准。 - 校准进行中保持旋转，不要重复发送
START。校准没有取消命令。STAT长时间停在 1 且PROGRESS不增加时，先补足转动；补足后仍无变化，给模块重新上电，再按第 3 步重新启动校准。
第 4 步：查询校准状态
发送 LOG MCAL STAT：
→ LOG MCAL STAT
← STAT=3
← PROGRESS=100
← OK| STAT | 状态 | 操作建议 |
|---|---|---|
| 0 | 空闲 | 可以开始新的校准 |
| 1 | 校准中 | 继续旋转模块（或模块与载体整体）。PROGRESS 长时间不增加，说明转动不足，补足姿态覆盖 |
| 3 | 校准成功 | 按第 5 步验证航向 |
| 4 | 校准失败 | 按故障排查流程处理后重新校准 |
| 其他值 | 未定义 | 按未成功处理：确认模块带磁传感器，保持姿态覆盖后重新校准；仍异常请联系技术支持 |
只以 STAT=3 为成功、STAT=4 为失败，不按固定时长判断。刚上电就读到 STAT=1，可能是模块自动执行的后台校准。等 STAT 不再为 1，再手动启动校准。
LOG MCAL STAT 返回若干 KEY=VALUE 行，按键名读取 STAT 与 PROGRESS，解析规则见命令格式与响应。PROGRESS 范围 0–100，只是进度提示，不能据此推算剩余时间。校准中最高显示 99，STAT=3 后显示 100。
校准成功后，补偿参数立即生效并自动保存，无需 SAVECONFIG。9 轴模式下，成功的瞬间航向可能阶跃一次，属正常现象。
第 5 步：航向旋转验证
- 水平放置模块，记下当前航向，缓慢旋转一周（360°）回到起点。
- 旋转中航向应连续变化，只在 ±180°（或 0/360°）边界回绕，没有其他跳变。
- 回到起点时的航向与起始读数相差不超过 5°。有手机罗盘或已知方位时，也可用它做参考。
- 相差超过 5°、出现非边界跳变，或航向不随旋转变化：按故障排查流程处理。
建议重新上电后再验证一次，确认校准结果已保存。
故障排查流程
校准失败（STAT=4）或验证异常时，按下表逐项排查，前一项合格再做下一项。磁场总强度 B_total = √(Bx² + By² + Bz²)，由磁场三轴 mag_b（单位 μT）计算。mag_b 在 HI91 中输出，也可在 CHCenter 中查看。
| 顺序 | 检查项 | 合格判据 | 不合格时的处理 |
|---|---|---|---|
| 1 | 静止读取 B_total | 20–60 μT | 低于 20 μT（被屏蔽）或高于 60 μT（附近有磁体）：远离干扰源或换位置后重新校准 |
| 2 | 姿态覆盖 | 3D：各轴充分覆盖，每轴 ≥ 360°，速度 20–100 deg/s；2D：水平绕竖直轴一周以上 | 覆盖不足或长时间停在同一姿态：重做旋转后重新校准。载体不能大幅俯仰、横滚时，改用 2D |
| 3 | 同一位置改变朝向时的 B_total | 在同一位置依次转到至少 4 个朝向，最大值与最小值之差 ≤ 10 μT | 超过 10 μT（以 B_total 判断，不看单轴变化）：换一个位置重新校准；换了位置仍超过，再考虑改用 6 轴模式。电机、驱动器启停时 B_total 或航向明显变化，属时变干扰，同样拉开距离或改用 6 轴 |
| 4 | 校准时位置是否移动，模块与载体是否相对位移 | 位置固定，安装固定 | 固定位置只改变姿态，把模块与载体整体重新校准 |
| — | 以上均合格仍异常 | — | 换到洁净环境重新校准一次；仍失败，按联系技术支持前准备资料后联系技术支持 |
磁干扰类型与校准边界
磁干扰按「是否随传感器一起运动」分为两类。只有随传感器运动的干扰才能通过校准消除。
| 项目 | 随传感器运动的干扰 | 空间磁场干扰 |
|---|---|---|
| 特点 | 干扰源随传感器一起运动 | 干扰源不随传感器运动 |
| 子类 | 硬磁（固联磁体 / PCB / 金属外壳）、软磁（固联导磁金属）、传感器标定误差 | 空间畸变（钢筋 / 家具 / 电器）、时间畸变（电机 / 电流变化） |
| 典型来源 | 与模块固联的 PCB、金属外壳、无人机机架 | 家具、家电、线缆、建筑钢筋 |
| 能否校准 | 可以 | 不可以，会显著增大航向误差 |
