25 gpio-通用输入输出接口

作者：拓毅恒　|　最后修改：2026-10-29

一、概述

GPIO（General Purpose Input/Output）即通用输入输出接口，是嵌入式系统中最常用的接口类型之一。它可以用于连接各种外部设备，如 LED、按键、传感器等，并通过软件控制这些设备的状态和行为。

LuatOS 提供了功能丰富的 GPIO 核心库，支持输入、输出、中断、电平捕获、脉冲输出等多种功能，满足各种应用场景的需求。

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考 LuatOS 仓库中各个产品目录下的相关示例：demo/gpio。

local gpio_number = 27

LED = gpio.setup(gpio_number, 1) -- 设置GPIO27为输出模式

function led_test()
    -- 开始呼吸灯
    local count = 0
    while true do
        -- 呼吸灯程序
        LED(1)
        log.info("GPIO", "LED OPEN")
        sys.wait(500)--点亮时间 500ms
        LED(0)
        log.info("GPIO", "LED CLOSE")
        sys.wait(500)--熄灭时间 500ms
        count = count + 1
    end
end

sys.taskInit(led_test)

三、常量详解

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

每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为LuatOS内核固件可能会变更每个常量对应的常量取值；

如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；

3.1 GPIO电平常量

gpio.LOW

常量含义：低电平；
数据类型：number；
示例代码：gpio.set(17, gpio.LOW)；
适用产品型号：全支持；

gpio.HIGH

常量含义：高电平；
数据类型：number；
示例代码：gpio.set(17, gpio.HIGH)；
适用产品型号：全支持；

gpio.OUTPUT

常量含义：早期兼容常量，取值为 0，与 gpio.LOW 取值相同（源码定义 Luat_GPIO_OUTPUT = 0x00）；
          源码里对这个常量的注释只有一句“留着做兼容”，仅为兼容早期脚本中
          gpio.setup(17, gpio.OUTPUT) 这种把“输出模式”和“输出低电平”混写的旧代码而保留；
          新代码请不要再用它来区分输入/输出，输出电平直接写 gpio.LOW / gpio.HIGH 即可；
数据类型：number；
示例代码：gpio.setup(17, gpio.OUTPUT)  -- 等价于 gpio.setup(17, gpio.LOW)，不推荐新代码使用
适用产品型号：全支持；

3.2 上下拉常量

gpio.PULLUP

常量含义：上拉；
数据类型：number；
示例代码：gpio.setup(17, nil, gpio.PULLUP)；
适用产品型号：全支持；

gpio.PULLDOWN

常量含义：下拉；
数据类型：number；
示例代码：gpio.setup(17, nil, gpio.PULLDOWN)；
适用产品型号：全支持；

3.3 中断触发方式常量

gpio.RISING

常量含义：上升沿触发；
数据类型：number；
示例代码：gpio.setup(27, irqFunc, gpio.PULLUP, gpio.RISING)；
适用产品型号：全支持；

gpio.FALLING

常量含义：下降沿触发；
数据类型：number；
示例代码：gpio.setup(27, irqFunc, gpio.PULLUP, gpio.FALLING)；
适用产品型号：全支持；

gpio.BOTH

常量含义：双向触发；
数据类型：number；
示例代码：gpio.setup(27, irqFunc, gpio.PULLUP, gpio.BOTH)；
适用产品型号：仅Air780EXXX系列支持，Air8000系列支持；

gpio.HIGH_IRQ

常量含义：高电平触发中断（电平中断，不是边沿中断）；
          源码注释为“部分设备支持”，属于平台相关能力，不是所有模组都支持；
数据类型：number；
示例代码：
          -- 高电平期间会持续保持在中断态，退出中断需要电平恢复为低
          gpio.setup(27, irqFunc, gpio.PULLDOWN, gpio.HIGH_IRQ)
适用产品型号：部分平台支持（源码注释“部分设备支持”），使用前请确认对应模组的中断能力；

gpio.LOW_IRQ

常量含义：低电平触发中断（电平中断，不是边沿中断）；
          源码注释为“部分设备支持”，属于平台相关能力，不是所有模组都支持；
          注意与 gpio.FALLING 的区别：FALLING 只在下降沿触发一次，LOW_IRQ 在低电平期间一直保持中断态；
