跳转至

exs_qmc5883l 扩展库

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

一、概述

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

1.1 主要特性

  • 16 位 ADC，三轴磁场测量（X/Y/Z）
  • 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 两种模式

1.2 注意事项

  • 推荐使用软件 I2C 模式：QMC5883L 在异常 I2C 通信后可能锁死 SDA 总线（拉低 SDA 不放），软件 I2C 模式可以通过 GPIO 直接脉冲 SCL 恢复总线。硬件 I2C 模式下无法控制引脚电平，总线锁死后无法恢复。
  • 硬件 I2C 如果在使用中遇到 SDA 被锁死导致通信超时，需要给传感器重新上电才能恢复。
  • SCL 和 SDA 需外接 4.7kΩ~10kΩ 上拉电阻到 VCC

1.3 加载方式

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

二、核心示例

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

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

2.1 基础读取示例（推荐：软件 I2C 模式）

-- 加载扩展库
local exs_qmc5883l = require "exs_qmc5883l"

-- 应用主函数
local function qmc5883l_demo()
    -- 使用软件 I2C 初始化 QMC5883L
    -- 软件 I2C 支持总线异常恢复，推荐使用
    local result = exs_qmc5883l.setup({
        scl = 27,
        sda = 26,
    })

    if not result then
        log.error("exs_qmc5883l", "QMC5883L 初始化失败")
        return
    end
    log.info("exs_qmc5883l", "QMC5883L 初始化成功")

    -- 循环读取磁场数据
    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))
        else
            log.error("exs_qmc5883l", "读取数据失败")
        end
        sys.wait(1000)
    end
end

-- 启动任务
sys.taskInit(qmc5883l_demo)

2.2 量程切换示例

-- 加载扩展库
local exs_qmc5883l = require "exs_qmc5883l"

exs_qmc5883l.setup({
    scl = 27,
    sda = 26,
})

-- 切换为 ±2G 量程（高精度，灵敏度 12000 LSB/G）
exs_qmc5883l.set_range("2G")

-- 读取高精度数据
local data = exs_qmc5883l.get_data()
if data then
    log.info("exs_qmc5883l", string.format("高精度: X=%.2f Y=%.2f Z=%.2f uT", data.x, data.y, data.z))
end

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

三、常量解释

扩展库常量，顾名思义是由合宙 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"。量程越小灵敏度越高，但可测量最大值越小
    参数示例："8G"
    config.range ,

    参数含义：输出数据速率
    数据类型：number
    取值范围：10、50、100、200，单位 Hz
    是否必选：否
    注意事项：默认 10。传入非精确值时向下取整到最近的可用值
    参数示例：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 值。

转换公式：μT = raw_value / sensitivity × 100（1 Gauss = 100 μT）

参数

无

返回值

local data = exs_qmc5883l.get_data()

data

含义说明：三轴磁场数据表
数据类型：table 或 nil
取值范围：成功返回包含 x/y/z 键和值的 table，值单位 μT，失败返回 nil
注意事项：不检查状态寄存器的 OVL/DOR 标志——这些是锁存标志，不影响数据寄存器有效值
返回示例：{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 高斯，12000 LSB/G）或 "8G"（±8 高斯，3000 LSB/G）
是否必选：是
注意事项：量程越小灵敏度越高，可测量最大值越小。仅在 setup() 之后调用有效。I2C 通信失败时不会切换
参数示例："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 通信失败时不会切换
参数示例：100

返回值

无

示例

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

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

4.4 控制与版本

4.4.1 exs_qmc5883l.soft_reset()

功能

软件复位 QMC5883L，复位后传感器进入待机模式，需要重新调用 exs_qmc5883l.setup(config) 以恢复工作

参数

无

返回值

无

示例

exs_qmc5883l.soft_reset()

4.4.2 exs_qmc5883l.version()

功能

获取 exs_qmc5883l 库的版本号

参数

无

返回值

local ver = exs_qmc5883l.version()

ver

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

示例

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

五、版本更新说明

版本号：202607131200

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

  2. 更新内容：

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

  4. 初始化接口使用 setup 命名，统一 TM16xx 系列命名规范
  5. 支持软件 I2C 和硬件 I2C 两种模式
  6. 支持量程切换（±2G / ±8G）
  7. 支持输出速率切换（10Hz / 50Hz / 100Hz / 200Hz）
  8. 支持过采样率配置（64 / 128 / 256 / 512）
  9. 支持软件复位

六、产品支持说明

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

问一下 AI