概述

GPIO（General Purpose Input/Output，通用输入输出引脚，就是开发板上可以编程控制的「金属针脚」）是模组最基础的外设，本教程通过 GPIO 输出 功能控制 LED 闪烁，带你走完 工程创建 → 代码编写 → 编译 → 烧录（把编译好的程序写进开发板芯片）→ 运行验证 的完整开发流程。这是后续所有外设教程的基础，建议先完成本教程。

用大白话讲：GPIO 引脚就像开发板伸出来的「电线头」。程序让它输出高电平（约 3.3V，相当于开关合上）时，接在它上面的 LED 就亮；输出低电平（约 0V，相当于开关断开）时 LED 就灭。本教程就是让程序像按开关一样，每 1 秒切换一次，让 LED 闪烁。

本教程基于安信可官方 SDK（Ai-Thinker-Open/Ai-Thinker-WB2，版本 release_bl_iot_sdk_1.6.40）的官方示例 applications/get-started/blink 编写，代码可在本地 SDK 中直接找到。

🎯本页目标通过 GPIO 输出控制板载 LED 以 1 秒间隔闪烁，并掌握 SDK 工程的编译与烧录命令。

🧰前置条件① Ai-WB2 开发板一块（如 Ai-WB2-32S-Kit）② 已按 [SDK 安装](../sdk/sdk_intro) 完成开发环境搭建。

🔗相关章节环境未就绪请先看 [SDK 简介](../sdk/sdk_intro) 与 [Linux 平台快速开始](../sdk/get-start_for_Linux)；GPIO 输入见 [GPIO输入(按键检测)](./gpio_button)。

---

①

硬件准备

1. 将 Ai-WB2 开发板用 Type-C 数据线连接到电脑，板载电源指示灯亮起。
2. 确认开发板板载 LED 位置：Ai-WB2-32S-Kit 板载 蓝色 LED（GPIO3），部分开发板型号引脚不同，请以开发板丝印为准。
3. 若板载 LED 不便观察，可将 LED 正极（长脚）经 330Ω 限流电阻 连接到 GPIO 引脚，负极接地。

💡 本教程示例代码默认使用 GPIO 3（#define GPIO_LED_PIN 3），修改这个宏（宏 = 给数字起的有名字的代号，编译时会被替换成实际数值）即可适配你的开发板。

②

进入示例工程

本教程直接使用官方 SDK 自带的 blink 示例工程，打开终端进入该工程目录：

cd ~/Ai-Thinker-WB2/applications/get-started/blink

说明：cd 是「进入目录」命令，这里进入 blink 示例工程目录；后续的 make 编译、make flash 烧录命令都必须先在这个目录里执行。

📌 官方 SDK 的示例工程位于 applications/ 下，按功能分类存放（get-started、peripherals、wifi 等），本教程系列均以官方示例工程为准。

工程目录结构说明：

文件	作用
main/main.c	主程序源码，本教程主要修改的文件
Makefile	编译入口，一般无需修改
proj_config.mk	工程配置（Flash 大小、功能开关等），一般无需修改

③

编写代码

打开 main/main.c，本步完整代码已移至文末，见：

📜 完整代码 — 位于本页「完整代码」章节，默认折叠，点击展开，与官方示例（applications/get-started/blink/blink/main.c）完全一致。

代码要点：

API	作用
bl_gpio_enable_output(pin, 0, 0)	先把 LED 引脚配置为推挽输出模式（能输出高/低电平），不做这步程序控制不了这个引脚
bl_gpio_output_set(pin, value)	让引脚输出电平：传 1 灯亮、传 0 灯灭，没有它 LED 永远不会亮
vTaskDelay(1000)	让程序睡 1 秒再继续，没有它 LED 亮灭切换快到肉眼看不清
xTaskCreate(...)	创建独立运行的任务（代码在任务里循环执行），不创建则程序什么也不做

④

编译工程

在工程目录执行编译：

make -j8

说明：make 是「编译工程」命令，把代码变成开发板能运行的固件（程序文件）；-j8 表示用 8 个核并行编译，速度更快。

编译成功后生成固件 build_out/blink.bin，并显示：

✓ Built target blink

⚠️ 若提示 riscv64-unknown-elf-gcc: command not found，说明工具链权限未配置，先执行 cd toolchain/riscv/Linux && . chmod755.sh 再重新编译。

⑤

烧录固件

开发板保持 USB 连接，确认串口设备号（Linux 下通常为 /dev/ttyUSB0），执行烧录：

make flash p=/dev/ttyUSB0 b=921600

