【武汉职业技术大学“一院一赛”第一周培训笔记--刘键宽】EC600M AI 语音交互终端:按键唤醒 + 云端 ASR/LLM/TTS + 裸 LCD 轮显

硬件:EC600M-CNLE(EC600X-EVB 底板),ST7789 240×240 屏,板载麦克风、NS4160 功放 + 小喇叭、AHT20 温湿度 运行环境:QuecPython,QPYcom V4.1.0 下载到 /usr 目录运行 功能效果:KEY1 按键唤醒后录音上传云端,经 ASR → LLM → TTS 处理,设备端接收云端下发的语音音频流播放;待机屏幕轮显主页面(时间/温湿度)、运行统计页(延迟/内存/Flash/信号)和像素表情页;15 秒无操作自动回到待机。 本帖为本周 QuecPython 实训系列记录的第一篇:知识总结 + 踩坑解决过程。

一、项目核心能力

综合练习 4G 蜂窝联网、音频录放、三态状态机、裸 LCD 界面绘制、板载传感器读取。端云分工:设备端只负责采集、播放、显示和状态管理;语音识别、对话理解、语音合成全部放在云端完成,设备端不做本地 TTS。

二、工程结构

代码按模块拆分,方便后续接传感器和调整界面:

文件 职责
main.py / voice_main.py 主程序入口,启动状态机和主循环
config.py 引脚、网络接口、TTS/ASR 参数、界面配色与轮显时长等常量
driver.py 屏幕绘制、卡片、文字、精灵位图加载等显示驱动
voice_driver.py 三态状态机、录音/播放调度、云端任务线程、统计数据
asr.py 百度语音识别(ASR)取 token 与上传录音
tts.py 百度 TTS 文本分段、请求合成、音频格式探测与落盘
aht20.py AHT20 温湿度 I2C 读取
mic_driver.py 麦克风录音控制与录音回放测试
runtime_stats.py 各环节耗时、内存/Flash、失败/恢复/异常次数统计

QPYcom V4.1.0 通过 Quectel USB REPL Port(波特率 115200)连接,工程文件下载到板子 /usr/ 目录后运行:

三、硬件与引脚

模块 接口 引脚 / 说明
温湿度 AHT20 I2C SCL=56,SDA=57
光敏 GT36528 ADC 引脚 19(预留,暂不接入对话)
麦克风 — 引脚 23、24
功放 NS4160 — 引脚 21、22,喇叭接 SPK+ / SPK-
显示屏 ST7789 SPI 引脚 63~67,240×240
按键 GPIO KEY1=唤醒/录音,KEY2=翻页

四、关键实现

  1. 三态状态机

整个交互由三个状态驱动,业务逻辑不散落在主循环里:

  • STANDBY:待机,屏幕轮显,等待唤醒;

  • LISTENING:聆听中,录音上传;

  • REPLYING:播报中,播放云端返回的语音音频流。

每次交互结束后重置 15 秒无操作计时器;超时自动回到 STANDBY,回到待机时默认落在主页面。

  1. 云端语音链路

  • 语音处理全部在云端:ASR 语音识别 → LLM 对话理解(DeepSeek)→ TTS 语音合成(百度);

  • 设备端不做本地 TTS 合成,只接收云端下发的音频流,用 playStream 流式播放;

  • 本地语音唤醒词检测在模组上不可靠,本项目改用 KEY1 按键唤醒,不做唤醒词识别。

串口上能看到完整链路日志:

Recognized: 介绍一下你。

DeepSeek: 我是……(大模型回复文本)

Reply audio ready.

Reply audio segment 1/6 completed.

Reply audio segment 2/6 completed.

...

STATS wake_record=1286ms upload_text=4136ms text_audio=3714ms turn=13011ms free_mem=794720B free_flash=106496B

串口实测分段播报与统计日志:

  1. 屏幕界面(裸 LCD,非 LVGL)

  • 240×240 裸屏直接用 LCD 原生接口画点、画字、画矩形,不引入 LVGL;

  • 待机轮显三个页面:

    • 主页面:时间、日期、温度、湿度;
    • 统计页:录音/上传/播报/整轮耗时、运行时长、重连/恢复/异常次数,以及内存、Flash 进度条和信号格;
    • 表情页:三张像素精灵(绿心团子、方块小猫、黄瞳白猫)按顺序轮换,每轮只显示一个,索引跨轮保留;
  • 整页批量渲染:先取完本页全部数据,再一次性绘制,避免逐行出现;数据周期整页刷新。

  1. 信号强度显示

  • 通过 net.csqQueryPoll() 获取 CSQ 值(0~31,-1 失败、99 异常);

  • 映射成 1~4 格信号条:无信号/异常 1 格灰色,0~9 一格,10~15 两格,16~21 三格,22~31 满格;

  • 实拍待机页可见 ONLINE、CSQ 27、IDLE、温湿度 34.0℃ / 47%。

  1. 内存 / Flash 进度条口径

