跳到主要内容

五向按键(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备注
up18普通 GPIO
down45Strapping 引脚
left46Strapping 引脚
right0Strapping 引脚,同时是 BOOT 键
center44普通 GPIO
上电 / 复位时不要按住 down、left、right

这三个引脚(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毫秒1000300–3000按住超过这个时长判定为长按
debounce_time毫秒5020–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_namestr'up' / 'down' / 'left' / 'right' / 'center'
press_typestr'short' / 'long'
callbackfunction零参数函数

无返回值。三个必须知道的行为:

  • 参数写错不会报错,只是静默失效——写成 '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 的中断、清空内部状态。

deinit() 之后实例就作废了

调用后再使用 register_callback()、get_button_state() 会直接抛异常。需要重新使用按键时,请重新构造一个新实例。

触发时机​

这是使用本模块最容易搞错的部分,四个场景的精确行为如下:

场景实际行为
短按(按住 → 松开,总时长小于阈值)在松手那一刻触发一次 'short'
长按(按住达到阈值)在达到阈值那一刻触发一次 'long',只一次,不连发
长按后松手不会再触发 'short'
同时按住两个键只有最后按下的那个能完成长按判定

常见坑点​

  1. 5 个按键共用同一个 Timer(1)。 ESP32 端口里 Timer(1) 与 Timer(3) 是同一个定时器,所以无法同时长按;你自己的代码也不要再用 Timer(1) / Timer(3)。
  2. 全系统只能有一个 Button 实例。 每个 GPIO 只保留最后一个中断处理函数,第二个实例会让第一个的回调全部失效。请把实例放在模块级变量。
  3. 回调运行在调度上下文,会阻塞主循环。 回调里只做打印、置标志位、beep.tone();刷屏、长 sleep、复杂 I2C/SPI 请放到主循环。
  4. 极快点按会被消抖吞掉。 一次点按的「按下 → 松开」总时长小于 debounce_time 时,松手事件被过滤,短按不触发,且内部状态需要再按一次才恢复。默认 50 毫秒对正常人手点按(约 60–150 毫秒)是安全的。
  5. 没有双击、连发检测。 需要时用 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()

相关模块见 电源管理(pm) 与 蜂鸣器(beep)。

排错​

现象原因 / 处理
按键完全无反应名字或事件名拼错(静默失效)→ 检查 '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/。

Agent 入口(即将上线)

入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。