exs_qmc5883l 扩展库

作者：江访　|　最后修改：2026-07-23

一、概述

exs_qmc5883l 是 上海矽睿科技股份有限公司（QST） QMC5883L 三轴地磁传感器的 LuatOS 扩展库。QMC5883L 是一款低功耗、高精度的三轴地磁传感器，广泛应用于电子罗盘、导航定位、磁力检测、无人机等领域。

1.1 主要特性

• 16 位 ADC，三轴磁场测量（X/Y/Z），输出范围 -32768~32767

• I2C 接口通信，固定 7 位地址 0x0D（写 0x1A，读 0x1B）

• 支持两种量程：±2G 和 ±8G（默认 ±8G）

• 支持 4 种输出数据速率（ODR）：10Hz / 50Hz / 100Hz / 200Hz

• 支持 4 种过采样率（OSR）：64 / 128 / 256 / 512（默认 512）

• 连续测量模式，无需手动触发

• 数据输出单位为微特斯拉（μT），1 Gauss = 100 μT

• 支持软件 I2C 和硬件 I2C 两种模式

• 内置 I2C 总线卡死自动检测与恢复

1.2 注意事项

• 推荐使用软件 I2C 模式：QMC5883L 在异常 I2C 通信后可能锁死 SDA 总线（拉低 SDA 不放），软件 I2C 模式可以通过 GPIO 直接脉冲 SCL 恢复总线。硬件 I2C 模式传引脚号同样支持总线恢复。

• 初始化总线恢复：每次调用 setup() 时，如果传入了 scl/sda 引脚号，驱动会先将 SCL/SDA 临时切为 GPIO 模式，向 SCL 发最多 9 个时钟脉冲，每发一个检测 SDA 是否释放，释放后发 STOP 信号使总线恢复空闲，确保总线在通信开始前处于正常状态。仅传 i2c_id 时跳过此步骤。

• 运行时自动恢复：扩展库已内置 I2C 总线卡死自动检测与恢复。当 i2c.send() 或 i2c.recv() 返回失败时，驱动自动执行上述恢复流程并重试通信。此功能同样需要 scl/sda 引脚配置。

• SCL 和 SDA 需外接 4.7kΩ~10kΩ 上拉电阻到 VCC

1.3 功耗说明

通过 setup() 的 config.odr 和 config.osr 控制采样速率来调节功耗，ODR/OSR 越低功耗越低。连续测量模式功耗：

输出数据速率	低功耗(OSR≥256)	高性能(OSR≤128)
10 Hz	75 μA	100 μA
50 Hz	150 μA	250 μA
100 Hz	250 μA	450 μA
200 Hz	450 μA	850 μA

待机（sleep）模式功耗约 3 μA。

1.4 加载方式

-- 扩展库需要 require 加载后才能调用
local exs_qmc5883l = require "exs_qmc5883l"

1.5 硬件连接

QMC5883L 通过 I2C 接口与主控连接，SCL/SDA 需外接 4.7kΩ~10kΩ 上拉电阻。

  ┌──────────────┐                    ┌──────────────────┐
  │    主控      │                    │    QMC5883L      │
  │  (AirXXX)    │                    │  三轴地磁传感器   │
  │              │                    │                  │
  │ GPIO_SCL ────┼────────────────────┼──→ SCL           │
  │              │                    │                  │
  │ GPIO_SDA ←───┼────────────────────┼──→ SDA           │
  │              │                    │ （需外接上拉电阻）│
  │              │                    │                  │
  │ VCC 3.3V ────┼────────────────────┼──→ VCC           │
  │              │                    │                  │
  │ GND      ────┼────────────────────┼──→ GND           │
  └──────────────┘                    └──────────────────┘

各平台示例接线（以软件 I2C 模式为例）：

• Air8101：SCL=GPIO4, SDA=GPIO5

• Air780EHM/EHV/EGH：SCL=GPIO31, SDA=GPIO30

• Air8000：SCL=GPIO1, SDA=GPIO2

二、核心示例

核心示例是使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码，帮助开发者快速理解如何使用本库。

更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/sensor/qmc5883l

2.1 按使用接口划分

2.1.1 软件 I2C 模式（推荐）

通过 GPIO 模拟 I2C 时序，不依赖硬件 I2C 外设，任何 GPIO 引脚都可使用。软件 I2C 支持总线异常时通过 GPIO 直接脉冲 SCL 恢复总线。

主动轮询读取：

