前言
MotionFX 是 X-CUBE-MEMS1 软件的中间件库组件，可在 STM32 上运行。它可提供实时运动传感器数据融合。它还执行陀螺仪偏差和磁力计硬铁校准。
2 B( y$ j2 T8 z  G7 _2 D: ]+ i该算法以静态库格式提供，旨在用于基于 ARM® Cortex®-M4 架构的 STM32 微控制器。
' A' t+ t* E; y: b1 n' d9 V! R$ _它以 STM32Cube 软件技术为基础而构建，便于在不同 STM32 微控制器之间移植。
该 软 件 附 带 了 NUCLEO-F401RE 或 NUCLEO-L476RG 开 发 板 上 的 X-NUCLEO-IKS01A1 （ 可 选STEVAL-MKI160V1）或 X-NUCLEO-IKS01A2 扩展板上运行的示例实现。

; F: o% W' Z1 H& |+ S+ G1 缩写和缩略语
6 o' ~7 d% c! v

: T- j' m; `! q. x2 MotionFX middleware library in X-CUBE-MEMS1 software expansion for STM32Cube
2.1 MotionFX 概述
2 |, ]3 m3 j9 a" g7 q( v# ?1 A  bMotionFX 库扩展了 X-CUBE-MEMS1 软件的功能。
该库从加速度计、陀螺仪（6 轴融合）和磁力计（9 轴融合）获取数据，并提供实时运动传感器数据融合。
无论环境条件如何，MotionFX 滤波和预测软件都利用高级算法智能地对来自多个 MEMS 传感器的输出进行整合，可以实现最佳性能。
X-NUCLEO-IKS01A2 和 X-NUCLEO-IKS01A1（可选 STEVAL-MKI160V1）扩展板上提供了一个示例实现，安装在 NUCLEO-F401RE 或 NUCLEO-L476RG 开发板上。

