一、项目概述
本项目实现一套 "说完即记" 的语音笔记系统:按下 ESP32 上的按键对着麦克风说话,松开后音频经局域网传到 PC 网关,由网关调用豆包(火山引擎)流式大模型 ASR 2.0 完成识别,自动追加写入 Markdown 笔记文件;识别状态(录音中 / 识别中 / 已保存 / 出错)实时回传 ESP32,由屏幕与状态灯同步呈现。
技术目标是把 ESP32 变成 "哑终端":它只负责采集、显示、传输,所有算力与密钥集中在 PC,从而在低成本 MCU 上获得大模型级语音能力,同时避免密钥烧进固件带来的泄露风险。

1、总体框架
系统采用 三层分离架构:

职责边界:
- ESP32:I2S 采集、PCM 组包、TCP 客户端、屏幕与灯光渲染
- PC 网关:TCP 服务端、音频缓存、WAV 封装、ASR 调用、Markdown 写入、状态 / 文本下发
- 云端 ASR:语音识别与大模型纠错
选择 PC 而非 ESP 直连云端的理由有三:ESP32 跑 TLS+WebSocket 内存压力大且证书维护困难;API Key 只存在于 PC,不落固件;断线重连、日志排查、参数调优都集中在 PC 侧,迭代成本低。
2、需求列表
|
需求 |
实现要点 |
|
按键启停录音 |
IO40 按下开始采集并上传,松开停止;带防抖 |
|
16K/16bit / 单声道 PCM 采集 |
INMP441 + I2S0,200ms 一包,与 ASR 采样率严格对齐 |
|
音频分包上传 |
自定义 TCP 帧协议,局域网直连 PC 网关 |
|
语音转文字 |
网关调用豆包 ASR 2.0(bigmodel_async) |
|
笔记自动落盘 |
按日期分文件,追加写入 Markdown,绝不覆盖历史 |
|
状态回传显示 |
recording /processing/saved /error 四态 |
|
识别文本回显 |
网关下发文本帧,ESP 屏幕显示识别结果 |
|
ST7789 状态 UI |
320×170 横屏四栏布局:状态栏 / 信息栏 / 主区 / 底栏 |
|
WS2812 状态灯 |
待机绿、录音红呼吸、识别黄闪、断连红快闪,亮度 30% |
|
断连自恢复 |
WiFi 状态机 + TCP 自动重连,不阻塞 UI |
非功能需求:录音全程屏幕不闪烁;单轮录音仅三次屏幕刷新;PC 网关热插拔 ESP 后可继续服务。
3、 程序数据流
- ESP32 上电 → 连 WiFi → 连接 PC 的 TCP 网关,上报就绪
- ESP32 启动 I2S 采集 16K 16bit PCM,按 200ms 分包,持续发给 PC
- PC 网关收到音频流,送入火山 ASR WebSocket 会话
- ASR 返回增量中间识别结果 → PC 网关返回状态
- ASR 检测到语音结束
- PC 拿到本轮稳定最终文本
- ASR 会话关闭,网关重置音频 buffer,等待下一轮语音
二、软硬件架构
1、 硬件清单与引脚
|
模块 |
型号 |
引脚 |
|
主控 |
ESP32-S3 |
— |
|
数字麦克风 |
INMP441 |
SCK=5, SD=6, WS=4(I2S0) |
|
音频功放 |
MAX98357A |
DIN=7, BCLK=15, LRCLK=16(I2S1,预留静音) |
|
LCD |
ST7789 170×320 |
CS=13, DC=11, SDA=10, SCL=12, RST=14, BL=3 |
|
按键 |
轻触 |
IO40(录音启停)、IO39(备用) |
|
状态灯 |
WS2812 ×1 |
IO48 |
2、 软件栈
- ESP32 端:Arduino 框架 +
AudioTools(I2SStream 封装 I2S 驱动)+Adafruit_ST7789+Adafruit_NeoPixel+ArduinoJson - PC 网关:Python 3 +
asyncio(TCP 服务)+websockets(ASR 链路)+wave/tempfile(音频封装)+ 火山官方protocol.py(私有二进制协议封装) - ASR 服务:豆包流式语音识别 2.0,
X-Api-Key新控制台鉴权,X-Api-Resource-Id = volc.seedasr.sauc.duration
3、 通信协议
ESP32 与 PC 网关之间自定义简易二进制 TCP 帧协议,用于解决 TCP 粘包,区分不同类型消息。
帧结构: 0xAA(帧头) | CMD(命令号) | LenH(长度高8bit) | LenL(长度低8bit) | Payload
字段解释
- 0xAA(1 字节,帧头) 固定魔数,用来标记一帧的开始;接收端在缓冲区里扫描
0xAA找到帧起始位置,用来拆包、处理 TCP 粘包。 - CMD(1 字节,命令) 消息类型编号,区分数据包含义:
- 0x01:ESP→PC,PCM 音频分包
- 0x02:ESP→PC,开始录音
- 0x03:ESP→PC,停止录音
- 0x04:PC→ESP,下发状态 JSON
- 0x05:PC→ESP,下发识别文本
LenH + LenL(共 2 字节,大端) Payload 的字节长度:payload_len = LenH * 256 + LenL
最大支持 65535 字节负载,足够承载音频分片和文本。
Payload(N 字节,可变长) 真正业务数据:音频 PCM 原始流 / JSON 字符串 / UTF8 文本。
|
CMD |
方向 |
含义 |
|
0x01 |
ESP→PC |
音频 PCM 分包(6400 字节 = 200ms) |
|
0x02 |
ESP→PC |
开始录音 |
|
0x03 |
ESP→PC |
结束录音 |
|
0x04 |
PC→ESP |
状态 JSON |
|
0x05 |
PC→ESP |
识别文本(UTF-8) |
三、重点功能设计说明
1、 音频采集与分包
采用 AudioTools 的 I2SStream i2s_in(I2S_NUM_0),配置 RX_MODE、16K/16bit / 单声道,与 ASR 的 audio 参数完全对齐(采样率不一致会导致识别乱码,这是本项目最容易踩的坑)。采集端持续读 16bit 样本,攒够 SEG_BYTES = 16000 × 0.2 × 2 = 6400 字节立即发一帧,与网关 --seg-duration 200 严格匹配。
2、 按键状态机
采用 "按下沿 / 松开沿 + 20ms 防抖" 的边沿检测,而非电平轮询。按下即本地切入 ST_RECORDING 并发送 CMD_START,松开发送 CMD_STOP 并切入 ST_PROCESSING。关键设计:本地状态先行、网关状态可覆盖—— 即使网络未就绪也能进入录音态(只是不发包),保证按键手感与 UI 反馈不被网络拖累。
3、屏幕 UI 与防闪刷新策略
ST7789 以 SPI.begin(SCK,-1,MOSI,CS) + tft.init(170,320) + setRotation(3) 初始化为 320×170 横屏,四栏布局:顶部在线状态与设备 IP、信息栏语音引擎与服务端地址、中部麦克风图标 + 录音秒数 + 识别文本、底部模式栏。
刷新策略是屏幕稳定性的核心:
- 状态变化才全屏重绘(
state != lastDrawState才调drawAll()) - 录音期间只局部刷新主区(每 500ms 调一次
drawMainArea(),只填 y48~143 一小块) - 绝不在
loop()里无条件全屏重绘
这一策略同时解决了两个对立问题:早期版本每 33ms 全屏刷导致肉眼可见闪烁,而改成 "纯状态驱动" 后秒数又冻在 0。
4、 帧解析的粘包处理
接收端不假设 "一次 read 正好一帧",而是维护 512 字节滑动缓冲:先扫描帧头 0xAA,把它 memmove 到缓冲区首位;凑齐 4 字节头后解析 payloadLen,等 4 + payloadLen 收全再处理;处理完将该帧从缓冲区移除。这一步解决了早期版本反复解析旧包、状态乱跳的问题。
5、 PC 网关与 ASR 调度
asyncio.start_server 监听 8888,每连接协程内循环 read_frame:CMD_START 清空缓冲并回 recording;CMD_AUDIO 累积 PCM;CMD_STOP 后统计时长 / 峰值 / RMS 音量,PCM 加 WAV 头写入临时文件,交给 protocol.AsrWsClient 走 bigmodel_async,取最后一条非空 payload_msg.result.text 作为定稿,写 MD 后回 saved + 文本帧,异常回 error。
ASR 请求参数(与实测跑通的配置一致,缺一不可):
"request": {
"model_name": "bigmodel",
"enable_itn": True, "enable_punc": True, "enable_ddc": True,
"show_utterances": True,
"enable_nonstream": True # 二遍识别增强,2.0 资源下缺失会直接 403
}
6、 日志与可观测性
网关将 protocol.logger 压到 WARNING,屏蔽 Sent audio segment with seq:N 刷屏,只保留精简输出:每轮录音打印字节数、时长、峰值百分比、RMS dBFS,再打印识别文本与落盘路径。音量指标直接服务于硬件调试 ——peak 接近 100% 说明削顶,RMS 低于 -35 dBFS 说明麦克风增益不足或距离过远。
六、项目部署与测试
1、 PC 端部署
pip install websockets aiohttp
# 目录结构:asr_gateway.py + protocol.py(官方协议封装,必须同目录)
python asr_gateway.py --api_key "你的X-Api-Key"
默认即 bigmodel_async + volc.seedasr.sauc.duration。启动后网关独占 8888 端口,防火墙需放行。
2、 ESP32 端部署
库管理器安装 AudioTools、Adafruit ST7789、Adafruit NeoPixel、ArduinoJson;
修改 WiFi 名称密码与 GATEWAY_IP;
烧录后串口 115200 观察连接日志。
3、 系统测试
启动服务端,设备端传入音频语音后,调用云端 ASR,返回对应文本。

