mobile_comm/luatos/air780epm/module/Air780EPM/demo/sensor/qmc5883p

QMC5883P 三轴地磁传感器演示

一、功能模块介绍

1.1 核心主程序模块

1. main.lua - 主程序入口，负责项目初始化、版本定义和任务调度
2. qmc5883p_app.lua - QMC5883P 功能演示模块，包含数据读取、量程切换、输出速率切换、过采样/降采样配置、软复位、自检、休眠唤醒等所有功能的演示用例

1.2 扩展库模块

1. exs_qmc5883p - QMC5883P 扩展库，提供初始化、三轴磁场数据读取、量程切换、输出速率切换、过采样/降采样配置、软复位、芯片自检、睡眠/唤醒、关闭等 API

1.3 I2C 模式说明

推荐使用软件 I2C 模式：QMC5883P 在异常 I2C 通信后可能锁死 SDA 总线。本库已内置 I2C 总线卡死自动检测与恢复功能。本 demo 默认使用软件 I2C 模式演示，也可通过 qmc5883p_app.lua 中的 MODE 变量切换为硬件 I2C 模式。

二、演示流程介绍

本 demo 按顺序演示 exs_qmc5883p 扩展库的 7 项功能：HELLO → [1/7] → [2/7] → [3/7] → [4/7] → [5/7] → [6/7] → [7/7] → End

2.1 功能演示项说明

1. [1/7] 初始化与数据读取 - 初始化 QMC5883P 传感器并读取三轴磁场数据（X/Y/Z，单位 μT）
2. [2/7] 量程切换演示 - 在 ±2G（高精度）、±8G（宽范围）和 ±30G（最宽量程）之间切换，观察数据变化
3. [3/7] 输出速率切换 - 依次切换 10Hz / 50Hz / 100Hz / 200Hz 输出速率
4. [4/7] 过采样/降采样配置 - 演示过采样率（OSR1）与降采样率（OSR2）的组合配置
5. [5/7] 软复位演示 - 软复位芯片并自动恢复当前配置
6. [6/7] 芯片自检演示 - 利用芯片内置自检激励信号验证信号链路是否正常
7. [7/7] 休眠唤醒与关闭 - 演示 sleep()/wakeup() 挂起与唤醒，以及 close() 关闭

三、显示效果

四、演示硬件环境

4.1 硬件清单

• Air780EPM 核心板 × 1
• QMC5883P 三轴地磁传感器模块 × 1 demo所演示的QMC5883P购买链接
• 母对母杜邦线 × 5
• TYPE-C 数据线 × 1

4.2 接线配置

4.2.1 QMC5883P 模块接线

Air780EPM 核心板	QMC5883P 模块
32/GPIO31	SCL
31/GPIO30	SDA
VDD_EXT	VCC
GND	GND

说明：接线时注意杜邦线不宜过长，以免通信不稳定。

五、演示软件环境

5.1 开发工具

• Luatools下载调试工具 - 固件烧录和代码调试

5.2 内核固件

• 点击下载Air780EPM系列最新版本内核固件，demo所使用的是 LuatOS-SoC_V2046_Air780EPM 1号固件

5.3 脚本文件

1. main.lua - 程序入口
2. qmc5883p_app.lua - QMC5883P 功能演示模块
3. exs_qmc5883p - QMC5883P 扩展库

六、演示核心步骤

6.1 硬件准备

1. 按照接线表将 QMC5883P 模块连接到核心板
2. 确保电源连接正确，通过 TYPE-C USB 口供电
3. 检查所有接线无误，避免短路

6.2 软件配置

在 main.lua 中加载对应的演示模块：

-- 加载 qmc5883p_app.lua 演示模块
require "qmc5883p_app"

如需切换通信模式，修改 qmc5883p_app.lua 中的 MODE 变量（1=软件 I2C，2=硬件 I2C）。

6.3 软件烧录

1. 使用 Luatools 选择最新内核固件
2. 下载本项目所有脚本文件
3. 将固件和脚本一起烧录到设备
4. 烧录成功后设备自动重启后开始运行

6.4 功能测试

6.4.1 初始化与数据读取演示

1. 设备启动后打印 "HELLO"，随后自动进入 [1/7] 初始化与数据读取
2. 观察日志输出，确认初始化成功
3. 观察三轴磁场数据（X/Y/Z，单位 μT）的连续读取

