反射屏语音终端 DoYitNow/esp32-rlcd-dsh-agent

ESP32 RLCD DSH 智能体

面向微雪 ESP32-S3-RLCD-4.2 的桌面 AI 终端：通过 USB 数据线或 Wi-Fi 连接本机 DeepSeek Harness（DSH），使用板载麦克风采集语音、云端 ASR 转写，在 400×300 单色反射式 LCD 上显示对话与工具状态，并通过外接扬声器播报回复。

当前版本：v0.5.0

默认模型：DeepSeek-V4-Flash-Vision-Exp

思考输出：Off

功能

- USB CDC 优先连接电脑，Wi-Fi 中继作为备用链路。
- ES7210 双麦克风采集 16 kHz / 16-bit PCM，板端降混为单声道上传。
- mimo-v2.5-asr 云端中文语音识别；Windows 中文识别器作为离线兜底。
- mimo-v2.5-tts 云端语音合成，ES8311 + GPIO46 功放播放，默认音量 100%。
- 使用独立 DSH 会话，避免开发会话的工具任务污染板端对话。
- 左侧机器人与工具活动面板、右侧无角色标题的纯正文对话卡。
- UTF-8 安全换行；长回复拆成短消息并保留最多 80 条历史。
- 长 TTS 按句分段生成，逐段握手传输并等待播放完成。
- 文件读取、写入、工具调用、等待、完成、错误和确认状态面板。
- PCF85063 RTC 时间、GPIO4 电池电量、USB/Wi-Fi 状态。
- BOOT/KEY 上下翻阅消息，BOOT 长按进入深度休眠。

界面布局

┌────────────────────────────────────────┐
│ DeepSeek-V4-Flash-Vision-Exp USB ▰87%│
├────────────────────────────────────────┤
│ 机器人 │ 用户头像 + 对话正文 │ │ 工具 │ 助手回复正文（无角色标题） │ │ 活动 │ 可通过按键上下翻阅历史 │ ├────────────────────────────────────────┤ │ ● 空闲 14:32 8/12 │ └────────────────────────────────────────┘

硬件

- 微雪 ESP32-S3-RLCD-4.2
- ESP32-S3，8 MiB PSRAM
- ST7305 400×300 单色反射式 LCD
- ES7210 麦克风 ADC
- ES8311 扬声器 DAC 与 GPIO46 功放
- MX1.25 2Pin 外接扬声器
- PCF85063 RTC
- 可选 18650 电池
- USB 数据线

使用的引脚

| 功能 | GPIO |
| LCD SCK | 11 |
| LCD MOSI | 12 |
| LCD DC | 5 |
| LCD CS | 40 |
| LCD RESET | 41 |
| KEY | 18，低有效 |
| BOOT | 0，低有效 |
| 电池 ADC | 4，12 dB，3× 分压 |
| I²C SDA | 13 |
| I²C SCL | 14 |

系统结构

ESP32 麦克风 │ 16k PCM over USB CDC ▼ usb_dsh_bridge.ps1 ├─ mimo-v2.5-asr 云端转写 ├─ Windows Speech 本机兜底 └─ session.prompt → 本地 DSH │ ▼ DeepSeek V4 Flash Vision │ session events ▼ 工具状态与最终回复 ┌────┴────┐ │ │ ▼ ▼ 400×300 RLCD MiMo TTS │ 24k PCM16 ▼ ES8311 → 扬声器

软件要求

- Windows 10/11
- Arduino IDE 2.x 或 arduino-cli
- Arduino-ESP32 3.3.x
- U8g2 2.36.19 或更高版本
- ArduinoJson 6.x/7.x
- PowerShell 7
- Windows PowerShell 5.1（仅用于本机 ASR 兜底）
- Node.js 与已安装的 DeepSeek Harness
- 云端 ASR/TTS API Key

setup_dsh_session.ps1 默认将专用板端会话设为 danger-full-access。这会关闭 DSH 文件沙箱和审批提示，只应在你信任的本机与项目中使用；可通过 -PermissionPreset workspace-write 改回工作区写入。

