跳转至

exs_ns2520 扩展库

作者：王世豪　|　最后修改：2026-07-16

一、概述

exs_ns2520 是 NS2520 数字压力传感器的 LuatOS 扩展库。NS2520 是一款 I2C 接口数字压力传感器，支持压力和温度同时输出。

1.1 主要特性

  • 24 位 ADC，压力温度双通道同时测量
  • I2C 接口通信，默认 7 位地址 0x77
  • 8 级可调过采样率（1x~128x），兼顾速度与精度
  • 内置校准系数，自动完成压力和温度补偿计算
  • 支持 4 种测量模式：待机、压力单次、温度单次、压力温度连续
  • 压力输出单位 hPa（百帕），温度输出单位 ℃
  • 支持温度偏移校准
  • 支持硬件 I2C 模式

1.2 注意事项

  • NS2520 温度读数普遍偏高约 7℃，setup() 默认启用 -7.0℃ 温度偏移校准
  • 首次上电温度可能异常（>85℃ 或 <-40℃），get_data() 内部会自动重试一次
  • 连续模式下读完数据会自动切回待机，避免干扰后续单次测量

1.3 加载方式

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

1.4 硬件连接

  ┌──────────────┐                    ┌──────────────────┐
  │    主控      │                    │     NS2520       │
  │              │                    │   压力传感器     │
  │              │                    │                  │
  │ I2C_SCL ─────┼────────────────────┼──→ SCL          │
  │              │                    │                  │
  │ I2C_SDA ←───┼────────────────────┼──→ SDA          │
  │              │                    │                  │
  │ VCC      ────┼────────────────────┼──→ VCC          │
  │              │                    │                  │
  │ GND      ────┼────────────────────┼──→ GND          │
  └──────────────┘                    └──────────────────┘

SCL 和 SDA 需外接上拉电阻到 VCC。默认 7 位 I2C 地址 0x77。

二、核心示例

2.1 基础读取示例

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

-- 应用主函数
local function ns2520_demo()
    -- 初始化 NS2520（使用默认 16x 过采样率，-7.0℃ 温度偏移）
    local result = exs_ns2520.setup({i2c_id = 1})

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

    -- 循环读取压力和温度数据
    while true do
        local data = exs_ns2520.get_data()
        if data then
            log.info("exs_ns2520", string.format("压力 %.2f hPa 温度 %.2f ℃", data.pressure, data.temperature))
        else
            log.error("exs_ns2520", "读取数据失败")
        end
        sys.wait(1000)
    end
end

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

2.2 过采样率切换示例

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

exs_ns2520.setup({i2c_id = 1})

-- 切换为 1x 快速模式（低精度、低功耗）
exs_ns2520.set_osr(0, 0)
sys.wait(50)
local data_fast = exs_ns2520.get_data()
if data_fast then
    log.info("exs_ns2520", string.format("快速模式: 压力 %.2f hPa 温度 %.2f ℃", data_fast.pressure, data_fast.temperature))
end

-- 切换为 64x 高精度模式
exs_ns2520.set_osr(6, 6)
sys.wait(200)
local data_high = exs_ns2520.get_data()
if data_high then
    log.info("exs_ns2520", string.format("高精度模式: 压力 %.2f hPa 温度 %.2f ℃", data_high.pressure, data_high.temperature))
end

-- 仅修改压力过采样率，温度保持不变
exs_ns2520.set_osr(4, nil)

2.3 单次读取示例

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

exs_ns2520.setup({i2c_id = 1})

-- 仅读取压力，不读温度
local pressure = exs_ns2520.get_pressure()
if pressure then
    log.info("exs_ns2520", string.format("压力 %.2f hPa", pressure))
end

-- 仅读取温度，不读压力
local temperature = exs_ns2520.get_temperature()
if temperature then
    log.info("exs_ns2520", string.format("温度 %.2f ℃", temperature))
end

三、常量解释

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

四、函数详解

4.1 初始化

4.1.1 exs_ns2520.setup(config)

功能

初始化 NS2520 压力传感器，配置 I2C 通信参数、过采样率和温度偏移

参数

config