数据类型：number；
示例代码：
          gpio.setup(27, irqFunc, gpio.PULLUP, gpio.LOW_IRQ)
适用产品型号：部分平台支持（源码注释“部分设备支持”），使用前请确认对应模组的中断能力；

3.4 唤醒脚常量

gpio.WAKEUP0

常量含义：休眠唤醒脚0，不支持输出；
数据类型：number；
示例代码：
          function wakeup0_callback()
              log.info("gpio", "wakeup0 interrupt triggered")
          end
          gpio.setup(gpio.WAKEUP0, wakeup0_callback)
适用产品型号：仅Air780EXXX系列支持，Air8000系列支持；

gpio.WAKEUP1

常量含义：VBUS，USB唤醒脚，不支持输出；
数据类型：number；
示例代码：
          function wakeup1_callback()
              log.info("gpio", "wakeup1 interrupt triggered")
          end
          gpio.setup(gpio.WAKEUP1, wakeup1_callback)
适用产品型号：仅Air780EXXX系列支持，Air8000系列支持；

gpio.VBUS

常量含义：VBUS，USB 插入检测/唤醒脚，与 gpio.WAKEUP1 是同一个引脚、同一个取值；
          两个名字可以互换使用，代码里看到 gpio.VBUS 就等于 gpio.WAKEUP1；
数据类型：number；
示例代码：
          function vbus_callback()
              log.info("gpio", "USB 插拔触发")
          end
          gpio.setup(gpio.VBUS, vbus_callback, gpio.PULLUP, gpio.BOTH)
适用产品型号：仅Air780EXXX系列支持，Air8000系列支持；

gpio.WAKEUP2

常量含义：USIM热插拔脚，不支持输出；
数据类型：number；
示例代码：
          function wakeup2_callback()
              log.info("gpio", "wakeup2 interrupt triggered")
          end
          gpio.setup(gpio.WAKEUP2, wakeup2_callback)
适用产品型号：仅Air780EXXX系列支持，Air8000系列支持；

gpio.USIM_DET

常量含义：USIM 热插拔检测脚，与 gpio.WAKEUP2 是同一个引脚、同一个取值；
          卡座带插拔检测开关时，用这个别名可读性更好，代码里就等于 gpio.WAKEUP2；
数据类型：number；
示例代码：
          function sim_callback()
              log.info("gpio", "SIM 卡插拔")
          end
          gpio.setup(gpio.USIM_DET, sim_callback, gpio.PULLUP, gpio.BOTH)
适用产品型号：仅Air780EXXX系列支持，Air8000系列支持；

gpio.WAKEUP3

常量含义：休眠唤醒脚3，与GPIO20是同一个引脚；
数据类型：number；
示例代码：
          function wakeup3_callback()
              log.info("gpio", "wakeup3 interrupt triggered")
          end
          gpio.setup(gpio.WAKEUP3, wakeup3_callback)
适用产品型号：仅Air780EXXX系列支持，Air8000系列支持；

gpio.WAKEUP4

常量含义：休眠唤醒脚4，与GPIO21是同一个引脚；
数据类型：number；
示例代码：
          function wakeup4_callback()
              log.info("gpio", "wakeup4 interrupt triggered")
          end
          gpio.setup(gpio.WAKEUP4, wakeup4_callback)
适用产品型号：仅Air780EXXX系列支持，Air8000系列支持；

gpio.WAKEUP5

常量含义：休眠唤醒脚5，与GPIO22是同一个引脚；
数据类型：number；
示例代码：
          function wakeup5_callback()
              log.info("gpio", "wakeup5 interrupt triggered")
          end
          gpio.setup(gpio.WAKEUP5, wakeup5_callback)
适用产品型号：仅Air780EXXX系列支持，Air8000系列支持；

gpio.WAKEUP6

常量含义：休眠唤醒脚6，不支持输出；
数据类型：number；
示例代码：
          function wakeup6_callback()
              log.info("gpio", "wakeup6 interrupt triggered")
          end
          gpio.setup(gpio.WAKEUP6, wakeup6_callback)
适用产品型号：仅Air8000系列支持；

gpio.WAKEUP7 ~ gpio.WAKEUP56