安全配置

仓库不会提交 Wi-Fi 密码、API Key 或个人电脑地址。

1. 固件配置

复制示例文件：

Copy-Item .\secrets.example.h .\secrets.h

编辑 secrets.h：

static const char WIFI_SSID = "your-wifi";
static const char WIFI_PASS = "your-password";
static const char PC_HOST = "192.168.1.100";
static const char TOKEN = "a-long-random-board-token";

secrets.h 已被 .gitignore 排除。

2. 电脑端环境变量

令牌必须与 secrets.h 中的 TOKEN 相同：

[Environment]::SetEnvironmentVariable(
'ESP32_BOARD_TOKEN',
'a-long-random-board-token',
'User'
)
[Environment]::SetEnvironmentVariable(
'ESP32_ASR_API_KEY',
'your-cloud-asr-key',
'User'
)

[Environment]::SetEnvironmentVariable(
'ESP32_TTS_API_KEY',
'your-cloud-tts-key',
'User'
)

如果 ASR 与 TTS 使用同一个 MiMo Key，可以不设置 ESP32_TTS_API_KEY，桥接脚本会复用 ESP32_ASR_API_KEY。设置后重新打开 PowerShell。不要把 Key 写进脚本、README、Issue、日志或固件源码。

编译与刷写

Arduino IDE 设置：

| 选项 | 值 |
| Board | ESP32S3 Dev Module |
| USB CDC On Boot | Enabled |
| USB Mode | Hardware CDC and JTAG |
| CPU Frequency | 240 MHz |
| Flash Mode | QIO |
| Flash Size | 16 MB |
| Partition Scheme | 16M Flash (3MB APP / 9.9MB FATFS) |
| PSRAM | OPI PSRAM |
| Upload Speed | 921600 |

用 Arduino IDE 打开 esp32_voice_agent.ino，确认已经创建 secrets.h，然后选择板子的 COM 端口并上传。

命令行示例：

arduino-cli compile
--fqbn "esp32:esp32:esp32s3:CDCOnBoot=cdc,USBMode=hwcdc,UploadMode=cdc,CPUFreq=240,FlashMode=qio,FlashSize=16M,PartitionScheme=app3M_fat9M_16MB,PSRAM=opi"
.

arduino-cli upload -p COM7
--fqbn "esp32:esp32:esp32s3:CDCOnBoot=cdc,USBMode=hwcdc,UploadMode=cdc,CPUFreq=240,FlashMode=qio,FlashSize=16M,PartitionScheme=app3M_fat9M_16MB,PSRAM=opi"
.

启动 DSH 与 USB 桥

1. 启动本地 DSH

.\start_local_dsh.ps1

脚本会自动从当前用户的 .dsh 目录寻找 DSH。若 Node.js 不在 PATH，可以传入：

.\start_local_dsh.ps1 -NodePath "C:\path\to\node.exe"

2. 初始化板子专用会话

.\setup_dsh_session.ps1

该脚本不会向模型发送消息，只会：

- 创建或复用 esp32-board-voice 会话；
- 选择 deepseek-v4-flash-vision-exp；
- 将 reasoning effort 设置为 off。

3. 启动 USB 桥

.\usb_dsh_bridge.ps1 -ComPort COM7

成功时会看到：

usb bridge: connected COM7 -> http://127.0.0.1:3080
usb bridge: subscribed DSH session events

按键

| 操作 | 功能 |
| 按住 KEY 超过 450 ms | 录音；松开后上传识别 |
| 短按 KEY | 向下翻阅消息 |
| 短按 BOOT | 向上翻阅消息 |
| 长按 BOOT 1.8 秒 | 深度休眠“关机” |
| 休眠时按 BOOT | 唤醒 |

这里的关机是 ESP32 深度休眠，不是物理切断电池。

消息与状态协议

电脑向板子发送长度前缀帧：

@DSH <UTF-8 JSON 字节数>\n <JSON payload>\n

