exs_sc7a20h 扩展库

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

一、概述

exs_sc7a20h 是 士兰微电子 SC7A20H 三轴加速度传感器的 LuatOS 扩展库。 SC7A20H 属于 士兰微系列，是一款超低功耗、高性能的三轴加速度传感器，广泛应用于运动检测、倾斜测量、自由落体检测、计步器等领域。

1.1 主要特性

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

• I2C 双接口通信

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

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

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

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

• 内置 32 级 FIFO

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

• 支持单击/双击检测

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

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

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

1.2 注意事项

• 推荐使用软件 I2C 模式：SC7A20H 在异常 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）扩展库默认使能（芯片硬件默认关闭），确保高/低字节读取一致性

1.3 功耗模式说明

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

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

三种功耗模式的区别：

特性	Low-power	Normal	High-res
分辨率	8-bit	10-bit	12-bit
可用 ODR	1.56 Hz ~ 800 Hz	1.56 Hz ~ 800 Hz	1.56 Hz ~ 4.434 kHz
功耗	最低（0.5 μA @ 1.56Hz）	中等	最高

三种功耗模式在不同 ODR 下的典型功耗（VDD=1.8V）：

注：芯片规格书（VDD=2.5V）仅给出 ODR=100Hz 一档的供电电流： 高性能 194 μA、增强 53.4 μA、正常 18.8 μA、低功耗 9.6 μA、掉电 0.5 μA。 下表 100Hz 行已按规格书修正，其余 ODR 行为估算值，仅供参考：

ODR	Low-power(8-bit)	Normal(10-bit)	High-res(12-bit)
1.56 Hz	0.5 μA	—	—
12.5 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	9.6 μA	18.8 μA	194 μA
200 Hz	~18 μA	~38 μA	~190 μA
400 Hz	~36 μA	~73 μA	~185 μA
800 Hz	~70 μA	~140 μA	~185 μA
1480 Hz	—	—	~190 μA
2660 Hz	—	—	~195 μA
4434 Hz	—	—	~200 μA

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

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

• Normal：中等分辨率（10-bit），功耗与 low-power 接近，适合日常运动检测。最高可用 800 Hz 的 ODR

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

1.4 中断事件类型说明

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

中断事件	触发时机	推荐用途
data_ready	每次新数据准备好时触发。100Hz+ 高频场景不适合用 cb 回调，建议通过 get_int_flag() 轮询	实时数据采集
activity	加速度超过阈值时触发（AOI 高阈值 OR 组合）	运动唤醒、节能
free_fall	检测到自由落体时触发（AOI 低阈值 AND 组合）	跌落保护

注意：activity 与 free_fall 共用同一 AOI 中断通道（INT1→AOI1、INT2→AOI2）， 两者配置互斥，不可在同一中断通道上同时使能。同时使能时扩展库仅启用 activity 并打印警告。 若需同时使用两种检测，请分别配置到 INT1 和 INT2。

1.5 方向检测说明

通过 setup() 的 config.enable_direction 参数开启方向检测。 enable_direction 是方向检测开关，开启后 get_data() 返回的 data.dir 和中断回调的 data.dir 均自动附带朝向值， 也可通过 get_orientation() 单独查询： - enable_direction = "6d" — 开启 6 方向检测（上/下/左/右/前/后） - enable_direction = "4d" — 开启 4 方向检测（上/下/左/右） - 不设置（默认）— 方向检测关闭

实现说明：本扩展库的方向检测为软件算法——读取三轴加速度后，取重力分量绝对值最大的轴判定朝向 （例：Z 轴 +1g 判为 "down"）。该方式与芯片硬件 6D/4D 中断（AOI 方向检测）无关， 硬件 6D/4D 中断未在本库中配置。若需硬件方向中断请自行配置 AOI1_CFG/I1_AOI1 路由。

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" — 前倾（仅 6d 模式）
-- "back" — 后倾（仅 6d 模式）
-- nil — 不在上述方向或方向检测未开启
-- 注：enable_direction="4d" 时仅返回 up/down/left/right，不区分 front/back