参数含义：初始化配置表
数据类型：table
取值范围：包含以下子参数：
{
    参数含义：硬件 I2C 总线 ID
    数据类型：number
    取值范围：有效的 I2C 总线编号（如 1 表示 I2C1）
    是否必选：是
    注意事项：根据实际硬件连接选择正确的 I2C 总线
    参数示例：1
    config.i2c_id ,

    参数含义：I2C 设备地址（7 位）
    数据类型：number
    取值范围：有效的 7 位 I2C 地址
    是否必选：否
    注意事项：默认 0x77，无需修改
    参数示例：0x77
    config.addr ,

    参数含义：压力过采样率（OSR，Oversampling Rate）
    数据类型：number
    取值范围：0~7，对应 1x/2x/4x/8x/16x/32x/64x/128x
    是否必选：否
    注意事项：默认 4（16x），一般情况下无需修改。NS2520 数据手册 Table 9 给出 3 个推荐配置：
              - 0（1x）：精度 5 Pa（~40 cm），电流 3 μA，1 次/秒，适合仅需判断气压升降趋势、对精度要求不高的低功耗场景
              - 4（16x）：精度 ~1.2 Pa（~10 cm），电流 22 μA，2 次/秒，适合高度计、室内楼层检测等常规场景
              - 6（64x）：精度 ~0.6 Pa（~5 cm），电流 200 μA，4 次/秒，适合无人机定高、运动追踪等需要厘米级高度分辨率的高精度场景
              注：OSR 取值范围 0~7 均为有效值，其余档位的精度和速度介于相邻推荐档位之间，可按需选择。
    参数示例：6
    config.prs_osr ,

    参数含义：温度过采样率（OSR，Oversampling Rate）
    数据类型：number
    取值范围：0~7，对应 1x/2x/4x/8x/16x/32x/64x/128x
    是否必选：否
    注意事项：默认 4（16x）。手册 Table 9 的 3 个推荐配置中温度 OSR 均为 1x。
             OSR 越高，温度精度越高，但测量时间越长；
             OSR 越低，测量时间越短，但温度噪声越大。
             温度噪声对压力精度影响极小（补偿公式中温度项系数很小），若应用仅需压力数据，1x 即可满足要求；若需准确的温度读数本身，可使用更大的 OSR。
    参数示例：6
    config.tmp_osr ,

    参数含义：温度偏移校正值（℃）
    数据类型：number
    取值范围：任意数值，正数提升读数，负数降低读数
    是否必选：否
    注意事项：默认 -7.0。NS2520 读数普遍偏高约 7℃，设 -7.0 可校准到真实温度；不填写或者设 0 则不做校准
    参数示例：0
    config.temp_offset ,
}
是否必选：是
参数示例：
         -- 最小化初始化（默认参数）
         exs_ns2520.setup({i2c_id = 1})

         -- 自定义过采样率 + 关闭温度偏移
         exs_ns2520.setup({i2c_id = 1, prs_osr = 6, tmp_osr = 6, temp_offset = 0})

返回值

local init_result = exs_ns2520.setup(config)

init_result

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

示例

-- 使用默认参数初始化
local result = exs_ns2520.setup({i2c_id = 1})

-- 使用高精度 + 关闭温度偏移
local result = exs_ns2520.setup({i2c_id = 1, prs_osr = 6, tmp_osr = 6, temp_offset = 0})

4.2 数据读取

4.2.1 exs_ns2520.get_data()

功能

同时读取压力和温度数据，一次 I2C 通信获取两项数据并自动完成补偿计算。

使用连续模式测量，读完后自动切回待机，不会干扰后续 get_pressure() / get_temperature() 单次调用。

参数

无

返回值

local data = exs_ns2520.get_data()

data

含义说明：压力和温度数据表，包含以下字段：
        - pressure：补偿后的压力值
        - temperature：补偿后的温度值
数据类型：table 或 nil，table内的pressure和temperature均为 number类型
取值范围：pressure：300~1200 hPa，保留 2 位小数
         temperature：-40~85 ℃，保留 2 位小数
注意事项：pressure 单位为 hPa（百帕）；temperature 单位为 ℃，已叠加热偏移校准（默认 -7.0℃）。若初始化后未调用 setup() 也会返回 nil
返回示例：{pressure = 991.98, temperature = 28.54}

示例

local data = exs_ns2520.get_data()
if data then
    log.info("exs_ns2520", string.format("压力 %.2f hPa 温度 %.2f ℃", data.pressure, data.temperature))
else
    log.error("exs_ns2520", "读取数据失败")
end

4.2.2 exs_ns2520.get_pressure()

功能

单次读取压力值，仅触发压力测量通道，不读取温度。适用于只需压力数据的场景，相比 get_data() 速度更快。

参数

无

返回值

local pressure = exs_ns2520.get_pressure()

pressure