项目 数据来源 总量计算
内存 gc.mem_alloc() / gc.mem_free() 堆总量 = 已用 + 余量
Flash(usr/bak) uos.statvfs(path) 总量 = f_bsize × f_blocks;余量 = f_bsize × f_bavail;占用 =(总量 − 余量)/ 总量

状态栏显示口径为「余量 / 总量」,例如 usr: 96/576 KB 表示余量 96KB、总量 576KB。比例限制在 0~100%,占用超过 85% 进度条变红提醒;总量读取失败时只画空轨道,不估算比例。

五、完整运行流程

  • 待机:屏幕在主页面、统计页、表情页之间轮显,监听 KEY1 唤醒和 KEY2 翻页;

  • 唤醒:按下 KEY1 进入 LISTENING,屏幕显示“聆听中…”,开始录音;

  • 上传与云端处理:音频上传云端,依次完成 ASR、LLM、TTS;

  1. 播报:进入 REPLYING,接收云端语音音频流并通过功放喇叭播放,屏幕显示“播报中…”;

  2. 回到待机:播报结束或 15 秒无操作,释放音频通道,复位状态与计时器,回到主页面待机。

六、调试过程与踩坑记录

  1. 编辑器直接“运行”找不到模块

  • 现象:写完代码在编辑器里直接运行,报找不到模块。

  • 原因:这是给 EC600M 开发板写的 QuecPython 程序,不能在电脑上直接跑。

  • 解决:用 QPYcom 连接模组串口(Quectel USB REPL Port,波特率 115200),把文件下载到板子 /usr/ 目录后再 example.exec('/usr/voice_main.py') 运行。

  1. PowerShell 禁止运行 .ps1 调试脚本
  • 现象:PC 端先用 chat_console.ps1 -Port COM11 联调云端对话,报错 PSSecurityException / UnauthorizedAccess,提示系统禁止运行脚本。

  • 解决:仅对当前进程放开执行策略:

Set-ExecutionPolicy -Scope Process Bypass -Force

再运行脚本连接 QPYcom 已打开的串口,先在 PC 端把 DeepSeek 对话链路调通,再移植到模组:

  1. 云端鉴权返回 HTTP 401

两类 401 都遇到过。

DeepSeek LLM 鉴权:请求对话时报 authentication_error,提示 api key 无效:

DeepSeek request failed: DeepSeek HTTP 401: {'error': {'code': 'invalid_request_error',

'type': 'authentication_error', 'message': 'Authentication Fails, Your api key: ****74f1 is invalid'}}

百度 ASR token:录音上传前获取 token 失败:

Baidu ASR token HTTP 401: {'error_description': 'Client authentication failed', 'error': 'invalid_client'}
  • 原因:API Key / Secret Key 填写错误,或 access_token 申请字段、鉴权方式不对。

  • 解决:分别核对 LLM 与 ASR 控制台的 Key、Secret Key,检查请求地址、鉴权头和返回字段,确认鉴权通过后再上传录音。

  1. TTS 文本超过 100 字限制

  • 现象:回复较长时报错 TTS text exceeds the configured 100-character limit。

  • 解决:在 tts.py 里按标点把回复切成分段文本(句号、问号、感叹号、逗号等边界优先),逐段送 TTS;单段文本不超过服务端字数上限。

  1. TTS 音频类型识别失败 + bytearray 报错

  • 现象一:Content-Type: audio/mp3 未被识别,日志提示 unknown,最后靠文件头探测到格式 3(MP3)。

  • 现象二:Reply audio failed: 'bytearray' object has no attribute 'startswith'。

  • 原因:response.content 是 bytearray,不能直接调字符串的 startswith;Content-Type 也可能和实际编码不一致。

  • 解决:判断类型前先转成 bytes;除了看 Content-Type,再用文件头(ID3 / 0xFFE0 等)探测音频格式,映射到 playStream 的 format 参数(2=WAVPCM,3=MP3,4=AMRNB)。

  1. TTS 音频超出大小限制

  • 现象:Reply audio failed: Baidu TTS audio exceeds size limit。

  • 原因:单段音频字节数超过本地 Flash 可写上限。

  • 解决:控制单段文本长度和音频字节上限;分段合成、分段播放;段音频优先走内存缓冲,不往 Flash 临时目录写大文件。

  1. 中文字库解析报错

  • 现象:读取 cjk16.bin 字库时出现 NameError: name 'n' is not defined、ValueError: arg out of range(256) 一类错误。

  • 原因:字库魔数、尺寸偏移和点阵数据读取位置算错,字节取值超出 0~256 范围。

  • 解决:按字库格式重新核对文件头魔数、宽高偏移和点阵索引公式,逐段 seek/read 校验字节范围后再上屏取模。

  1. 渐变背景触发 bytearray 赋值错误

