跳到主要内容

按键控制(button)

独角仙S1 机身上有六个按键:五个方向键(up / down / left / right / center)加一个功能键(start)。固件把引脚配置、消抖和长短按判定都封装在 button 模块里:你只要建一个 Button() 对象、注册回调,就能分别拿到「短按」和「长按」两个事件。

一个对象管六个键

Button() 构造时一次性接管全部按键并挂上中断,不用逐个建实例。

短按长按分开回调

register_callback('center', 'long', cb) ——一次「按下—松手」只会产生一个事件。

按键能喂狗

每次按下都会置位活动标记,launcher 靠它判断设备是否需要自动关机。

硬件与引脚​

按键名GPIO按下时的电平内部电阻说明
up46低(0)上拉方向键
down0低(0)上拉方向键
left18低(0)上拉方向键
right45低(0)上拉方向键
center43低(0)上拉方向键(确认)
start44高(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_thresholdint1000按住多久算长按,单位毫秒
debounce_timeint50消抖窗口,单位毫秒

返回按键对象。构造时就会把六个 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_namestr'up' / 'down' / 'left' / 'right' / 'center' / 'start'
press_typestr'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 运行期间就不再产生活动标记了。

短按和长按是怎么判定的​

一次完整的「按下—松手」流程:

  1. 按下 → 中断触发 → 消抖通过后:置位 activity_flag、记录按下时间、把状态标为「已按下」,并启动一个单次定时器(周期 = long_press_threshold)。
  2. 定时器到期时仍然按着 → 触发长按回调。定时器是单次模式且不会重启,所以长按只报一次。
  3. 松手 → 算出按住时长:小于阈值 → 触发短按回调;大于等于阈值 → 什么都不触发(长按已经报过了)。

所以结论是:长按不会再额外报一次短按,一次操作最多只产生一个事件。

常见坑点​

现象原因 / 处理
注册的回调完全不触发名字或类型拼错('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/。

Agent 入口(即将上线)

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