6.4.2 量程切换演示

1. 自动进入 [2/7] 量程切换演示
2. 观察 ±2G 高精度量程下的数据
3. 观察 ±8G 宽范围量程下的数据
4. 观察 ±30G 最宽量程下的数据

6.4.3 输出速率切换演示

1. 自动进入 [3/7] 输出速率切换演示
2. 依次观察 10Hz / 50Hz / 100Hz / 200Hz 下的数据读取
3. 最终恢复为 10Hz

6.4.4 过采样/降采样配置演示

1. 自动进入 [4/7] 过采样/降采样配置演示
2. 观察最高滤波配置（OSR1=8 + OSR2=8）下的数据
3. 观察最低功耗配置（OSR1=1 + OSR2=1）下的数据

6.4.5 软复位演示

1. 自动进入 [5/7] 软复位演示
2. 观察软复位完成后配置自动恢复
3. 观察复位后的数据读取

6.4.6 芯片自检演示

1. 自动进入 [6/7] 芯片自检演示
2. 观察自检增量 dx/dy/dz 输出
3. 增量明显大于正常噪声表示信号链路正常

6.4.7 休眠唤醒与关闭演示

1. 自动进入 [7/7] 休眠唤醒与关闭演示
2. 观察 sleep() 进入挂起模式
3. 观察 wakeup() 唤醒后数据恢复
4. 观察 close() 关闭传感器

6.5 预期效果

• 初始化与数据读取：QMC5883P 初始化成功，三轴磁场数据正常输出
• 量程切换：量程切换后数据范围随之变化，灵敏度不同
• 输出速率切换：不同速率下均能正常读取数据
• 过采样/降采样配置：配置切换后均能正常读取数据
• 软复位：复位后配置自动恢复，数据读取正常
• 芯片自检：自检增量明显大于噪声，信号链路正常
• 休眠唤醒与关闭：sleep 后进入低功耗，wakeup 后数据读取正常

日志如下：

