exs_adxl34x 扩展库

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

一、概述

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 模式下推荐使用软件 I2C：ADXL345/ADXL346 在异常 I2C 通信后可能锁死 SDA 总线（拉低 SDA 不放），软件 I2C 模式可以通过 GPIO 直接脉冲 SCL 恢复总线。硬件 I2C 模式下无法控制引脚电平，总线锁死后无法恢复。
• 硬件 I2C 如果在使用中遇到 SDA 被锁死导致通信超时，需要给传感器重新上电才能恢复。
• I2C 模式下 SCL 和 SDA 需外接 4.7kΩ~10kΩ 上拉电阻到 VCC
• 芯片上电后默认处于待机模式，调用 setup() 后自动进入测量模式
• I2C 器件地址根据 SDO 引脚电平决定：SDO 接 GND 时地址 0x53，SDO 接 VCC 时地址 0x1D。库内自动检测两种地址
• SPI 模式未适配，请使用 I2C 模式进行通信

中断事件类型说明：

中断事件	触发时机	触发频率	推荐用途	其他关联参数
data_ready	每次新数据准备好时触发	100Hz ODR 下每秒 100 次，频率非常高	实时数据采集	无
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.3 加载方式

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

1.4 硬件连接

二、核心示例

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

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

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

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

2.1 软件 I2C 示例（推荐）

-- 轮询读取（无中断）
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)
end

-- int1中断回调函数（需定义在 setup 之前）
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

-- 单一中断触发（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_int1_cb},
})
if not result then
    return
end

-- int1 配置多种触发事件（data_ready + activity + free_fall）
-- 三种事件任一满足即触发，其中 data_ready 触发最频繁
local result = exs_adxl34x.setup("I2C", {
    scl = 27, sda = 26,
    int1 = {int_gpio = 10, data_ready = true, activity = true, free_fall = true, cb = adxl34x_int1_cb},
})
if not result then
    return
end

-- int1中断回调函数（需定义在 setup 之前）
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

-- int2中断回调函数（需定义在 setup 之前）
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

-- 同时注册 int1 和 int2 中断，分别配置不同事件
-- int1 使用 data_ready，100Hz ODR 下每秒触发 100 次
-- int2 使用 activity，晃动模块时触发
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.2 硬件 I2C 示例

-- 轮询读取（无中断）
local result = exs_adxl34x.setup("I2C", {i2c_id = 0})
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)
end

-- int1中断回调函数（需定义在 setup 之前）
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

-- 中断触发（int1）
local result = exs_adxl34x.setup("I2C", {
    i2c_id = 0,
    int1 = {int_gpio = 10, data_ready = true, cb = adxl34x_int1_cb},
})
if not result then
    return
end

-- int1中断回调函数（需定义在 setup 之前）
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

-- int2中断回调函数（需定义在 setup 之前）
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

-- 同时注册 int1 和 int2 中断，分别配置不同事件
local result = exs_adxl34x.setup("I2C", {
    i2c_id = 0,
    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.3 SPI 模式示例

-- SPI 模式未适配，请使用 I2C 模式

2.4 量程切换示例

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

exs_adxl34x.setup("I2C", {
    scl = 27,
    sda = 26,
})

-- 切换为 ±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")

---

三、常量解释

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

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

                 参数含义：数据就绪中断
                 数据类型：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，失败返回 nil
返回示例：{x = 0.02, y = -0.01, z = 1.01}

示例

-- 数据读取
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 通信失败时不会切换
参数示例："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 通信失败时不会切换
参数示例：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 参数。

参数

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(不传入则保留原值)
         是否必选：可选
         参数示例：{activity = 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", "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.soft_reset()

功能

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

参数

无

返回值

无

示例

exs_adxl34x.soft_reset()

---

4.5.2 exs_adxl34x.version()

功能

获取 exs_adxl34x 库的版本号

参数

无

返回值

local ver = exs_adxl34x.version()

ver

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

示例

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

---

五、版本更新说明

版本号：202607141200

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

2. 更新内容：

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

4. 初始化接口使用 setup 命名，统一 TM16xx 系列命名规范
5. 支持软件 I2C 和硬件 I2C 两种通信模式（SPI 未适配）
6. 支持量程切换（±2g / ±4g / ±8g / ±16g）
7. 支持输出速率切换（0.78Hz~3200Hz）
8. 支持自动器件地址检测
9. 支持软件复位

---

六、产品支持说明

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