外部按键中断LED

【ESP32-S3 Rust 入门】外部中断详解 —— 按键控制 LED

作者：CXi
开发板：ESP32-S3R8N8 嘉立创
框架：esp-hal v1.1.0 + esp-rtos v0.3.0
日期：2026-06-16

一、前言

在嵌入式开发中，外部中断是最基础也最常用的外设功能之一。相比轮询（Polling）方式，中断能让 CPU 在没有事件时"休息"，有事件时立刻响应，既高效又省电。

本文将以嘉立创 ESP32-S3R8N8 开发板为例，用 Rust + esp-hal 实现：

按下 BOOT 按键（GPIO0）→ 板载 LED（GPIO48）切换亮灭

你将学到：

• GPIO 输入/输出的基本配置
• 外部中断的注册与触发
• 中断服务程序（ISR）的编写
• critical_section在中断安全中的作用

二、硬件准备

引脚电平逻辑

BOOT 按键（GPIO0）： 空闲 → 高电平（内部上拉） 按下 → 低电平（接地） ──→ 下降沿触发中断 LED（GPIO48）： 输出 HIGH → 灯亮 输出 LOW → 灯灭

三、工程结构

外部中断/ ├── Cargo.toml └── src/ ├── lib.rs # crate 入口（仅 #![no_std]） └── bin/ └── main.rs # 主程序

关键依赖

[dependencies] esp-hal = { version = "~1.1.0", features = ["esp32s3", "unstable"] } esp-rtos = { version = "0.3.0", features = ["esp-alloc", "esp-radio", "esp32s3"] } esp-bootloader-esp-idf = { version = "0.5.0", features = ["esp32s3"] } critical-section = "1.2.0" panic-rtt-target = "0.2.0" rtt-target = "0.6.2"

四、完整代码

//! 外部中断示例 —— 按下 BOOT 按键(GPIO0)，切换板载 LED(GPIO48) 亮灭//!//! 原理：配置 GPIO0 下降沿触发中断 → 中断处理函数中翻转 LED 电平#![no_main]#![no_std]usecore::cell::RefCell;usecritical_section::Mutex;useesp_bootloader_esp_idf;useesp_hal::{gpio::{Event,Input,InputConfig,Io,Level,Output,OutputConfig,Pull},handler,main,ram,};usepanic_rtt_targetas_;usertt_target::{rprintln,rtt_init_print};// 必须：声明 IDF 应用描述符，bootloader 据此加载固件esp_bootloader_esp_idf::esp_app_desc!();// Mutex + RefCell：跨线程/中断安全地共享外设所有权// Option：外设初始化后才放入，初始为 NonestaticBUTTON:Mutex<RefCell<Option<Input>>>=Mutex::new(RefCell::new(None));staticLED:Mutex<RefCell<Option<Output>>>=Mutex::new(RefCell::new(None));#[main]fnmain()->!{// 初始化 RTT 日志通道（芯片复位后需重新初始化）rtt_init_print!();rprintln!("外部中断 -- 点灯");// 初始化 HAL，获取所有外设句柄letperipherals=esp_hal::init(esp_hal::Config::default());// IO_MUX 负责 GPIO 引脚复用配置，同时管理 GPIO 中断letmutio=Io::new(peripherals.IO_MUX);io.set_interrupt_handler(gpio_isr);// 注册中断处理函数// 板载 LED：GPIO48，默认低电平（灭）letled=Output::new(peripherals.GPIO48,Level::Low,OutputConfig::default());// BOOT 按键：GPIO0，内部上拉（空闲为高电平）letconfig=InputConfig::default().with_pull(Pull::Up);letmutbutton=Input::new(peripherals.GPIO0,config);// 临界区：配置中断监听 + 将外设移入全局静态变量// 中断处理函数需要通过这些全局变量访问外设critical_section::with(|cs|{button.listen(Event::FallingEdge);// 检测下降沿（按键按下）BUTTON.borrow_ref_mut(cs).replace(button);LED.borrow_ref_mut(cs).replace(led);});// 主循环空转，所有逻辑由中断驱动loop{}}/// GPIO 中断服务程序（ISR）////// `#[handler]` — 标记为中断处理函数/// `#[ram]` — 代码放入 RAM 执行，避免 Flash 访问延迟////// 注意：ISR 中应尽快完成工作并返回，避免长时间阻塞#[handler]#[ram]fngpio_isr(){critical_section::with(|cs|{// 拆成两行：RefMut 临时值必须先绑定到变量，否则会在语句末被释放letmutbtn_ref=BUTTON.borrow_ref_mut(cs);letbtn=btn_ref.as_mut().unwrap();// 仅处理按键触发的中断（同一向量可能有多个 GPIO 源）ifbtn.is_interrupt_set(){rprintln!("按键中断触发！");LED.borrow_ref_mut(cs).as_mut().unwrap().toggle();btn.clear_interrupt();// 必须手动清除中断标志，否则会反复触发}});}

五、逐段详解

5.1 文件头与属性

#![no_main]#![no_std]

5.2 全局静态变量 —— 中断与主函数共享外设

staticBUTTON:Mutex<RefCell<Option<Input>>>=Mutex::new(RefCell::new(None));staticLED:Mutex<RefCell<Option<Output>>>=Mutex::new(RefCell::new(None));

这是 Rust 嵌入式中最经典的"三层包装"模式：