local exs_qmc5883l = require "exs_qmc5883l"
local result = exs_qmc5883l.setup({scl = 27, sda = 26})
if not result then return end

while true do
    local data = exs_qmc5883l.get_data()
    if data then
        log.info("exs_qmc5883l", string.format("X=%.1f Y=%.1f Z=%.1f uT", data.x, data.y, data.z))
    end
    sys.wait(1000)  -- 等待 1 秒后继续
end

2.1.2 硬件 I2C 模式

使用芯片内置的硬件 I2C 外设，引脚固定。传入引脚号同样支持总线恢复。

主动轮询读取：

local exs_qmc5883l = require "exs_qmc5883l"
local result = exs_qmc5883l.setup({i2c_id = 0, scl = 27, sda = 26})
if not result then return end

while true do
    local data = exs_qmc5883l.get_data()
    if data then
        log.info("exs_qmc5883l", string.format("X=%.1f Y=%.1f Z=%.1f uT", data.x, data.y, data.z))
    end
    sys.wait(1000)  -- 等待 1 秒后继续
end

2.2 按使用场景划分

2.2.1 电子罗盘静态指向（省电）

适用场景：指南针、导航设备、需要持续输出方向信息。

local result = exs_qmc5883l.setup({
    scl = 27, sda = 26,
    range = "8G",   -- 标准地磁场范围
    odr = 10,       -- 10Hz 低功耗
    osr = 512,      -- 最高精度
})
if not result then return end

2.2.2 量程切换示例

适用场景：在弱磁场环境用高精度 ±2G 量程，强磁场环境用宽范围 ±8G 量程。

-- 切换为 ±2G 量程（高精度，灵敏度 12000 LSB/G）
exs_qmc5883l.set_range("2G")
local data = exs_qmc5883l.get_data()
if data then
    log.info("exs_qmc5883l", string.format("2G 量程: X=%.1f Y=%.1f Z=%.1f uT", data.x, data.y, data.z))
end

-- 切换回 ±8G 量程（宽范围，灵敏度 3000 LSB/G）
exs_qmc5883l.set_range("8G")

2.2.3 输出速率切换

适用场景：低速采样省电（10Hz），高速采样跟踪快速运动（200Hz）。

-- 设置为 200Hz 高速输出（适合快速运动检测）
exs_qmc5883l.set_odr(200)

-- 设置为 10Hz 低功耗输出（适合静态指向）
exs_qmc5883l.set_odr(10)

2.2.4 休眠与唤醒示例

适用场景：间歇性采样的设备，不需要时休眠节省功耗。

-- 进入待机模式（低功耗，保留配置）
exs_qmc5883l.sleep()

-- 需要时唤醒，无需重新 setup()
exs_qmc5883l.wakeup()
local data = exs_qmc5883l.get_data()

---

三、常量解释

扩展库常量，顾名思义是由合宙 LuatOS 扩展库中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用，本扩展库没有常量。

---

四、函数详解

4.1 初始化

4.1.1 exs_qmc5883l.setup(config)

功能

初始化 QMC5883L 地磁传感器，配置 I2C 引脚和采样参数

参数

config