常量含义：BK72xx 平台（Air8101、Air6201 等 WiFi SoC）额外提供的一批休眠唤醒脚，取值规则为 64 + 序号，
          即 gpio.WAKEUP7 取值为 71、gpio.WAKEUP56 取值为 120；
          这批常量在源码中包在 #ifdef __BK72XX__ 里，只有 BK72xx 平台的固件才会注册；
          其中 gpio.WAKEUP10、gpio.WAKEUP11 在源码中被注释掉（这两个序号分别是 UART0_TX / UART0_RX），
          实际并不存在，调用得到 nil；
数据类型：number；
示例代码：
          -- 仅 BK72xx 平台可用，EC7xx 系列上这些常量不存在（为 nil）
          gpio.setup(gpio.WAKEUP12, wakeup_callback)
适用产品型号：仅 BK72xx 平台（Air8101、Air6201 等 WiFi SoC）支持；Air780EXXX / Air8000 / Air1601 等 EC7xx 系列不支持；

各常量与序号的对应关系如下（连续取值，无其它含义）：

常量	取值	常量	取值	常量	取值	常量	取值
`gpio.WAKEUP7`	71	`gpio.WAKEUP20`	84	`gpio.WAKEUP33`	97	`gpio.WAKEUP46`	110
`gpio.WAKEUP8`	72	`gpio.WAKEUP21`	85	`gpio.WAKEUP34`	98	`gpio.WAKEUP47`	111
`gpio.WAKEUP9`	73	`gpio.WAKEUP22`	86	`gpio.WAKEUP35`	99	`gpio.WAKEUP48`	112
`gpio.WAKEUP12`	76	`gpio.WAKEUP23`	87	`gpio.WAKEUP36`	100	`gpio.WAKEUP49`	113
`gpio.WAKEUP13`	77	`gpio.WAKEUP24`	88	`gpio.WAKEUP37`	101	`gpio.WAKEUP50`	114
`gpio.WAKEUP14`	78	`gpio.WAKEUP25`	89	`gpio.WAKEUP38`	102	`gpio.WAKEUP51`	115
`gpio.WAKEUP15`	79	`gpio.WAKEUP26`	90	`gpio.WAKEUP39`	103	`gpio.WAKEUP52`	116
`gpio.WAKEUP16`	80	`gpio.WAKEUP27`	91	`gpio.WAKEUP40`	104	`gpio.WAKEUP53`	117
`gpio.WAKEUP17`	81	`gpio.WAKEUP28`	92	`gpio.WAKEUP41`	105	`gpio.WAKEUP54`	118
`gpio.WAKEUP18`	82	`gpio.WAKEUP29`	93	`gpio.WAKEUP42`	106	`gpio.WAKEUP55`	119
`gpio.WAKEUP19`	83	`gpio.WAKEUP30`	94	`gpio.WAKEUP43`	107	`gpio.WAKEUP56`	120
		`gpio.WAKEUP31`	95	`gpio.WAKEUP44`	108
		`gpio.WAKEUP32`	96	`gpio.WAKEUP45`	109

结论：EC7xx 系列（Air780EXXX、Air8000、Air1601/1602/1603）能用作唤醒的只有 gpio.WAKEUP0 ~ gpio.WAKEUP6，再配合 gpio.PWR_KEY、gpio.CHG_DET；文档里之所以只写到 WAKEUP6，是因为更高序号在 EC7xx 上确实没有。

3.5 特殊功能引脚常量

gpio.AUDIOPA_EN

常量含义：音频PA使能脚，仅Air780EHV特有的引脚；
数据类型：number；
示例代码：gpio.setup(gpio.AUDIOPA_EN, 0)；
适用产品型号：仅Air780EHV支持；

gpio.PWR_KEY

常量含义：开机键，模组工作电压范围 3.3V-4.35V，内部上拉至 VBAT；
          如果 PWRKEY 接地，此功能无法使用，芯片上电即开机；
          PWRKEY 不接地时:
          开机前：只能做输入，检测到 PWRKEY下降沿，模组启动上电流程；
          开机后：
                 1. 作为中断输入使用，是否执行关机或者其它动作，由软件决定；
                 2. 软件可以检测上升沿和下降沿，也可以检测高电平和低电平；
                 3. 模组内部已上拉至VBAT，因此，不支持上下拉操作；