2.2 MotionFX 库
在“Documentation”文件夹的 HTML 文件（使用 MotionFX_Package.chm 编译）中，提供了完整描述 MotionFX API 的功能和参数的技术信息。
2.2.1 MotionFX 库说明
& o8 F! A0 R  V. a- J3 ZMotionFX 传感器融合库可管理从加速度计、陀螺仪和磁力计传感器获取的数据；它能够：
• 实时 9 轴运动传感器数据融合（加速度计，陀螺仪，磁力计）
" Y! D/ P( D, [/ i7 R1 c• 实时 6 轴运动传感器数据融合（加速度计，陀螺仪）
7 w4 r/ J7 f) L8 A( y+ W" U0 X& K• 计算旋转、四元数、重力和线性加速度数据
8 q# R: d% x! R  d4 `  k- e• 陀螺仪偏差校准
• 磁力计硬铁校准
+ A, y1 S) L, j6 h8 Q5 d: M• 建议传感器数据采样频率为 100 Hz
• 45 kB 的代码和 8 kB 的数据存储器
实际空间大小对于不同的 IDE（工具链）可能不同
: S5 Z2 ~* Q: W- `1 U• 适用于 ARM Cortex-M4 架构

2.2.2 MotionFX 6 轴和 9 轴传感器融合模式
MotionFX 库实现了传感器融合算法，用来估算空间中的 3D 方向。它使用基于 Kalman 理论的数字滤波器来融合来自多个传感器的数据，并补偿单个传感器的限制。例如，陀螺仪数据可能会漂移，这会影响定向估计；这个问题可以通过使用磁力计提供绝对定向信息来解决。
类似地，磁力计带宽不高，并且受磁力干扰，但是这些弱点可利用陀螺仪来进行补偿。

$ y& _+ U3 Z5 o* h9 轴传感器融合使用来自加速度计、陀螺仪和磁力计的数据，并提供 3D 空间中的绝对定向，包括航向（即磁性北方向）。
6 轴传感器融合仅使用加速度计和陀螺仪数据。它对计算要求较低，但不能提供有关器件绝对定向的信息。
! w& z' e% y* c! k% i' K" d0 M6 轴传感器融合适用于快速移动（例如，游戏中）并且不需要绝对定位时的场景。

( y% Q. |! d. {/ {* w: D
2.2.3 MotionFX 库操作
MotionFX 库将 6 轴和 9 轴传感器融合算法集成在一个库中；甚至可以同时运行它们。
该库实现了传感器融合计算相关的以下关键内部函数：
8 A4 W  O, _0 \  A* q6 P1. MotionFX_propagate 是用于估计 3D 空间中定向的预测函数；在此阶段给予了陀螺仪数据更高权重。
3 _9 b' q5 m5 W2. MotionFX_update 是校正函数，可在需要时调整预测值；这个阶段给予了加速度计和磁力计数据更高权重。
7 o8 U* K5 E3 ?# w每当调用 MotionFX_propagate 时，都可调用 MotionFX_update 函数，在计算能力较小的系统中不经常调用该函数。
MotionFX_update 函数大约比 MotionFX_propagate 函数多花费三倍的 MCU 计算时间。

2.2.4 MotionFX 库参数
MotionFX 库使用 MFX_knobs_t 结构体进行“参数化”。
0 {- b$ s! {6 }/ X! ~, u- ?' {# H结构体参数如下：
• ATime、MTime、FrTime 表示用于预测的传感器（信任因子）的加权稳定性，从 0 到 1。建议使用默认值。
• LMode 代表陀螺仪偏差学习模式；库能够自动监测校准条件并进行零偏校准。
3 h* @! Z( D3 t: M此可能的参数值是：
− LMode = 0 – 学习关闭；如果陀螺仪已校准，则使用此模式
( ~- k! b+ S  P4 i3 [% Z! j1 D− LMode = 1 – 静态学习；仅当系统不动时进行学习
− LMode = 2 – 动态学习；系统移动时也进行学习
• gbias_acc/gyro/mag_th_sc_6X, gbias_acc/gyro/mag_th_sc_9X 表示阈值，低于这些阈值时 gbias 算法自动启动。这些值应通过测试来确定（不同型号器件对应不同的阈值）。
- h3 {1 x$ T0 ^/ Y5 A& z示例项目中的值通常是正确的
+ A' A7 t5 f" S0 t' J0 I$ M− modx 表示 MotionFX_update 调用频率的抽取
− output_type 用于定义融合库输出数据的坐标系统类型：0 = NED，1 = ENU
− start_automatic_gbias_calculation 表示一个标志，当该标志设置为 1 时可重新启动陀螺仪偏差校准
− acc/gyro/mag_orientation 是由三个字符组成的 acc/gyro/mag 数据定向字符串，指示速度计数据输出使用的参考框架的每个正定向的方向，顺序为 x、y、z。有效值
6 i, y& A, q' N, Y为：n（北）或 s（南），w（西）或 e（东），u（上）或 d（下）。
如下图所示，X-NUCLEO-IKS01A1 加速度计传感器采用 ENU 定向（x - 东，y - 北，z - 上），因此字符串为“enu”，而 STEVAL-MKI160V1 中的加速度计传感器为 NWU 定向（x-北，y-西，z-上），字符串为“nwu”。
& M0 J) M* ]! g/ r# N3 V

5 T4 F% x' J% K4 T  T0 l4 u9 T% {
MotionFX_propagate 和 MotionFX_update 函数从 MFX_input_t 结构体获取传感器数据：
• mag 表示校准后的磁力计数据，以 µT/ 50 计
, b1 W' X6 j6 z4 k• acc 表示加速度计数据，以 g 计
• gyro 表示陀螺仪数据，以 dps 计
/ s5 F) ~7 X/ W5 |1 G2 M( J
) N' ^! Q4 C! Y( TMotionFX_propagate 和 MotionFX_update 将融合算法输出保存到 MFX_output_t 结构体中：
0 ^  c/ b5 |2 ?8 u( F• rotation_6/9X 表示系统定向为三角格式：偏航角，俯仰角，翻滚角
• quaternion_6/9X 表示系统定向四元素格式；此格式可提供与 rotation_6/9X 同样的信息，但它在计算方面具有优势，因此通常用于其他算法（基于传感器融合）。
9 \1 V8 P' f4 q5 [! T• gravity_6/9X 表示从加速度数据中所得到的静态加速度（即，地球重力）向量
( {4 k. `9 b; T8 K: m2 R• linear_acceleration_6/9X 表示从加速度数据中得到的动态加速度（即，移动）向量。

完整版请查看：附件

% o: i, t' ]' K" }6 S( y