概述
本教程通过 GPIO 输入 功能检测按键状态：按下按键点亮 LED，松开按键熄灭 LED。与上一篇的 GPIO 输出形成对照，带你掌握输入模式的配置与电平（引脚上的电压高低：高电平≈3.3V，低电平≈0V）读取。
用大白话讲：GPIO 输入就像给开发板装了一双「眼睛」。按键按下时，IO8 引脚读到高电平（约 3.3V，相当于门铃被按响）；松开时读回低电平（约 0V，门铃没响）。程序像门卫一样不停盯着这个引脚，根据电平高低决定 LED 亮还是灭。
本教程基于安信可官方 SDK（Ai-Thinker-Open/Ai-Thinker-WB2，版本
release_bl_iot_sdk_1.6.40）的官方示例applications/peripherals/demo_gpio编写，代码可在本地 SDK 中直接找到。
按官方示例接线（见 SDK applications/peripherals/demo_gpio/README.md）：
| Ai-WB2 引脚 | 外设 |
|---|---|
| IO14 | LED 正极（串联 330Ω 限流电阻），LED 负极接 GND |
| IO8 | 按键一端，按键另一端接 3V3（按下时 IO8 为高电平） |
| 3V3 / GND | 供电 |
💡 示例代码中按键采用外部上拉接法（上拉 = 让引脚悬空时保持一个确定的电平，这里靠按键另一端接 3V3 实现；
bl_gpio_enable_input(pin, 0, 0)不启用内部上下拉），按下按键 IO8 读到的电平为高。
打开终端，进入官方 demo_gpio 示例工程目录：
cd ~/Ai-Thinker-WB2/applications/peripherals/demo_gpio
说明：
cd是「进入目录」命令，这里进入 demo_gpio 示例工程目录；后续的make编译、make flash烧录命令都必须先在这个目录里执行。
打开 demo_gpio/main.c，本步完整代码已移至文末，见：
📜 完整代码 — 位于本页「完整代码」章节，默认折叠，点击展开，与官方示例（
applications/peripherals/demo_gpio/demo_gpio/main.c）完全一致。
代码要点：
| 代码 | 作用 |
|---|---|
bl_gpio_enable_input(GPIO_BUTTON_PIN, 0, 0) |
把 IO8 配置为输入模式（让引脚能「看」电平），不配置则这个引脚读不到按键状态 |
bl_gpio_input_get_value(GPIO_BUTTON_PIN) |
读取 IO8 电平：返回 1（高电平/按下）或 0（低电平/松开），没有它程序就不知道按键状态 |
vTaskDelay(pdMS_TO_TICKS(5)) |
每 5ms 重新检查一次按键状态，没有它检查节奏失控，按键响应要么太快要么失灵 |
在工程目录执行编译：
make -j8
说明：
make是「编译工程」命令，把代码变成开发板能运行的固件（程序文件）；-j8表示用 8 个核并行编译，速度更快。
编译成功后生成固件 build_out/demo_gpio.bin，并显示：
✓ Built target demo_gpio
开发板保持 USB 连接，确认串口设备号后执行烧录：
make flash p=/dev/ttyUSB0 b=921600
说明：
make flash是「烧录」命令，把编译好的固件写进开发板芯片。p=后面是串口设备号（改成你电脑上实际的串口，可用ls /dev/ttyUSB*查看），b=是烧录波特率（传输速度）。
⏳ 烧录过程中按提示长按开发板 EN 键进入下载模式，等待进度条完成即烧录成功。
烧录完成后开发板自动重启运行，按下按键 IO8 变为高电平，LED 点亮；松开按键 LED 熄灭。
💡 由于程序每 5ms 轮询一次（轮询 = 程序不停反复检查某个状态，与之相对的是「中断」），按键响应迅速无延迟感；这也是按键防抖以外的轮询检测实现方式，适合低速场景。
看到「按下 LED 亮、松开 LED 灭」即为成功；如果按下没反应或灯乱闪，说明还没成功，对照文末「常见问题与踩坑提示」排查。
代码执行流程
例程从启动到运行的完整流程如下（图中的循环箭头表示反复执行）：
本文 API 汇总
bl_gpio_enable_input(pin, pullup, pulldown)
把指定引脚配置为数字输入模式，可读取按键、传感器高低电平（本教程用于读取按键）。
参数：
pin：引脚号，可选值：0~22（GPIO0~GPIO22），本教程按键用8（GPIO_BUTTON_PIN）pullup：是否使能内部上拉，可选值：1使能 /0关闭（按键对地接法推荐1，悬空时读到高电平）pulldown：是否使能内部下拉，可选值：1使能 /0关闭（按键对 VCC 接法推荐1）
返回值：成功返回 0；失败返回负值错误码
bl_gpio_enable_output(pin, pullup, pulldown)
把指定引脚配置为推挽输出模式，可驱动 LED、蜂鸣器等负载（本教程用于点亮 LED）。
参数：
pin：引脚号，可选值：0~22（GPIO0~GPIO22），本教程 LED 用14（GPIO_LED_PIN）pullup：是否使能内部上拉，可选值：1使能 /0关闭（推挽输出无需上拉，传0）pulldown：是否使能内部下拉，可选值：1使能 /0关闭
返回值：成功返回 0；失败返回负值错误码
bl_gpio_output_set(pin, value)
向已配置为输出的引脚输出高电平或低电平。
参数：
pin：引脚号，可选值同bl_gpio_enable_output（0~22）value：输出电平，可选值：1高电平（3.3V）/0低电平（0V）
返回值：成功返回 0；失败返回负值错误码
完整代码
以下为 demo_gpio/main.c 完整源码，与官方示例（applications/peripherals/demo_gpio/demo_gpio/main.c）完全一致：
📜 点击展开 demo_gpio/main.c 完整代码
#include <stdio.h>
#include <string.h>
#include <FreeRTOS.h>
#include <task.h>
#include <bl_gpio.h>
#define GPIO_BUTTON_PIN 8
#define GPIO_LED_PIN 14
void main(void)
{
bl_gpio_enable_input(GPIO_BUTTON_PIN, 0, 0);
bl_gpio_enable_output(GPIO_LED_PIN, 0, 0);
bl_gpio_output_set(GPIO_LED_PIN, 0);
for (;;) {
if (bl_gpio_input_get_value(GPIO_BUTTON_PIN)) {
bl_gpio_output_set(GPIO_LED_PIN, 1);
}
else {
bl_gpio_output_set(GPIO_LED_PIN, 0);
}
vTaskDelay(pdMS_TO_TICKS(5));
}
}常见问题与踩坑提示
⚠️ 按下按键 LED 不亮
原因：按键另一端未接 3V3、杜邦线接触不良，或 IO8 引脚被占用
解决：确认按键一端接 IO8、另一端接 3V3；拔掉 IO8 上其他杜邦线后重试
⚠️ LED 常亮不灭
原因：LED 正负极接反，或 IO14 与开发板其他外设冲突
解决：确认 LED 正极（长脚）经电阻接 IO14、负极接 GND
⚠️ 按键状态抖动（偶尔误触发）
原因：机械按键按下/松开瞬间电平抖动
解决：demo 示例为轮询演示，未做防抖；需要稳定检测时可在软件中增加 10~20ms 延时防抖或使用中断，见 EXTI 外部中断
⚠️ 烧录一直卡住等待，进度条不动
原因：未进入下载模式，或数据线只能充电不能传数据
解决：烧录时按提示长按 EN 键进入下载模式；换一根能传数据的 Type-C 数据线后重试
⚠️ 执行 make 报找不到 Makefile
原因：在错误的目录执行了编译命令（必须在示例工程目录内）
解决：先执行 cd ~/Ai-Thinker-WB2/applications/peripherals/demo_gpio 进入工程目录，再执行 make -j8
运行自检
按下按键 LED 立即点亮，松开立即熄灭，即 GPIO 输入功能验证通过。
遇到问题？
如有其他问题，请到统一的提问与讨论区：Ai-Thinker Discussions