数据类型：number；
示例代码：local function wakeup_irq_func()
             log.info("PWR_KEY PRESS")
          end
          gpio.setup(gpio.PWR_KEY, wakeup_irq_func, gpio.PULLUP, gpio.FALLING)
适用产品型号：仅Air780EXXX系列支持，Air8000系列支持；

gpio.CHG_DET

常量含义:命名为CHG_DET，但实际功能同PWRKEY一样；
         开机前用于开机，开机后用于中断输入检测，内部固定上拉至一个不对外开放的LDO_1.8V；
         CHRG DET 开机前，下降沿触发模组开机;
         CHRG DET 内部上拉，不可外接高电平，只能外接高阻、强下拉或弱下拉;
         USB Vbus 可通过 MOS 管反向连接到 CHRG DET，实现插入 USB 线触发开机;
         不实现插入 USB 线开机时:
         开机前:只能做输入，检测到 CHG_DET下降沿，模组启动上电流程;
         开机后:
         1.开机后和PWRKEY一样的功能和特性;
         2.开机后仅支持双向触发中断，不支持输出;
         3.模组内部固定上拉至LDO_1.8V，因此，不支持上下拉操作;
         如果需要关闭此管脚，需要调用 gpio.close() 接口关闭，不能将其配置为输入下拉模式，否则会导致模组被误触唤醒；
数据类型：number；
示例代码：local function wakeup_irq_func()
             log.info("CHG_DET PRESS")
          end
          gpio.setup(gpio.CHG_DET, wakeup_irq_func, gpio.PULLUP, gpio.BOTH)
适用产品型号：Air780Exx系列(780EPM/EHM除外)/Air8000系列支持;

3.6 其它常量

gpio.NONE

常量含义：无效引脚；
          取值为 0xff，用来告诉底层“这个功能不指定引脚”；
          典型用法是外设初始化时某个引脚不用接，就传 gpio.NONE 占位；
数据类型：number；
示例代码：
          -- 初始化时不需要用到某个引脚，用它占位而不是传 nil
          local cfg = {pin = gpio.NONE, level = 0}
适用产品型号：全支持；

注意：gpio.NONE 只用于“参数占位”，不能传给 gpio.setup() 去配置引脚，也不要去 gpio.get(gpio.NONE)。

四、函数详解

gpio.setup(pin, mode, pull, irq)

功能

设置 GPIO 引脚的功能，包括输入/输出模式、上下拉配置、中断触发方式等。

注意：

1、AGPIO配置为输出模式可以在PSM+模式下保持；

2、Air8000中大于100的GPIO（WGPIO），在低功耗模式或者PSM模式下均无法配置为中断功能；

3、Air8000中大于100的GPIO（WGPIO），底层固件≥2018 并且 WIFI版本≥V18 才能在常规模式下配置为中断功能。

4、在配置 WAKEUP0 ~ WAKEUP6 、PWR_KEY 管脚为输入模式时，需要注意以下情况：

4.1、WAKEUP0 ~ WAKEUP2、WAKEUP6、PWR_KEY 是独立的 WAKEUP 管脚，使用 gpio.setup() 接口配置为输入模式时，

如果内核固件是 V2046 及之前的版本，在使用 gpio.setup() 接口配置为输入模式时，不仅有输入功能，还有唤醒功能；

如果是 V2048 及之后的版本，在使用 gpio.setup() 接口配置为输入模式时，只有输入功能，没有唤醒功能；

4.2、使用 gpio.setup() 接口配置 WAKEUP6 管脚时，第一个参数可以填 gpio.WAKEUP6，也可以填 gpio.CHG_DET，功能是一致的；

4.3、WAKEUP3 ~ WAKEUP5 既是 AGPIOWAKEUP 管脚（对应 AGPIOWU0 ~ AGPIOWU2），也是 GPIO 管脚（对应 GPIO20 ~ GPIO22），使用 gpio.setup() 接口配置为输入模式时，如果第一个参数填写为 gpio.WAKEUP3/gpio.WAKEUP4/gpio.WAKEUP5 ，那么内核中统一会配置为输入唤醒功能，当 WAKEUP3 ~ WAKEUP5 引脚的电平发生变化时，会触发中断，导致模组唤醒；如果只需要输入功能，那么需要将第一个参数填写为 20 ~ 22，及对应的 GPIO 号；这是软件配置方式的问题，与内核固件无关；

