init: Air780EPM 官方 LuatOS 项目代码基线

- 来源: 合宙 LuatOS 官方仓库 air780epm 模块完整代码 - 路径: luatos/air780epm/module/Air780EPM/demo 含官方 demo(含 mqtt/mqtts/socket/uart 等) - 后续: 基于 demo 开发 UART<->MQTT 数据上报功能
2026-08-31 08:53:49 +08:00
commit 173dd6874f
813 changed files with 125484 additions and 0 deletions
@@ -0,0 +1,73 @@
+--[[
+@module  main
+@summary QMC5883P 三轴地磁传感器 Demo 入口
+@version 1.0
+@date    2026.08.05
+@author  江访
+]]
+
+--[[
+=== 演示内容 ===
+
+本 demo 演示 exs_qmc5883p 扩展库的完整功能，顺序为：
+HELLO→[1/7]→[2/7]→[3/7]→[4/7]→[5/7]→[6/7]→[7/7]→End
+
+1、初始化和数据读取（[1/7]）
+2、量程切换演示（[2/7]）
+3、输出速率切换（[3/7]）
+4、过采样/降采样配置（[4/7]）
+5、软复位演示（[5/7]）
+6、芯片自检演示（[6/7]）
+7、休眠唤醒与关闭（[7/7]）
+
+更多说明参考本目录下的 readme.md 文件
+]]
+
+--[[
+VERSION：项目版本号，ascii string类型
+        如果使用合宙iot.openluat.com进行远程升级，必须按照"XXX.YYY.ZZZ"三段格式定义：
+            X、Y、Z各表示1位数字，三个X表示的数字可以相同，也可以不同，同理三个Y和三个Z表示的数字也是可以相同，可以不同
+            因为历史原因，YYY这三位数字必须存在，但是没有任何用处，可以一直写为000
+        如果不使用合宙iot.openluat.com进行远程升级，根据自己项目的需求，自定义格式即可
+]]
+
+PROJECT = "QMC5883P_Demo"    -- 项目命名
+VERSION = "001.999.000"    -- 项目版本号
+
+-- 在日志中打印项目名和项目版本号
+log.info("main", PROJECT, VERSION)
+
+-- 设置日志输出风格为样式2（建议调试时开启）
+-- log.style(2)
+
+
+-- 如果内核固件支持errDump功能，此处进行配置，【强烈建议打开此处的注释】
+-- 因为此功能模块可以记录并且上传脚本在运行过程中出现的语法错误或者其他自定义的错误信息，可以初步分析一些设备运行异常的问题
+-- 以下代码是最基本的用法，更复杂的用法可以详细阅读API说明文档
+-- 启动errDump日志存储并且上传功能，600秒上传一次
+-- if errDump then
+--     errDump.config(true, 600)
+-- end
+
+
+-- 使用LuatOS开发的任何一个项目，都强烈建议使用远程升级FOTA功能
+-- 可以使用合宙的iot.openluat.com平台进行远程升级
+-- 也可以使用客户自己搭建的平台进行远程升级
+-- 远程升级的详细用法，可以参考fota的demo进行使用
+
+
+-- 启动一个循环定时器
+-- 每隔3秒钟打印一次总内存，实时的已使用内存，历史最高的已使用内存情况
+-- 方便分析内存使用是否有异常
+-- sys.timerLoopStart(function()
+--     log.info("mem.lua", rtos.meminfo())
+--     log.info("mem.sys", rtos.meminfo("sys"))
+-- end, 3000)
+
+-- 加载 qmc5883p_app.lua 演示模块
+require "qmc5883p_app"
+
+-- 用户代码已结束
+-- 结尾总是这一句
+sys.run()
+-- sys.run()之后不要加任何语句!!!!!
@@ -0,0 +1,289 @@
+--[[
+@module  qmc5883p_app
+@summary QMC5883P 三轴地磁传感器演示模块，包含所有功能的演示用例
+@version 1.0
+@date    2026.08.05
+@author  江访
+@usage
+本文件包含 QMC5883P 的逐项功能演示。
+通过 exs_qmc5883p 扩展库的 API 逐一演示数据读取、量程切换、输出速率切换、
+过采样/降采样配置、软复位、芯片自检、休眠唤醒等功能。
+
+通过 MODE 变量选择通信模式（改 MODE 的值即可，无需注释/取消注释代码）：
+  MODE = 1  软件 I2C（默认推荐，仅需 scl/sda 引脚，任意 GPIO 均可，接线最灵活）
+  MODE = 2  硬件 I2C（指定 i2c_id，占用 CPU 少，Air780EPM 用 I2C1）
+]]
+
+-- 加载 exs_qmc5883p 扩展库
+-- 该库提供 QMC5883P 的全部驱动功能: 初始化/数据读取/量程配置/速率配置/自检/电源管理
+local exs_qmc5883p = require "exs_qmc5883p"
+
+-- ==================== 通信模式选择 ====================
+-- 改 MODE 的值选择通信模式：
+--   1 = 软件 I2C（默认）   2 = 硬件 I2C
+-- 各模式所需引脚/参数见下方 init_config，接线说明见 readme.md
+local MODE = 1
+
+local init_config
+if MODE == 1 then
+    -- 软件 I2C：SCL/SDA 用任意 GPIO，Air780EPM 接线示例用 GPIO31/GPIO30
+    init_config = {scl = 31, sda = 30}
+elseif MODE == 2 then
+    -- 硬件 I2C：i2c_id 为总线号（Air780EPM 用 1），不传 scl/sda 时无总线恢复能力
+    init_config = {i2c_id = 1}
+else
+    log.error("qmc5883p_demo", "MODE 取值错误，应为 1/2")
+    return
+end
+
+--------------------------------------------------------------
+-- [1/7] 初始化与数据读取
+-- - setup() 自动完成芯片 ID 校验、I2C 总线恢复、采样参数配置
+-- - get_data() 返回三轴磁场强度，单位 μT，并带溢出标志 overflow
+--------------------------------------------------------------
+local function demo_init_and_read()
+    log.info("qmc5883p_demo", "===== [1/7] 初始化与数据读取 =====")
+
+    local result = exs_qmc5883p.setup(init_config)
+    if not result then
+        log.error("qmc5883p_demo", "QMC5883P 初始化失败")
+        log.error("qmc5883p_demo", "检查接线: VCC=3.3V GND SCL SDA")
+        return false  -- 初始化失败必须返回 false
+    end
+
+    log.info("qmc5883p_demo", "QMC5883P 初始化成功，版本:", exs_qmc5883p.version())
+
+    sys.wait(200)   -- 等待首次测量数据就绪，200ms
+
+    local data = exs_qmc5883p.get_data()
+    if data then
+        log.info("qmc5883p_demo", string.format("X=%.2f Y=%.2f Z=%.2f uT", data.x, data.y, data.z))
+    else
+        log.error("qmc5883p_demo", "读取数据失败")
+    end
+
+    for i = 1, 3 do
+        sys.wait(500)   -- 每 500ms 读取一次
+        local d = exs_qmc5883p.get_data()
+        if d then
+            log.info("qmc5883p_demo", string.format("第%d次读取: X=%.2f Y=%.2f Z=%.2f uT", i, d.x, d.y, d.z))
+        end
+    end
+
+    log.info("qmc5883p_demo", "---- [1/7] 完成 ----")
+    return true
+end
+
+--------------------------------------------------------------
+-- [2/7] 量程切换演示
+-- - set_range() 支持 "2G"/"8G"/"12G"/"30G" 四种量程
+-- - 切换后 get_data() 自动按新灵敏度换算 μT 值，无需重新 setup()
+--------------------------------------------------------------
+local function demo_range_switch()
+    log.info("qmc5883p_demo", "===== [2/7] 量程切换演示 =====")
+
+    log.info("qmc5883p_demo", "切换量程为 2G（高精度，灵敏度 15000 LSB/G）")
+    exs_qmc5883p.set_range("2G")
+    sys.wait(300)   -- 等待量程切换生效，300ms
+
+    local data = exs_qmc5883p.get_data()
+    if data then
+        log.info("qmc5883p_demo", string.format("2G 量程: X=%.2f Y=%.2f Z=%.2f uT", data.x, data.y, data.z))
+    end
+    sys.wait(1000)  -- 展示间隔，1 秒
+
+    log.info("qmc5883p_demo", "切换量程为 8G（宽范围，灵敏度 3750 LSB/G）")
+    exs_qmc5883p.set_range("8G")
+    sys.wait(300)   -- 等待量程切换生效，300ms
+
+    data = exs_qmc5883p.get_data()
+    if data then
+        log.info("qmc5883p_demo", string.format("8G 量程: X=%.2f Y=%.2f Z=%.2f uT", data.x, data.y, data.z))
+    end
+    sys.wait(1000)  -- 展示间隔，1 秒
+
+    log.info("qmc5883p_demo", "切换量程为 30G（最宽量程，抗干扰最强）")
+    exs_qmc5883p.set_range("30G")
+    sys.wait(300)   -- 等待量程切换生效，300ms
+
+    data = exs_qmc5883p.get_data()
+    if data then
+        log.info("qmc5883p_demo", string.format("30G 量程: X=%.2f Y=%.2f Z=%.2f uT", data.x, data.y, data.z))
+    end
+
+    -- 恢复默认量程
+    exs_qmc5883p.set_range("8G")
+    log.info("qmc5883p_demo", "---- [2/7] 完成 ----")
+end
+
+--------------------------------------------------------------
+-- [3/7] 输出速率切换演示
+-- - set_odr() 支持 10Hz / 50Hz / 100Hz / 200Hz
+-- - ODR 越低功耗越低，越高响应越快
+--------------------------------------------------------------
+local function demo_odr_switch()
+    log.info("qmc5883p_demo", "===== [3/7] 输出速率切换 =====")
+
+    local odr_list = {10, 50, 100, 200}
+    for _, odr in ipairs(odr_list) do
+        log.info("qmc5883p_demo", string.format("设置输出速率为 %dHz", odr))
+        exs_qmc5883p.set_odr(odr)
+        sys.wait(500)   -- 等待速率配置生效，500ms
+
+        local data = exs_qmc5883p.get_data()
+        if data then
+            log.info("qmc5883p_demo", string.format("%dHz 下: X=%.2f Y=%.2f Z=%.2f uT", odr, data.x, data.y, data.z))
+        end
+        sys.wait(500)   -- 展示间隔，500ms
+    end
+
+    exs_qmc5883p.set_odr(10)    -- 恢复默认 10Hz
+    log.info("qmc5883p_demo", "---- [3/7] 完成 ----")
+end
+
+--------------------------------------------------------------
+-- [4/7] 过采样/降采样配置演示
+-- - set_osr(osr, osr2)：osr 为过采样率（8/4/2/1），osr2 为降采样率（1/2/4/8）
+-- - 两者乘积最大 64，值越大噪声越低、功耗越高
+--------------------------------------------------------------
+local function demo_osr_config()
+    log.info("qmc5883p_demo", "===== [4/7] 过采样/降采样配置 =====")
+
+    log.info("qmc5883p_demo", "配置为最高滤波：OSR1=8（过采样 8 次）+ OSR2=8（降采样 8 次）")
+    exs_qmc5883p.set_osr(8, 8)
+    sys.wait(300)   -- 等待配置生效，300ms
+
+    local data = exs_qmc5883p.get_data()
+    if data then
+        log.info("qmc5883p_demo", string.format("最高滤波: X=%.2f Y=%.2f Z=%.2f uT", data.x, data.y, data.z))
+    end
+    sys.wait(1000)  -- 展示间隔，1 秒
+
+    log.info("qmc5883p_demo", "配置为最低功耗：OSR1=1 + OSR2=1")
+    exs_qmc5883p.set_osr(1, 1)
+    sys.wait(300)   -- 等待配置生效，300ms
+
+    data = exs_qmc5883p.get_data()
+    if data then
+        log.info("qmc5883p_demo", string.format("最低功耗: X=%.2f Y=%.2f Z=%.2f uT", data.x, data.y, data.z))
+    end
+
+    -- 恢复默认配置
+    exs_qmc5883p.set_osr(8, 8)
+    log.info("qmc5883p_demo", "---- [4/7] 完成 ----")
+end
+
+--------------------------------------------------------------
+-- [5/7] 软复位演示
+-- - soft_reset() 复位芯片后自动重新应用当前配置，无需重新 setup()
+--------------------------------------------------------------
+local function demo_soft_reset()
+    log.info("qmc5883p_demo", "===== [5/7] 软复位演示 =====")
+
+    local result = exs_qmc5883p.soft_reset()
+    if not result then
+        log.error("qmc5883p_demo", "软复位失败")
+        return false
+    end
+    log.info("qmc5883p_demo", "软复位完成，配置已恢复")
+    sys.wait(300)   -- 等待复位后数据稳定，300ms
+
+    local data = exs_qmc5883p.get_data()
+    if data then
+        log.info("qmc5883p_demo", string.format("复位后数据: X=%.2f Y=%.2f Z=%.2f uT", data.x, data.y, data.z))
+    end
+    log.info("qmc5883p_demo", "---- [5/7] 完成 ----")
+    return true
+end
+
+--------------------------------------------------------------
+-- [6/7] 芯片自检演示
+-- - self_test() 利用芯片内置自检激励信号验证信号链路是否正常
+-- - 返回自检前后三轴增量（单位 LSB），增量明显大于正常噪声
+--   表示信号链路正常
+--------------------------------------------------------------
+local function demo_self_test()
+    log.info("qmc5883p_demo", "===== [6/7] 芯片自检演示 =====")
+
+    local delta = exs_qmc5883p.self_test()
+    if not delta then
+        log.error("qmc5883p_demo", "芯片自检失败")
+        return false
+    end
+    log.info("qmc5883p_demo", string.format("自检增量 dx=%d dy=%d dz=%d", delta.dx, delta.dy, delta.dz))
+    log.info("qmc5883p_demo", "自检增量明显大于正常噪声表示信号链路正常")
+    log.info("qmc5883p_demo", "---- [6/7] 完成 ----")
+    return true
+end
+
+--------------------------------------------------------------
+-- [7/7] 休眠唤醒与关闭
+-- - sleep() 进入挂起模式（功耗约 22 μA），wakeup() 快速恢复，无需重新 setup()
+-- - close() 关闭传感器，之后需重新 setup() 才能使用
+--------------------------------------------------------------
+local function demo_sleep_wakeup_close()
+    log.info("qmc5883p_demo", "===== [7/7] 休眠唤醒与关闭 =====")
+
+    log.info("qmc5883p_demo", "进入挂起模式（低功耗约 22 μA）")
+    exs_qmc5883p.sleep()
+    sys.wait(3000)  -- 挂起演示 3 秒
+
+    log.info("qmc5883p_demo", "从挂起模式唤醒")
+    exs_qmc5883p.wakeup()
+    sys.wait(200)   -- 等待唤醒后数据稳定，200ms
+
+    local data = exs_qmc5883p.get_data()
+    if data then
+        log.info("qmc5883p_demo", string.format("唤醒后数据: X=%.2f Y=%.2f Z=%.2f uT", data.x, data.y, data.z))
+    end
+
+    exs_qmc5883p.close()
+    log.info("qmc5883p_demo", "---- [7/7] 完成 ----")
+    return true
+end
+
+--------------------------------------------------------------
+-- 主任务：按 [1/7]~[7/7] 顺序执行全部演示
+--------------------------------------------------------------
+local function qmc5883p_demo_task_func()
+    log.info("qmc5883p_demo", "HELLO")
+    sys.wait(1000)  -- 等待系统启动稳定，1 秒
+
+    local ok = demo_init_and_read()
+    if not ok then
+        log.error("qmc5883p_demo", "初始化失败，演示终止")
+        return
+    end
+    sys.wait(500)   -- 演示间隔，500ms
+
+    demo_range_switch()
+    sys.wait(500)   -- 演示间隔，500ms
+
+    demo_odr_switch()
+    sys.wait(500)   -- 演示间隔，500ms
+
+    demo_osr_config()
+    sys.wait(500)   -- 演示间隔，500ms
+
+    ok = demo_soft_reset()
+    if not ok then
+        log.error("qmc5883p_demo", "软复位失败，演示终止")
+        return
+    end
+    sys.wait(500)   -- 演示间隔，500ms
+
+    ok = demo_self_test()
+    if not ok then
+        log.error("qmc5883p_demo", "自检失败，演示终止")
+        return
+    end
+    sys.wait(500)   -- 演示间隔，500ms
+
+    demo_sleep_wakeup_close()
+
+    log.info("qmc5883p_demo", "===== [演示完毕] =====")
+    log.info("qmc5883p_demo", "End")
+end
+
+-- 启动演示任务协程
+sys.taskInit(qmc5883p_demo_task_func)
@@ -0,0 +1,265 @@
+# 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() 关闭
+
+## 三、显示效果
+
+![](https://docs.openluat.com/cdn/image/Air780EHM_qmc5883p.png)
+
+## 四、演示硬件环境
+
+### 4.1 硬件清单
+
+- Air780EPM 核心板 × 1
+- QMC5883P 三轴地磁传感器模块 × 1
+  demo所演示的QMC5883P[购买链接](https://item.taobao.com/item.htm?id=40554139118&mi_id=000052zSrRJbsW6EV_ocgwEuuox1wD1Jox20itdXNm9CiTc&skuId=4534297737305&spm=tbpc.boughtlist.suborder_itemtitle.1.67002e8dIVsk7g)
+- 母对母杜邦线 × 5
+- TYPE-C 数据线 × 1
+
+### 4.2 接线配置
+
+#### 4.2.1 QMC5883P 模块接线
+
+<table>
+<tr>
+<td>Air780EPM 核心板<br/></td><td>QMC5883P 模块<br/></td></tr>
+<tr>
+<td>32/GPIO31<br/></td><td>SCL<br/></td></tr>
+<tr>
+<td>31/GPIO30<br/></td><td>SDA<br/></td></tr>
+<tr>
+<td>VDD_EXT<br/></td><td>VCC<br/></td></tr>
+<tr>
+<td>GND<br/></td><td>GND<br/></td></tr>
+</table>
+
+> 说明：接线时注意杜邦线不宜过长，以免通信不稳定。
+
+## 五、演示软件环境
+
+### 5.1 开发工具
+
+- [Luatools下载调试工具](https://docs.openluat.com/air780egh/luatos/common/download/) - 固件烧录和代码调试
+
+### 5.2 内核固件
+
+- [点击下载Air780EPM系列最新版本内核固件](https://docs.openluat.com/air780epm/luatos/firmware/780epm_version/)，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` 中加载对应的演示模块：
+
+```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 后数据读取正常
+
+**日志如下：**
+
+```lua
+[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 扩展库说明](https://docs.openluat.com/osapi/ext/sensor/exs_qmc5883p/)