1.7 硬件连接

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

  ┌──────────────┐                    ┌──────────────────┐
  │    主控      │                    │   SC7A20H       │
  │  (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_sc7a20h = require "exs_sc7a20h"

---

二、核心示例

2.1 按使用接口划分

2.1.1 软件 I2C 模式（推荐）

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

主动轮询读取：

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

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

2.1.2 硬件 I2C 模式

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

主动轮询读取：

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

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

2.2 按使用场景划分

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

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

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

2.2.2 运动检测（活动检测）

适用场景：屏幕亮灭、设备休眠唤醒、电动车震动报警。

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

local result = exs_sc7a20h.setup("I2C", {
    scl = 30, sda = 29,
    int1 = {
        int_gpio = 10,
        activity = true,
        threshold_mg = 300,  -- 300mg 阈值，轻微晃动即可触发
        duration_ms = 80,    -- 持续 80ms 超过阈值
        cb = sc7a20h_cb,
    },
})
if not result then
    return
end

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

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

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

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

2.2.4 实时高速数据采集

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

local function int_poll_task()
    while true do
        local int1 = exs_sc7a20h.get_int_flag()
        if int1 then
            local d = exs_sc7a20h.get_data()
            if d then
                log.info("exs_sc7a20h", 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_sc7a20h.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_sc7a20h.setup("I2C", {
    scl = 30, sda = 29,
})
if not result then
    return
end

sys.wait(200)  -- 等待传感器稳定，200ms 为数据手册推荐值

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

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

适用场景：横竖屏切换、设备翻转检测。 开启 enable_direction 后 get_data().dir 自动附带朝向。

-- 初始化并开启方向检测
local result = exs_sc7a20h.setup("I2C", {
    scl = 30, sda = 29,
    enable_direction = "6d",
})
if not result then return end

-- 读取数据（含朝向）
local data = exs_sc7a20h.get_data()
if data and data.dir then
    log.info("exs_sc7a20h", string.format("朝向=%s X=%.3f Y=%.3f Z=%.3f g", data.dir, data.x, data.y, data.z))
end

-- 或者单独获取朝向
local dir = exs_sc7a20h.get_orientation()

---

2.2.7 休眠与唤醒示例

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

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

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

---

三、常量解释

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

---

四、函数详解

4.1 初始化

4.1.1 exs_sc7a20h.setup(model, config)

功能

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

参数

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"、"4g"、"8g"、"16g"
    是否必选：否
    注意事项：默认 "2g"。量程越小灵敏度越高。各量程灵敏度（高精度模式 12-bit 左对齐）：
            - ±2g：16384 LSB/g（约 0.0625 mg/LSB），适合倾斜检测、静止姿态、穿戴设备
            - ±4g：8192 LSB/g（约 0.125 mg/LSB），适合步行计步、常见运动检测
            - ±8g：4096 LSB/g（约 0.25 mg/LSB），适合振动监测、冲击检测
            - ±16g：2048 LSB/g（约 0.49 mg/LSB），适合剧烈运动、碰撞分析
    参数示例："4g"
    config.range ,

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

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

    参数含义：方向检测开关
    数据类型：string
    是否必选：否
    取值范围："6d" 或 "4d"，不设置或设为其他值表示关闭
    注意事项："6d"=6 方向检测，"4d"=4 方向检测。开启后 get_orientation() 随时可读，中断回调的 data.dir 自动附带朝向
    参数示例："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 ,

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

        参数含义：活动/自由落体检测阈值，单位 mg
        数据类型：number
        取值范围：各量程下可设范围不同（AOI_THS 寄存器 7bit，最大值 127）：
            - ±2g（16mg/LSB）：16 ~ 2032 mg
            - ±4g（32mg/LSB）：32 ~ 4064 mg
            - ±8g（64mg/LSB）：64 ~ 8128 mg
            - ±16g（128mg/LSB）：128 ~ 16256 mg
            超出范围的值会被自动钳到该量程的有效范围；默认 500
        是否必选：可选
        注意事项：仅在 activity 或 free_fall 中断时有效。
        注意：activity 与 free_fall 共用同一 AOI 中断通道，配置互斥（一个用高阈值 OR 组合，
        一个用低阈值 AND 组合），**不可在同一中断通道上同时使能**。同时使能时扩展库仅启用 activity
        参数示例：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_sc7a20h.setup("I2C", {scl = 30, sda = 29})


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

返回值

local init_result = exs_sc7a20h.setup(model, config)

init_result

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

示例

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

---

4.2 数据读取

4.2.1 exs_sc7a20h.get_data()

功能

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

参数

无

返回值

local data = exs_sc7a20h.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" — 前倾（仅 6d 模式）
                "back"  — 后倾（仅 6d 模式）
                nil     — 不在上述方向或方向检测未开启
                （enable_direction="4d" 时仅返回 up/down/left/right，不区分 front/back）
注意事项：中断回调的 data（cb 函数参数）和 get_data() 返回的 data 结构完全一致，均包含 x/y/z/dir
返回示例：{x = 0.023, y = -0.012, z = 1.012, dir = "up"}

示例

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

---

---

4.3 参数配置

4.3.1 exs_sc7a20h.set_range(range)

功能

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

参数

range

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

返回值

无

示例

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

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

---

4.3.2 exs_sc7a20h.set_odr(hz)

功能

切换输出数据速率（ODR）

参数

hz

参数含义：目标输出速率
数据类型：number
取值范围：1.56、12.5、25、50、100、200、400、800、1480、2660、4434（单位 Hz）
是否必选：是
注意事项：仅在 setup() 之后调用有效。ODR 越低功耗越低，power-down（sleep）模式功耗约 0.5 μA，各 ODR 对应的功耗见 1.3 功耗模式说明。
参数示例：100

返回值

无

示例

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

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

---

4.3.3 exs_sc7a20h.set_powermode(mode)

功能

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

参数

mode

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

返回值

无

示例

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

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

---

4.4 中断控制

4.4.1 exs_sc7a20h.get_int_flag()

功能

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

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

参数

无

返回值

local int1_flag, int2_flag = exs_sc7a20h.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_sc7a20h.get_int_flag()
        if int1 then
            log.info("exs_sc7a20h", "INT1 中断触发")
            local data = exs_sc7a20h.get_data()
            if data then
                log.info("exs_sc7a20h", string.format("X=%.3f Y=%.3f Z=%.3f g", data.x, data.y, data.z))
            end
        end
        sys.wait(50)
    end
end
sys.taskInit(int_poll_task)

---

4.4.2 exs_sc7a20h.get_int_src()

功能

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

参数

无

返回值

local src = exs_sc7a20h.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_sc7a20h.get_int_src()
if src then
    log.info("exs_sc7a20h", "INT1 中断源:", json.encode(src.int1))
    log.info("exs_sc7a20h", "INT2 中断源:", json.encode(src.int2))
end

---

4.4.3 exs_sc7a20h.get_orientation()

功能

获取设备当前朝向（软件算法，根据三轴加速度的重力分量判定）。 需要先在 setup 中通过 enable_direction = "6d" 或 enable_direction = "4d" 使能方向检测。

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

参数

无

返回值

local dir = exs_sc7a20h.get_orientation()

dir

含义说明：设备当前朝向
数据类型：string 或 nil
取值范围：
        "up"    — 正面朝上
        "down"  — 正面朝下
        "left"  — 左侧朝上
        "right" — 右侧朝上
        "front" — 前倾（仅 6d 模式）
        "back"  — 后倾（仅 6d 模式）
        nil     — 未触发或不在上述方向
        （enable_direction="4d" 时仅返回 up/down/left/right，不区分 front/back）
注意事项：本函数仅读取加速度并计算朝向，不会清除任何中断标志（中断标志需读 INT1_SRC/INT2_SRC 清除）
返回示例："up"

示例

local function int_poll_task()
    while true do
        local int1 = exs_sc7a20h.get_int_flag()
        if int1 then
            local dir = exs_sc7a20h.get_orientation()
            if dir then
                log.info("exs_sc7a20h", "设备朝向:", dir)
            end
        end
        sys.wait(50)
    end
end
sys.taskInit(int_poll_task)

---

4.5 电源管理

4.5.1 exs_sc7a20h.sleep()

功能

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

参数

无

返回值

无

示例

exs_sc7a20h.sleep()

---

4.5.2 exs_sc7a20h.wakeup()

功能

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

参数

无

返回值

无

示例

exs_sc7a20h.wakeup()
local data = exs_sc7a20h.get_data()

---

4.6 调试工具

4.6.1 exs_sc7a20h.dump_regs()

功能

打印关键寄存器值，用于调试。输出 CTRL1~CTRL5、STATUS、INT1_SRC、INT2_SRC、FIFO_SRC 寄存器当前值。

参数

无

返回值

无

示例

exs_sc7a20h.dump_regs()

---

4.7 传感器控制

4.7.1 exs_sc7a20h.close()

功能

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

参数

无

返回值

无

示例

exs_sc7a20h.close()

---

4.8 辅助函数

4.8.1 exs_sc7a20h.version()

功能

获取 exs_sc7a20h 库的版本号。

参数

无

返回值

local ver = exs_sc7a20h.version()

ver

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

示例

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

---

五、版本更新说明

版本号：202608170000

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

2. 更新内容：

   • 【修正】HR（高性能模式）位位置：从 CTRL_REG4(0x23) bit3 迁移到 CTRL_REG0(0x1F) bit0（与规格书 §12.3 对齐），highres 模式真正生效；同时避免误置 DLPF[0]

   • 【新增】CTRL_REG0(0x1F) 寄存器配置，为后续 OSR 分频 / DLPF[1] 扩展提供基础

   • 【修正】功耗表 100Hz 档按规格书修正：High-res 194μA、Normal 18.8μA、Low-power 9.6μA

   • 【修正】噪声指标 2.2mg → 3mg RMS（规格书：FS=2g/100Hz/高性能/DLPF=00）

   • 【修正】±16g 灵敏度笔误：0.75 mg/LSB → 0.49 mg/LSB

   • 【修正】sleep 功耗 1μA → 0.5μA

   • 【修正】方向检测说明：明确为软件算法（绝对值最大轴），非芯片硬件 6D/4D

   • 【新增】WHO_AM_I 判型时读取 VERSION(0x70)

   • 【修正】>800Hz ODR 仅高性能模式可用，非 highres 时自动钳到 800Hz

   • 【修正】高通滤波（HPIS）仅用于活动检测；自由落体不可用（会滤掉重力导致三轴近零持续误触发）

   • 【修正】4d 方向检测不再返回 front/back（仅 up/down/left/right），对齐文档描述

   • 【修正】duration_ms=0 现在真正表示"立即触发"（DURATION 寄存器写 0，此前误钳到 1）

   • 【修正】threshold_mg 可设范围按量程区分（2g:16~2032 / 4g:32~4064 / 8g:64~8128 / 16g:128~16256）

   • 【修正】activity 与 free_fall 共用同一 AOI 通道配置互斥，同时使能时仅启用 activity 并告警

   • 【修正】setup 初始化日志标签 mode 重复 → 区分 model/powermode

   • 【修正】get_orientation 文档"调用后自动清除中断标志"为误述，已更正

版本号：202607180900

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

2. 更新内容：

   • 初版，实现 SC7A20H 驱动所有基础功能

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

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

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

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

   • 支持 6D/4D 方向检测（软件算法，非芯片硬件 AOI 中断）

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

   • 支持输出速率切换（1.56Hz~4.434kHz）

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

   • 支持睡眠/唤醒/关闭

---

六、产品支持说明

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