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

QMC5883L 三轴地磁传感器演示

一、功能模块介绍

1.1 核心主程序模块

1. main.lua - 主程序入口，负责项目初始化、版本定义和任务调度
2. qmc5883l_demo.lua - QMC5883L 功能演示模块，包含数据读取、量程切换、输出速率切换等所有功能的演示用例

1.2 扩展库模块

1. exs_qmc5883l - QMC5883L 扩展库，提供初始化、三轴磁场数据读取、量程切换、输出速率切换、睡眠/唤醒、关闭等 API

1.3 I2C 模式说明

推荐使用软件 I2C 模式：QMC5883L 在异常 I2C 通信后可能锁死 SDA 总线。本库已内置 I2C 总线卡死自动检测与恢复功能。本 demo 使用软件 I2C 模式演示。

二、演示流程介绍

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

2.1 功能演示项说明

1. [1/4] 初始化与数据读取 - 初始化 QMC5883L 传感器并读取三轴磁场数据（X/Y/Z，单位 μT）
2. [2/4] 量程切换演示 - 在 ±2G（高精度）和 ±8G（宽范围）量程之间切换，观察数据变化
3. [3/4] 输出速率切换 - 依次切换 10Hz / 50Hz / 100Hz / 200Hz 输出速率
4. [4/4] 休眠与唤醒演示 - 演示 sleep()/wakeup() 待机与唤醒

三、显示效果

四、演示硬件环境

3.1 硬件清单

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

3.2 接线配置

3.2.1 QMC5883L 模块接线

Air780EPM 核心板	QMC5883L 模块
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. qmc5883l_demo.lua - QMC5883L 功能演示模块
3. exs_qmc5883l - QMC5883L 扩展库

六、演示核心步骤

6.1 硬件准备

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

6.2 软件配置

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

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

6.3 软件烧录

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

6.4 功能测试

6.4.1 初始化与数据读取演示

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

6.4.2 量程切换演示

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

6.4.3 输出速率切换演示

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

6.4.4 休眠与唤醒演示

1. 自动进入 [4/4] 休眠与唤醒演示
2. 观察 sleep() 进入待机模式
3. 观察 wakeup() 唤醒后数据恢复

6.5 预期效果

• 初始化与数据读取：QMC5883L 初始化成功，三轴磁场数据正常输出
• 量程切换：量程切换后数据范围随之变化，灵敏度不同
• 输出速率切换：不同速率下均能正常读取数据
• 休眠与唤醒：sleep 后进入低功耗，wakeup 后数据读取正常
• 日志如下：

