exs_lis2dh12 扩展库

作者：江访　|　最后修改：2026-08-06

一、概述

exs_lis2dh12 是 意法半导体 LIS2DH12 三轴加速度传感器的 LuatOS 扩展库。 LIS2DH12 属于 ST "femto"系列，是一款超低功耗、高性能的三轴加速度传感器，广泛应用于运动检测、倾斜测量、自由落体检测、计步器等领域。

1.1 主要特性

• 12/10/8 位分辨率 ADC，三轴加速度测量（X/Y/Z）

• I2C 双接口通信

• I2C 7 位地址可选 0x18（SA0=GND）或 0x19（SA0=VCC）

• 支持四种量程：±2g / ±4g / ±8g / ±16g（默认 ±2g）

• 支持多种输出数据速率（ODR）：1Hz 至 5.376kHz

• 三种功耗模式：高精度模式（HR）、普通模式（Normal）、低功耗模式（Low-power）

• 内置温度传感器

• 内置 32 级 FIFO

• 支持自由落体和运动检测中断

• 支持单击/双击检测

• 支持 6D/4D 方向检测

• 数据输出单位为重力加速度 g

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

1.2 注意事项

• 推荐使用软件 I2C 模式：LIS2DH12 在异常 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 引脚配置。

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

• 三种功耗模式：HR（高精度 12-bit）、Normal（普通 10-bit）、Low-power（低功耗 8-bit）

• BDU（Block Data Update）默认使能，确保高/低字节读取一致性

• 温度传感器需要先通过 enable_temp(true) 或在 setup 中设置 enable_temp = true 使能

1.3 功耗模式说明

通过 setup() 的 config.powermode 参数配置，默认 highres。示例：

-- 低功耗模式初始化
local ok = exs_lis2dh12.setup("I2C", {
    scl = 27, sda = 26,
    powermode = "lowpower",
})

三种功耗模式的区别：

特性	Low-power	Normal	High-res
分辨率	8-bit（±128 LSB/g @ ±2g）	10-bit（±512 LSB/g @ ±2g）	12-bit（±16000 LSB/g @ ±2g，左对齐）
可用 ODR	1 Hz ~ 5376 Hz	1 Hz ~ 1344 Hz	1 Hz ~ 1344 Hz
噪声（RMS @ 50Hz）	30 mg	10 mg	2.2 mg

三种功耗模式在不同 ODR 下的典型功耗（来源：芯片数据手册）：

ODR	Low-power(8-bit)	Normal(10-bit)	High-res(12-bit)
1 Hz	2 μA	2 μA	2 μA
10 Hz	3 μA	4 μA	4 μA
25 Hz	4 μA	6 μA	6 μA
50 Hz	6 μA	11 μA	11 μA
100 Hz	10 μA	20 μA	20 μA
200 Hz	18 μA	38 μA	38 μA
400 Hz	36 μA	73 μA	73 μA
1344 Hz	—	185 μA	185 μA
1620 Hz	100 μA	—	—
5376 Hz	185 μA	—	—

power-down（sleep）模式功耗约 1 μA。

说明： - Low-power：分辨率最低（8-bit），但功耗极低，可使用高达 5376 Hz 的 ODR，适合对精度要求不高但需要高速采样或超低功耗的场景

• Normal：中等分辨率（10-bit），功耗与 high-res 基本相同，适合日常运动检测

• High-res：最高分辨率（12-bit，左对齐为 16-bit），噪声最低（2.2 mg），适合姿态解算、振动分析等精度要求高的场景

1.4 中断事件类型说明

通过 setup() 的 config.int1 / config.int2 参数配置中断事件，设置 int_gpio 和事件 boolean 即可。详情见 setup 参数说明。

中断事件	触发时机	推荐用途
data_ready	每次新数据准备好时触发。100Hz+ 高频场景不适合用 cb 回调，建议通过 get_int_flag() 轮询	实时数据采集
activity	加速度超过阈值时触发	运动唤醒、节能
free_fall	检测到自由落体时触发	跌落保护
tap	检测到敲击时触发	敲击交互
direction	设备朝向变化时触发	横竖屏切换、翻转检测

1.5 方向检测说明

