193 lines
6.0 KiB
Markdown
193 lines
6.0 KiB
Markdown
# TQ Printer Firmware (ESP32-S3)
|
||
|
||
本仓库是 TalkingQ 热敏打印设备固件，当前已经完成四层分层重构，并切换为
|
||
"按键驱动 + 云端语音/文生图 + 本地打印" 的运行模式。
|
||
|
||
当前状态（2026-03）:
|
||
- 提供打印、语音、配网、屏幕预览能力
|
||
- 仅保留 Wi-Fi 配网 SoftAP HTTP 服务（`http://192.168.4.1`）
|
||
|
||
> [!WARNING]
|
||
> 本仓库当前配置默认开启 **Flash Encryption** 与 **Secure Boot**（安全启动）。
|
||
> 这类安全特性通常涉及 eFuse 烧写与不可逆行为，配置不当可能导致设备无法按预期启动、升级或调试。
|
||
> 在烧录、量产或对外发布前，请务必根据你的产品安全策略与运维流程，先在 `menuconfig` / `sdkconfig` 中完成适配与复核，再执行构建和烧录。
|
||
|
||
## 当前能力
|
||
|
||
- 热敏打印驱动（固定 384 像素宽）
|
||
- 打印任务队列与后台 worker（队列/运行/完成/失败/取消状态）
|
||
- 打印前安全检查（缺纸、电量、温度）
|
||
- MIC 按键按住说话/松开停止（push-to-talk）
|
||
- DashScope WebSocket 语音对话（`wss://dashscope.aliyuncs.com/api-ws/v1/inference`）
|
||
- DashScope Z-Image 文生图（HTTP）
|
||
- ST7789 屏幕预览（启动 logo、文本/图片预览）
|
||
- Wi-Fi STA 优先，失败后自动回退 SoftAP 配网
|
||
- POWER_KEY 长按 2 秒触发优雅停机并释放 `POWER_HOLD`
|
||
|
||
## 架构分层
|
||
|
||
依赖方向严格为:
|
||
|
||
`app_composition -> control_plane -> domain -> platform`
|
||
|
||
对应公开 facade 头文件:
|
||
- `components/app_composition/include/app_composition.h`
|
||
- `components/control_plane/include/control_plane.h`
|
||
- `components/domain/include/domain.h`
|
||
- `components/platform/include/platform.h`
|
||
|
||
入口与职责:
|
||
- `app_composition`: 仅做启动装配（`app_main`）
|
||
- `control_plane`: 生命周期/策略编排
|
||
- `domain`: 打印协议、语音会话、图像生成、屏幕预览等业务域能力
|
||
- `platform`: Wi-Fi、按键、显示屏、热敏打印硬件、音频设备等底层抽象
|
||
|
||
更多分层说明:
|
||
- `components/platform/README.md`
|
||
- `components/domain/README.md`
|
||
- `components/control_plane/README.md`
|
||
- `components/app_composition/README.md`
|
||
|
||
## 目录概览
|
||
|
||
- `components/`: 分层组件主目录
|
||
- `main/Kconfig.projbuild`: 工程级 `menuconfig` 配置项
|
||
- `partitions.csv`: 当前分区表（16MB flash，双 OTA 分区）
|
||
- `docs/gpio-map.md`: 当前实现与 `sdkconfig` 对齐后的 GPIO 映射
|
||
- `tools/esptool-factory/`: 产线打包与加密烧录工具
|
||
|
||
## 构建环境
|
||
|
||
本项目按当前实际使用 ESP-IDF `v5.5.3`。
|
||
|
||
先激活环境:
|
||
|
||
```bash
|
||
export PATH=/opt/homebrew/bin:$PATH
|
||
export IDF_PATH=/Users/moyyang/.espressif/v5.5.3/esp-idf
|
||
source $IDF_PATH/export.sh
|
||
```
|
||
|
||
首次仅需执行一次目标设置:
|
||
|
||
```bash
|
||
idf.py set-target esp32s3
|
||
```
|
||
|
||
构建:
|
||
|
||
```bash
|
||
idf.py build
|
||
```
|
||
|
||
烧录并查看串口日志:
|
||
|
||
```bash
|
||
idf.py -p <PORT> flash monitor
|
||
```
|
||
|
||
清理后全量重编:
|
||
|
||
```bash
|
||
idf.py fullclean && idf.py build
|
||
```
|
||
|
||
## 运行流程
|
||
|
||
1. `app_main` 调用 `control_plane_lifecycle_start()`
|
||
2. 生命周期按顺序启动:
|
||
- `system_runtime_start()`（底层初始化 + Wi-Fi）
|
||
- 电源键事件绑定
|
||
- `printer_protocol_init()`
|
||
- `voice_interaction_init()`
|
||
- `image_generation_schedule_prewarm()`
|
||
3. 若 `POWER_KEY` 长按触发关机事件:
|
||
- 先执行生命周期 stop（语音 -> 打印协议 -> 系统运行时）
|
||
- 最后 `platform_power_hold_set(false)` 断保持电
|
||
|
||
## Wi-Fi 配网行为
|
||
|
||
- 启动时优先加载 NVS 中保存的 STA 凭据（命名空间 `wifi_cfg`）
|
||
- 若无凭据或连接失败，启动 SoftAP + 本地 HTTP 配网页
|
||
- 配网入口:
|
||
- 页面: `GET /`（`http://192.168.4.1`）
|
||
- 扫描: `GET /scan`
|
||
- 提交: `POST /provision`
|
||
- 凭据仅在 STA 连接成功后写入 NVS
|
||
|
||
## 语音与打印行为
|
||
|
||
- MIC_KEY:
|
||
- 按下（长按开始阈值）: 尝试启动语音会话并进入说话流程
|
||
- 松开: 发送停止说话信号
|
||
- 语音链路:
|
||
- WebSocket 建链后发送 `Start`
|
||
- 对话中按状态发送 `RequestToSpeak` / `SendSpeech` / `StopSpeech`
|
||
- 后台有心跳任务维持会话
|
||
- 当回复首句包含 `/*提示词*/` 标记时，会触发一次文生图并自动提交打印任务
|
||
- 打印链路:
|
||
- 所有任务进入队列，由单 worker 顺序执行
|
||
- 默认打印前会做纸张/电量/温度校验
|
||
- 图像与文本最终都会转为 384 宽 1bpp raster
|
||
|
||
## 关键配置（`menuconfig -> TQ Printer Config`）
|
||
|
||
- Wi-Fi/配网: `TQ_WIFI_*`
|
||
- 生命周期重试与回退: `TQ_LIFECYCLE_*`
|
||
- 打印策略与保护阈值: `TQ_PRINTER_*`
|
||
- 文生图: `TQ_Z_IMAGE_*`
|
||
- 语音会话与音频参数: `TQ_VOICE_*`
|
||
- 板级 GPIO 映射: `TQ_POWER_*`, `TQ_LED_*`, `TQ_PRINT_*`, `TQ_SPI_*`, `TQ_SCREEN_*`
|
||
- 屏幕参数: `TQ_SCREEN_*`
|
||
|
||
## 分区与镜像
|
||
|
||
当前使用 `partitions.csv`（16MB）:
|
||
|
||
- `ota_0` at `0x30000`, size `0x780000`
|
||
- `ota_1` at `0x7B0000`, size `0x780000`
|
||
- `nvs_key` 分区启用加密标记
|
||
|
||
`idf.py build` 后会自动执行 bin 同步目标，将构建产物同步到:
|
||
|
||
- `tools/esptool-factory/bin/`
|
||
|
||
## 字库资源
|
||
|
||
当前嵌入字库:
|
||
- `components/domain/assets/fonts/cn16_index.bin`
|
||
- `components/domain/assets/fonts/cn16_glyphs.bin`
|
||
|
||
重新生成示例:
|
||
|
||
```bash
|
||
python3 -m pip install --user pillow
|
||
python3 tools/gen_cn16_font.py \
|
||
--font /path/to/your/font.ttf \
|
||
--font-index 0 \
|
||
--out-dir components/domain/assets/fonts
|
||
```
|
||
|
||
## 验证建议（最小闭环）
|
||
|
||
- 编译检查: `idf.py build`
|
||
- 设备验证:
|
||
- 首次上电无 Wi-Fi 时，确认可通过 `http://192.168.4.1` 配网
|
||
- 配网后设备可连网并进入运行态
|
||
- MIC_KEY 按住说话/松开停止流程可跑通
|
||
- 至少完成一次打印闭环（文本或图像）
|
||
- POWER_KEY 长按可触发停机
|
||
|
||
## 安全说明
|
||
|
||
- 不要在源码中保留真实生产密钥
|
||
- 请使用 `menuconfig` 或本地配置覆盖 `TQ_VOICE_API_KEY` / `TQ_Z_IMAGE_API_KEY`
|
||
- 不要提交本地 `sdkconfig` 变体、串口特定命令和 `build/` 产物
|
||
|
||
## 相关文档
|
||
|
||
- GPIO 映射: `docs/gpio-map.md`
|
||
- WebSocket 协议参考: `docs/websocket.md`
|
||
- Z-Image 参考: `docs/z-image.md`
|
||
- 产线打包工具: `tools/esptool-factory/README.md`
|