TypeError: 'bytearray' object doesn't support item assignment
      **原因**:裸 LCD 帧缓冲是 bytearray,渐变逐像素改写方式不被支持;且 RGB565 颜色分层有限,渐变本身也容易出色带、色块。
  • 解决:放弃渐变,背景统一用纯色;温度/湿度卡片底色与背景太淡看不清时,提亮卡片底色并加 1px 描边拉开层次。
  1. 文件系统路径 ENODEV

  • 现象:uos.listdir("/usr/") 报 OSError: [Errno 19] ENODEV,而空路径 uos.listdir("") 能看到 usr、bak 目录。

  • 解决:核对 QuecPython 文件系统路径写法,目录枚举和文件读写按模组支持的路径格式调整,避免硬编码带尾斜杠的绝对路径。

  1. 多会话同时改同一配置文件冲突

  • 现象:VSCode 提示 Could not keep the changes to config.py: another chat in this session also changed it。

  • 解决:AI 辅助生成时避免多个对话同时改 config.py;改动前先合并现有配置,再统一落盘,防止引脚、参数被覆盖。

  1. 音频通道单路复用

EC600M 只有一路音频通道,录音和播放不能同时占用;切换录音/播放前必须先释放上一路通道,否则会出现无声或通道占用异常。

  1. 回调里不要做重活

按键、音频等回调只做事件标记和通道切换;耗时的网络请求、音频合成、界面刷新放到主流程或后台线程/定时器回调里处理,避免阻塞中断和播放线程。

七、本周学习感悟

  • 事件驱动的分工:课堂 GPIO 实验里中断只负责捕获按键边沿,消抖和业务交给软件/硬件定时器;语音项目里回调也只做事件标记和通道切换,耗时的网络请求、音频合成、界面刷新放到主流程或后台线程。这是嵌入式开发最基本的思路。

  • 模块化拆分的好处:把引脚配置、云端参数、显示驱动、录音播放调度、传感器读取分开成 config、driver、voice_driver、asr、tts、aht20 等模块后,改界面或调参数不容易把业务代码搅在一起,也方便定位问题。

  • 串口日志是调试主线:这次每个环节都在串口打日志——识别文本、大模型回复、音频分段完成、各环节耗时、剩余内存/Flash、失败次数。出问题先看日志停在哪一步,比反复猜硬件或网络更有效。

  1. AI 辅助要对照真机核对:VSCode AI 插件能快速生成代码框架,但引脚号、文件路径、QuecPython 接口、bytearray/bytes 类型这些细节必须对照官方文档和实机日志核对,不能直接照搬。

  2. 端云分工的体会:EC600M 模组资源有限,本地只做录音、播放、显示和状态管理,ASR、对话理解、语音合成放云端;本地唤醒词检测和本地 TTS 受模组能力限制,本项目改用按键唤醒,也是结合硬件能力做的取舍。

  3. 不足与后续:分段播报段间停顿、模型人设、传感器语音联动还没做完,计划在后续系列帖里继续记录优化过程。

八、待优化与拓展

  • 传感器语音联动(预留):后续可让对话中读取本地温湿度、光敏数据回答,本次实训暂未接入;光敏引脚仅预留。

  • 摄像头识图:扩展外接摄像头拍照,走云端识图/大模型理解。

  • 音色与唤醒优化:TTS 音色由云端侧切换;本地唤醒词受模组能力限制,如需远场唤醒需评估外接语音芯片方案。