exs_adxl34x 扩展库

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

一、概述

exs_adxl34x 是 Analog Devices 公司 ADXL345/ADXL346 三轴加速度传感器的 LuatOS 扩展库。ADXL345/ADXL346 是一款低功耗、高精度的三轴加速度传感器，广泛应用于运动检测、倾斜测量、自由落体检测、振动监测等领域。

1.1 主要特性

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

• I2C/SPI 双接口通信（I2C 已适配，SPI 未适配），I2C 7 位地址可选 0x53（SDO=GND）或 0x1D（SDO=VCC）

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

• 支持多种输出数据速率（ODR）：0.1Hz 至 3200Hz

• 自动器件检测（区分 ADXL345 和 ADXL346）

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

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

• 支持 INT1 和 INT2 两个独立中断引脚，同一引脚可配置多种中断触发事件

1.2 注意事项

• 推荐使用软件 I2C 模式：ADXL345/ADXL346 在异常 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

• 芯片上电后默认处于待机模式，调用 setup() 后自动进入测量模式

• I2C 器件地址根据 SDO 引脚电平决定：SDO 接 GND 时地址 0x53，SDO 接 VCC 时地址 0x1D。库内自动检测两种地址

• SPI 模式未适配，请使用 I2C 模式进行通信

• XYZ 数据范围：输出值范围 ±当前量程，单位 g。

1.3 功耗说明

通过 setup() 的 config.odr 控制采样速率来调节功耗，ODR 越低功耗越低。典型功耗与数据速率对照（正常测量模式，VS=2.6V）：

输出数据速率	带宽	典型功耗
0.10 Hz	0.05 Hz	23 μA
0.20 Hz	0.10 Hz	23 μA
0.39 Hz	0.20 Hz	23 μA
0.78 Hz	0.39 Hz	23 μA
1.56 Hz	0.78 Hz	23 μA
3.13 Hz	1.56 Hz	27 μA
6.25 Hz	3.13 Hz	31 μA
12.5 Hz	6.25 Hz	40 μA
25 Hz	12.5 Hz	55 μA
50 Hz	25 Hz	90 μA
100 Hz	50 Hz	140 μA
200 Hz	100 Hz	140 μA
400 Hz	200 Hz	140 μA
800 Hz	400 Hz	140 μA
1600 Hz	800 Hz	90 μA
3200 Hz	1600 Hz	140 μA

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

1.4 中断事件类型说明

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

中断事件	触发时机	触发频率	推荐用途	其他关联参数
data_ready	每次新数据准备好时触发	100Hz ODR 下每秒 100 次，频率非常高。高频场景不适合用 cb 回调，建议通过 get_int_source() 轮询	实时数据采集	无
activity	加速度超过活动阈值时触发（默认 300mg）	仅在运动超过阈值时触发	运动唤醒、节能模式	thresh_act
inactivity	加速度低于静止阈值超过设定时间后触发	进入静止状态后触发一次	静止检测、自动休眠	thresh_inact、time_inact
free_fall	检测到自由落体时触发	极少触发（默认阈值 563mg，时间 20ms）	跌落保护	无
tap	检测到单击/双击时触发	敲击时触发（默认阈值 2g）	敲击交互	无

AC 耦合与 DC 耦合说明：

• AC 耦合（默认）：检测加速度变化量，静止时不会触发。适合移动设备

• DC 耦合：检测绝对加速度值。适合需要检测倾斜角度的场景

• 通过 act_couple 和 inact_couple 配置，例如 act_couple = "DC"

• DC 耦合下 Z 轴始终有 1g 重力，活动阈值需设得比 1g 大，否则静止时也会持续触发

参数	含义	单位	默认值	示例
thresh_act	活动检测阈值	g	0.3g	thresh_act = 0.5
thresh_inact	静止检测阈值	g	0.2g	thresh_inact = 0.1
time_inact	持续静止时间	秒	2 秒	time_inact = 5
act_couple	活动检测耦合模式	"AC"或"DC"	"AC"	act_couple = "DC"
inact_couple	静止检测耦合模式	"AC"或"DC"	"AC"	inact_couple = "DC"