参数含义：初始化配置表
数据类型：table
取值范围：包含以下子参数：
{
    参数含义：SCL 时钟引脚 GPIO 编号
    数据类型：number
    取值范围：有效的 GPIO 编号
    是否必选：与 sda 一起可选
    注意事项：与 sda 一起传入时，无 i2c_id 则创建软件 I2C（推荐），有 i2c_id 则走硬件 I2C 并附带总线恢复
    参数示例：27
    config.scl ,

    参数含义：SDA 数据引脚 GPIO 编号
    数据类型：number
    取值范围：有效的 GPIO 编号
    是否必选：与 scl 一起可选
    注意事项：该引脚需外接 4.7kΩ~10kΩ 上拉电阻到 VCC
    参数示例：26
    config.sda ,

    参数含义：硬件 I2C 总线 ID
    数据类型：number
    取值范围：有效的 I2C 总线编号
    是否必选：可选
    注意事项：默认 0。与 scl/sda 一起传时使用硬件 I2C 通信 + 引脚恢复总线；不传 scl/sda 时使用硬件 I2C 但无总线恢复能力
    参数示例：1
    config.i2c_id ,

    参数含义：量程
    数据类型：string
    取值范围："2G"（±2 高斯，12000 LSB/G）或 "8G"（±8 高斯，3000 LSB/G）
    是否必选：否
    注意事项：默认 "8G"。量程越小灵敏度越高，可测量最大值越小。量程选择参考：
            - ±2G（灵敏度 12000 LSB/G）：适合弱磁场环境或需要高分辨率检测微小磁场变化的场景，如金属探测、磁异常检测、近距离磁场定位。每个 LSB 约 83 nT
            - ±8G（灵敏度 3000 LSB/G）：适合通用电子罗盘、导航定向等场景。地磁场强度一般 25~65 μT（约 0.25G~0.65G），±8G 量程完全覆盖。每个 LSB 约 333 nT
    参数示例："8G"
    config.range ,

    参数含义：输出数据速率
    数据类型：number
    取值范围：10、50、100、200，单位 Hz
    是否必选：否
    注意事项：默认 10。传入非精确值时向下取整到最近的可用值。ODR 越低功耗越低，待机（sleep）模式功耗约 3 μA，各 ODR 对应的功耗见 1.3 功耗说明。
    参数示例：50
    config.odr ,

    参数含义：过采样率
    数据类型：number
    取值范围：64、128、256、512
    是否必选：否
    注意事项：默认 512（最高精度）。过采样率越高噪声越低，但转换时间越长
    参数示例：512
    config.osr ,
}
是否必选：是
参数示例：
         -- 方式一：软件 I2C 模式（推荐），指定任意 GPIO 号
         exs_qmc5883l.setup({scl = 30, sda = 29})

         -- 方式二：硬件 I2C 模式 + 总线恢复，传 i2c_id + i2c引脚GPIO号
         exs_qmc5883l.setup({i2c_id = 1, scl = 18, sda = 19})

         -- 方式三：硬件 I2C 模式（无恢复），仅传 i2c_id
         exs_qmc5883l.setup({i2c_id = 1})

返回值

local init_result = exs_qmc5883l.setup(config)

init_result

含义说明：初始化是否成功
数据类型：boolean
取值范围：true（成功）, false（失败）
注意事项：失败时请检查接线、供电和 I2C 地址
返回示例：true

示例

-- 方式一：软件 I2C 模式（推荐），指定任意 GPIO 号
local result = exs_qmc5883l.setup({scl = 30, sda = 29})

-- 方式二：硬件 I2C 模式 + 总线恢复，传 i2c_id + i2c引脚GPIO号
local result = exs_qmc5883l.setup({i2c_id = 1, scl = 18, sda = 19})

-- 方式三：硬件 I2C 模式（无恢复），仅传 i2c_id
local result = exs_qmc5883l.setup({i2c_id = 1})

---

4.2 数据读取

4.2.1 exs_qmc5883l.get_data()

功能

读取 QMC5883L 三轴磁场数据，根据当前量程自动计算 μT 值。

参数

无

返回值

local data = exs_qmc5883l.get_data()

data

含义说明：三轴磁场数据表
数据类型：table 或 nil
取值范围：成功返回包含 x/y/z 键和值的 table，值单位 μT，失败返回 nil
注意事项：无
返回示例：{x = 25.3, y = -12.8, z = 35.6}

示例

-- 数据读取
local data = exs_qmc5883l.get_data()
if data then
    log.info("exs_qmc5883l", string.format("X=%.1f Y=%.1f Z=%.1f uT", data.x, data.y, data.z))
else
    log.error("exs_qmc5883l", "读取数据失败")
end

---

4.3 参数配置

4.3.1 exs_qmc5883l.set_range(range)

功能

切换量程，量程改变后会重置内部灵敏度系数

参数

range

参数含义：目标量程
数据类型：string
取值范围："2G"（±2 高斯）或 "8G"（±8 高斯）
是否必选：是
注意事项：量程越小灵敏度越高，可测量最大值越小。仅在 setup() 之后调用有效。I2C 通信失败时不会切换。
         量程选择参考：
            "2G"（±2G，灵敏度 12000 LSB/G）：适合弱磁场环境或需要高分辨率检测微小磁场变化的场景，如金属探测、磁异常检测、近距离磁场定位。每个 LSB 约 83 nT，可测量范围 ±200 μT
            "8G"（±8G，灵敏度 3000 LSB/G）：适合通用电子罗盘、导航定向等场景。地磁场强度一般 25~65 μT（约 0.25G~0.65G），±8G 量程完全覆盖。每个 LSB 约 333 nT，可测量范围 ±800 μT
            地磁场强度一般 25~65 μT（约 0.25G~0.65G），±8G 量程完全覆盖。每个 LSB 约 333 nT，可测量范围 ±800 μT
