前阵子整理训练数据集时，又一次把大模型微调任务丢到后台，然后坐在电脑前干等。桌面横幅通知早就被折叠了，手机推送也很安静，等我想起来去看进度，任务已经结束快半个小时。这种“等通知”的别扭感让我决定做一个叫 buzz 的小项目：用一只蜂鸣器，把“该去看结果了”这件事用物理声音直接拍在脸上。项目本身不复杂，但做完之后我很确定，它在很多场景里都能替代手机通知，适合那些常年在跑脚本、盯日志、维护服务器，或者在实验室、机房和家庭工作区来回走动的人。这篇就是我的完整搭建过程和踩坑记录，从硬件选型到代码实现都写清楚，你可以直接照着复制。
1. 为什么我最终选了“物理蜂鸣器”而不是手机推送
1.1 手机推送的真正短板是“通知疲劳”
我们不是没有通知工具。手机上有企业微信、钉钉、Telegram bot，电脑上有各种桌面弹窗，但真正到了需要“立刻知道”的那个瞬间，你还是会错过。原因不是工具坏了，而是通知密度太高。一天收到上百条横幅之后，大脑会自动过滤掉它们，等真正的关键事件到来时，它混在一堆噪声里毫不起眼，哪怕你把字体调到最大也救不回来。
这是我做 buzz 之前反复想明白的一件事：通知系统缺的不是“多一个渠道”，而是“一个不可忽略的信号”。审美疲劳无法靠加大弹窗音量解决，但物理蜂鸣器可以，因为它的声音出现频率低、音色突兀，而且就放在你身边半米内。它和人类“警惕突发声响”的本能直接挂钩，不需要你主动去看屏幕。
1.2 项目的自我定位：只做一件事，但要做到底
很多个人项目做着做着就失控了，加湿度传感器、加 OLED 显示、加远程控制，最后变成一个大杂烩。buzz 在最开始就把定位锁死：它只负责“在某个事件发生时，发出足够明显的蜂鸣声”，不做 UI、不做屏幕、不做数据库，唯一要保证的就是极低的故障率和极短的触发延迟。
硬件上我选了一个朴素但扎实的组合：ESP32-C3 开发板加一个有源蜂鸣器模块。成本不到三十块钱，功耗也很低，日常挂在一个 5V 充电头上，常年通电也不心疼。软件上，设备端只维护一个 HTTP 服务，主机端通过脚本检测事件并向设备发送请求。整条链路没有云端依赖，全部跑在局域网里，隐私和安全都捏在自己手里。
1.3 适合谁参考
如果你属于下面几种情况之一，这个项目可以直接抄作业：
- 经常跑模型训练、爬虫任务、批量数据处理，总会离开屏幕等结果。
- 维护家庭或小型办公室里的服务器、NAS，需要在日志出现关键字时立刻被提醒。
- 有“忘记关洗衣机、忘记收衣服、小孩回家没锁门”这类生活场景，想做一个简单可靠的提醒装置。
- 刚开始接触 ESP32 / MicroPython，想要一个不用理解太多协议就能跑通的小项目。
我不建议把 buzz 当成一个智能家居平台来用，那不在它的定位里。它要解决的就是一个很原始的问题：让一个物理设备在你需要的时候叫出声来。
2. 硬件材料与选型里的门道
买材料之前先把几个关键件搞清楚，能省下很多退货和重买的麻烦。这一节把选择逻辑拆开讲。
2.1 主控选型：ESP32-C3 是这类项目的优解
可以做蜂鸣器控制的板子很多，Arduino UNO 可以，树莓派 Pico 也可以，STM32 更是绰绰有余，但综合来看我推荐 ESP32-C3 开发板。理由主要有三个。
第一，ESP32-C3 自带 Wi-Fi。buzz 需要接收主机发来的网络请求，如果选纯单片机的 Arduino UNO，还要额外配一个 ESP8266 或 ENC28J60 网口模块，接线和代码复杂度都会上升。ESP32-C3 一体解决，开机自动联网，代码里十几行就能完成。
第二，MicroPython 支持非常成熟。虽然我最开始也考虑过 Arduino 的 C++ 环境，但 MicroPython 在调试阶段实在方便，改完代码直接通过串口上传，不需要等编译，非常适合快速迭代。而且 ESP32-C3 的板子便宜，带 Type-C 接口的型号也就十几二十块钱，坏了也不心疼。
第三，GPIO 数量完全够用。这类项目对引脚需求极少，一个蜂鸣器占用一个 GPIO，最多再加一个状态 LED。ESP32-C3 提供的引脚数量绰绰有余，剩下的还能留给未来扩展。
如果手头已经有 ESP32 经典版或者 Pico W，也完全没必要再买新的，只要能联网、能输出 GPIO 电平，逻辑一模一样。
2.2 有源蜂鸣器 vs 无源蜂鸣器：不要选错
“有源”和“无源”这两个词是新人最容易踩的坑。有源蜂鸣器内部自带振荡电路，只要给它一个直流电平，它就会自己发声，不需要外部提供频率信号。无源蜂鸣器内部没有振荡源，必须用 PWM 或方波去驱动，给不同频率就会发出不同音调的音乐。
buzz 的核心需求是“可靠地叫”，不是“演奏音乐”，所以我选了有源蜂鸣器。它的好处非常实在：主控只要把引脚置高电平就响，置低电平就停，代码逻辑简单到不可能出错。无源蜂鸣器虽然可以玩旋律，但控制逻辑复杂、占资源，而且如果代码里忘了关闭 PWM，它还会产生持续噪音，反而干扰人。
有一点要特别注意：直接买蜂鸣器裸器件和三极管驱动模块是两回事。我用的是有源蜂鸣器模块，模块上自带 S8550 这类三极管驱动电路，可以直接用 3.3V 逻辑电平控制，VCC 接 3.3V 或 5V 都行。如果你买的是裸蜂鸣器，直接从 GPIO 接出去，电流可能不够，声音会很弱，甚至把引脚烧坏。建议新手一律买带驱动模块的版本，接线就三根线，非常简单。
2.3 其他材料清单与采购建议
完整材料清单如下：
| 材料 | 数量 | 作用 | 预算参考 |
|---|---|---|---|
| ESP32-C3 开发板 | 1 | 主控，联网接收通知 | 约15元 |
| 有源蜂鸣器模块 | 1 | 发声装置 | 约3元 |
| 5V/1A 充电头 | 1 | 供电 | 家里闲置即可 |
| 普通 USB 数据线 | 1 | 供电+烧录固件 | 家里闲置即可 |
| 面包板与杜邦线 | 若干 | 接线，方便调整 | 约10元 |
| 小外壳 | 1 | 后期整理美观 | 可省略 |
采购买蜂鸣器模块时，看一下模块上的丝印有没有标 I/O、VCC、GND 三根针脚，标准模块都有。少数模块还有一根“S”口，注意别接成面包板电源的正负反了。杜邦线的母头到公头、母头到母头都准备几根，后面调试会用到。
3. 整条链路的工作原理：从日志行到蜂鸣声
很多教程只会告诉你“连上这根线、烧这段代码”，但不懂原理出了问题根本无从排查。这里把链路拆成三段讲清楚。
3.1 事件检测方式：主机端监听，而不是设备端探测
设计的时候要考虑一个重要问题：谁来判断“事件发生了”？一开始我想过让 ESP32 直接去轮询某个服务的 API，但很快否掉了。让设备轮询，设备就得知道所有事件源的地址、端口、认证信息，耦合度太高，以后每加一种事件源都要改设备固件。
最终采用的做法是：主机端负责任务状态检测和事件判定，发现符合条件的事件之后，发一个 HTTP 请求给设备，设备只负责响。这个职责划分有两个直接好处：一是设备固件几乎不用改，所有业务逻辑集中在主机端脚本里；二是可以同时接多个事件源，不管哪个检测到了，最终都是调同一个通知接口。
以我实际用的一个场景为例：我跑模型训练时会在终端启动训练命令，并通过记录进程的输出日志。检测脚本每 3 秒读一次日志尾部，用正则匹配关键字，比如“训练完成”或“Error”。一旦命中，就往设备的/notify接口发一个 POST 请求。
3.2 消息传输协议设计：为什么用 HTTP 而不是 MQTT
传输协议最初有两个选择：HTTP 和 MQTT。MQTT 在物联网领域非常流行，有 QoS 机制，消息不会丢，看起来更适合做通知推送。但实际评估下来，buzz 只需要一个设备、一条局域网链路，MQTT 反而把事情复杂化了。MQTT 需要再搭一个 broker（比如本地跑 Mosquitto），设备要维护订阅关系，主机端还要多写一套客户端代码，收益只是每条消息“大概率不丢”，而这个概率 HTTP 在局域网里同样能达到。
HTTP 方案的逻辑最简单：主机端检测到事件后，直接发一个POST http://192.168.1.88:8080/notify请求，设备端监听 8080 端口，收到请求就把蜂鸣器拉高。即使 HTTP 请求因为网络抖动失败，主机端做一次重试就能解决，完全不需要引入复杂基础设施。
还有一点是安全性考虑。HTTP 明文在局域网里虽然不加密，但我的网络环境相对可信，设备也只响应白名单请求。如果把这个方案暴露到公网，就必须要加 Token 鉴权和 HTTPS，这个后面扩展部分会提到。
3.3 为什么不在设备端直接做情绪检测或语音识别
也许有人会想，既然只是“声音提醒”，干脆用手机语音助手识别提示音算了。但那只适合人坐在同一个空间里的情况，而且识别逻辑放在云端，延迟不可控。buzz 的价值恰恰在于低延迟和确定性：同一网络下，从事件触发到蜂鸣响起的延迟大约是 50 毫秒到 300 毫秒之间，这是人耳几乎无感的范围。设备端只需要对 GPIO 做一次拉高操作，没有任何中间环节。
这也解释了为什么这套系统这么稳：链路里没有任何一个环节依赖第三方服务，家里断外网也不会影响它工作。
4. 手把手搭建与代码实现
下面从接线到跑通，完整过一遍。我以 ESP32-C3 和 MicroPython 为例，如果你用别的板子，原理完全一致。
4.1 接线：三根线的连接顺序
先断电，再把蜂鸣器模块插到面包板上。模块上的三根针脚分别接：
- 模块的 VCC 接开发板的 3V3 引脚
- 模块的 GND 接开发板的 GND 引脚
- 模块的 I/O 接开发板的 GPIO2 引脚
我选 GPIO2 的原因是这个引脚在 ESP32-C3 上默认没有特殊功能，开机时也不会产生干扰信号。如果你想换引脚，改代码里的Pin(2, Pin.OUT)即可。接好后检查一遍正负极，模块的正负极反接不会立刻烧掉，但蜂鸣器不会响，你可以用万用表或者直接肉眼核对丝印上的 VCC 和 GND 标识。
接线完成之后，用 Type-C 数据线把开发板和电脑连接起来，Windows 上设备管理器里会多出一个串口设备，一般是 COM3 或 COM4，这就说明板子已经被识别了。
4.2 设备端固件：MicroPython 版本
烧录固件之前先确认板子上已经刷上 MicroPython。大多数 ESP32-C3 开发板买回来时自带 AT 固件，需要先用 esptool 烧一遍 MicroPython。在终端执行：
esptool.py --port COM3 erase_flash esptool.py --port COM3 --baud 460800 write_flash -z 0x0 ESP32_GENERIC_C3-20240205-v1.22.2.bin刷完之后用 Thonny 或者 mip 安装好驱动，新建一个main.py，写入下面的代码：
import time import network import socket import json from machine import Pin # GPIO2 接有源蜂鸣器模块 buzzer = Pin(2, Pin.OUT) buzzer.value(0) # 初始化静音 WIFI_SSID = "你的WiFi名称" WIFI_PASSWORD = "你的WiFi密码" def connect_wifi(): wlan = network.WLAN(network.STA_IF) wlan.active(True) if not wlan.isconnected(): wlan.connect(WIFI_SSID, WIFI_PASSWORD) for _ in range(30): if wlan.isconnected(): break time.sleep(0.5) if wlan.isconnected(): ip = wlan.ifconfig()[0] print("WiFi connected:", ip) return ip return None def beep(times, duration_ms=150): for _ in range(times): buzzer.value(1) time.sleep_ms(duration_ms) buzzer.value(0) time.sleep_ms(120) def handle_request(client): request = client.recv(1024).decode() print("Request:", request) if "/notify" in request: beep(3, 180) response = "HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\n\r\nok" client.send(response) client.close() ip = connect_wifi() if not ip: raise SystemExit("WiFi connection failed") server = socket.socket(socket.AF_INET, socket.SOCK_STREAM) server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) server.bind(("0.0.0.0", 8080)) server.listen(2) print("buzz server listening on:", ip) while True: try: conn, addr = server.accept() handle_request(conn) except Exception as e: print("Error:", e) time.sleep(1)这段代码的逻辑不复杂：开机连接 Wi-Fi，启动 TCP 服务监听 8080 端口，收到包含/notify的 HTTP 请求后调用beep(3, 180)，鸣响 3 次、每次 180 毫秒。beep函数末尾设置了 120 毫秒的间隔，实际听起来像“嘀-嘀-嘀”三声，比持续长鸣要清晰很多。
4.3 主机端检测脚本：以日志关键字为例
设备端就位后，接下来是主机端。下面是一个通用 Python 脚本，监控一个日志文件，发现匹配的事件后向设备发通知。
import time import requests LOG_FILE = "/path/to/your/log.txt" KEYWORDS = ["训练完成", "ERROR", "FATAL"] DEVICE_URL = "http://192.168.1.88:8080/notify" def tail_follow(filepath): with open(filepath, "r", encoding="utf-8", errors="ignore") as f: f.seek(0, 2) while True: line = f.readline() if not line: time.sleep(1) continue yield line for line in tail_follow(LOG_FILE): if any(keyword in line for keyword in KEYWORDS): try: resp = requests.post(DEVICE_URL, timeout=3) print("已通知，状态码:", resp.status_code) except Exception as e: print("通知失败，将重试:", e)tail_follow函数模仿了tail -F的行为：先把文件指针移到末尾，然后循环读新行。每次读到非空行就检查是否包含关键字，一旦命中就发通知。主机端脚本可以根据自己的需求自由改，不限于日志文件，比如可以改成监控某个目录的文件数量变化，也可以改成检查某个进程是否退出。
4.4 首次联调与结果评估
联调时最忌讳一上来就把所有功能都打开。我先做了一个最简单的测试：手动在终端执行curl -X POST http://设备IP:8080/notify，观察蜂鸣器有没有按预期响三声。这一步确认通过，再启动日志监控脚本。然后写一行包含“训练完成”的测试日志到日志文件，等 3 秒左右就能听到蜂鸣器鸣叫。
实际跑下来的触发延迟大概是这样的：日志轮询间隔 1 秒，TCP 建连和 HTTP 传输在局域网内一般 20 毫秒左右，所以从日志写入到蜂鸣器响起基本在 1 到 2 秒之间。如果你对延迟要求更高，可以把轮询间隔缩短到 0.5 秒，代价是 CPU 占用稍微高一点，但对于日志文件监控这种场景完全不是问题。
到目前为止，一只完整可用的电子蜂鸣通知器已经可以工作了。但从“能跑”到“稳定跑”，中间还有几个坑基本是每个人都会踩到的。
5. 实战遇到的问题与我的处理方式
设备刚通电的那几个小时非常顺利，但用了几天之后陆续冒出几个问题，我逐一排查并解决，这里完整记录一下，省得你重复走弯路。
5.1 蜂鸣器的“鬼叫”：共地问题和我当时的低级错误
第一次接好线时，蜂鸣器没有遵守代码里的节奏，而是持续发出细小的滋滋声。我第一反应是代码写坏了，反复检查buzzer.value(0)是否生效，发现 GPIO 确实被置低了，但模块仍然有微弱声音。
排查方法是从电路上找问题。有源蜂鸣器模块虽然自带驱动，但它和主控之间需要“共地”，也就是模块的 GND 必须和开发板的 GND 连在同一参考电位上。我用面包板供电时，VCC 接的是面包板电源轨、GND 也接面包板电源轨，但面包板电源轨的另一侧和开发板之间少了一根杜邦线，导致模块和 GPIO 之间的参考地不一致，逻辑电平判定失灵，模块才一直行为异常。
补上那根共地线，噪音立刻消失。如果你也遇到类似情况，优先检查三件事：GND 是否共地、VCC 电压是否充足、I/O 线是否插错到 GND 轨道上。
5.2 设备拿到的是临时 IP，路由器重启后失联了
开发板指示灯显示已联网，但主机端再也发不出通知，就是一个 IPv4 地址变化了。默认 DHCP 会在设备断连后收回地址，下次重新获取时可能分配到别的 IP，而主机端脚本里写死的是旧的。
解决办法有两个方向。最简单的是登录路由器后台，把设备的 MAC 地址和某个固定 IP 绑定，这样设备每次上网都会拿到同一地址。如果不方便改路由器，也可以在设备端代码里把 IP 设置成静态 IP——在 MicroPython 的connect_wifi()里加一段wlan.ifconfig(("192.168.1.99", "255.255.255.0", "192.168.1.1", "192.168.1.1"))。我个人更推荐静态 IP，少依赖路由器配置，换到任何网络环境只需要改前三行参数。
还有一个隐藏细节：设备开机时如果还没联网就去 listen 端口，程序会直接抛异常。我的修复方式是把connect_wifi()后的 Wi-Fi 连接循环延长到 15 秒，同时监听端口放到连接成功之后再初始化，这样即使路由器启动慢，主程序也不会崩。
5.3 重试机制反而扩大了故障窗口
主机端第一次实现时，我在requests.post外面加了三层重试，每次失败等 5 秒再试。初衷是怕网络抖动丢包，但实际效果很糟糕：设备如果断网，重试会让脚本阻塞几十秒，真正的事件通知反而被拖到很久之后，甚至完全被淹没。
后来的做法改成“失败只记录日志，不阻塞主循环”。脚本每次检查到事件后只尝试一次通知，如果失败就把这条事件写进buzz_failed.log，之后由另一个定时任务每隔 5 分钟检查一次这个失败日志并补发提醒。这样既不阻塞新的日志到来，也保证了事件不会完全丢失。对个人项目来说，比起“每条都要成功”，更合理的指标是“关键事件尽量不要错过”。
5.4 持续长鸣和“三短声”的取舍
刚开始我把提醒声音设计成持续 3 秒的长鸣，测试时自己都觉得吵得不行。长鸣的问题是：一旦你当时不在附近，声音一直在响，听着非常煎熬，但你回来后也没法从声音里分辨事件的重要性；三短声则克制得多，听到之后你明确知道“这里有情况”，去查看日志就知道了。
我最后把代码里的beep参数调整成 3 次、每次 180 毫秒，听起来像“嘀-嘀-嘀”，整段声音不到 1 秒。如果你有多个事件源，甚至可以让不同事件用不同的响法：比如错误用三次急促短鸣，完成用两次较长的声音。代码只需要在调用beep时传入不同参数即可，不需要改任何硬件。
5.5 网关、AP 和信号强度对延迟的隐性影响
还有一个很多人不会注意到的点：设备放在路由器旁边，和放在隔了两堵墙的房间，信号强度会直接影响触发延迟。设备处于弱信号时，Wi-Fi 重传会让 TCP 建连变得不稳定，蜂鸣器响起的时刻可能比事件发生晚好几秒。我后来把 buzz 挪到了离路由器直线距离更近的位置，并用ping实测延迟稳定在 5 毫秒以内，问题就消失了。
如果你的安装位置无法改变，可以考虑用带天线的开发板或加一个 Wi-Fi 中继器，这比调代码有效得多。网络通信的根子，永远是物理链路质量。
6. 从 buzz 往外扩展的玩法
现在这版 buzz 已经稳定跑了一段时间，偶尔有朋友问“还能拿它做什么”，我把验证过的几个扩展方向列出来，按投入从小到大排序。
6.1 无源蜂鸣器版：让提醒变成旋律
如果你不满足于“嘀嘀嘀”，可以在不改主机端逻辑的前提下，把有源蜂鸣器模块换成无源蜂鸣器模块，然后设备端代码改用 PWM 输出。比如训练完成时播放一小段《欢乐颂》，出错误时播放低沉的下降音。
关键点是 MicroPython 里用PWM(Pin(2), freq=988, duty_u16=32768)可以把指定频率的声音发出来。注意无源蜂鸣器需要持续输出高频方波，程序里要控制好关闭时机，否则很容易变成刺耳长鸣，比有源版难调，但可玩性确实高不少。
6.2 从手动脚本升级到与 Home Assistant 联动
buzz 的接口本质上就是一个 HTTP 地址，任何能发 HTTP 请求的系统都可以直接调用。如果你家里有 Home Assistant，可以建一个自动化规则：当某个 sensor 状态变为异常时，调用/notify；当门磁传感器检测到门打开超过 5 分钟时，同样触发提醒。
这种集成为一个小时就能搭完，而且对原有代码零侵入。一个非常实用的场景是“洗衣机洗完提醒”：智能插座检测到功率跌到待机值，就触发蜂鸣器。这样哪怕你在另一个房间刷剧，也不会晾衣服迟到。
6.3 多设备转发：局域网消息总线
如果家里有多个房间，或者工作室和卧室相距较远，单只蜂鸣器可能不够响。简单的办法是再购入两块 ESP32-C3，各自烧录同样的固件，主机端把通知请求同时发给它们的 IP 列表。每增加一个设备，只需要在主机脚本里多写一行 URL。
甚至可以升级成一个更通用的局域网消息总线：主机端用一个简单的notify.py脚本，读取一个devices.json配置文件，把所有通知事件广播到所有在线设备。这本质上就是一个微型通知网关，配合路由器静态 IP 使用，维护成本依然很低。
6.4 鉴权与安全加固：如果非要从外网访问
我强烈不建议直接把 8080 端口暴露到公网，因为设备端代码没有做任何身份验证，任何人只要能连到这个端口，都能让蜂鸣器响，干扰不算大，但被恶意刷请求终归不安全。如果有一天你必须从外网触发提醒，至少要在设备端代码里加上一个 Token 校验：
if "/notify" in request and "Authorization: Bearer your_token" in request: beep(3, 180)再配合端口转发或者反向代理，安全性才算说得过去。不过我个人的使用场景一直保持局域网部署，这也是 buzz 能长期稳定不乱报的原因之一。
写在最后
做完 buzz 之后我最大的感受是：一个好的提醒设备不在功能多，而在存在感强。很多通知系统输不是因为没做，而是因为做了太多，让人自动忽略了。物理蜂鸣器反而是最原始、最难忽略的交互方式之一。如果你想搭一个同款，我建议先用最简配置跑通“日志触发到蜂鸣器响”的最小闭环，之后再慢慢加功能，别一开始就想着把旋律、显示屏、远程控制都塞进去，那样大概率会像我第一次尝试时一样，被一堆调试问题淹没。要让它长期稳定，记住一个原则：硬件越少越好，代码越短越好，链路越直接越好。