示例：

-- 配置活动检测和静止检测中断
local result = exs_adxl34x.setup("I2C", {
    scl = 27, sda = 26,
    thresh_act = 0.5,     -- 活动阈值 0.5g
    thresh_inact = 0.1,   -- 静止阈值 0.1g
    time_inact = 5,       -- 持续静止 5 秒触发
    int1 = {int_gpio = 10, activity = true, inactivity = true, cb = adxl34x_int1_cb},
})

1.5 加载方式

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

1.6 硬件连接

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

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

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

• Air8101：SCL=GPIO4, SDA=GPIO5, INT=GPIO3

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

二、核心示例

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

int1 和 int2 两个中断引脚无功能区别，均可配置任意中断事件： - 同一引脚可同时设置多种触发事件，例如 {data_ready = true, activity = true} 表示数据就绪或检测到活动都会触发该引脚

• 两个引脚可以分别配置不同事件，例如 int1 响应数据就绪，int2 响应活动检测

注意：data_ready 中断在 100Hz ODR 下每秒触发 100 次。如需降低频率可降低 ODR 或改用 activity 事件。

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

2.1 按使用接口划分

2.1.1 软件 I2C 模式（推荐）

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

主动轮询读取：

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

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

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

local exs_adxl34x = require "exs_adxl34x"