含义说明：补偿后的压力值
数据类型：number 或 nil
取值范围：300~1200 hPa(保留 2 位小数)，失败返回 nil
注意事项：需要先调用 setup()。若 I2C 通信失败或测量超时，返回 nil
返回示例：991.98

示例

local pressure = exs_ns2520.get_pressure()
if pressure then
    log.info("exs_ns2520", string.format("压力 %.2f hPa", pressure))
end

4.2.3 exs_ns2520.get_temperature()

功能

单次读取温度值，仅触发温度测量通道，不读取压力。适用于只需温度数据的场景，相比 get_data() 速度更快。

参数

无

返回值

local temperature = exs_ns2520.get_temperature()

temperature

含义说明：补偿后的温度值（℃）
数据类型：number 或 nil
取值范围：-40~85 ℃(保留 2 位小数)，失败返回 nil
注意事项：需要先调用 setup()。温度值已叠加热偏移校准（默认 -7.0℃）。若测量超时，返回 nil
返回示例：28.55

示例

local temperature = exs_ns2520.get_temperature()
if temperature then
    log.info("exs_ns2520", string.format("温度 %.2f ℃", temperature))
end

4.3 参数配置

4.3.1 exs_ns2520.set_osr(prs_osr, tmp_osr)

功能

在线切换过采样率，无需重新初始化。可分别设置压力和温度的过采样率，支持单独修改其中一个。

参数

prs_osr

参数含义：压力过采样率（OSR，Oversampling Rate）
数据类型：number
取值范围：0~7，对应 1x/2x/4x/8x/16x/32x/64x/128x
是否必选：否
注意事项：默认 4（16x），一般情况下无需修改。NS2520 数据手册 Table 9 给出 3 个推荐配置：
          - 0（1x）：精度 5 Pa（~40 cm），电流 3 μA，1 次/秒，适合仅需判断气压升降趋势、对精度要求不高的低功耗场景
          - 4（16x）：精度 ~1.2 Pa（~10 cm），电流 22 μA，2 次/秒，适合高度计、室内楼层检测等常规场景
          - 6（64x）：精度 ~0.6 Pa（~5 cm），电流 200 μA，4 次/秒，适合无人机定高、运动追踪等需要厘米级高度分辨率的高精度场景
          注：OSR 取值范围 0~7 均为有效值，其余档位的精度和速度介于相邻推荐档位之间，可按需选择。
参数示例：6

tmp_osr

参数含义：温度过采样率（OSR，Oversampling Rate）
数据类型：number
取值范围：0~7，对应 1x/2x/4x/8x/16x/32x/64x/128x
是否必选：否
注意事项：默认 4（16x）。手册 Table 9 的 3 个推荐配置中温度 OSR 均为 1x。
         OSR 越高，温度精度越高，但测量时间越长；
         OSR 越低，测量时间越短，但温度噪声越大。
         温度噪声对压力精度影响极小（补偿公式中温度项系数很小），若应用仅需压力数据，1x 即可满足要求；若需准确的温度读数本身，可使用更大的 OSR。
参数示例：6

返回值

无

示例

-- 同时设置压力和温度为 64x 高精度
exs_ns2520.set_osr(6, 6)

-- 同时设置压力和温度为 1x 快速模式
exs_ns2520.set_osr(0, 0)

-- 仅修改压力过采样率，温度不变
exs_ns2520.set_osr(4, nil)

4.4 控制与版本

4.4.1 exs_ns2520.close()

功能

关闭传感器，使其进入待机模式以降低功耗。关闭后需重新调用 exs_ns2520.setup(config) 才能恢复使用。

参数

无

返回值

无

示例

-- 关闭传感器
exs_ns2520.close()

-- 关闭后再读返回 nil
local data = exs_ns2520.get_data()  -- 返回 nil

4.4.2 exs_ns2520.version()

功能

获取 exs_ns2520 库的版本号

参数

无

返回值

local ver = exs_ns2520.version()

ver

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

示例

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

五、版本更新说明

版本号：202607161400

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

  2. 更新内容：

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

  4. 遵循 exs_ 扩展库设计规范
  5. 支持 I2C 通信重试机制（最多 3 次重试）
  6. 支持校准系数自动读取和补偿计算
  7. 支持过采样率动态配置（0~7 共 8 级）
  8. 支持压力和温度单独读取 / 同时读取
  9. 支持温度偏移校准（默认 -7.0℃）
  10. 支持关闭 / 待机模式

六、产品支持说明

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

AI问答/AI搜索