按键控制(button)
独角仙S1 机身上有六个按键:五个方向键(up / down / left / right / center)加一个功能键(start)。固件把引脚配置、消抖和长短按判定都封装在 button 模块里:你只要建一个 Button() 对象、注册回调,就能分别拿到「短按」和「长按」两个事件。
Button() 构造时一次性接管全部按键并挂上中断,不用逐个建实例。
register_callback('center', 'long', cb) ——一次「按下—松手」只会产生一个事件。
每次按下都会置位活动标记,launcher 靠它判断设备是否需要自动关机。
硬件与引脚
| 按键名 | GPIO | 按下时的电平 | 内部电阻 | 说明 |
|---|---|---|---|---|
up | 46 | 低(0) | 上拉 | 方向键 |
down | 0 | 低(0) | 上拉 | 方向键 |
left | 18 | 低(0) | 上拉 | 方向键 |
right | 45 | 低(0) | 上拉 | 方向键 |
center | 43 | 低(0) | 上拉 | 方向键(确认) |
start | 44 | 高(1) | 下拉 | 机身「功能键」,S1 独有 |
中断触发方式为双边沿(IRQ_FALLING | IRQ_RISING),按下和松手都会进处理函数。
两个要注意的点:
up/down/right分别落在 GPIO46 / GPIO0 / GPIO45 上,这几个是 ESP32-S3 的启动配置脚(strapping)。S1 用上拉保证上电时处于正常启动电平,这也意味着它们不适合再拿去做别的外设。- 引脚号写死在
button模块里,软件不可改。按键在机身上的位置见 基础操作。
快速开始
回调式(推荐)
from button import Button
buttons = Button() # 默认:长按 1 秒算长按,消抖 50 毫秒
def on_confirm():
print("确认")
def on_exit():
print("退出")
buttons.register_callback('center', 'short', on_confirm)
buttons.register_callback('center', 'long', on_exit)
运行现象:轻点中键打印「确认」;按住中键超过 1 秒打印「退出」,松手时不会再打印「确认」。
轮询式
import time
from button import Button
buttons = Button()
value = 50
while True:
if buttons.get_button_state('left'): # 按住左键持续加
value = min(100, value + 1)
elif buttons.get_button_state('right'): # 按住右键持续减
value = max(0, value - 1)
time.sleep(0.03) # 约 33 次/秒
运行现象:按住左键数值持续上升,按住右键持续下降——适合「按住连续调参」这类操作。
两种用法怎么选
回调 register_callback | 轮询 get_button_state | |
|---|---|---|
| 触发时机 | 短按在松手瞬间、长按在按满阈值时 | 主循环里你自己问「现在按着吗」 |
| 适合做的事 | 单击确认、长按退出这类一次性动作 | 按住连续调速、调亮度这类持续动作 |
| 代码运行在 | 中断上下文,要写得尽量短 | 普通上下文,可以随便耗时 |
| 典型页面 | 菜单确认 / 退出 | 参数微调 |
两者可以同时用:同一个键既注册短按回调,又在主循环里轮询状态,互不干扰。
API 参考
Button(long_press_threshold=1000, debounce_time=50)
from button import Button
buttons = Button() # 长按 1 秒、消抖 50 毫秒
buttons = Button(long_press_threshold=500) # 改成按住 0.5 秒算长按
buttons = Button(debounce_time=20) # 消抖更灵敏
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
long_press_threshold | int | 1000 | 按住多久算长按,单位毫秒 |
debounce_time | int | 50 | 消抖窗口,单位毫秒 |
返回按键对象。构造时就会把六个 GPIO 配好(up / down / left / right / center 上拉,start 下拉)并挂上双边沿中断。
- 一个程序只建一个实例。GPIO 的中断处理函数是唯一的,建第二个实例会把第一个的顶掉,两个都用不好。
- 各按键状态、定时器、回调表都在构造时一起建好,所以构造完就可以直接注册回调。
register_callback(button_name, press_type, callback)
buttons.register_callback('up', 'short', on_up) # 上键短按
buttons.register_callback('center', 'long', on_exit) # 中键长按
| 参数 | 类型 | 说明 |
|---|---|---|
button_name | str | 'up' / 'down' / 'left' / 'right' / 'center' / 'start' |
press_type | str | 'short'(短按)或 'long'(长按) |
callback | 函数 | 无参数函数 |
无返回值。每个按键的每种事件只保留最后一个回调,重复注册会覆盖。
button_name或press_type写错不会报错,只是静默不生效——这是最容易排查半天的坑,名字要全小写。- 不注册回调也没关系:按键照样会置位活动标记,
get_button_state()照样能读到状态。
get_button_state(button_name)
pressed = buttons.get_button_state('left') # True 表示此刻正被按住
返回 bool。模块已经帮你处理了电平极性(低电平触发的键取反,start 不取反),所以你只管看 True / False。
- 它读的是引脚的当前电平,不经过消抖、也不做长短按判定,所以适合在主循环里当「按住」用。
- 名字不在按键表里(或已
deinit())时返回None,不是False。
deinit()
buttons.deinit()
无参数、无返回值。释放全部资源:停掉定时器、摘掉所有中断处理函数、清空内部字典。
- 程序退出前一定要调。中断还挂在 GPIO 上就退回 launcher,按键会同时被两套代码响应。
- 调用之后这个实例就作废了:
get_button_state()只会返回None,再register_callback()也不会生效。
check_and_reset_activity() 与 activity_flag
from button import Button
if Button.check_and_reset_activity():
print("刚刚有按键活动")
Button.activity_flag是类变量:任一按键按下的瞬间就被置为True。check_and_reset_activity()是类方法:有活动则返回True并把标记清零,否则返回False。不需要实例就能调用。- launcher 的自动关机线程每秒调用一次它,有活动就重置休眠计时——所以你操作按键时设备不会到点自动关机。
- 一次只能有一个
Button实例真正生效(中断是唯一的)。launcher 里有一个用于自动关机判断,你的 App 再建一个后接管的是同一批中断,activity_flag依然会被正常置位;但如果你在 App 里调了deinit(),App 运行期间就不再产生活动标记了。
短按和长按是怎么判定的
一次完整的「按下—松手」流程:
- 按下 → 中断触发 → 消抖通过后:置位
activity_flag、记录按下时间、把状态标为「已按下」,并启动一个单次定时器(周期 =long_press_threshold)。 - 定时器到期时仍然按着 → 触发长按回调。定时器是单次模式且不会重启,所以长按只报一次。
- 松手 → 算出按住时长:小于阈值 → 触发短按回调;大于等于阈值 → 什么都不触发(长按已经报过了)。
所以结论是:长按不会再额外报一次短按,一次操作最多只产生一个事件。
常见坑点
| 现象 | 原因 / 处理 |
|---|---|
| 注册的回调完全不触发 | 名字或类型拼错('Up'、'press')→ 静默忽略;改成全小写 'up' / 'short' |
| 长按之后松手没反应 | 设计如此:长按报过就不再报短按 |
| 两个键同时按住时长按不灵 | 六个键共用同一个定时器实例,同一时刻只有一个键能处于长按计时状态 |
| 快速连点会漏几次 | 消抖窗口默认 50ms,两次按下的间隔要大于它 → 要更灵敏就 Button(debounce_time=20) |
| 回调里做耗时操作导致卡死或重启 | 回调运行在中断上下文 → 里面只置标志位,耗时的活放主循环 |
建了两个 Button() | GPIO 中断是唯一的,后建的顶掉先建的 → 全程只建一个实例 |
get_button_state() 一直返回 None | 名字不在按键表里,或者已经 deinit() 过了 |
| 退出 App 后按键乱触发 | 忘了 deinit(),旧的中断处理函数还挂着 → 退出前务必调用 |
自己读 Pin.value() 得到的极性是反的 | start 是高电平触发(下拉),其余是低电平触发 → 用 get_button_state() 让它替你判断 |
| 设备用一会儿自动关机 | 这是 S1 的自动休眠(默认 300 秒无按键活动),不是按键坏了 → 按一下任意键,或在 config.json 里关掉 auto_shutdown |
更多配方
给所有键加一声蜂鸣反馈
import beep
from button import Button
def feedback():
beep.tone(2000, 60)
buttons = Button()
for name in ('up', 'down', 'left', 'right', 'center'):
buttons.register_callback(name, 'short', feedback)
长按连发(按住不放持续触发)
长按回调本身只会触发一次。要「按住连发」,可以在回调里置一个标志,由主循环按自己的节奏处理:
import time
from button import Button
repeat = False
buttons = Button()
def on_down():
global repeat
repeat = True
buttons.register_callback('down', 'long', on_down)
while True:
if repeat and buttons.get_button_state('down'):
print("连发中")
time.sleep(0.2)
else:
repeat = False
time.sleep(0.02)
完整示例
放在 SD 卡的 /sd/apps/button-demo/boot.py:上/下键调亮度档位,长按中键退出。回调里只改数、置标志,真正耗时的活(打印、蜂鸣、刷灯)全放在主循环——这是中断上下文里唯一稳妥的写法。
import time
import beep
from button import Button
level = 5 # 亮度档位 0-10
dirty = False # 有没有新变化待处理
running = True
def bump(delta):
"""回调里只做最轻的事:改一个数,置一个标志"""
global level, dirty
level = max(0, min(10, level + delta))
dirty = True
def on_exit():
global running
running = False
buttons = Button()
buttons.register_callback('up', 'short', lambda: bump(1))
buttons.register_callback('down', 'short', lambda: bump(-1))
buttons.register_callback('center', 'long', on_exit)
try:
while running:
if dirty:
dirty = False
brightness = level / 10
print("brightness:", brightness)
beep.tone(2000, 40)
# 真正耗时的活都放这里:刷灯带、画屏幕……
time.sleep(0.03)
finally:
beep.stop()
buttons.deinit()
排错
| 现象 | 原因 / 处理 |
|---|---|
| 所有按键都没反应 | 没建 Button() 实例,或建完马上就 deinit() 了 |
| 某个键一直被判定为按下 | 该引脚被别的外设占用或短路,也可能是键卡住了 → 用 get_button_state() 逐个确认 |
| 按一下就重启 | 回调里做了耗内存或耗时的操作(中断上下文)→ 改成置标志位 |
| 短按偶尔被当成长按 | long_press_threshold 设得太小 → 适当加大 |
| 短按偶尔丢失 | 消抖窗口太长,或按得太快 → 调小 debounce_time |
| 松手后还多出一两个事件 | 机械抖动落在消抖窗口之外 → 适当加大 debounce_time(默认 50ms 一般够用) |
| 按键与屏幕/灯带一起用时偶发异常 | 回调与主循环同时操作同一份数据 → 回调只改简单变量,复杂结构交给主循环处理 |
相关模块:灯光控制(WS2812) · 蜂鸣器(beep) · 显示屏(ST7789)
AI 用法(即将上线)
以后你不用自己写消抖、也不用纠结回调里能做什么:用自然语言描述你想要的按键交互,Agent 会照着本文档里的 API,直接生成能在独角仙S1 上运行的完整程序。
比如直接对它说:
上键调亮、下键调暗,长按中键退出;每次按键都响一声,退出前把蜂鸣器关掉。
它就会把 Button 的回调、get_button_state() 和 beep 组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。
入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。