4.4、上述情况说明仅适用于 Air700/Air1780/Air780Exx/Air8000 系列模组；

参数

pin

参数含义：GPIO 编号，必须是数值；
数据类型：number；
取值范围：产品支持的 GPIO，可以查询具体产品的硬件手册；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：17 表示设置 GPIO17；

mode

参数含义：输入输出模式；
数据类型：number或者nil或者function；
取值范围：数字0/1代表输出模式，0 输出低电平，1 输出高电平；
         nil代表输入模式；
         function代表中断模式；
         gpio.count代表中断计数功能，中断时不回调(详情看下方gpio.count)；
是否必选：必须传入此参数；
注意事项：不同模式下，GPIO 的操作方式不同，不能初始化输入模式，实际上使用输出模式；
参数示例：0 表示设置为输出模式，初始电平为低；

pull

参数含义：内部上拉下拉模式；
数据类型：number；
取值范围：gpio.PULLUP（上拉）、gpio.PULLDOWN（下拉）、0（开漏模式）；
是否必选：可选传入此参数；如果没有传入此参数或者传入了 nil 类型，则遵循硬件默认配置；
注意事项：需要根据实际硬件选用合适的上下拉模式；
参数示例：gpio.PULLUP 表示启用内部上拉；

irq

参数含义：中断触发模式；
数据类型：number；
取值范围：gpio.RISING（上升沿）、gpio.FALLING（下降沿）、gpio.BOTH（双向触发）；
是否必选：可选传入此参数；如果没有传入此参数或者传入了 nil 类型，则使用默认值 gpio.BOTH；
注意事项：仅在中断模式下有效，gpio.BOTH，并不是所有产品都支持，需参考常量详解中gpio.BOTH的说明；
参数示例：gpio.RISING 表示设置为上升沿触发；

返回值

local pin_func = gpio.setup(pin, mode, pull, irq)

pin_func

含义说明：输出模式返回设置电平的函数，输入模式和中断模式返回获取电平的函数；
数据类型：function；
取值范围：无特别限制；
注意事项：可以直接调用返回的函数来设置或获取电平；
返回示例：返回一个函数，调用该函数可以设置或获取 GPIO 的电平；

示例

-- 设置gpio17为输入
gpio.setup(17, nil)

-- 设置gpio17为输出，且初始化电平为低，使用硬件默认上下拉配置
gpio.setup(17, 0)

-- 设置gpio17为输出，且初始化电平为高
gpio.setup(17, 1)

-- 设置gpio27为中断，默认双向触发
function gpio_func(val, io_num)
    log.info("io", io_num, val) -- 提醒，val并不代表触发方向，仅代表中断后某个时间点的电平，io_num是IO序号
end

gpio.setup(27, gpio_func, gpio.PULLUP)

-- 设置gpio27为中断，仅上升沿触发
function gpio_func(val)
    print("IRQ_27", val) -- 提醒，val并不代表触发方向，仅代表中断后某个时间点的电平
end

gpio.setup(27, gpio_func, gpio.PULLUP, gpio.RISING)

-- 设置gpio7为中断计数，获取 GPIO 的中断数量，并清空累计值。
gpio.setup(7, gpio.count)

-- 注意：Air8000中大于100的GPIO ID（WGPIO），在低功耗模式或者PSM模式下，如果要保持输出高电平，需要配置为gpio.PULLUP；反之如果要保持输出低电平，需要配置为gpio.PULLDOWN
-- 设置Air8000 GPIO140 在 PSM 模式下保持输出高电平
gpio.setup(140, 1, gpio.PULLUP)

local function enterlowpower()
    sys.wait(3000)
    log.info("lowpower","进入PSM模式")
    -- 进入PSM模式
    pm.power(pm.WORK_MODE, 3)
end
sys.taskInit(enterlowpower)

-- 注意：Air8101的GPIO，在低功耗模式或者PSM模式下，如果要保持输出高电平，需要配置为gpio.PULLUP；反之如果要保持输出低电平，需要配置为gpio.PULLDOWN
-- 设置Air8101 GPIO5 在PSM模式下保持输出低电平
gpio.setup(5, 0, gpio.PULLDOWN)

