460 lines
11 KiB
Markdown
460 lines
11 KiB
Markdown
# lyfPrinter 上位机 APP 迁移到 ESP32(ESP-IDF) 实施文档
|
||
|
||
本文档基于当前 Android 上位机 APP 实现（`MainActivity + ECBLE + BlueHandler + 各预览页`），给出一套可落地的 ESP32/ESP-IDF 迁移方案。
|
||
|
||
适用目标：
|
||
- 让 ESP32 作为 BLE Central 连接 `lyfPrinter` 热敏打印机
|
||
- 复用现有私有打印协议（`0x00~0x07`、`0xA0~0xA4`）
|
||
- 在 ESP32 上实现打印、状态监控、标签纸定位、OTA（打印机固件）能力
|
||
|
||
---
|
||
|
||
## 1. 现有 APP 能力基线（迁移输入）
|
||
|
||
Android 端关键行为：
|
||
|
||
1. 扫描过滤设备名 `lyfPrinter`
|
||
2. 连接 BLE 外设并绑定特征：
|
||
- Notify: `0000fff1-0000-1000-8000-00805f9b34fb`
|
||
- Write: `0000fff2-0000-1000-8000-00805f9b34fb`
|
||
3. 请求 `MTU=247`
|
||
4. 向写特征发送私有协议帧，接收 Notify 回包并解析状态
|
||
5. 打印流程：
|
||
- 输入内容转 384 点宽位图
|
||
- 二值化
|
||
- 行取模（8 像素打包 1 字节）
|
||
- 按 240 字节数据体分包（整帧 244 字节）
|
||
- 按应答节奏发送完毕
|
||
6. 打印前后控制：
|
||
- 开启/关闭 VH 电源
|
||
- 设置热参数（浓度映射）
|
||
- 结束后走纸留白
|
||
|
||
可参考：
|
||
- `APP_BLE打印控制实现说明.md`
|
||
- `BLE_PAIRING_PARAMETERS.md`
|
||
|
||
---
|
||
|
||
## 2. 迁移目标定义
|
||
|
||
建议按两级目标推进：
|
||
|
||
### 2.1 M1（必做，先跑通）
|
||
|
||
1. 扫描/连接/重连
|
||
2. 状态查询与解析（纸张、电量、温度）
|
||
3. 基础打印（接收已编码点阵数据后发送）
|
||
4. 标签纸 gap 定位与偏移读写
|
||
|
||
### 2.2 M2（增强）
|
||
|
||
1. ESP32 端文本渲染与位图编码
|
||
2. 图片/二维码本地生成与打印
|
||
3. 打印机 OTA 完整流程
|
||
4. UI 层（按键、串口命令、Web、LCD+LVGL 任一）
|
||
|
||
---
|
||
|
||
## 3. ESP-IDF 技术选型建议
|
||
|
||
推荐：
|
||
- ESP-IDF `v5.1+` 或 `v5.2+`
|
||
- BLE Host：`NimBLE`（内存占用更低，Central 场景稳定）
|
||
|
||
备选：
|
||
- Bluedroid 也可实现，但本项目建议优先 NimBLE。
|
||
|
||
编译配置建议（`menuconfig`）：
|
||
|
||
1. 启用 BLE（NimBLE）
|
||
2. 增大 GATT MTU 到 `247`
|
||
3. 提升 BT controller/host 内存预算
|
||
4. 打开 NVS（存储设备地址、标签偏移、最近配置）
|
||
|
||
---
|
||
|
||
## 4. Android 到 ESP32 模块映射
|
||
|
||
| Android 类 | 迁移后模块 | 说明 |
|
||
|---|---|---|
|
||
| `MainActivity` | `printer_ble_scan.c` + `app_cli.c` | 扫描、设备选择、连接触发 |
|
||
| `ECBLE` | `printer_ble_client.c` | GATT 连接、服务发现、通知订阅、写特征 |
|
||
| `BlueHandler` | `printer_proto.c` + `printer_engine.c` | 协议封装/解析、状态机、分包与流控 |
|
||
| `DataConvertTool` | `image_raster.c` | 二值化、384宽缩放、行取模 |
|
||
| 各 PreviewActivity | `content_renderer_*.c` | 文本/二维码/模板渲染 |
|
||
| `otaUpdateActivity` | `printer_ota.c` | `A0~A4` 升级流程 |
|
||
|
||
建议目录：
|
||
|
||
```text
|
||
components/
|
||
printer_ble/
|
||
include/printer_ble_client.h
|
||
printer_ble_client.c
|
||
printer_proto/
|
||
include/printer_proto.h
|
||
printer_proto.c
|
||
printer_engine/
|
||
include/printer_engine.h
|
||
printer_engine.c
|
||
image_raster/
|
||
include/image_raster.h
|
||
image_raster.c
|
||
printer_ota/
|
||
include/printer_ota.h
|
||
printer_ota.c
|
||
main/
|
||
app_main.c
|
||
app_cli.c
|
||
app_config.c
|
||
```
|
||
|
||
---
|
||
|
||
## 5. BLE 迁移要点（与 Android 行为对齐）
|
||
|
||
### 5.1 扫描与过滤
|
||
|
||
逻辑对齐 Android：
|
||
- 仅处理设备名 `lyfPrinter`
|
||
- 保存 MAC、RSSI、最后发现时间
|
||
- 支持“按 MAC 直连”模式（量产更稳）
|
||
|
||
### 5.2 建链流程
|
||
|
||
1. `scan -> connect`
|
||
2. `discover service/characteristics`
|
||
3. 找到 `FFF1/FFF2`
|
||
4. 对 `FFF1` 写 CCCD `0x0001` 开启 Notify
|
||
5. 交换 MTU（目标 247）
|
||
|
||
### 5.3 写入策略
|
||
|
||
与 Android 保持一致：
|
||
- Write Without Response
|
||
- 发送内容使用十六进制帧字节序列
|
||
|
||
### 5.4 断线策略
|
||
|
||
建议状态机：
|
||
- `DISCONNECTED`
|
||
- `SCANNING`
|
||
- `CONNECTING`
|
||
- `DISCOVERING`
|
||
- `READY`
|
||
- `PRINTING`
|
||
|
||
断线后：
|
||
- 延时 300ms 重连
|
||
- 最多重试 4 次（与 Android 一致）
|
||
- 失败后回 `SCANNING`
|
||
|
||
---
|
||
|
||
## 6. 私有协议迁移（核心）
|
||
|
||
### 6.1 指令定义
|
||
|
||
```c
|
||
// 打印
|
||
#define CMD_POWER 0x00
|
||
#define CMD_GET_STATUS 0x01
|
||
#define CMD_SET_DISTANCE 0x02
|
||
#define CMD_SET_PARAM 0x03
|
||
#define CMD_SEND_DATA 0x04
|
||
#define CMD_GAP_MOVE 0x05
|
||
#define CMD_GET_LABEL_OFFSET 0x06
|
||
#define CMD_SET_LABEL_OFFSET 0x07
|
||
|
||
// OTA
|
||
#define CMD_BOOT_JUMP_BOOT 0xA0
|
||
#define CMD_BOOT_ERASE_PAGE 0xA1
|
||
#define CMD_BOOT_WRITE_DATA 0xA2
|
||
#define CMD_BOOT_JUMP_APP 0xA3
|
||
#define CMD_BOOT_GET_VERSION 0xA4
|
||
```
|
||
|
||
### 6.2 帧结构
|
||
|
||
常规帧：
|
||
|
||
```text
|
||
[addr:1][func:1][lenH:1][lenL:1][payload:len][checksum:optional]
|
||
```
|
||
|
||
校验和规则：
|
||
- 从 `addr` 到 payload 最后一个字节累加，取低 8 位
|
||
|
||
与 Android 对齐点：
|
||
- 控制类命令一般带校验
|
||
- `CMD_SEND_DATA(0x04)` 数据帧可不带校验（当前 Android 逻辑）
|
||
|
||
### 6.3 回包解析
|
||
|
||
按 `func` 分发处理：
|
||
|
||
1. `0x01`：设备状态
|
||
2. `0x04`：数据发送 ACK，用于释放“发送下一包”锁
|
||
3. `0x05`：标签定位完成
|
||
4. `0x06`：标签偏移读取结果
|
||
5. `0xA1~0xA4`：OTA流程响应
|
||
|
||
---
|
||
|
||
## 7. 打印引擎迁移设计
|
||
|
||
### 7.1 打印参数映射
|
||
|
||
浓度映射（与 Android 对齐）：
|
||
- `较淡 -> 1000`
|
||
- `中等 -> 1500`
|
||
- `较浓 -> 2000`
|
||
- `最深 -> 3000`
|
||
|
||
打印前序列：
|
||
|
||
1. `CMD_POWER` 开
|
||
2. `CMD_SET_PARAM(hot_mode, move_time, hot_time)`
|
||
3. 分包发送 `CMD_SEND_DATA`
|
||
|
||
打印后序列：
|
||
|
||
1. `CMD_POWER` 关
|
||
2. `CMD_SET_DISTANCE(12.5mm)` 留白走纸
|
||
|
||
### 7.2 分包规则
|
||
|
||
与 Android 同步：
|
||
- 单帧上限 244 bytes
|
||
- 协议头 4 bytes
|
||
- 数据体 240 bytes（384 点宽 -> 48 bytes/行 -> 每包 5 行）
|
||
|
||
流控策略：
|
||
- 发出数据包后等待 `0x04` ACK
|
||
- 首包后可短延时一次
|
||
- 后续每包 ACK 驱动
|
||
- ACK 超时建议 `2~5s`，整任务超时 `30s`
|
||
|
||
### 7.3 打印状态门限
|
||
|
||
建议保持一致：
|
||
- 缺纸：禁止打印
|
||
- 电量 `<=40%`：禁止打印
|
||
- 温度 `>=60℃`：禁止打印
|
||
|
||
---
|
||
|
||
## 8. 图像处理迁移策略（重点）
|
||
|
||
ESP32 内存有限，不建议一次性处理大图。推荐 3 种模式：
|
||
|
||
### 8.1 模式 A（推荐首版）
|
||
|
||
外部（PC/手机/云）先生成“384宽 + 二值化 + 行取模”数据，ESP32 仅负责协议发送。
|
||
|
||
优点：
|
||
- 开发最快
|
||
- ESP32 负载最低
|
||
|
||
### 8.2 模式 B（文本优先）
|
||
|
||
ESP32 只做文本/模板渲染，不做复杂图片解码。
|
||
|
||
优点：
|
||
- 资源可控
|
||
- 适合收据、标签、测试页
|
||
|
||
### 8.3 模式 C（全本地）
|
||
|
||
ESP32 本地做图片解码+缩放+二值化+取模。需外接 PSRAM，建议 ESP32-S3。
|
||
|
||
---
|
||
|
||
## 9. FreeRTOS 任务模型建议
|
||
|
||
建议拆成 4 个任务 + 2 个队列：
|
||
|
||
1. `ble_task`
|
||
- 处理 GAP/GATT 事件
|
||
2. `proto_task`
|
||
- 帧收发、ACK 管理、回包解析
|
||
3. `print_task`
|
||
- 打印流程状态机（预热、分包、收尾）
|
||
4. `cmd_task`
|
||
- 外部命令入口（串口/Web/UI）
|
||
|
||
队列：
|
||
- `q_cmd`：业务命令（print/status/ota）
|
||
- `q_evt`：BLE/协议事件（connected/ack/timeout）
|
||
|
||
同步对象：
|
||
- `EventGroup`：`READY`、`ACK_04`、`GAP_OK`、`OTA_ACK`
|
||
- `Mutex`：写特征互斥
|
||
|
||
---
|
||
|
||
## 10. 关键 C 接口建议
|
||
|
||
```c
|
||
// BLE
|
||
esp_err_t printer_ble_start_scan(void);
|
||
esp_err_t printer_ble_connect_by_name(const char *name);
|
||
esp_err_t printer_ble_write(const uint8_t *data, size_t len, bool no_rsp);
|
||
|
||
// 协议
|
||
size_t printer_proto_build_frame(uint8_t addr, uint8_t cmd,
|
||
const uint8_t *payload, uint16_t len,
|
||
bool with_checksum, uint8_t *out);
|
||
void printer_proto_handle_notify(const uint8_t *data, size_t len);
|
||
|
||
// 打印引擎
|
||
esp_err_t printer_engine_print_raw(const uint8_t *raw, size_t len, int hot_time);
|
||
esp_err_t printer_engine_get_status(void);
|
||
esp_err_t printer_engine_gap_move(void);
|
||
esp_err_t printer_engine_set_label_offset(uint8_t value);
|
||
|
||
// OTA
|
||
esp_err_t printer_ota_run(const uint8_t *fw, size_t len);
|
||
```
|
||
|
||
---
|
||
|
||
## 11. OTA 迁移（针对打印机固件升级）
|
||
|
||
流程对齐 Android：
|
||
|
||
1. `A0` 跳 Boot
|
||
2. `A1` 擦页（按 1024 bytes 估页数）
|
||
3. `A2` 写入（单包 236 bytes 数据）
|
||
4. `A3` 跳回 App
|
||
5. `A4` 读版本确认
|
||
|
||
建议：
|
||
- 每步都有超时和重试（每步 3 次）
|
||
- 断电恢复策略：记录 last packet index
|
||
|
||
---
|
||
|
||
## 12. 分阶段实施计划
|
||
|
||
### Phase 1（3~5天）
|
||
|
||
1. BLE 扫描连接 + 订阅通知 + MTU
|
||
2. 实现 `GET_STATUS`
|
||
3. 实现 `POWER / SET_PARAM / SEND_DATA / SET_DISTANCE`
|
||
4. 用固定测试页 raw 数据打印
|
||
|
||
验收：
|
||
- 可稳定打印 50 次无死锁
|
||
|
||
### Phase 2（3~7天）
|
||
|
||
1. 文本模板渲染
|
||
2. 标签定位/偏移
|
||
3. 设备参数保存（NVS）
|
||
|
||
验收：
|
||
- 标签纸对齐稳定
|
||
|
||
### Phase 3（3~7天）
|
||
|
||
1. OTA 全流程
|
||
2. 回归测试与异常恢复
|
||
|
||
验收：
|
||
- 升级成功率 > 99%
|
||
|
||
---
|
||
|
||
## 13. 测试清单
|
||
|
||
基础通信：
|
||
|
||
1. 扫描到 `lyfPrinter`
|
||
2. 连接后找到 `FFF1/FFF2`
|
||
3. Notify 有数据
|
||
4. MTU 协商到 247
|
||
|
||
协议一致性：
|
||
|
||
1. 每条命令帧结构正确
|
||
2. 校验和与 Android 一致
|
||
3. `0x04` ACK 能正确驱动分包
|
||
|
||
打印质量：
|
||
|
||
1. 浓度 4 档效果一致
|
||
2. 长图连续打印无丢行
|
||
3. 结束留白距离稳定
|
||
|
||
异常场景：
|
||
|
||
1. 打印中断线后可恢复
|
||
2. 缺纸/低电/高温阻断生效
|
||
3. OTA 超时重试有效
|
||
|
||
---
|
||
|
||
## 14. 常见问题与规避
|
||
|
||
1. `write without response` 太快导致对端缓存溢出
|
||
规避：严格按 `0x04 ACK` 节奏发送。
|
||
|
||
2. 连接成功但收不到 Notify
|
||
规避：确认 CCCD 写成功且未被后续重连覆盖。
|
||
|
||
3. 打印偏移不稳定
|
||
规避：先 `GAP_MOVE`，再按偏移走纸，偏移值写入 NVS。
|
||
|
||
4. ESP32 内存不足
|
||
规避：首版采用“外部预编码 raw 数据”，不在设备端做重图像处理。
|
||
|
||
---
|
||
|
||
## 15. 最小可用迁移路径（建议）
|
||
|
||
如果你希望最快落地，按下面最小路径：
|
||
|
||
1. 先只做 BLE + 协议 + raw 发送
|
||
2. 用串口命令输入 `print_raw/status/gap/offset`
|
||
3. 打通后再逐步补 UI 和本地渲染
|
||
|
||
这样可以最短时间复用 Android 的核心协议能力，并把主要风险收敛在 BLE 链路与分包流控上。
|
||
|
||
---
|
||
|
||
## 16. 附：协议发送伪代码
|
||
|
||
```c
|
||
void do_print(const uint8_t *raw, size_t raw_len, int hot_time) {
|
||
send_cmd_power(true); // 0x00
|
||
send_cmd_set_param(1, 2, hot_time); // 0x03
|
||
|
||
const size_t chunk = 240;
|
||
size_t off = 0;
|
||
int idx = 0;
|
||
|
||
while (off < raw_len) {
|
||
size_t n = (raw_len - off > chunk) ? chunk : (raw_len - off);
|
||
send_cmd_data(raw + off, n); // 0x04
|
||
|
||
if (idx > 0) {
|
||
if (!wait_ack_04(3000)) {
|
||
// 超时处理：重发或中止
|
||
break;
|
||
}
|
||
} else {
|
||
vTaskDelay(pdMS_TO_TICKS(10));
|
||
}
|
||
|
||
off += n;
|
||
idx++;
|
||
}
|
||
|
||
send_cmd_power(false); // 0x00
|
||
send_cmd_set_distance(12.5f); // 0x02
|
||
}
|
||
```
|
||
|