local function adxl34x_cb(data)
    log.info("exs_adxl34x", string.format("X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z))
end

-- 单一中断触发（int1），使用 data_ready 事件
-- 注意：data_ready 在 100Hz ODR 下每秒触发 100 次
local result = exs_adxl34x.setup("I2C", {
    scl = 27, sda = 26,
    int1 = {int_gpio = 10, data_ready = true, cb = adxl34x_cb},
})
if not result then return end

-- int1 配置多种触发事件（data_ready + activity + free_fall）
local result = exs_adxl34x.setup("I2C", {
    scl = 27, sda = 26,
    int1 = {int_gpio = 10, data_ready = true, activity = true, free_fall = true, cb = adxl34x_cb},
})
if not result then return end

-- 同时注册 int1 和 int2 中断，分别配置不同事件
local function adxl34x_int1_cb(data)
    log.info("exs_adxl34x", string.format("int1: X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z))
end

local function adxl34x_int2_cb(data)
    log.info("exs_adxl34x", string.format("int2: X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z))
end

local result = exs_adxl34x.setup("I2C", {
    scl = 27, sda = 26,
    int1 = {int_gpio = 10, data_ready = true, cb = adxl34x_int1_cb},
    int2 = {int_gpio = 11, activity = true, cb = adxl34x_int2_cb},
})
if not result then return end

2.1.2 硬件 I2C 模式

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

-- 轮询读取（无中断）
local result = exs_adxl34x.setup("I2C", {i2c_id = 0, scl = 27, sda = 26})
if not result then return end

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

-- 中断触发（int1）
local function adxl34x_int1_cb(data)
    log.info("exs_adxl34x", string.format("X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z))
end

local result = exs_adxl34x.setup("I2C", {
    i2c_id = 0, scl = 27, sda = 26,
    int1 = {int_gpio = 10, data_ready = true, cb = adxl34x_int1_cb},
})
if not result then return end

2.2 按使用场景划分

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

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

local result = exs_adxl34x.setup("I2C", {
    scl = 30, sda = 29,
    range = "2g",  -- 高精度
    odr = 25,      -- 25Hz 省电
})
if not result then return end

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

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

local function adxl34x_cb(data)
    log.info("exs_adxl34x", string.format("X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z))
end

local result = exs_adxl34x.setup("I2C", {
    scl = 30, sda = 29,
    thresh_act = 0.5,   -- 活动阈值 0.5g
    thresh_inact = 0.1, -- 静止阈值 0.1g
    time_inact = 5,     -- 静止 5 秒触发
    int1 = {int_gpio = 10, activity = true, inactivity = true, tap = true, cb = adxl34x_cb},
})
if not result then return end

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

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

local function adxl34x_cb(data)
    log.info("exs_adxl34x", "自由落体！")
end

local result = exs_adxl34x.setup("I2C", {
    scl = 30, sda = 29,
    int1 = {int_gpio = 10, free_fall = true, cb = adxl34x_cb},
})
if not result then return end

2.2.4 量程切换示例

-- 切换为 ±4g 量程
exs_adxl34x.set_range("4g")
local data = exs_adxl34x.get_data()
if data then
    log.info("exs_adxl34x", string.format("4g 量程: X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z))
end

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

2.2.5 输出速率切换

-- 设置为 400Hz 高速输出（适合振动分析）
exs_adxl34x.set_odr(400)

-- 恢复为 25Hz 低功耗输出
exs_adxl34x.set_odr(25)

2.2.6 休眠与唤醒示例

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

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

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

---

三、常量解释

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

---

四、函数详解

4.1 初始化

4.1.1 exs_adxl34x.setup(model, config)

功能

初始化 ADXL345/ADXL346 加速度传感器，配置通信接口和采样参数。

参数

model

参数含义：通信模式选择
数据类型：string
取值范围："I2C"
是否必选：是
注意事项："I2C" 模式下使用 I2C 总线通信（可选用软件 I2C 或硬件 I2C）；"SPI" 模式未适配
参数示例："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。与 scl/sda 一起传时使用硬件 I2C 通信 + 引脚恢复总线；不传 scl/sda 时使用硬件 I2C 但无总线恢复能力
    参数示例：1
    config.i2c_id ,

    参数含义：量程
    数据类型：string
    取值范围："2g"、"4g"、"8g"、"16g"
    是否必选：否
    注意事项：默认 "2g"。量程越小灵敏度越高，可测量最大值越小。全分辨率模式下各量程灵敏度：
    - ±2g：256 LSB/g（约 3.9 mg/LSB），适合倾斜检测、静止姿态、穿戴设备
    - ±4g：128 LSB/g（约 7.8 mg/LSB），适合步行计步、常见运动检测
    - ±8g：64 LSB/g（约 15.6 mg/LSB），适合振动监测、冲击检测
    - ±16g：32 LSB/g（约 31.25 mg/LSB），适合剧烈运动、自由落体检测、碰撞分析
    参数示例："4g"
    config.range ,

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

    参数含义：活动检测阈值
    数据类型：number
    取值范围：0.01~16 (g)，默认 0.3g
    是否必选：否
    注意事项：数值越小越灵敏。设为 0.1 表示 100mg 加速度变化即触发
    参数示例：0.5
    config.thresh_act ,

    参数含义：静止检测阈值
    数据类型：number
    取值范围：0.01~16 (g)，默认 0.2g
    是否必选：否
    注意事项：加速度低于此值认为处于静止状态
    参数示例：0.1
    config.thresh_inact ,

    参数含义：静止检测持续时间
    数据类型：number
    取值范围：0.5~255 (秒)，默认 2 秒
    是否必选：否
    注意事项：加速度持续低于静止阈值超过此时间才触发中断
    参数示例：5
    config.time_inact ,

    参数含义：INT1 中断配置表。包含 int 引脚 GPIO 编号、事件 boolean 和回调函数
    数据类型：table
    是否必选：可选
    取值范围：包含以下参数：

    {

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

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

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

        参数含义：静止检测中断
        数据类型：boolean
        取值范围：true 或 false(不传入则不开启)
        是否必选：可选
        参数示例：true
        int1.inactivity ,

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

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

        参数含义：中断回调函数，触发中断时自动读取加速度数据并传入回调
        数据类型：function
        取值范围：function(data) end，data = {x, y, z}
        是否必选：可选
        参数示例：int1_cb
        int1.cb ,
    },

    参数含义：INT2 中断配置表。包含 pin 引脚 GPIO 编号、事件 boolean 和回调函数
    数据类型：table
    是否必选：可选
    取值范围：包含以下参数：

    {

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

        参数含义：数据就绪中断
        数据类型：boolean
        取值范围：true 或 false(不传入则默认开启)
        是否必选：可选
        参数示例：true
        int2.data_ready ,

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

        参数含义：静止检测中断
        数据类型：boolean
        取值范围：true 或 false(不传入则不开启)
        是否必选：可选
        参数示例：true
        int2.inactivity ,

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

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

        参数含义：中断回调函数，触发中断时自动读取加速度数据并传入回调
        数据类型：function
        取值范围：function(data) end，data = {x, y, z}
        是否必选：可选
        参数示例：int1_cb
        int2.cb ,
    }
}

是否必选：是
参数示例：
-- 1、软件I2C 模式
exs_adxl34x.setup("I2C", {scl = 30, sda = 29})

-- 2、软件I2C 模式 + 中断
-- 1）中断回调函数（需定义在 setup 之前）
local function int1_cb(data)
log.info("exs_adxl34x", "X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z)
end

-- 2）初始化
exs_adxl34x.setup("I2C", {scl = 30, sda = 29, int1 = {int_gpio = 10, data_ready = true, cb = int1_cb}})

返回值

local init_result = exs_adxl34x.setup(model, config)

init_result

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

示例

-- 中断回调函数（需定义在 setup 之前）
local function int1_cb(data)
    log.info("exs_adxl34x", "X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z)
end

-- I2C 软件模式
local result = exs_adxl34x.setup("I2C", {scl = 30, sda = 29})

-- I2C 软件模式 + INT1 中断（数据就绪自动回调）
local result = exs_adxl34x.setup("I2C", {
    scl = 30, sda = 29,
    int1 = {int_gpio = 10, data_ready = true, cb = int1_cb},
})

---

4.2 数据读取

4.2.1 exs_adxl34x.get_data()

功能

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

参数

无

返回值

local data = exs_adxl34x.get_data()

data

含义说明：三轴加速度数据表
数据类型：table 或 nil
取值范围：成功返回包含 x/y/z 键和值的 table，值单位 g，小数点后保留 3 位，失败返回 nil。
返回示例：{x = 0.023, y = -0.012, z = 1.012}

示例

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

---

4.3 参数配置

4.3.1 exs_adxl34x.set_range(range)

功能

切换量程，量程改变后会重置内部灵敏度系数。全分辨率模式下，灵敏度随量程自动变化。

参数

range

参数含义：目标量程
数据类型：string
取值范围："2g"、"4g"、"8g"、"16g"
是否必选：是
注意事项：量程越小灵敏度越高，可测量最大值越小。仅在 setup() 之后调用有效。I2C 通信失败时不会切换。量程选择参考：
            - ±2g（256 LSB/g）：适合倾斜检测、静止姿态、穿戴设备
            - ±4g（128 LSB/g）：适合步行计步、常见运动检测
            - ±8g（64 LSB/g）：适合振动监测、冲击检测
            - ±16g（32 LSB/g）：适合剧烈运动、自由落体检测、碰撞分析
参数示例："4g"

返回值

无

示例

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

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

---

4.3.2 exs_adxl34x.set_odr(hz)

功能

切换输出数据速率（ODR）

参数

hz

参数含义：目标输出速率
数据类型：number
取值范围：0.78、1.56、3.13、6.25、12.5、25、50、100、200、400、800、1600、3200（单位 Hz）
是否必选：是
注意事项：传入整数，非精确匹配时向下取整到最近的可用值（例如 75 会被设置为 50Hz）。
          仅在 setup() 之后调用有效。I2C 通信失败时不会切换。ODR 选择参考：
          - 0.1Hz~50Hz（≤90 μA）：低功耗，适合静止监测、温度监控、倾斜检测
          - 100Hz~200Hz（140 μA）：适合运动检测、姿态跟踪
          - 400Hz~800Hz（140 μA）：适合振动分析、高频数据采集
          - 1600Hz（90 μA）~3200Hz（140 μA）：适合超高速冲击检测
参数示例：100

返回值

无

示例

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

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

---

4.4 中断控制

4.4.1 exs_adxl34x.int_config(int, config)

功能

配置指定中断引脚的事件触发条件。

注意：

1. 与 setup 中 int1/int2 的事件参数格式一致。
2. 仅配置芯片内部中断映射和使能，不注册 GPIO 中断回调。
3. 如需 GPIO 中断自动回调，请先在 setup 中配置 int1/int2 参数。
4. data_ready 中断在 100Hz+ 频率高，不适合 callback 高频触发。如需使用 data_ready，建议不传 cb，通过 get_int_source() 轮询。

参数

int

参数含义：中断引脚名称
数据类型：string
取值范围："int1" 或 "int2"
是否必选：是
参数示例："int1"

config

参数含义：中断事件配置表，通过 boolean 值开启对应事件
数据类型：table
取值范围：
{
    参数含义：数据就绪中断，每次新数据准备好时触发
    数据类型：boolean
    取值范围：true 或 false(不传入则保留原值)
    是否必选：可选
    参数示例：true
    data_ready ,

    参数含义：活动检测中断，检测到运动时触发
    数据类型：boolean
    取值范围：true 或 false(不传入则保留原值)
    是否必选：可选
    参数示例：true
    activity ,

    参数含义：静止检测中断，长时间静止时触发
    数据类型：boolean
    取值范围：true 或 false(不传入则保留原值)
    是否必选：可选
    参数示例：true
    inactivity ,

    参数含义：自由落体检测中断
    数据类型：boolean
    取值范围：true 或 false(不传入则保留原值)
    是否必选：可选
    参数示例：true
    free_fall ,

    参数含义：敲击检测中断（单击/双击）
    数据类型：boolean
    取值范围：true 或 false(不传入则保留原值)
    是否必选：可选
    参数示例：true
    tap ,
}
是否必选：否
参数示例：{activity = true}

返回值

无

示例

-- 开启 INT1 的数据就绪中断
exs_adxl34x.int_config("int1", {data_ready = true})

-- 开启 int2 的活动检测中断
exs_adxl34x.int_config("int2", {activity = true})

---

4.4.2 exs_adxl34x.get_int_source()

功能

读取当前触发了哪些中断事件。读取后自动清除中断标志。

参数

无

返回值

local events = exs_adxl34x.get_int_source()

events

含义说明：中断事件名称数组
数据类型：table
取值范围：nil或空数组{}或{"data_ready"}、{"activity", "free_fall"}等，包含下面一个或多个值
        data_ready（数据就绪）、single_tap（单击）、double_tap（双击）、activity（活动）、
        inactivity（静止）、free_fall（自由落体）、watermark（FIFO水印）、overrun（数据溢出）
注意事项：读取后自动清除中断标志
返回示例：{"data_ready", "activity"}

示例

local events = exs_adxl34x.get_int_source()
if events then
    for _, ev in ipairs(events) do
        log.info("exs_adxl34x", "触发中断:", ev)
    end
end

---

4.5 电源管理

4.5.1 exs_adxl34x.sleep()

功能

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

参数

无

返回值

无

示例

exs_adxl34x.sleep()

---

4.5.2 exs_adxl34x.wakeup()

功能

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

参数

无

返回值

无

示例

exs_adxl34x.wakeup()

---

4.5.3 exs_adxl34x.close()

功能

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

参数

无

返回值

无

示例

exs_adxl34x.close()

---

4.6 版本信息

4.6.1 exs_adxl34x.version()

功能

获取 exs_adxl34x 库的版本号

参数

无

返回值

local ver = exs_adxl34x.version()

ver

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

示例

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

---

五、版本更新说明

版本号：202607171800

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

2. 更新内容：

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

   • 新增常量中文注释

版本号：202607170900

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

2. 更新内容：

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

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

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

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

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

版本号：202607141200

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

2. 更新内容：

   • 初版，实现 ADXL345/ADXL346 驱动所有基础功能

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

   • 支持软件 I2C 和硬件 I2C 两种通信模式（SPI 未适配）

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

   • 支持输出速率切换（0.78Hz~3200Hz）

   • 支持自动器件地址检测

   • 支持软件复位

---

六、产品支持说明

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