local function enterlowpower()
    sys.wait(3000)
    log.info("lowpower","进入PSM模式")
    -- 进入PSM模式
    pm.power(pm.WORK_MODE, 3)
end
sys.taskInit(enterlowpower)

-- 注意事项: 
-- 当管脚为输入模式或中断,才能通过gpio.get()获取到电平
-- 当管脚为输出模式,才能通过gpio.set()设置电平
-- 当管脚为输出模式,通过gpio.get()总会得到0
-- 中断回调的val参数不代表触发方向, 仅代表中断后某个时间点的电平
-- 双向触发EC618不支持，BK7258不支持，BK7236不支持，EC718M支持
-- 默认设置下,中断是没有防抖时间的,可以通过gpio.debounce(pin, 50)来设置防抖时间

gpio.caplevel(pin, level, func)

功能

（仅输入模式可用）捕获 GPIO 引脚电平持续的时长，单位为微秒（us）。

注意：WAKEUP管脚不能使用捕捉电平变化操作

参数

pin

参数含义：GPIO 编号，必须是数值；
数据类型：number；
取值范围：产品支持的 GPIO，可以查询具体产品的硬件手册；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：26 表示捕获 GPIO26 的电平；

level

参数含义：需要捕获的电平；
数据类型：number；
取值范围：gpio.HIGH（高电平）、gpio.LOW（低电平）、1（高电平）、0（低电平）；
是否必选：必须传入此参数；
注意事项：捕获设定的 level 持续时间；
参数示例：1 表示捕获高电平的持续时间；

func

参数含义：完成捕获后的回调函数；
数据类型：function；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：回调函数仅在成功捕获一次完整的电平持续时间后执行一次，而不是每次检测到电平变化就执行；
         回调函数仅一个参数，参数为捕获到的时间长度（number 型数值，单位 us）；
参数示例：捕获到的时间：
         function(us_int) 
             log.info("us_int:", us_int)
         end；

返回值

local get_level = gpio.caplevel(pin, level, func)

get_level

含义说明：返回获取电平的函数；
数据类型：function；
取值范围：无特别限制；
注意事项：调用该函数可以获取当前 GPIO 的电平；
返回示例：返回一个函数，调用该函数可以获取 GPIO 的当前电平；

示例

gpio.setup(26, nil, gpio.PULLUP)

-- 回调函数会在每次成功捕获一段完整的高电平持续时间后执行一次
-- us_int参数为捕获到的高电平持续时间，单位为微秒
function gpio_test(us_int)
    log.info("GPIO测试", "高电平持续时间:", us_int, "微秒")
end

gpio.caplevel(26, 1, gpio_test)

gpio.set(pin, value)

功能

（仅输出模式可用）设置 GPIO 引脚的输出电平，使用前需先用 gpio.setup 进行过一次初始化。

注意：普通IO设置完毕进入PSM+模式后，引脚输出电平会因掉电而变得不可控；AGPIO设置完毕进入PSM+模式后，可以保持引脚的输出电平。

参数

pin

参数含义：GPIO 编号，必须是数值；
数据类型：number；
取值范围：产品支持的 GPIO，可以查询具体产品的硬件手册；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：17 表示设置 GPIO17 的电平；

value

参数含义：输出电平值；
数据类型：number；
取值范围：gpio.HIGH（高电平）、gpio.LOW（低电平）、1（高电平）、0（低电平）；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：1 表示设置为输出高电平；

返回值

无返回值。

示例

-- 注意!!! 仅输出状态下，这个函数才有效
-- 一定要先gpio.setup，起码执行过一次gpio.setup，才能使用本函数，但不需要每次都gpio.setup
-- 设置gpio17输出低电平
gpio.set(17, 0)

-- 设置gpio17输出高电平
gpio.set(17, gpio.HIGH)

gpio.get(pin)

功能

（仅输入模式和中断模式可用）获取 GPIO 引脚的当前电平，使用前需先用 gpio.setup 进行过一次初始化。

参数

pin

参数含义：GPIO 编号，必须是数值；
数据类型：number；
取值范围：产品支持的 GPIO，可以查询具体产品的硬件手册；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：17 表示获取 GPIO17 的电平；