[2026-08-07 14:44:44.084][000000000.200] I/user.main QMC5883P_Demo 001.999.000
[2026-08-07 14:44:44.090][000000000.215] D/user.exs_qmc5883p version -> 202608050000
[2026-08-07 14:44:44.099][000000000.216] I/user.qmc5883p_demo HELLO
[2026-08-07 14:44:44.219][000000001.216] I/user.qmc5883p_demo ===== [1/7] 初始化与数据读取 =====
[2026-08-07 14:44:44.224][000000001.222] I/user.exs_qmc5883p I2C总线恢复完成
[2026-08-07 14:44:44.229][000000001.229] I/user.exs_qmc5883p 初始化完成, range=8G odr=10Hz osr=8 osr2=8 set_reset=on
[2026-08-07 14:44:44.237][000000001.229] I/user.qmc5883p_demo QMC5883P 初始化成功，版本: 202608050000
[2026-08-07 14:44:44.242][000000001.431] I/user.exs_qmc5883p 首次读取原始字节: F4 FC 23 FB 31 FF
[2026-08-07 14:44:44.251][000000001.433] I/user.qmc5883p_demo X=-20.80 Y=-33.20 Z=-5.52 uT
[2026-08-07 14:44:44.418][000000001.937] I/user.qmc5883p_demo 第1次读取: X=-20.83 Y=-33.39 Z=-5.71 uT
[2026-08-07 14:44:44.929][000000002.441] I/user.qmc5883p_demo 第2次读取: X=-20.80 Y=-33.36 Z=-5.81 uT
[2026-08-07 14:44:45.426][000000002.945] I/user.qmc5883p_demo 第3次读取: X=-22.00 Y=-29.60 Z=-6.40 uT
[2026-08-07 14:44:45.433][000000002.945] I/user.qmc5883p_demo ---- [1/7] 完成 ----
[2026-08-07 14:44:45.922][000000003.445] I/user.qmc5883p_demo ===== [2/7] 量程切换演示 =====
[2026-08-07 14:44:45.926][000000003.445] I/user.qmc5883p_demo 切换量程为 2G（高精度，灵敏度 15000 LSB/G）
[2026-08-07 14:44:45.938][000000003.450] I/user.exs_qmc5883p 量程切换为 2G
[2026-08-07 14:44:46.234][000000003.754] I/user.qmc5883p_demo 2G 量程: X=-16.60 Y=-6.70 Z=-29.81 uT
[2026-08-07 14:44:47.229][000000004.754] I/user.qmc5883p_demo 切换量程为 8G（宽范围，灵敏度 3750 LSB/G）
[2026-08-07 14:44:47.244][000000004.758] I/user.exs_qmc5883p 量程切换为 8G
[2026-08-07 14:44:47.541][000000005.062] I/user.qmc5883p_demo 8G 量程: X=31.09 Y=5.89 Z=-17.23 uT
[2026-08-07 14:44:48.551][000000006.062] I/user.qmc5883p_demo 切换量程为 30G（最宽量程，抗干扰最强）
[2026-08-07 14:44:48.558][000000006.066] I/user.exs_qmc5883p 量程切换为 30G
[2026-08-07 14:44:48.847][000000006.370] I/user.qmc5883p_demo 30G 量程: X=-16.50 Y=5.40 Z=-19.00 uT
[2026-08-07 14:44:48.862][000000006.374] I/user.exs_qmc5883p 量程切换为 8G
[2026-08-07 14:44:48.868][000000006.374] I/user.qmc5883p_demo ---- [2/7] 完成 ----
[2026-08-07 14:44:49.361][000000006.874] I/user.qmc5883p_demo ===== [3/7] 输出速率切换 =====
[2026-08-07 14:44:49.368][000000006.875] I/user.qmc5883p_demo 设置输出速率为 10Hz
[2026-08-07 14:44:49.373][000000006.879] I/user.exs_qmc5883p 输出速率切换为 10Hz
[2026-08-07 14:44:49.859][000000007.383] I/user.qmc5883p_demo 10Hz 下: X=-23.39 Y=-9.60 Z=-20.96 uT
[2026-08-07 14:44:50.367][000000007.883] I/user.qmc5883p_demo 设置输出速率为 50Hz
[2026-08-07 14:44:50.371][000000007.887] I/user.exs_qmc5883p 输出速率切换为 50Hz
[2026-08-07 14:44:50.866][000000008.391] I/user.qmc5883p_demo 50Hz 下: X=11.52 Y=-20.48 Z=19.33 uT
[2026-08-07 14:44:51.366][000000008.891] I/user.qmc5883p_demo 设置输出速率为 100Hz
[2026-08-07 14:44:51.382][000000008.895] I/user.exs_qmc5883p 输出速率切换为 100Hz
[2026-08-07 14:44:51.881][000000009.399] I/user.qmc5883p_demo 100Hz 下: X=-14.75 Y=-15.76 Z=12.11 uT
[2026-08-07 14:44:52.378][000000009.899] I/user.qmc5883p_demo 设置输出速率为 200Hz
[2026-08-07 14:44:52.383][000000009.903] I/user.exs_qmc5883p 输出速率切换为 200Hz
[2026-08-07 14:44:52.891][000000010.407] I/user.qmc5883p_demo 200Hz 下: X=-19.97 Y=-13.39 Z=-27.09 uT
[2026-08-07 14:44:53.389][000000010.911] I/user.exs_qmc5883p 输出速率切换为 10Hz
[2026-08-07 14:44:53.400][000000010.911] I/user.qmc5883p_demo ---- [3/7] 完成 ----
[2026-08-07 14:44:53.889][000000011.411] I/user.qmc5883p_demo ===== [4/7] 过采样/降采样配置 =====
[2026-08-07 14:44:53.893][000000011.411] I/user.qmc5883p_demo 配置为最高滤波：OSR1=8（过采样 8 次）+ OSR2=8（降采样 8 次）
[2026-08-07 14:44:53.907][000000011.416] I/user.exs_qmc5883p 过采样/降采样配置为 osr=8 osr2=8
[2026-08-07 14:44:54.199][000000011.720] I/user.qmc5883p_demo 最高滤波: X=-19.60 Y=-11.20 Z=-25.89 uT
[2026-08-07 14:44:55.206][000000012.720] I/user.qmc5883p_demo 配置为最低功耗：OSR1=1 + OSR2=1
[2026-08-07 14:44:55.212][000000012.724] I/user.exs_qmc5883p 过采样/降采样配置为 osr=1 osr2=1
[2026-08-07 14:44:55.504][000000013.028] I/user.qmc5883p_demo 最低功耗: X=-25.89 Y=-8.88 Z=-5.39 uT
[2026-08-07 14:44:55.519][000000013.032] I/user.exs_qmc5883p 过采样/降采样配置为 osr=8 osr2=8
[2026-08-07 14:44:55.526][000000013.032] I/user.qmc5883p_demo ---- [4/7] 完成 ----
[2026-08-07 14:44:56.015][000000013.532] I/user.qmc5883p_demo ===== [5/7] 软复位演示 =====
[2026-08-07 14:44:56.030][000000013.544] I/user.exs_qmc5883p 软复位完成，配置已恢复
[2026-08-07 14:44:56.033][000000013.544] I/user.qmc5883p_demo 软复位完成，配置已恢复
[2026-08-07 14:44:56.327][000000013.848] I/user.qmc5883p_demo 复位后数据: X=3.01 Y=5.31 Z=-5.41 uT
[2026-08-07 14:44:56.334][000000013.848] I/user.qmc5883p_demo ---- [5/7] 完成 ----
[2026-08-07 14:44:56.823][000000014.348] I/user.qmc5883p_demo ===== [6/7] 芯片自检演示 =====
[2026-08-07 14:44:57.043][000000014.559] I/user.exs_qmc5883p 自检完成, 增量 dx=-154 dy=-130 dz=-84
[2026-08-07 14:44:57.049][000000014.559] I/user.qmc5883p_demo 自检增量 dx=-154 dy=-130 dz=-84
[2026-08-07 14:44:57.053][000000014.560] I/user.qmc5883p_demo 增量明显大于正常噪声（通常 >1000 LSB）表示信号链路正常
[2026-08-07 14:44:57.058][000000014.560] I/user.qmc5883p_demo ---- [6/7] 完成 ----
[2026-08-07 14:44:57.540][000000015.060] I/user.qmc5883p_demo ===== [7/7] 休眠唤醒与关闭 =====
[2026-08-07 14:44:57.546][000000015.060] I/user.qmc5883p_demo 进入挂起模式（低功耗约 22 μA）
[2026-08-07 14:44:57.551][000000015.062] I/user.exs_qmc5883p 已进入挂起模式
[2026-08-07 14:45:00.545][000000018.062] I/user.qmc5883p_demo 从挂起模式唤醒
[2026-08-07 14:45:00.551][000000018.064] I/user.exs_qmc5883p 已从挂起模式唤醒
[2026-08-07 14:45:00.747][000000018.267] I/user.qmc5883p_demo 唤醒后数据: X=-4.85 Y=-0.27 Z=3.81 uT
[2026-08-07 14:45:00.752][000000018.268] I/user.exs_qmc5883p 传感器已关闭
[2026-08-07 14:45:00.754][000000018.268] I/user.qmc5883p_demo ---- [7/7] 完成 ----
[2026-08-07 14:45:00.757][000000018.269] I/user.qmc5883p_demo ===== [演示完毕] =====
[2026-08-07 14:45:00.761][000000018.269] I/user.qmc5883p_demo End

6.6 故障排除

1. 传感器初始化失败：

   • 检查 QMC5883P 接线是否正确（SCL、SDA、VCC、GND）
   • 确认 GPIO 引脚配置与接线一致
   • 检查电源电压是否稳定（3.3V）
   • 确认 exs_qmc5883p 扩展库已正常加载

2. 读取数据始终为零：

   • 检查传感器供电是否正常
   • 检查 I2C 地址是否正确（QMC5883P 7 位地址为 0x2C，写操作地址 0x58，读操作地址 0x59）
   • 确认接线无松动

3. 量程切换无效果：

   • 确认 set_range() 参数为 "2G"/"8G"/"12G"/"30G"
   • 切换后需等待传感器稳定再读取数据

4. 自检增量过小：

   • 确认传感器工作正常，供电稳定
   • 自检增量明显大于正常噪声表示信号链路正常

6.7 扩展功能建议

exs_qmc5883p 更多接口的使用可以查看 exs_qmc5883p 扩展库说明