通过 setup() 的 config.enable_direction 参数开启，开启后 get_data() 返回的 data.dir 自动附带朝向信息， 也可通过 get_orientation() 单独查询。

enable_direction 是方向检测独立开关，任何时候 get_orientation() 都能读到芯片当前朝向，不受中断影响： - enable_direction = "6d" — 开启 6D 方向检测（上/下/左/右/前/后）

• enable_direction = "4d" — 开启 4D 方向检测（上/下/左/右）

• 不设置（默认）— 方向检测关闭

config.int1 / config.int2 中的 direction 是中断通知开关： - int1 = { direction = true } — 朝向变化时通过 INT1 引脚触发中断，不设就没中断通知，但不影响 get_orientation() 直接读取

• 具体 6D 还是 4D 由 enable_direction 决定，int1 不需要重复指定

1.6 中断回调与 get_data() 返回数据说明

通过 setup() 的 config.int1.cb和config.int2.cb收到的 data 参数与 get_data() 返回的数据，结构完全一致，都包含上述所有字段。

data.x   -- X 轴加速度，单位 g
data.y   -- Y 轴加速度，单位 g
data.z   -- Z 轴加速度，单位 g
-- 如果使能了方向检测（`enable_direction`），还会自动附带：
data.dir -- 芯片自动判断的设备朝向，无需单独调用
-- data.dir 芯片朝向取值：
-- "up" — 正面朝上
-- "down" — 正面朝下  
-- "left" — 左侧朝上
-- "right" — 右侧朝上
-- "front" — 前倾
-- "back" — 后倾
-- nil — 不在上述方向或方向检测未开启

1.7 硬件连接

LIS2DH12 通过 I2C 接口与主控连接，SCL/SDA 需外接 4.7kΩ~10kΩ 上拉电阻。INT1/INT2 为中断输出引脚，不接上拉电阻。

  ┌──────────────┐                    ┌──────────────────┐
  │    主控      │                    │   LIS2DH12       │
  │  (AirXXX)    │                    │  三轴加速度传感器 │
  │              │                    │                  │
  │ GPIO_SCL ────┼────────────────────┼──→ SCL           │
  │              │                    │                  │
  │ GPIO_SDA ←───┼────────────────────┼──→ SDA           │
  │              │                    │  （需外接上拉电阻）│
  │              │                    │                  │
  │ GPIO_INT1 ───┼────────────────────┼──→ INT1          │
  │              │                    │                  │
  │ GPIO_INT2 ───┼────────────────────┼──→ INT2          │
  │              │                    │                  │
  │ VCC 3.3V ────┼────────────────────┼──→ VCC           │
  │              │                    │                  │
  │ GND      ────┼────────────────────┼──→ GND           │
  └──────────────┘                    └──────────────────┘

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

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

---

1.8 加载方式

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

---

二、核心示例

2.1 按使用接口划分

2.1.1 软件 I2C 模式（推荐）

通过 GPIO 模拟 I2C 时序，不依赖硬件 I2C 外设，任何 GPIO 引脚都可使用。

主动轮询读取：

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

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

中断回调读取（适合 tap/activity 等低频事件）：

local exs_lis2dh12 = require "exs_lis2dh12"