返回值

local value = gpio.get(pin)

value

含义说明：输入电平值；
数据类型：number；
取值范围：gpio.HIGH（高电平，对应数值1）、gpio.LOW（低电平，对应数值0）；
注意事项：仅输入模式或者中断模式状态下，这个函数才有效；
返回示例：1 表示当前输入电平为高电平；

示例

-- 注意!!! 仅输入模式或者中断模式状态下，这个函数才有效
-- 一定要先gpio.setup，起码执行过一次gpio.setup，才能使用本函数，但不需要每次都gpio.setup
-- 获取gpio17的当前输入电平
local value = gpio.get(17)
log.info("gpio", "GPIO17:", value)

gpio.close(pin)

功能

关闭 GPIO 引脚功能，恢复高阻输入态，并关掉中断。

参数

pin

参数含义：GPIO 编号，必须是数值；
数据类型：number；
取值范围：产品支持的 GPIO，可以查询具体产品的硬件手册；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：17 表示关闭 GPIO17；

返回值

无返回值，总是执行成功。

示例

-- 关闭gpio17
gpio.close(17)

gpio.toggle(pin)

功能

变换 GPIO 脚的输出电平，翻转一次大概所需50ns，仅输出模式可用。

参数

pin

参数含义：GPIO 编号，必须是数值；
数据类型：number；
取值范围：产品支持的 GPIO，可以查询具体产品的硬件手册；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：16 表示切换 GPIO16 的电平；

返回值

无返回值。

示例

-- 注意!!! 仅输出状态下，这个函数才有效
-- 每500ms变换一次输出电平
gpio.setup(16, 0)

function gpio_test()
    gpio.toggle(16)
end
sys.timerLoopStart(gpio_test, 500)

gpio.setDefaultPull(val)

功能

设置 gpio.setup() 中 pull 参数的默认值。设置一次后，之后调用 gpio.setup() 时如果不传 pull（传 nil 或省略），就会使用这里设置的默认上下拉，而不是平台默认值。

平台的默认值一般是“开漏”（即不配置内部上下拉，由外部电路决定），在需要整机默认上拉的板子上，用这个接口可以省掉每个 gpio.setup() 都写一遍 gpio.PULLUP。

参数

参数	类型	解释
val	number	默认上下拉设置。`0` = 平台自定义（一般为开漏）；`1` = 上拉；`2` = 下拉

返回值

返回值	类型	解释
result	boolean	传值正确返回 true，否则返回 false

示例

-- 设置 gpio.setup 的 pull 默认值为上拉
gpio.setDefaultPull(1)

-- 之后不传 pull 的 setup 都会用上拉，等效于 gpio.setup(17, 0, gpio.PULLUP)
gpio.setup(17, 0)

-- 需要个别脚用下拉时，仍然显式传入即可，不受默认值影响
gpio.setup(18, 1, gpio.PULLDOWN)

注意事项

这个接口只影响之后调用 gpio.setup() 且没有显式传 pull 的场景，对已经配置好的引脚没有影响；
传 0 是“平台自定义/开漏”，不是“不配置”，在支持开漏的平台上有实际意义，与传 nil 不同；
该接口是全局设置，建议在 main.lua 初始化阶段调用一次，不要在执行过程中反复切换。

gpio.pulse(pin, level, len, delay)

功能

函数用于在同一个 GPIO 上输出一组脉冲。

注意事项：

这是一个阻塞操作，不可以一次性输出太多脉冲，否则可能导致系统死机；
该函数仅适用于 GPIO 输出模式；
len 参数的单位是 bit，高位在前。

参数

pin

参数含义：GPIO 编号，必须是数值；
数据类型：number；
取值范围：产品支持的 GPIO，可以查询具体产品的硬件手册；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：1 表示使用 GPIO1 输出脉冲；

level

参数含义：脉冲数据；
数据类型：number：表示以十六进制或十进制形式的数值，例如 0xA9 表示输出一个字节的数据
         string：可以传入二进制字符串形式的脉冲数据；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：0xA9 表示输出一个字节的数据；

len

参数含义：脉冲长度；
数据类型：number；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：单位是 bit，高位在前；
参数示例：8 表示输出 8 位的脉冲；

delay