┌─────────────────────────────────────────────────┐ │ Mutex — 临界区保护，防止中断和主函数同时访问 │ │ ┌───────────────────────────────────────────┐ │ │ │ RefCell — 运行时借用检查，允许内部可变性 │ │ │ │ ┌─────────────────────────────────────┐ │ │ │ │ │ Option — 初始为 None，初始化后 │ │ │ │ │ │ 放入 Some(外设) │ │ │ │ │ └─────────────────────────────────────┘ │ │ │ └───────────────────────────────────────────┘ │ └─────────────────────────────────────────────────┘

为什么需要这样？

• static变量必须是Sync的 → 用Mutex包装
• Mutex::new()需要在编译期确定值 → 外设还没初始化，只能放None
• 运行时需要"把值放进去" → 用RefCell实现内部可变性

5.3 HAL 初始化

letperipherals=esp_hal::init(esp_hal::Config::default());

这一行完成了：

• 时钟配置
• 电源管理初始化
• 将所有外设的"所有权"从芯片硬件映射到 Rust 类型系统

peripherals是一个结构体，每个字段对应一个外设（GPIO、SPI、I2C 等），只能取一次—— Rust 的所有权系统保证你不会意外重复初始化。

5.4 中断注册

letmutio=Io::new(peripherals.IO_MUX);io.set_interrupt_handler(gpio_isr);

Io是 GPIO 中断的"总管"。ESP32-S3 的所有 GPIO 共享同一个中断向量，通过Io注册一个统一的 ISR。gpio_isr是我们自己写的中断处理函数（见后文）。

5.5 GPIO 配置

// 输出：LEDletled=Output::new(peripherals.GPIO48,Level::Low,OutputConfig::default());// 输入：按键，内部上拉letconfig=InputConfig::default().with_pull(Pull::Up);letmutbutton=Input::new(peripherals.GPIO0,config);

5.6 临界区 —— 中断安全的关键

critical_section::with(|cs|{button.listen(Event::FallingEdge);// 监听下降沿BUTTON.borrow_ref_mut(cs).replace(button);// 将 button 移入全局变量LED.borrow_ref_mut(cs).replace(led);// 将 led 移入全局变量});

critical_section::with做了什么？

1. 关闭中断（进入临界区）
2. 执行闭包内的代码
3. 恢复中断（离开临界区）

为什么需要它？如果不关中断，可能在赋值到一半时中断触发，访问到"半初始化"的状态 → 未定义行为。

button.listen(Event::FallingEdge)让 GPIO0 检测下降沿：高电平 → 低电平的瞬间触发中断。对应按键按下的瞬间。

5.7 中断服务程序（ISR）

#[handler]#[ram]fngpio_isr(){...}

ISR 内部逻辑

critical_section::with(|cs|{letmutbtn_ref=BUTTON.borrow_ref_mut(cs);letbtn=btn_ref.as_mut().unwrap();ifbtn.is_interrupt_set(){rprintln!("按键中断触发！");LED.borrow_ref_mut(cs).as_mut().unwrap().toggle();btn.clear_interrupt();}});

执行流程：

中断触发 ↓ 进入临界区（关中断） ↓ 检查：是 BUTTON 的中断吗？（is_interrupt_set） ├─ 否 → 跳过，清除中断标志，退出 └─ 是 → 翻转 LED（toggle） ↓ 清除中断标志（clear_interrupt） ↓ 退出临界区（恢复中断）

重要提醒：

clear_interrupt()必须手动调用！ESP32 的 GPIO 中断标志不会自动清除，如果不清除，退出 ISR 后中断会立刻再次触发，形成"中断风暴"。

5.8 为什么btn_ref要拆成两行？

// ❌ 编译错误letbtn=BUTTON.borrow_ref_mut(cs).as_mut().unwrap();// ✅ 正确letmutbtn_ref=BUTTON.borrow_ref_mut(cs);letbtn=btn_ref.as_mut().unwrap();

borrow_ref_mut(cs)返回一个RefMut<T>临时值。如果链式调用.as_mut().unwrap()，RefMut在这行结束时就被释放了，btn引用的内存随之失效 →悬垂引用。

拆成两行后，btn_ref的生命周期延续到critical_section闭包结束，btn始终有效。

六、运行效果

烧录后打开 RTT 日志：

外部中断 -- 点灯

按下 BOOT 按键：

按键中断触发！ 按键中断触发！ 按键中断触发！

每按一次，LED 切换一次亮灭。

七、常见问题

Q1：中断没反应？

• 确认io.set_interrupt_handler()在button.listen()之前调用
• 确认button.listen()在critical_section::with内执行
• 检查引脚号是否与开发板原理图一致

Q2：中断触发一次后就不停触发？

• 忘记调用btn.clear_interrupt()，中断标志未清除

Q3：LED 不亮？

• 嘉立创 ESP32-S3R8N8 的板载 LED 是高电平点亮还是低电平点亮，请查阅原理图
• 本例默认高电平点亮，如果是低电平点亮，修改Level::Low为Level::High

Q4：#![no_main]和#[main]有什么区别？

• #![no_main]（带!）是文件级属性，告诉编译器"不要生成标准 main 函数"
• #[main]（不带!）是函数级属性宏，由 esp-hal 提供，生成真正的入口点

八、总结

本文核心知识点：

掌握了外部中断，你就打通了嵌入式开发的关键一环：事件驱动编程。后续的定时器中断、串口接收、SPI 通信等，都是这个模式的延伸。

作者：CXi
项目地址：Rust_ESP32_Dome
参考：esp-hal 官方仓库