local function lis2dh12_cb(data)
    if data.dir then
        log.info("exs_lis2dh12", string.format("朝向=%s X=%.3f Y=%.3f Z=%.3f g", data.dir, data.x, data.y, data.z))
    else
        log.info("exs_lis2dh12", string.format("X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z))
    end
end

local result = exs_lis2dh12.setup("I2C", {
    scl = 27, sda = 26,
    int1 = { int_gpio = 10, tap = true, cb = lis2dh12_cb },
})
if not result then return end

2.1.2 硬件 I2C 模式

使用芯片内置的硬件 I2C 外设，引脚固定，总线锁死后无法软件恢复。

主动轮询读取：

local exs_lis2dh12 = require "exs_lis2dh12"
local result = exs_lis2dh12.setup("I2C", {i2c_id = 0})
if not result then return end

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

中断回调读取：

local exs_lis2dh12 = require "exs_lis2dh12"

local function lis2dh12_cb(data)
    if data.dir then
        log.info("exs_lis2dh12", string.format("朝向=%s X=%.3f Y=%.3f Z=%.3f g", data.dir, data.x, data.y, data.z))
    else
        log.info("exs_lis2dh12", string.format("X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z))
    end
end

local result = exs_lis2dh12.setup("I2C", {
    i2c_id = 0,
    int1 = { int_gpio = 10, tap = true, cb = lis2dh12_cb },
})
if not result then return end

2.2 按使用场景划分

2.2.1 静止水平放置，轮询读取（省电）

适用场景：每隔几秒读一次数据，不关心实时变化。

local result = exs_lis2dh12.setup("I2C", {
    scl = 30, sda = 29,
    powermode = "lowpower",  -- 省电模式
    odr = 25,                -- 25Hz 够用
})
if not result then
    return
end

2.2.2 运动检测（活动/静止/敲击识别）

适用场景：屏幕亮灭、设备休眠唤醒、电动车震动报警、敲击替代按键。

-- 中断回调函数（需定义在 setup 之前）
local function lis2dh12_cb(data)
    if data.dir then
        log.info("exs_lis2dh12", string.format("朝向=%s X=%.3f Y=%.3f Z=%.3f g", data.dir, data.x, data.y, data.z))
    else
        log.info("exs_lis2dh12", string.format("运动或敲击触发: X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z))
    end
end

local result = exs_lis2dh12.setup("I2C", {
    scl = 30, sda = 29,
    int1 = {
        int_gpio = 10,
        activity = true,
        threshold_mg = 300,
        duration_ms = 80,
        tap = true,
        cb = lis2dh12_cb,
    },
})
if not result then
    return
end

2.2.3 自由落体检测（跌落保护）

适用场景：硬盘保护、无人机炸机检测、高空坠落报警。

-- 中断回调函数（需定义在 setup 之前）
local function lis2dh12_cb(data)
    if data.dir then
        log.info("exs_lis2dh12", string.format("朝向=%s 自由落体 X=%.3f Y=%.3f Z=%.3f g", data.dir, data.x, data.y, data.z))
    else
        log.info("exs_lis2dh12", "自由落体！")
    end
end

local result = exs_lis2dh12.setup("I2C", {
    scl = 30, sda = 29,
    int1 = {
        int_gpio = 10,
        free_fall = true,
        duration_ms = 60,       -- 连续 60ms 失重才算自由落体
        cb = lis2dh12_cb,
    },
})
if not result then
    return
end

2.2.4 实时高速数据采集

适用场景：振动分析、姿态解算、计步器。

local function int_poll_task()
    while true do
        local int1 = exs_lis2dh12.get_int_flag()
        if int1 then
            local d = exs_lis2dh12.get_data()
            if d then
                log.info("exs_lis2dh12", string.format("X=%.3f Y=%.3f Z=%.3f g", d.x, d.y, d.z))
            end
        end
        sys.wait(5)  -- 200Hz 对应 5ms 轮询一次
    end
end
sys.taskInit(int_poll_task)

local result = exs_lis2dh12.setup("I2C", {
    scl = 30, sda = 29,
    powermode = "highres",
    odr = 200,
    int1 = { int_gpio = 10, data_ready = true },
})
if not result then
    return
end

2.2.5 温度+加速度同时采集

适用场景：环境监测、工业设备状态。

local result = exs_lis2dh12.setup("I2C", {
    scl = 30, sda = 29,
    enable_temp = true,
})
if not result then
    return
end

-- 读取温度
sys.wait(200)  -- 等待传感器稳定，200ms 为数据手册推荐值
local temp = exs_lis2dh12.get_temp()
if temp then
    log.info("exs_lis2dh12", string.format("温度: %.1f °C", temp))
end

-- 读取加速度
local data = exs_lis2dh12.get_data()
if data then
    log.info("exs_lis2dh12", string.format("X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z))
end

2.2.6 6D/4D 方向检测（横竖屏/翻转检测）

适用场景：横竖屏切换、设备翻转检测。

local result = exs_lis2dh12.setup("I2C", {
    scl = 30, sda = 29,
    enable_direction = "6d",        -- 开启方向检测，"6d"或"4d"，get_orientation() 随时可读
    int1 = { int_gpio = 10, direction = true },  -- 朝向变化时中断通知
})
if not result then
    return
end

-- 主动读取（data.dir 自动附带方向）
-- 同步读取
local data = exs_lis2dh12.get_data()
if data then
    if data.dir then
        log.info("exs_lis2dh12", string.format("朝向=%s X=%.3f Y=%.3f Z=%.3f g", data.dir, data.x, data.y, data.z))
    else
        log.info("exs_lis2dh12", string.format("X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z))
    end
end

-- 中断回调获取朝向变化（data.dir 自动附带方向信息）
local function lis2dh12_cb(data)
    if data.dir then
        log.info("exs_lis2dh12", string.format("朝向=%s X=%.3f Y=%.3f Z=%.3f g", data.dir, data.x, data.y, data.z))
    end
end

local result = exs_lis2dh12.setup("I2C", {
    scl = 30, sda = 29,
    enable_direction = "6d",
    int1 = { int_gpio = 10, direction = true, cb = lis2dh12_cb },
})
if not result then
    return
end

---

2.2.7 休眠与唤醒示例

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

-- 进入 power-down 模式（低功耗，保留配置）
exs_lis2dh12.sleep()

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

---

三、常量解释

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

---

四、函数详解

4.1 初始化

4.1.1 exs_lis2dh12.setup(model, config)

功能

初始化 LIS2DH12 加速度传感器，配置通信接口、采样参数和功耗模式。

参数

model

参数含义：通信模式选择
数据类型：string
取值范围："I2C" 或 "SPI"
是否必选：是
注意事项："I2C" 模式使用 I2C 总线；（可选用软件 I2C 或硬件 I2C）
        "SPI" 模式使用 SPI 总线 4 线模式，需要提供 cs 片选引脚
参数示例："I2C"

config

参数含义：配置参数表
数据类型：table
取值范围：根据 model 不同，支持的参数不同：
{
    参数含义：SCL 时钟引脚 GPIO 编号
    数据类型：number
    取值范围：有效的 GPIO 编号
    是否必选：与 sda 一起可选
    注意事项：与 sda 一起传入时，无 i2c_id 则创建软件 I2C（推荐），有 i2c_id 则走硬件 I2C
    参数示例：27
    config.scl ,

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

    参数含义：硬件 I2C 总线 ID
    数据类型：number
    取值范围：有效的 I2C 总线编号
    是否必选：可选
    注意事项：默认 0
    参数示例：1
    config.i2c_id ,

    参数含义：SPI 总线 ID（当前版本未适配，预留）
    数据类型：number
    是否必选：当前不可用
    参数示例：0
    config.spi_id ,

    参数含义：SPI 片选 GPIO 引脚（当前版本未适配，预留）
    数据类型：number
    是否必选：当前不可用
    参数示例：8
    config.cs ,

    参数含义：量程
    数据类型：string
    取值范围："2g"（±2g，灵敏度最高），适合倾斜检测、静止姿态、穿戴设备
            - "4g"（±4g），适合步行计步、常见运动检测
            - "8g"（±8g），适合振动监测、冲击检测
            - "16g"（±16g），适合剧烈运动、碰撞分析
    是否必选：否
    注意事项：默认 "2g"。量程越小灵敏度越高。各量程灵敏度（高精度模式 12-bit 左对齐）：
    - ±2g：16000 LSB/g（约 0.0625 mg/LSB），适合倾斜检测、静止姿态、穿戴设备
    - ±4g：8000 LSB/g（约 0.125 mg/LSB），适合步行计步、常见运动检测
    - ±8g：4000 LSB/g（约 0.25 mg/LSB），适合振动监测、冲击检测
    - ±16g：1333 LSB/g（约 0.75 mg/LSB），适合剧烈运动、碰撞分析
    参数示例："4g"
    config.range ,

    参数含义：输出数据速率
    数据类型：number
    取值范围：1、10、25、50、100、200、400、1344、5376（单位 Hz）
    是否必选：否
    注意事项：默认 100。ODR 越低功耗越低，power-down（sleep）模式功耗约 1 μA，各 ODR 对应的功耗见 1.3 功耗模式说明。
    参数示例：100
    config.odr ,

    参数含义：功耗模式
    数据类型：string
    取值范围："highres"（高精度 12-bit，噪声最低 2.2 mg），适合姿态解算、振动分析等精度要求高的场景
            - "normal"（普通 10-bit），适合日常运动检测
            - "lowpower"（低功耗 8-bit，功耗极低），适合对精度要求不高但需要超低功耗的场景
    是否必选：否
    注意事项：默认 "highres"
    参数示例："highres"
    config.powermode ,

    参数含义：使能温度传感器
    数据类型：boolean
    是否必选：否
    注意事项：true 使能温度传感器，之后可调用 get_temp() 读取温度
    参数示例：true
    config.enable_temp ,

    参数含义：方向检测开关
    数据类型：string
    是否必选：否
    取值范围："6d" 或 "4d"，不设置或设为其他值表示关闭
    注意事项："6d"=6 方向检测，"4d"=4 方向检测。开启后 get_orientation() 随时可读，无需依赖中断。int1 中的 direction 参数控制中断通知，两者互补
    参数示例："6d"
    config.enable_direction ,

    参数含义：int1 中断配置表
    数据类型：table
    是否必选：可选
    取值范围：包含以下参数：

    {

        参数含义：INT1 中断引脚 GPIO 编号
        数据类型：number
        取值范围：有效的 GPIO 编号
        是否必选：是
        参数示例：10
        int1.int_gpio ,

        参数含义：数据就绪中断，每次新数据准备好时触发。注意：100Hz+ 高频场景不适合用 cb 回调，应不传 cb 通过 get_int_flag() 轮询
        数据类型：boolean
        取值范围：true 或 false（不传入则不开启）
        是否必选：可选
        参数示例：true
        int1.data_ready ,

        参数含义：活动检测中断
        数据类型：boolean
        取值范围：true 或 false（不传入则不开启）
        是否必选：可选
        参数示例：true
        int1.activity ,

        参数含义：自由落体检测中断
        数据类型：boolean
        取值范围：true 或 false（不传入则不开启）
        是否必选：可选
        参数示例：true
        int1.free_fall ,

        参数含义：方向检测中断通知。开启后设备朝向变化时通过 GPIO 触发中断，用户轮询 get_int_flag() 后调 get_orientation() 获取结果
        数据类型：boolean
        取值范围：true 或 false（不传入则不开启）
        是否必选：可选
        注意事项：需要先通过 config.enable_direction 使能方向检测功能。6D 还是 4D 由 enable_direction 决定，本参数仅仅是中断通知开关。
                不设或设 false 不影响 get_orientation() 直接读取
        参数示例：true
        int1.direction ,

        参数含义：敲击检测中断（单击/双击）
        数据类型：boolean
        取值范围：true 或 false（不传入则不开启）
        是否必选：可选
        参数示例：true
        int1.tap ,

        参数含义：仅单击检测（配合 tap=true 使用）
        数据类型：boolean
        是否必选：可选
        参数示例：true
        int1.tap_single ,

        参数含义：仅双击检测（配合 tap=true 使用）
        数据类型：boolean
        是否必选：可选
        参数示例：true
        int1.tap_double ,

        参数含义：中断信号保持（默认开启），开启后中断触发后会保持在 INT 引脚上，直到读取中断状态寄存器才清除
        数据类型：boolean
        是否必选：可选
        参数示例：true
        int1.latched ,

        参数含义：活动/自由落体检测阈值，单位 mg
        数据类型：number
        取值范围：16~2032，默认 500
        是否必选：可选
        注意事项：仅在 activity 或 free_fall 中断时有效。各量程下每个 LSB 对应值不同：±2g 下 125mg/LSB，±4g 下 250mg/LSB
        参数示例：500
        int1.threshold_mg ,

        参数含义：活动/自由落体检测持续时间，单位 ms。表示加速度超过/低于阈值连续持续多久才触发中断
        数据类型：number
        取值范围：取决于当前 ODR。100Hz 下最长约 1270ms，50Hz 下最长约 2540ms。填 0 表示不设持续时间，立即触发
        是否必选：可选
        注意事项：仅在 activity 或 free_fall 中断时有效。扩展库会根据当前 ODR 自动换算，无需关心芯片寄存器值
        参数示例：200
        int1.duration_ms ,
    },

    参数含义：int2 中断配置表，同 int1 格式，可同时设置int1和int2
    数据类型：table
    是否必选：可选
}

是否必选：是
参数示例：
         -- 1、软件I2C初始化，不注册中断
         exs_lis2dh12.setup("I2C", {scl = 30, sda = 29})

         -- 2、软件I2C初始化，开启温度采集
         exs_lis2dh12.setup("I2C", {scl = 30, sda = 29, enable_temp = true})

         -- 3、软件I2C初始化，指定 int_gpio 和事件
         exs_lis2dh12.setup("I2C", {
             scl = 30, sda = 29,
             int1 = {int_gpio = 10, data_ready = true},
         })

返回值

local init_result = exs_lis2dh12.setup(model, config)

init_result

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

示例

-- 轮询读取（最简用法）
local result = exs_lis2dh12.setup("I2C", {scl = 30, sda = 29})
if not result then
    return
end

---

4.2 数据读取

4.2.1 exs_lis2dh12.get_data()

功能

读取 LIS2DH12 三轴加速度数据，根据当前量程自动计算 g 值。

参数

无

返回值

local data = exs_lis2dh12.get_data()

data

含义说明：三轴加速度数据表。如果使能了方向检测（enable_direction），还会附带 data.dir
数据类型：table 或 nil
取值范围：
         必选返回字段：
            data.x   - X 轴加速度，单位 g，范围为 ±当前量程，小数点后保留 4 位
            data.y   - Y 轴加速度，单位 g，范围为 ±当前量程，小数点后保留 4 位
            data.z   - Z 轴加速度，单位 g，范围为 ±当前量程，小数点后保留 4 位
         可选返回字段（enable_direction 开启后自动附带）：
            data.dir - 设备当前朝向，字符串类型，包含以下值
                "up"    — 正面朝上
                "down"  — 正面朝下
                "left"  — 左侧朝上
                "right" — 右侧朝上
                "front" — 前倾
                "back"  — 后倾
                nil     — 不在上述方向或方向检测未开启
注意事项：中断回调的 data（cb 函数参数）和 get_data() 返回的 data 结构完全一致，均包含 x/y/z/dir
返回示例：{x = 0.023, y = -0.012, z = 1.012, dir = "up"}

示例

local data = exs_lis2dh12.get_data()
if data then
    if data.dir then
        log.info("exs_lis2dh12", string.format("朝向=%s X=%.3f Y=%.3f Z=%.3f g", data.dir, data.x, data.y, data.z))
    else
        log.info("exs_lis2dh12", string.format("X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z))
    end
else
    log.error("exs_lis2dh12", "读取数据失败")
end

---

4.2.2 exs_lis2dh12.get_temp()

功能

读取 LIS2DH12 芯片内置温度传感器数值。需要先通过 enable_temp(true) 或在 setup 时设置 enable_temp = true 使能温度传感器。

温度值 8-bit 有符号存于 OUT_TEMP_H (0x0D)，0 = 25°C，1 LSB/°C。

参数

无

返回值

local temp = exs_lis2dh12.get_temp()

temp

含义说明：芯片温度值
数据类型：number 或 nil
取值范围：成功返回温度值（单位 °C），失败返回 nil
注意事项：温度传感器未使能时返回 nil
返回示例：25.0

示例

local temp = exs_lis2dh12.get_temp()
if temp then
    log.info("exs_lis2dh12", string.format("温度: %.1f °C", temp))
end

---

4.3 参数配置

4.3.1 exs_lis2dh12.set_range(range)

功能

切换量程，量程改变后灵敏度系数自动变化。

参数

range

参数含义：目标量程
数据类型：string
取值范围："2g"（±2g，灵敏度最高），适合倾斜检测、静止姿态、穿戴设备
            - "4g"（±4g），适合步行计步、常见运动检测
            - "8g"（±8g），适合振动监测、冲击检测
            - "16g"（±16g），适合剧烈运动、碰撞分析
是否必选：是
注意事项：仅在 setup() 之后调用有效。量程选择参考：
            - ±2g：灵敏度最高（16000 LSB/g），适合倾斜检测、静止姿态、穿戴设备
            - ±4g：适合步行计步、常见运动检测
            - ±8g：适合振动监测、冲击检测
            - ±16g：适合剧烈运动、碰撞分析
参数示例："4g"

返回值

无

示例

-- 切换为 ±4g 量程
exs_lis2dh12.set_range("4g")

-- 切换回 ±2g 量程（高精度）
exs_lis2dh12.set_range("2g")

---

4.3.2 exs_lis2dh12.set_odr(hz)

功能

切换输出数据速率（ODR）

参数

hz

参数含义：目标输出速率
数据类型：number
取值范围：1、10、25、50、100、200、400、1344、5376（单位 Hz）
是否必选：是
注意事项：仅在 setup() 之后调用有效。ODR 越低功耗越低，power-down（sleep）模式功耗约 1 μA，各 ODR 对应的功耗见 1.3 功耗模式说明。ODR 选择参考：
            - 1Hz~100Hz：适合静止监测、运动唤醒、常见运动检测。100Hz 时功耗约 20 μA（高精度模式）
            - 200Hz~400Hz：适合振动分析、快速运动跟踪。400Hz 时功耗约 73 μA
            - 1344Hz：较高功耗（185 μA），适合高速振动采集
            - 5376Hz：最高功耗（185 μA，仅低功耗模式可用），适合超高速率采样
参数示例：100

返回值

无

示例

-- 设置为 400Hz 输出
exs_lis2dh12.set_odr(400)

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

---

4.3.3 exs_lis2dh12.set_powermode(mode)

功能

切换功耗模式，影响 ADC 分辨率和功耗。

参数

mode

参数含义：目标功耗模式
数据类型：string
取值范围："highres"（12-bit，噪声最低），适合姿态解算、振动分析等精度要求高的场景
    - "normal"（10-bit），适合日常运动检测
    - "lowpower"（8-bit，功耗极低），适合对精度要求不高但需要超低功耗的场景
是否必选：是
注意事项：仅在 setup() 之后调用有效，三种功耗模式的区别见 1.3 功耗模式说明
参数示例："lowpower"

返回值

无

示例

-- 切换为低功耗模式
exs_lis2dh12.set_powermode("lowpower")

-- 切换为高精度模式
exs_lis2dh12.set_powermode("highres")

---

4.4 中断控制

4.4.1 exs_lis2dh12.get_int_flag()

功能

查询 INT1 和 INT2 中断触发标志。查询后自动清除标志。

注意：低频中断（tap/activity/free_fall）可直接通过 int1.cb 回调获取数据。高频场景（data_ready 100Hz+）不适合用回调，应通过本函数轮询。

参数

无

返回值

local int1_flag, int2_flag = exs_lis2dh12.get_int_flag()

int1_flag

含义说明：INT1 中断触发标志
数据类型：boolean
注意事项：查询后自动清除
返回示例：true

int2_flag

含义说明：INT2 中断触发标志
数据类型：boolean
注意事项：查询后自动清除
返回示例：false

示例

-- 在协程中轮询中断标志
local function int_poll_task()
    while true do
        local int1, int2 = exs_lis2dh12.get_int_flag()
        if int1 then
            log.info("exs_lis2dh12", "INT1 中断触发")
            local data = exs_lis2dh12.get_data()
            if data then
                log.info("exs_lis2dh12", string.format("X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z))
            end
        end
        sys.wait(50)  -- 等待 50ms（按键消抖）
    end
end
sys.taskInit(int_poll_task)

---

4.4.2 exs_lis2dh12.get_int_src()

功能

读取中断触发时哪个轴（X/Y/Z）超出了阈值。读取后自动清除中断标志，可用于排查中断触发原因。

参数

无

返回值

local src = exs_lis2dh12.get_int_src()

src

含义说明：中断状态表
数据类型：table
取值范围：nil 或 {int1 = {"ia", "xh"}, int2 = {}}
注意事项：读取后自动清除中断标志。ia = 中断触发，xh/xl = X轴正/负方向，yh/yl = Y轴正/负方向，zh/zl = Z轴正/负方向
返回示例：{int1 = {"ia", "xh"}, int2 = {}}

示例

local src = exs_lis2dh12.get_int_src()
if src then
    log.info("exs_lis2dh12", "INT1 中断源:", json.encode(src.int1))
    log.info("exs_lis2dh12", "INT2 中断源:", json.encode(src.int2))
end

---

4.4.3 exs_lis2dh12.get_orientation()

功能

获取芯片自动判断的设备当前朝向（6D/4D 方向检测）。 需要先在 setup 中通过 enable_direction = "6d" 或 enable_direction = "4d" 使能方向检测。

使能后 get_data() 返回的 data.dir 自动附带朝向信息，无需单独调用本函数。get_orientation() 适用于需要独立查询且不想获取加速度的场景。

参数

无

返回值

local dir = exs_lis2dh12.get_orientation()

dir

含义说明：设备当前朝向
数据类型：string 或 nil
取值范围：
        "up"    — 正面朝上
        "down"  — 正面朝下
        "left"  — 左侧朝上
        "right" — 右侧朝上
        "front" — 前倾
        "back"  — 后倾
        nil     — 未触发或不在上述方向
注意事项：调用后自动清除中断标志
返回示例："up"

示例

local function int_poll_task()
    while true do
        local int1 = exs_lis2dh12.get_int_flag()
        if int1 then
            local dir = exs_lis2dh12.get_orientation()
            if dir then
                log.info("exs_lis2dh12", "设备朝向:", dir)
            end
        end
        sys.wait(50)  -- 等待 50ms（按键消抖）
    end
end
sys.taskInit(int_poll_task)

---

4.5 温度控制

4.5.1 exs_lis2dh12.enable_temp(en)

功能

使能/禁用内置温度传感器。

参数

en

参数含义：使能或禁用
数据类型：boolean
是否必选：是
注意事项：使能后需要等待约 200ms 让温度 ADC 稳定再读取
参数示例：true

返回值

无

示例

-- 使能温度传感器
exs_lis2dh12.enable_temp(true)
sys.wait(200)  -- 等待传感器稳定，200ms 为数据手册推荐值

-- 读取温度
local temp = exs_lis2dh12.get_temp()

---

4.6 电源管理

4.6.1 exs_lis2dh12.sleep()

功能

将传感器切换到 power-down 模式（ODR=0），保持内部配置状态。调用 wakeup() 可快速恢复工作，无需重新 setup()。

参数

无

返回值

无

示例

exs_lis2dh12.sleep()

---

4.6.2 exs_lis2dh12.wakeup()

功能

从 power-down 模式唤醒，恢复传感器到之前的 ODR 和功耗模式，保持休眠前的配置。无需重新调用 setup()。

参数

无

返回值

无

示例

exs_lis2dh12.wakeup()

---

4.6.3 exs_lis2dh12.close()

功能

关闭 LIS2DH12 传感器。将所有关键寄存器写回默认值，重置内部状态。close 后需要重新调用 setup() 才能再次使用。

参数

无

返回值

无

示例

exs_lis2dh12.close()

---

4.7 版本信息

4.7.1 exs_lis2dh12.version()

功能

获取 exs_lis2dh12 库的版本号

参数

无

返回值

local ver = exs_lis2dh12.version()

ver

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

示例

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

---

五、版本更新说明

版本号：202607171800

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

2. 更新内容：

   • 修复 close() 未注销 GPIO 中断，传感器关闭后 INT 引脚变化导致死机

版本号：202607170900

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

2. 更新内容：

   • 支持 I2C 通信（软件 I2C / 硬件 I2C）

   • 支持量程切换（±2g / ±4g / ±8g / ±16g）

   • 支持三种功耗模式（highres / normal / lowpower）

   • 支持 data_ready、activity、free_fall、tap 中断事件

   • 支持 6D/4D 方向检测

   • 支持自动器件 ID 检测（WHO_AM_I = 0x33）

   • 支持内置温度传感器

   • 支持输出速率切换（1Hz~5376Hz）

   • 支持 I2C 总线卡死自动检测与恢复

   • 支持睡眠/唤醒/关闭

---

六、产品支持说明

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