参数含义：高低电平延迟时间，0表示不延迟；
数据类型：number；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：用的软件 while 来 delay，这里的 delay 值是 while 循环次数，具体 delay 时间必须实际调试才知道，适用于时序要求不是特别严格的场景；
参数示例：当调用 gpio.pulse(1, 0xA9, 8, 10) 时：
         0xA9的二进制是10101001
         函数会依次输出高电平(1)、低电平(0)、高电平(1)、低电平(0)、高电平(1)、低电平(0)、低电平(0)、高电平(1)
         每个电平变化后都会执行10次空循环作为延迟；

返回值

无返回值。

示例

-- 注意，len的单位是bit，高位在前，高低电平时间均是由delay决定。
-- 本API是阻塞操作，一次性最多输出5条脉冲！！！ 否则有可能会死机!!!
-- 通过GPIO1脚输出输出8个电平变化，while循环次数是0，即不进行任何延迟
gpio.pulse(1, 0xA9, 8, 0)
-- 通过GPIO2输出16位数据0xAA55，每一位之间延迟5次循环
gpio.pulse(2, 0xAA55, 16, 5)

gpio.debounce(pin, ms, mode)

功能

设置 GPIO 的防抖参数，根据硬件 ticks（时钟滴答）来进行精确的时间计算，确保防抖时间的准确性。该函数是对 GPIO 输入信号进行预处理，可以与任何需要稳定输入信号的场景配合使用。

注意事项：

此函数设置的是软件防抖
“唤醒”行为不支持防抖操作，所以无论mode模式设置为0（冷却模式）还是1（延时模式），在低功耗模式（包含1和3）下，触发中断就立即唤醒，无法做到延迟唤醒

参数

pin

参数含义：GPIO 编号，必须是数值；
数据类型：number；
取值范围：产品支持的 GPIO，可以查询具体产品的硬件手册；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：7 表示设置 GPIO7 的防抖；

ms

参数含义：防抖时长；
数据类型：number；
取值范围：0~65555 ms，设置为 0 则关闭防抖；
是否必选：必须传入此参数；
注意事项：单位为毫秒；
参数示例：100 表示设置 100ms 的防抖时间；

mode

参数含义：防抖模式；
数据类型：number；
取值范围：0（冷却模式）、1（延时模式）；
是否必选：可选传入此参数；如果没有传入此参数或者传入了 nil 类型，则使用默认值 0；
注意事项：0：触发中断后，马上上报一次，然后冷却ms个毫秒(具体时长看参数二)后，重新接受中断；
         1：触发中断后，延迟ms个毫秒(具体时长看参数二)，期间没有新中断且电平没有变化，上报一次；
参数示例：1 表示使用延时模式；

返回值

无返回值。

示例

-- 消抖模式，当前支持2种
-- 0 触发中断后，马上上报一次，然后冷却ms个毫秒后，重新接受中断
-- 1 触发中断后，延迟ms个毫秒，期间没有新中断且电平没有变化，上报一次

-- 开启防抖，模式0-冷却，中断后马上上报，但100ms内只上报一次
gpio.debounce(7, 100) -- 对应GPIO7

-- 开启防抖，模式1-延时，中断后等待100ms，期间若保持该电平了，时间到之后上报一次
-- 对应的，如果输入的是一个 50hz的方波，那么不会触发任何上报
gpio.debounce(7, 100, 1)

-- 关闭防抖，时间设置为0就关闭
gpio.debounce(7, 0)

gpio.count(pin)

功能

（仅中断计数模式可用）获取 GPIO 的中断数量，并清空累计值。

参数

pin

参数含义：GPIO 编号，必须是数值；
数据类型：number；
取值范围：产品支持的 GPIO，可以查询具体产品的硬件手册；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：10 表示获取 GPIO10 的中断计数；

返回值

local count = gpio.count(pin)

count

含义说明：从中断计数开始或上次获取计数后到当前的中断次数；
数据类型：number；
取值范围：无特别限制；
注意事项：中断计数最大值为uint32_t，即4294967295。调用此函数后会清空累计值；
返回示例：5 表示捕获到 5 次中断；

示例

log.info("irq cnt", gpio.count(10))

五、产品支持说明

支持 LuatOS 开发的所有产品都支持 gpio 核心库。