五向按键(button)
button 是萤火虫T1 固件内置的五向按键输入模块,用「中断 + 消抖」识别上、下、左、右、中的短按与长按,并通过回调把事件交给你的程序。
up=18、down=45、left=46、right=0、center=44,内部上拉、按下为低电平。
直接 from button import Button,不用往 SD 卡拷文件。
主循环专心做灯效渲染,按键事件由回调处理。
引脚
up (GPIO18)
left (GPIO46) center (GPIO44) right (GPIO0)
down (GPIO45)
按键名(button_name) | GPIO | 备注 |
|---|---|---|
up | 18 | 普通 GPIO |
down | 45 | Strapping 引脚 |
left | 46 | Strapping 引脚 |
right | 0 | Strapping 引脚,同时是 BOOT 键 |
center | 44 | 普通 GPIO |
这三个引脚(GPIO0 / GPIO45 / GPIO46)是 ESP32-S3 的 Strapping 引脚,它们在上电或复位的那一瞬间决定芯片的启动模式。
开机之后再按键完全不受影响;但若在上电 / 复位时正好按住,设备可能无法正常启动或进入下载模式。
快速开始
from button import Button
import time
buttons = Button() # 全系统只创建一个
def on_center_short():
print("中键短按")
buttons.register_callback('center', 'short', on_center_short)
while True:
time.sleep(0.1)
运行现象:每次按下再松开中键,REPL 打印一次「中键短按」。注意是松手的那一刻才打印,不是按下的那一刻。
API 参考
构造方法 Button()
Button(long_press_threshold=1000, debounce_time=50)
| 参数 | 单位 | 默认值 | 建议范围 | 说明 |
|---|---|---|---|---|
long_press_threshold | 毫秒 | 1000 | 300–3000 | 按住超过这个时长判定为长按 |
debounce_time | 毫秒 | 50 | 20–50 | 消抖时间,同时作用于按下与松手两个边沿 |
构造函数执行后立即开始监听,没有单独的 start()。它会占用 5 个 GPIO 的中断,以及硬件定时器 Timer(1)。
buttons = Button(long_press_threshold=500, debounce_time=30)
注册回调 register_callback()
register_callback(button_name, press_type, callback)
| 参数 | 类型 | 取值 |
|---|---|---|
button_name | str | 'up' / 'down' / 'left' / 'right' / 'center' |
press_type | str | 'short' / 'long' |
callback | function | 零参数函数 |
无返回值。三个必须知道的行为:
- 参数写错不会报错,只是静默失效——写成
'Center'、'mid'都无效,这是最常见的踩坑点; - 同一按键、同一事件重复注册是覆盖,不会叠加执行;
- 回调不能带参数,要传值请用闭包默认参数:
lambda n=name: print(n)。
查询状态 get_button_state()
get_button_state(button_name) # 返回 bool 或 None
返回该按键当前是否被按住;按键名非法时返回 None。
它直接读引脚、绕过消抖与内部状态,因此适合「按住期间持续处理」,例如按住不放让某个参数连续变化:
while buttons.get_button_state('center'):
print("中键按住中…")
time.sleep(0.1)
释放资源 deinit()
deinit()
停止所有定时器、解除 5 个 GPIO 的中断、清空内部状态。
调用后再使用 register_callback()、get_button_state() 会直接抛异常。需要重新使用按键时,请重新构造一个新实例。
触发时机
这是使用本模块最容易搞错的部分,四个场景的精确行为如下:
| 场景 | 实际行为 |
|---|---|
| 短按(按住 → 松开,总时长小于阈值) | 在松手那一刻触发一次 'short' |
| 长按(按住达到阈值) | 在达到阈值那一刻触发一次 'long',只一次,不连发 |
| 长按后松手 | 不会再触发 'short' |
| 同时按住两个键 | 只有最后按下的那个能完成长按判定 |
常见坑点
- 5 个按键共用同一个
Timer(1)。 ESP32 端口里Timer(1)与Timer(3)是同一个定时器,所以无法同时长按;你自己的代码也不要再用Timer(1)/Timer(3)。 - 全系统只能有一个
Button实例。 每个 GPIO 只保留最后一个中断处理函数,第二个实例会让第一个的回调全部失效。请把实例放在模块级变量。 - 回调运行在调度上下文,会阻塞主循环。 回调里只做打印、置标志位、
beep.tone();刷屏、长sleep、复杂 I2C/SPI 请放到主循环。 - 极快点按会被消抖吞掉。 一次点按的「按下 → 松开」总时长小于
debounce_time时,松手事件被过滤,短按不触发,且内部状态需要再按一次才恢复。默认 50 毫秒对正常人手点按(约 60–150 毫秒)是安全的。 - 没有双击、连发检测。 需要时用
time.ticks_ms()自己判断两次短按的间隔(见下方配方)。
推荐写法:回调只置标志,主循环干重活
from button import Button
import time
buttons = Button()
pending = {'prev': False, 'next': False}
def on_left():
pending['prev'] = True # 回调里只置标志,极快
def on_right():
pending['next'] = True
buttons.register_callback('left', 'short', on_left)
buttons.register_callback('right', 'short', on_right)
while True:
if pending['prev']:
pending['prev'] = False
print("上一项(这里做重活)")
if pending['next']:
pending['next'] = False
print("下一项(这里做重活)")
time.sleep(0.02) # 耗时的灯效渲染也放这里
更多配方
按键反馈音
回调里做这类短操作是安全的。启动器用的就是 beep.tone(7000, 50)(7000Hz、持续 50 毫秒):
import beep
def feedback():
beep.tone(7000, 50)
buttons.register_callback('up', 'short', feedback)
buttons.register_callback('down', 'short', feedback)
buttons.register_callback('center', 'short', feedback)
长按休眠
import pm
def on_center_long():
beep.tone(7000, 50)
pm.sleep() # 充电中不会休眠,会返回 "no sleep"
buttons.register_callback('center', 'long', on_center_long)
模拟双击
模块没有双击检测,用 time.ticks_ms() 判断两次短按的间隔即可:
DOUBLE_CLICK_MS = 300
last_click = [0]
def on_center_short():
now = time.ticks_ms()
if time.ticks_diff(now, last_click[0]) < DOUBLE_CLICK_MS:
print("双击中键")
last_click[0] = 0 # 清零,避免三击被识别成两次双击
else:
last_click[0] = now # 记录第一次点击
buttons.register_callback('center', 'short', on_center_short)
完整示例
萤火虫T1 的应用放在 SD 卡的 /sd/apps/<应用目录>/ 下,入口是 boot.py。启动器在进入 App 之前会释放自己的按键,所以 App 内可以放心创建自己的 Button(同样只能创建一个)。
下面这段放进 /sd/apps/my-light-app/boot.py 即可运行:上 / 下短按切换灯效,中键短按确认,中键长按退出。
from button import Button
import beep
import time
EFFECTS = ['红灯常亮', '绿色呼吸', '彩虹渐变']
index = 0
running = True
buttons = Button(long_press_threshold=800, debounce_time=30)
def beep_click():
beep.tone(7000, 50)
def on_up():
global index
index = (index - 1) % len(EFFECTS)
beep_click()
print("上一项:", EFFECTS[index])
def on_down():
global index
index = (index + 1) % len(EFFECTS)
beep_click()
print("下一项:", EFFECTS[index])
def on_center_short():
beep_click()
print("确认:", EFFECTS[index])
def on_center_long():
global running
running = False
buttons.register_callback('up', 'short', on_up)
buttons.register_callback('down', 'short', on_down)
buttons.register_callback('center', 'short', on_center_short)
buttons.register_callback('center', 'long', on_center_long)
while running:
# 灯效渲染写在这里
time.sleep(0.05)
buttons.deinit()
排错
| 现象 | 原因 / 处理 |
|---|---|
| 按键完全无反应 | 名字或事件名拼错(静默失效)→ 检查 'up'/'down'/'left'/'right'/'center' 与 'short'/'long' |
| 按键完全无反应 | 存在第二个 Button 实例覆盖了中断 → 只保留一个,放模块级变量 |
| 按键完全无反应 | 之前调用过 deinit() → 重新 Button() |
触发时抛 TypeError | 回调带了参数 → 改成零参数函数 |
| 短按偶尔丢失 | 点按快于 debounce_time → 降到 20–30 毫秒 |
| 回调里刷屏后整机卡顿 | 回调中做了耗时操作 → 只置标志位,重活放主循环 |
| 上电后无法正常启动 | 上电 / 复位时按住了 Strapping 引脚 → 松开后重新上电 |
AI 用法(即将上线)
以后你不用自己逐行写代码:用自然语言描述你想要的按键行为,Agent 会照着本文档里的 API,直接生成能在萤火虫T1 上运行的完整程序。
比如直接对它说:
中键短按切换灯效,长按休眠,每次按键都有提示音。
它就会把 Button、beep、pm 组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。
入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。