设备端接入服务端后会显示状态信息,录音与转文本会显示状态提示。

4、开发经历总结
(1). 接口调试的教训是 "参数组合即契约"。 火山 ASR 的 url、resource_id、enable_nonstream 三者是绑定的组合关系,任一项不匹配都会以 403 或空识别表现,但错误信息高度失真。最终确定的排查方法论是:先用最小可运行的单文件脚本跑通,再把成功日志的完整 payload 逐字段照搬进业务代码,绝不 "凭理解改写"。
(2). 流式与非流式不是性能差异,而是协议差异。 bigmodel_async 允许一次性快速喂完整段音频(所以本地测文件体验很好),而 bigmodel_nostream 严格要求单包全量提交。混淆两者会得到 "能连上、能发完、但识别为空" 的迷惑现象。项目最终选择 async + enable_nonstream,既保留了验证过的发包逻辑,又拿到了二遍识别的准确率。
(3). MCU 侧的稳定性问题几乎都源于 "刷太快"。 屏幕闪烁、状态乱跳、WiFi 报错刷屏,三个看似无关的现象,根子都是同一类错误:在 loop() 里无条件、无状态判断地重复执行有副作用的操作。改成 "事件驱动 + 状态缓存 + 局部刷新" 后全部消失。这条经验对任何带屏 MCU 项目通用。
(4). 职责分层是低成本设备获得大模型能力的正确路径。 把 TLS、鉴权、重试、日志全部上移到 PC,ESP32 退化为采集器与显示器,代码量、内存占用、故障面同时下降。代价是依赖局域网,但对 "坐在电脑旁做语音笔记" 这一场景完全可接受。
(5). 可观测性直接决定调试效率。 网关打印的 duration /peak/ RMS 三项数据,让 "识别不准" 这类模糊问题迅速收敛到 "音量不足、削顶、采样率错误" 等可量化根因,比反复听录音猜问题快得多。
转载自 CSDN-专业IT技术社区
原文链接:https://blog.csdn.net/Tony_Shen/article/details/171111904




