蜂鸣器(beep)
beep 是独角仙S1 固件内置的蜂鸣器模块,用 ESP32 硬件 PWM(LEDC)产生方波,让你用一行代码发出指定频率、指定时长的提示音,到点自动静音。
固定在 GPIO12,LEDC 10 位分辨率、50% 占空比,音调由频率决定。
直接 import beep,不用往 SD 卡拷文件。
tone() 设置完就返回,静音由定时器负责,不占用主循环。
引脚与硬件参数
| 项目 | 值 |
|---|---|
| 引脚 | GPIO12(固定,不可改) |
| PWM 控制器 | LEDC 低速模式 |
| 定时器 / 通道 | LEDC_TIMER_1 / LEDC_CHANNEL_1 |
| 占空比分辨率 | 10 位(0–1023),发声时固定 512,即 50% |
| 初始化默认频率 | 2000 Hz |
| 自动静音的实现 | esp_timer 一次性定时器,到期关闭 PWM |
蜂鸣器是单音源:同一时刻只能发出一个频率。所谓「和弦」「多音轨」在硬件上无法实现,需要拆成前后相接的短音。
快速开始
import beep
beep.tone(2000, 300) # 2000Hz 响 300 毫秒,然后自动静音
运行现象:蜂鸣器发出一声短促的「嘀」,约 0.3 秒后自动停止。整段代码不会卡住——tone() 把频率和定时器设好就立刻返回,后面的代码照常执行。
不需要手动 beep.init():tone() 检测到模块未初始化会自己初始化。
API 参考
初始化 beep.init()
beep.init()
无参数、无返回值。作用是配置 LEDC 定时器与通道、把引脚置于静音状态、创建自动静音用的 esp_timer。
- 可以重复调用:内部用
beep_initialized标记,已初始化时直接返回,不做任何事。 - 一般不用手动调用:
tone()会自动完成初始化。只有想在发声前就把硬件准备好的场景才需要显式调用。
发声 beep.tone()
beep.tone(freq, duration_ms)
| 参数 | 类型 | 说明 |
|---|---|---|
freq | int | 发声频率,单位 Hz,数值越大音调越高 |
duration_ms | int | 持续时间,单位毫秒,到点自动静音 |
无返回值。必须知道的几个行为:
- 非阻塞:只设置 PWM 频率、占空比和定时器,随后立即返回,主循环不会被占用。
- 未初始化会自动初始化,所以
init()不是必需的。 - 重复调用是「替换」,不是「排队」:还在响的时候再调一次
tone(),会立刻换成新频率并重新计时,前一声不会放完。 - 发声期间占空比固定 50%(
512 / 1024),音色是标准方波,没有音量控制。 - 参数必须是整数(浮点、字符串会抛
TypeError);频率不做合法性校验,非法值不会报错,只是响不出来或音调不对。
停止 beep.stop()
beep.stop()
立即关闭 PWM 输出,不管定时器是否还在倒计时。无参数、无返回值;未初始化时调用是安全的空操作。
注意:它只负责静音,不会取消已经排定的自动静音定时器。因为定时器到期也只是再关一次输出,所以没有副作用。
释放 beep.deinit()
beep.deinit()
停止 PWM、删除 esp_timer、把初始化标记复位。无参数、无返回值。
之后再调用 tone(),模块会自动重新初始化,所以 deinit() 之后不需要手动 beep.init()。
时序与行为
tone() 的时长是「自动静音」而不是「阻塞等待」,几种组合下的真实行为如下:
| 场景 | 实际行为 |
|---|---|
tone(f, d) 后什么都不做 | 频率 f 持续到第 d 毫秒,定时器到期后 PWM 关闭,静音 |
声音没结束就再次 tone(f2, d2) | 立刻切成 f2,并从 d2 重新计时 |
声音没结束调用 stop() | 立刻静音;已排定的定时器仍在,到期时再执行一次静音 |
stop() 之后、定时器到期前再 tone() | 正常发声,定时器被重置,新的一声不会被提前掐掉 |
deinit() 之后调用 tone() | 自动重新初始化,正常发声 |
| 传入浮点数或字符串 | 抛 TypeError |
常见坑点
freq的单位是 Hz,不是 kHz。 想要 2kHz 要写2000;官方光绘 App 的按键提示音用的是7000,也就是 7kHz。- 连播音符必须自己留间隔。 因为
tone()是替换语义,写tone(523, 200); tone(659, 200)只会听到后一个音。两句之间要有time.sleep_ms()。 - 长音靠
duration_ms,不要用while死等。tone()本身不阻塞,让主循环继续跑,静音交给定时器。 - 频率别超出硬件与人耳范围。 10 位分辨率下 LEDC 的输出上限约为 78 kHz(80 MHz ÷ 1024);频率太低则人耳听不见。提示音常用 2000–8000 Hz。
- 全系统共用一个蜂鸣器。 模块用的是模块级全局状态,别的代码正在发声时你调
deinit()会把它一起关掉。 - 不要在按键回调里播整段旋律。 回调运行在调度上下文,
sleep整段旋律会拖住调度;回调里只发单声短音,长音效放主循环或线程。
更多配方
按键提示音
回调里做发声这类极短操作是安全的,官方光绘 App 用的就是 beep.tone(7000, 50)(7000Hz、持续 50 毫秒):
import beep
from button import Button
buttons = Button()
def beep_click():
beep.tone(7000, 50)
buttons.register_callback('up', 'short', beep_click)
buttons.register_callback('down', 'short', beep_click)
buttons.register_callback('center', 'short', beep_click)
播放一段旋律
tone() 不阻塞,所以只要在音符之间补上间隔,就能连续演奏:
import beep
import time
# 中央 C 起的七声音阶(Hz)
NOTES = [262, 294, 330, 349, 392, 440, 494]
def play(notes, duration=200, gap=30):
for f in notes:
beep.tone(f, duration)
time.sleep_ms(duration + gap) # 必须留间隔,否则前一个音会被顶掉
play([262, 330, 392, 523]) # do mi so 高音do
play(list(reversed(NOTES))) # 再下行跑一遍
提前打断正在响的音
import beep
import time
beep.tone(1000, 5000) # 准备响 5 秒
time.sleep_ms(300)
beep.stop() # 300 毫秒后提前静音,不用等满 5 秒
提醒音与错误音
import beep
import time
def warn():
beep.tone(2000, 300) # 自动休眠前就是这个参数
def error():
for _ in range(3):
beep.tone(800, 150)
time.sleep_ms(200)
完整示例
独角仙S1 的应用放在 SD 卡的 /sd/apps/<应用目录>/ 下,入口是 boot.py。启动器在进入 App 之前会释放自己的按键,所以 App 内可以放心创建自己的 Button(同样只能创建一个)。
下面这段放进 /sd/apps/my-beep-app/boot.py 即可运行:开机自检三声上行提示音,上 / 下短按试听不同频率,中键短按是轻点反馈,中键长按退出。
from button import Button
import beep
import time
TONES = [1000, 2000, 4000, 7000] # 可试听的音调(Hz)
index = 0
running = True
buttons = Button()
def on_up():
global index
index = (index - 1) % len(TONES)
beep.tone(TONES[index], 300)
def on_down():
global index
index = (index + 1) % len(TONES)
beep.tone(TONES[index], 300)
def on_center_short():
beep.tone(7000, 50) # 轻点反馈音
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)
# 开机自检:三声上行提示音,每声之间留出间隔
for f in (1000, 2000, 4000):
beep.tone(f, 120)
time.sleep_ms(180)
while running:
time.sleep(0.1) # 灯效渲染之类的活干在这里
beep.stop() # 退出前静音,避免余音
beep.deinit()
buttons.deinit()
相关模块:USB串口控制(CDC) · 按键控制(button) · 灯光控制(WS2812) · 显示屏(ST7789)
排错
| 现象 | 原因 / 处理 |
|---|---|
| 完全不响 | 只调了 init(),它只做准备不出声 → 用 tone() |
| 完全不响 | freq 写成了千赫兹(2 是 2 Hz,听不见)→ 写 2000 |
| 完全不响 | duration_ms 太小(如 0)→ 至少几十毫秒 |
抛 TypeError | 传了浮点数或字符串 → 两个参数都必须是整数 |
| 声音一直停不下来 | duration_ms 给得太长 → 用 beep.stop() 立即静音 |
| 只听到最后一个音 | 连续 tone() 之间没有间隔,前一声被替换 → 中间加 time.sleep_ms() |
| 音调不对 / 忽高忽低 | 频率超出 LEDC 在当前分辨率下能输出的范围 → 提示音用 2000–8000 Hz |
| App 退出后还在响 | 退出前没静音 → 退出前调 stop() 或 deinit() |
AI 用法(即将上线)
以后你不用自己算频率、自己补间隔:用自然语言描述你想要的音效,Agent 会照着本文档里的 API,直接生成能在独角仙S1 上运行的完整程序。
比如直接对它说:
按键切换菜单时「嘀」一声,操作失败时连响三声低音,开机时播放一小段上行提示音。
它就会把 beep、Button 组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。
入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。