跳到主要内容

蜂鸣器(beep)

beep 是萤火虫T1 固件内置的蜂鸣器模块,用 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)
参数类型说明
freqint发声频率,单位 Hz,数值越大音调越高
duration_msint持续时间,单位毫秒,到点自动静音

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

  • 非阻塞:只设置 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

常见坑点​

  1. freq 的单位是 Hz,不是 kHz。 想要 2kHz 要写 2000;启动器的提示音用的是 7000,也就是 7kHz。
  2. 连播音符必须自己留间隔。 因为 tone() 是替换语义,写 tone(523, 200); tone(659, 200) 只会听到后一个音。两句之间要有 time.sleep_ms()。
  3. 长音靠 duration_ms,不要用 while 死等。 tone() 本身不阻塞,让主循环继续跑,静音交给定时器。
  4. 频率别超出硬件与人耳范围。 10 位分辨率下 LEDC 的输出上限约为 78 kHz(80 MHz ÷ 1024);频率太低则人耳听不见。提示音常用 2000–8000 Hz。
  5. 全系统共用一个蜂鸣器。 模块用的是模块级全局状态,别的代码正在发声时你调 deinit() 会把它一起关掉。
  6. 不要在按键回调里播整段旋律。 回调运行在调度上下文,sleep 整段旋律会拖住调度;回调里只发单声短音,长音效放主循环或线程。

更多配方​

按键提示音​

回调里做发声这类极短操作是安全的,启动器用的就是 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)

完整示例​

萤火虫T1 的应用放在 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()

相关模块见 五向按键(button) 与 电源管理(pm)。

排错​

现象原因 / 处理
完全不响只调了 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,直接生成能在萤火虫T1 上运行的完整程序。

比如直接对它说:

按键切换菜单时「嘀」一声,操作失败时连响三声低音,开机时播放一小段上行提示音。

它就会把 beep、Button 组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。

Agent 入口(即将上线)

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