说明：make flash 是「烧录」命令，把编译好的固件写进开发板芯片。p= 后面是串口设备号（要改成你电脑上实际的串口，可用 ls /dev/ttyUSB* 查看），b= 是烧录波特率（传输速度）。

⏳ 烧录过程中按提示长按开发板 EN 键进入下载模式（部分开发板自动进入），等待进度条完成即烧录成功。 Windows 平台烧录方法见 Windows 平台快速开始。

⑥

运行验证

烧录完成后开发板自动重启运行，观察板载 LED 每 1 秒闪烁一次。

打开串口助手（波特率 921600，波特率 = 串口传输速度，收发两端必须设成一样）查看日志：

Turning the LED ON!
Turning the LED OFF!
Turning the LED ON!
Turning the LED OFF!
...

日志与 LED 动作同步，说明 GPIO 输出功能工作正常 ✅

看到 LED 每 1 秒闪一次、串口交替打印 Turning the LED ON/OFF! 即为成功；如果 LED 不闪或串口没日志，说明还没成功，对照文末「常见问题与踩坑提示」排查。

代码执行流程

例程从启动到运行的完整流程如下（图中的循环箭头表示反复执行）：

---

本文 API 汇总

bl_gpio_enable_output(pin, pullup, pulldown)

把指定引脚配置为推挽输出模式，可驱动 LED、蜂鸣器等负载（本教程用于点亮 LED）。

参数：

• pin：引脚号，可选值：0~22（GPIO0~GPIO22），本教程默认 3（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；失败返回负值错误码

vTaskDelay(ms)

让当前任务挂起指定毫秒数，期间让出 CPU 给其他任务。

参数：

• ms：延时毫秒数，可选值：任意非负整数（内部经 pdMS_TO_TICKS 换算为系统节拍）

返回值：无

xTaskCreate(task, name, stack, param, prio, handle)

创建任务并加入就绪队列，由调度器按优先级调度执行。

参数：

• task：任务入口函数指针，形如 void task(void *arg)，必填
• name：任务名称字符串（调试用），如 "led_task"
• stack：任务栈大小（单位：字），可选值：内存允许范围内任意值，如 2048（栈过小易溢出死机）
• param：传给入口函数的参数指针，无参传 NULL
• prio：任务优先级，可选值：0（最低）~19（最高，SDK 配置），如 16
• handle：任务句柄输出指针，不需要可传 NULL

返回值：成功返回 pdPASS；失败返回 pdFAIL（如内存不足）

---

完整代码

以下为 main/main.c 完整源码，与官方示例（applications/get-started/blink/blink/main.c）完全一致：

📜 点击展开 main/main.c 完整代码

#include <stdio.h>
#include <string.h>
#include <FreeRTOS.h>
#include <task.h>
#include <bl_gpio.h>

#define GPIO_LED_PIN 3

void blink_test(void *param)
{
    uint8_t value = 1;
    while (1)
    {
        bl_gpio_enable_output(GPIO_LED_PIN, 0, 0);
        printf("Turning the LED %s! \r\n", value == 1 ? "ON" : "OFF");
        bl_gpio_output_set(GPIO_LED_PIN, value);
        value = !value;
        vTaskDelay(1000);
    }
}

void main(void)
{
    xTaskCreate(blink_test, "blink", 1024, NULL, 15, NULL);
}

---

常见问题与踩坑提示

⚠️ LED 不亮
原因：LED 极性接反、限流电阻过大，或 GPIO 引脚与开发板型号不匹配
解决：确认 LED 正极接 GPIO、负极接地；检查 GPIO_LED_PIN 是否为开发板实际引脚

⚠️ 编译报 command not found
原因：工具链没有执行权限
解决：执行 cd toolchain/riscv/Linux && . chmod755.sh 后重新 make

⚠️ 烧录时提示无法打开串口
原因：串口设备号不对或权限不足
解决：确认设备号 ls /dev/ttyUSB*；权限不足执行 sudo usermod -aG dialout $USER 后重新登录

⚠️ 烧录一直卡住等待，进度条不动
原因：未进入下载模式，或数据线只能充电不能传数据
解决：烧录时按提示长按 EN 键进入下载模式；换一根能传数据的 Type-C 数据线后重试

⚠️ 执行 make 报找不到 Makefile
原因：在错误的目录执行了编译命令（必须在示例工程目录内）
解决：先执行 cd ~/Ai-Thinker-WB2/applications/get-started/blink 进入工程目录，再执行 make -j8

运行自检

LED 以 1 秒间隔稳定闪烁，且串口输出 Turning the LED ON/OFF! 交替打印，即 GPIO 输出功能验证通过。

遇到问题？

如有其他问题，请到统一的提问与讨论区：Ai-Thinker Discussions