[2026-07-21 10:31:33.902][000000000.180] I/main LuatOS@Air780EPM base 26.04 bsp V2046 32bit
[2026-07-21 10:31:33.908][000000000.180] I/main ROM Build: Jul  7 2026 20:39:17
[2026-07-21 10:31:33.914][000000000.182] W/pins /luadb/pins_air780epm.json not exist!!
[2026-07-21 10:31:33.921][000000000.184] D/main loadlibs luavm 1048568 14784 14784
[2026-07-21 10:31:33.930][000000000.184] D/main loadlibs sys   2366664 82756 89356
[2026-07-21 10:31:33.940][000000000.185] D/main loadlibs psram 2366664 82756 89356
[2026-07-21 10:31:33.945][000000000.202] I/user.main QMC5883L_Demo 001.999.000
[2026-07-21 10:31:33.953][000000000.215] D/user.exs_qmc5883l version -> 202607200639
[2026-07-21 10:31:33.958][000000000.216] I/user.qmc5883l_demo HELLO
[2026-07-21 10:31:34.544][000000001.216] I/user.qmc5883l_demo ===== [1/4] 初始化与数据读取 =====
[2026-07-21 10:31:34.551][000000001.224] I/user.exs_qmc5883l I2C总线恢复完成
[2026-07-21 10:31:34.561][000000001.230] I/user.exs_qmc5883l 初始化完成, range=8G odr=10Hz osr=512
[2026-07-21 10:31:34.571][000000001.231] I/user.qmc5883l_demo QMC5883L 初始化成功，版本: 202607200639
[2026-07-21 10:31:34.586][000000001.434] I/user.qmc5883l_demo X=-25.90 Y=13.70 Z=13.33 uT
[2026-07-21 10:31:36.087][000000002.863] I/mobile sim0 sms ready
[2026-07-21 10:31:36.099][000000002.863] D/mobile cid1, state0
[2026-07-21 10:31:36.113][000000002.864] D/mobile bearer act 0, result 0
[2026-07-21 10:31:36.125][000000002.864] D/mobile NETIF_LINK_ON -> IP_READY
[2026-07-21 10:31:36.133][000000002.906] D/mobile TIME_SYNC 0 tm 1784601099
[2026-07-21 10:31:36.144][000000002.937] I/user.qmc5883l_demo 第1次读取: X=-30.07 Y=14.53 Z=7.33 uT
[2026-07-21 10:31:36.579][000000003.440] I/user.qmc5883l_demo 第2次读取: X=-29.90 Y=15.93 Z=3.53 uT
[2026-07-21 10:31:37.075][000000003.943] I/user.qmc5883l_demo 第3次读取: X=-19.70 Y=21.90 Z=-12.53 uT
[2026-07-21 10:31:37.088][000000003.943] I/user.qmc5883l_demo ---- [1/4] 完成 ----
[2026-07-21 10:31:37.572][000000004.443] I/user.qmc5883l_demo ===== [2/4] 量程切换演示 =====
[2026-07-21 10:31:37.587][000000004.444] I/user.qmc5883l_demo 切换量程为 2G（高精度）
[2026-07-21 10:31:37.599][000000004.446] I/user.exs_qmc5883l 量程切换为 2G
[2026-07-21 10:31:37.884][000000004.749] I/user.qmc5883l_demo 2G 量程: X=8.56 Y=16.00 Z=-10.85 uT
[2026-07-21 10:31:38.892][000000005.749] I/user.qmc5883l_demo 切换量程为 8G（宽范围）
[2026-07-21 10:31:38.906][000000005.752] I/user.exs_qmc5883l 量程切换为 8G
[2026-07-21 10:31:39.186][000000006.055] I/user.qmc5883l_demo 8G 量程: X=-37.03 Y=10.07 Z=-3.60 uT
[2026-07-21 10:31:40.192][000000007.055] I/user.qmc5883l_demo ---- [2/4] 完成 ----
[2026-07-21 10:31:40.690][000000007.555] I/user.qmc5883l_demo ===== [3/4] 输出速率切换 =====
[2026-07-21 10:31:40.701][000000007.556] I/user.qmc5883l_demo 设置输出速率为 10Hz
[2026-07-21 10:31:40.711][000000007.558] I/user.exs_qmc5883l 输出速率切换为 10Hz
[2026-07-21 10:31:41.203][000000008.061] I/user.qmc5883l_demo 10Hz 下: X=-16.93 Y=-30.57 Z=-4.20 uT
[2026-07-21 10:31:41.696][000000008.561] I/user.qmc5883l_demo 设置输出速率为 50Hz
[2026-07-21 10:31:41.709][000000008.564] I/user.exs_qmc5883l 输出速率切换为 50Hz
[2026-07-21 10:31:42.208][000000009.067] I/user.qmc5883l_demo 50Hz 下: X=-32.77 Y=-15.93 Z=7.07 uT
[2026-07-21 10:31:42.704][000000009.567] I/user.qmc5883l_demo 设置输出速率为 100Hz
[2026-07-21 10:31:42.717][000000009.570] I/user.exs_qmc5883l 输出速率切换为 100Hz
[2026-07-21 10:31:43.201][000000010.073] I/user.qmc5883l_demo 100Hz 下: X=-33.20 Y=-13.87 Z=8.43 uT
[2026-07-21 10:31:43.715][000000010.573] I/user.qmc5883l_demo 设置输出速率为 200Hz
[2026-07-21 10:31:43.725][000000010.576] I/user.exs_qmc5883l 输出速率切换为 200Hz
[2026-07-21 10:31:44.213][000000011.079] I/user.qmc5883l_demo 200Hz 下: X=-32.93 Y=-13.70 Z=8.43 uT
[2026-07-21 10:31:44.711][000000011.581] I/user.exs_qmc5883l 输出速率切换为 10Hz
[2026-07-21 10:31:44.722][000000011.582] I/user.qmc5883l_demo ---- [3/4] 完成 ----
[2026-07-21 10:31:45.211][000000012.082] I/user.qmc5883l_demo ===== [4/4] 休眠与唤醒演示 =====
[2026-07-21 10:31:45.222][000000012.083] I/user.qmc5883l_demo 进入待机模式（低功耗）
[2026-07-21 10:31:45.233][000000012.084] I/user.exs_qmc5883l 已进入待机模式
[2026-07-21 10:31:55.716][000000022.584] I/user.qmc5883l_demo 从待机模式唤醒
[2026-07-21 10:31:55.727][000000022.585] I/user.exs_qmc5883l 已从待机模式唤醒
[2026-07-21 10:31:55.918][000000022.788] I/user.qmc5883l_demo 唤醒后数据: X=-32.70 Y=-13.93 Z=8.53 uT
[2026-07-21 10:31:55.930][000000022.788] I/user.qmc5883l_demo ---- [4/4] 完成 ----
[2026-07-21 10:31:56.431][000000023.289] I/user.qmc5883l_demo ===== [演示完毕] =====
[2026-07-21 10:31:56.445][000000023.290] I/user.exs_qmc5883l 传感器已关闭
[2026-07-21 10:31:56.461][000000023.291] I/user.qmc5883l_demo End

6.6 故障排除

1. 传感器初始化失败：

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

2. 读取数据始终为零：

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

3. 量程切换无效果：

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

6.7 扩展功能建议

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