常用消息：

{"type":"text","role":"assistant","text":"你好"} {"type":"status","text":"云端识别中"}
{"type":"event","kind":"read","text":"正在读取文件：README.md"} {"type":"telemetry","time":"14:32","model":"V4 Vision"}

板子发送音频：

@AUDIO <bytes> <sample-rate> <channels> <bits>\n
<raw PCM bytes>\n

PCM 使用 1 KiB 分块写入 USB CDC，避免大块传输丢失尾部字节。

电脑向板子发送 TTS 音频：

@TTS <bytes> <sample-rate> <channels> <bits>\n
<raw PCM bytes>

板子使用 PSRAM 接收完整 PCM，再将单声道复制为双声道并交给 ES8311 播放。单段音频上限为 2 MiB。

常见问题

一直显示“处理中”

- 检查 DSH 会话是否被旧工具调用或批准请求占用。
- 重新运行 setup_dsh_session.ps1，确保桥接使用独立会话。
- 查看 USB 桥输出中是否存在 DSH prompt failed。

云端识别不准确或回退到本机识别

- 检查 ESP32_ASR_API_KEY 是否存在。
- 查看是否出现 cloud ASR failed。
- 靠近板载麦克风，按下 KEY 后稍等片刻再说话。
- 避免同时遮挡两个麦克风或在强风噪环境使用。

COM7 找不到或被占用

- 关闭 Arduino Serial Monitor 和重复运行的桥接脚本。
- 重新插拔 USB 数据线。
- 在设备管理器中确认新的 COM 端口，并通过 -ComPort 指定。

回复显示正常但扬声器没有声音

- 扬声器必须接到 MX1.25 2Pin 扬声器接口，不能只连接 USB。
- 查看桥接输出是否出现 TTS sent ... bytes；若出现 TTS failed，先检查 Key、账户和网络。
- 串口应看到 audio codec ready、playback complete；若 play 为空，检查 ES8311/I²C 初始化。
- 当前默认音量为 90%，可修改固件中的 SPEAKER_VOLUME（0–100）。
- MiMo TTS 必须使用 /v1/chat/completions；项目已按官方 assistant + audio.pcm16 协议实现。

Wi-Fi 备用链路不可用

- 确认 PC_HOST 是电脑的局域网 IPv4 地址。
- 确认防火墙允许 TCP 8180。
- 确认板子和电脑在同一局域网。

项目结构

esp32_voice_agent.ino 固件入口、UI、网络、按键和 PCM 收发 ST7305_U8g2.* ST7305 U8g2 显示适配 audio_codec.* ES7210、ES8311、功放与板载 RTC 接口 usb_dsh_bridge.ps1 USB、云端 ASR/TTS 与 DSH 事件桥 windows_asr.ps1 Windows 中文识别兜底 start_local_dsh.ps1 启动本地 DSH setup_dsh_session.ps1 创建专用会话并设置模型 pc_relay.js Wi-Fi HTTP 中继 secrets.example.h 固件配置模板 src/ExternLib/ Espressif 音频组件 CHANGELOG.md 版本记录 THIRD_PARTY_NOTICES.md 第三方许可证说明

隐私与安全

- 录音默认发送到配置的云端 ASR 服务；云端失败时才使用 Windows 本机识别。
- 助手回复文本会发送到配置的云端 TTS 服务生成语音。
- DSH 在本机 127.0.0.1:3080 运行。
- USB 优先模式不要求板子通过 Wi-Fi 访问 DSH。
- 发布日志前检查其中是否包含语音转写、文件路径或会话内容。
- 提交前建议运行：

rg -n -i "api[_-]?key|password|authorization|bearer|sk-[a-z0-9]" .
git status --short

第三方组件

本项目保留第三方组件的原始许可证文件。详情见 THIRD_PARTY_NOTICES.md。特别注意：codec_board 使用 Espressif Modified MIT License，只允许与 Espressif 产品结合使用。

版本记录

参见 CHANGELOG.md。