参数示例："2G"

返回值

无

示例

-- 切换为 ±2G 量程（高精度）
exs_qmc5883l.set_range("2G")

-- 切换回 ±8G 量程（宽范围）
exs_qmc5883l.set_range("8G")

---

4.3.2 exs_qmc5883l.set_odr(hz)

功能

切换输出数据速率（ODR）

参数

hz

参数含义：目标输出速率
数据类型：number
取值范围：10、50、100、200（单位 Hz）
是否必选：是
注意事项：传入整数，非精确匹配时向下取整到最近的可用值（例如 75 会被设置为 50Hz）。
          仅在 setup() 之后调用有效。I2C 通信失败时不会切换。ODR 选择参考：
          - 10Hz（75 μA）：低功耗，适合电子罗盘静态指向、静止姿态监测等不需要快速更新的场景
          - 50Hz（150 μA）：中等功耗，适合步行导航、手持设备方向跟踪
          - 100Hz（250 μA）：较高功耗，适合游戏控制、快速姿态变化跟踪
          - 200Hz（450 μA）：高功耗，适合高速运动检测、无人机飞行控制等需要快速响应的场景
参数示例：100

返回值

无

示例

-- 设置为 100Hz 输出
exs_qmc5883l.set_odr(100)

-- 设置为 10Hz 输出（低功耗）
exs_qmc5883l.set_odr(10)

---

4.4 电源管理

4.4.1 exs_qmc5883l.sleep()

功能

将传感器切换到待机模式，保持内部配置状态。调用 wakeup() 可快速恢复工作，无需重新 setup()。

参数

无

返回值

无

示例

exs_qmc5883l.sleep()

---

4.4.2 exs_qmc5883l.wakeup()

功能

从待机模式唤醒，恢复传感器到连续测量模式，配置保持休眠前的参数。无需重新调用 setup()。

参数

无

返回值

无

示例

exs_qmc5883l.wakeup()

---

4.4.3 exs_qmc5883l.close()

功能

关闭 QMC5883L 传感器。将传感器切换到待机模式，重置内部状态。close 后需要重新调用 setup() 才能再次使用。

参数

无

返回值

无

示例

exs_qmc5883l.close()

---

4.5 版本信息

4.5.1 exs_qmc5883l.version()

功能

获取 exs_qmc5883l 库的版本号

参数

无

返回值

local ver = exs_qmc5883l.version()

ver

含义说明：版本号字符串
数据类型：string
取值范围：格式 "yyyymmddhhmm"，表示 yyyy年mm月dd日hh时mm分发布的版本
注意事项：无
返回示例："202607170900"

示例

local ver = exs_qmc5883l.version()
log.info("exs_qmc5883l", "版本号:", ver)

---

五、版本更新说明

版本号：202607200639

1. 更新时间：2026-07-20

2. 更新内容：

   • i2c_bus_recovery SDA 释放检测移到 SCL 低电平期间执行，避免引脚模式切换毛刺干扰从机状态机

   • 恢复 SDA 释放检测功能（提前结束脉冲循环），同时保证异常状态下总线恢复不受影响

版本号：202607170900

1. 更新时间：2026-07-17

2. 更新内容：

   • i2c_bus_recovery 增加 sys.wait(1) 确保脉冲宽度足够

   • i2c_bus_recovery 增加 SDA 释放检测，提前结束脉冲循环

   • i2c_write/i2c_read 增加 I2C 总线卡死自动检测与恢复

   • 硬件 I2C 恢复后自动重新 i2c.setup()

   • 新增 exs_qmc5883l.close() 接口，关闭传感器并释放资源

   • 新增 exs_qmc5883l.sleep()/wakeup() 低功耗接口，替换 soft_reset()

版本号：202607131200

1. 更新时间：2026-07-13

2. 更新内容：

   • 初版，实现 QMC5883L 驱动所有基础功能

   • 初始化接口使用 setup 命名，统一 TM16xx 系列命名规范

   • 支持软件 I2C 和硬件 I2C 两种模式

   • 支持量程切换（±2G / ±8G）

   • 支持输出速率切换（10Hz / 50Hz / 100Hz / 200Hz）

   • 支持过采样率配置（64 / 128 / 256 / 512）

   • 支持软件复位

---

六、产品支持说明

所有支持 luatos 二次开发的模块，具体可以查看选型手册。