# lyfPrinter APP BLE 打印控制实现说明

本文档基于当前项目源码，说明 Android 上位机如何通过 BLE 控制热敏打印机完成打印。

适用代码目录：`app/src/main/java/com/example/electronicScale`

---

## 1. 总体架构

APP 的控制链路可分为 4 层：

1. 页面层（各类预览页）
   - 负责生成待打印位图（图片/文本/二维码/小票/标签）。
2. 业务协议层（`BlueHandler`）
   - 负责打印协议封装、状态解析、分包发送、打印参数下发。
3. BLE 传输层（`ECBLE`）
   - 负责扫描、连接、订阅通知、写特征、MTU 协商。
4. 打印机固件
   - 解析自定义指令，执行打印、走纸、标签定位、OTA 等动作。

核心类：
- `MainActivity`：权限、扫描、连接入口。
- `ECBLE`：BLE 扫描/连接/读写底层。
- `BlueHandler`：打印协议与数据处理核心。
- `PrinterControlActivity`：打印机状态面板与功能入口页。
- 各 `*PreviewActivity`：生成位图并调用统一打印入口。

---

## 2. 连接与初始化流程

### 2.1 权限与系统开关

`MainActivity` 在进入时先做权限检查，再打开蓝牙：

- 位置权限：`ACCESS_FINE_LOCATION`、`ACCESS_COARSE_LOCATION`
- Android 12+ 蓝牙权限：`BLUETOOTH_SCAN`、`BLUETOOTH_ADVERTISE`、`BLUETOOTH_CONNECT`

参考：
- `MainActivity.java:264`
- `AndroidManifest.xml`

`ECBLE.openBluetoothAdapter()` 会继续检查：
- 是否支持蓝牙
- 蓝牙开关是否开启
- 定位开关是否开启（GPS 或 Network）

参考：
- `ECBLE.java:61`

---

### 2.2 扫描与设备过滤

扫描使用 `BluetoothAdapter.startLeScan()`，回调设备名与 MAC。

APP 仅展示设备名为 `lyfPrinter`（忽略大小写、去空格）的设备。

参考：
- `ECBLE.java:132`
- `MainActivity.java:238`
- `MainActivity.java:244`

---

### 2.3 建链与 GATT 特征绑定

用户点击设备后，调用 `ECBLE.createBLEConnection()`。

连接策略：
- 失败自动重试，最多 5 次（初次 + 4 次重试）。
- 每次重试间隔约 300ms。

参考：
- `MainActivity.java:176`
- `ECBLE.java:336`

服务发现后，绑定两个关键特征：
- Notify：`0000fff1-0000-1000-8000-00805f9b34fb`
- Write：`0000fff2-0000-1000-8000-00805f9b34fb`

并执行：
- 开启通知（`setCharacteristicNotification + CCCD`）
- 请求 MTU = 247
- 写入类型 `WRITE_TYPE_NO_RESPONSE`

参考：
- `ECBLE.java:180`
- `ECBLE.java:181`
- `ECBLE.java:219`
- `ECBLE.java:291`
- `ECBLE.java:303`
- `ECBLE.java:378`

---

## 3. BlueHandler：统一打印控制核心

`BlueHandler` 是单例，负责：

1. 注册 BLE 回调并解析回包。
2. 定时查询打印机状态（每 5 秒）。
3. 校验打印条件（缺纸/低电/高温）。
4. 将位图转为热敏点阵数据。
5. 按打印协议分帧发送并处理进度。

参考：
- `BlueHandler.java:70`
- `BlueHandler.java:91`
- `BlueHandler.java:232`
- `BlueHandler.java:296`
- `BlueHandler.java:438`

---

## 4. 自定义通信协议（打印指令）

### 4.1 帧格式

常规帧由 `printer_sendParam()` 组包：

1. `slaveAddr`（1字节，默认 `0x01`）
2. `function`（1字节）
3. `lengthH`（1字节）
4. `lengthL`（1字节）
5. `payload`（可变）
6. `checkSum`（可选，1字节）

校验规则（若启用）：
- 从地址到 payload 所有字节求和，取低 8 位。

参考：
- `BlueHandler.java:590`

---

### 4.2 指令码

打印控制相关：

| 指令 | 功能 |
|---|---|
| `0x00` | 电源开关（`PRINT_POWER_CMD`） |
| `0x01` | 获取状态（`PRINT_GET_STATUS_CMD`） |
| `0x02` | 走纸距离（`PRINT_SET_DISTANCE_CMD`） |
| `0x03` | 打印参数（`PRINT_SET_PARAM_CMD`） |
| `0x04` | 发送打印数据（`PRINT_SEND_DATA_CMD`） |
| `0x05` | 标签间隙定位（`PRINT_GAP_MOVE_CMD`） |
| `0x06` | 查询标签偏移（`PRINT_GET_LABEL_OFFSET_CMD`） |
| `0x07` | 设置标签偏移（`PRINT_SET_LABEL_OFFSET_CMD`） |

OTA 相关：

| 指令 | 功能 |
|---|---|
| `0xA0` | 跳转 Boot |
| `0xA1` | 擦页 |
| `0xA2` | 写固件数据 |
| `0xA3` | 跳转 App |
| `0xA4` | 查询版本 |

参考：
- `BlueHandler.java:49`
- `BlueHandler.java:59`

---

### 4.3 回包解析

`BlueHandler.anasysBlueData()` 解析 `hexBuf[1]`（功能码）：

- `0x01`（状态）
  - `hexBuf[4]`：纸张状态
  - `hexBuf[5]`：电量
  - `hexBuf[6]`：温度符号（`0x2D` 表示负）
  - `hexBuf[7..8]`：温度数值（0.1℃）
- `0x04`（打印数据应答）
  - 将 `printerIsIdle = 0`，允许发送下一包
- `0x05`（标签定位完成）
  - 将 `printerPaperPosition = 1`

参考：
- `BlueHandler.java:296`

---

## 5. 从页面到打印的通用流程

无论是图片、文字、二维码、小票、标签，最终都走统一入口：

`mBlueHandler.printImageToPrinter(bitmap, density)`

参考：
- `ImagePreviewActivity.java:369`
- `TextPreviewActivity.java:352`
- `QrPreviewMainActivity.java:367`
- `receiptPreviewActivity.java:412`
- `labelPapaerPreviewActivity.java:927`
- `factoryTestPreviewActivity.java:308`

通用步骤：

1. 页面先调用 `printrt_errorDetect()` 做可打印校验。
2. 各页面把预览内容渲染成 384 宽位图。
3. 调用 `printImageToPrinter()` 进入统一发送流程。

---

## 6. 位图到热敏数据的转换

`BlueHandler.printImageToPrinter()` 内部流程：

1. `convertBitmapToThermalData(bitmap, 384)`  
2. `scaleBitmapToPrinterWidth()`：缩放到 384 像素宽  
3. `convertToBlackWhite()`：阈值二值化（灰度 < 128 记黑）  
4. `convertBitmapToRawData()`：按行取模，8 像素打包 1 字节（MSB first）  
5. 得到连续点阵字节流后进行分包发送

参考：
- `BlueHandler.java:438`
- `BlueHandler.java:379`
- `BlueHandler.java:401`
- `DataConvertTool.java:117`
- `DataConvertTool.java:128`

---

## 7. 分包发送与打印执行

### 7.1 分包策略

APP 设置单帧上限为 244 字节，其中：
- 协议头 4 字节
- 数据体最多 240 字节

这样每帧可发送 5 行（384点宽 => 48字节/行，5行=240字节）。

参考：
- `BlueHandler.java:442`
- `BlueHandler.java:476`

---

### 7.2 打印前参数下发

实际发送前会执行：

1. 开启打印电源：`printer_setVhSwitch(true)`（`0x00`）
2. 设置打印参数：`printer_setPrintParam(1, 2, hotTime)`
3. `hotTime` 来自浓度映射：
   - 较淡=1000
   - 中等=1500
   - 较浓=2000
   - 最深=3000

参考：
- `BlueHandler.java:505`
- `BlueHandler.java:509`
- `BlueHandler.java:450`

---

### 7.3 数据发送节奏

发送循环中每个分包都走 `PRINT_SEND_DATA_CMD(0x04)`，但 `isSendCheck=false`（打印数据帧不附加校验字节）。

流控机制：
- 发送后置 `printerIsIdle = 0x04`
- 收到 `0x04` 应答时在解析函数中将其清零
- 第 1 包后只短延时
- 从第 2 包开始等待空闲再发下一包（超时 30s）

参考：
- `BlueHandler.java:520`
- `BlueHandler.java:334`
- `BlueHandler.java:551`

---

### 7.4 收尾动作

发送结束后统一执行：

1. 关闭打印电源：`printer_setVhSwitch(false)`
2. 走纸留白：`printer_setMoveDistance(12.5f)`（约 12.5mm）
3. 恢复状态轮询
4. 弹窗提示“打印完成”

参考：
- `BlueHandler.java:566`
- `BlueHandler.java:574`

---

## 8. 各打印页面的实现差异

### 8.1 图片打印（`ImagePreviewActivity`）

- 用户选图后预处理成 384 宽位图。
- 预览和打印使用误差扩散（Floyd-Steinberg/Atkinson）提升灰阶视觉效果。
- 最终把二值结果送入统一打印入口。

参考：
- `ImagePreviewActivity.java:184`
- `ImagePreviewActivity.java:319`
- `ImagePreviewActivity.java:354`

### 8.2 文本打印（`TextPreviewActivity`）

- 把 `TextView` 按 384 固定宽重新测量布局。
- 绘制到白底 Bitmap 后打印。

参考：
- `TextPreviewActivity.java:328`
- `TextPreviewActivity.java:356`

### 8.3 二维码打印（`QrPreviewMainActivity`）

- 先生成二维码，再按打印宽度 384 等比缩放后打印。

参考：
- `QrPreviewMainActivity.java:340`
- `QrPreviewMainActivity.java:367`

### 8.4 小票与工厂测试页

- 都是将固定模板文本绘制为 Bitmap，再统一打印。

参考：
- `receiptPreviewActivity.java:387`
- `factoryTestPreviewActivity.java:286`

### 8.5 标签纸打印（`labelPapaerPreviewActivity`）

标签场景在打印前多了“找缝 + 偏移”动作：

1. 查询/设置标签偏移（`0x06` / `0x07`）。
2. 打印前发送 `0x05` 做 gap 定位，等待 `printerPaperPosition` 标志。
3. 再走纸到 `currentOffset` 位置后开始打印。

参考：
- `labelPapaerPreviewActivity.java:117`
- `labelPapaerPreviewActivity.java:234`
- `labelPapaerPreviewActivity.java:886`
- `labelPapaerPreviewActivity.java:909`

---

## 9. 打印状态与防呆

状态评估来自 `detectJundge()`：

- 缺纸 -> 禁止打印
- 电量 `<= 40%` -> 禁止打印
- 温度 `>= 60℃` -> 禁止打印

页面点击打印时会先调用 `printrt_errorDetect()`，失败就弹窗并中止。

参考：
- `DataConvertTool.java:12`
- `BlueHandler.java:787`

---

## 10. 一次打印的时序（简化）

```text
用户点击打印
  -> PreviewActivity 生成 Bitmap(384宽)
  -> BlueHandler.printrt_errorDetect()
  -> BlueHandler.printImageToPrinter()
      -> 位图转点阵字节流
      -> printer_setVhSwitch(true)
      -> printer_setPrintParam(...)
      -> 循环发送 0x04 数据帧
          -> 等待 0x04 应答解锁下一帧
      -> printer_setVhSwitch(false)
      -> printer_setMoveDistance(12.5)
      -> 弹窗: 打印完成
```

---

## 11. 代码实现中的关键注意点

1. `ECBLE` 与 `BlueHandler` 的回调是静态单实例风格，多个页面共享同一通道，页面切换时需正确注册/移除监听器。  
2. 打印分包等待采用忙等循环（无休眠），高负载时可能有 CPU 占用峰值。  
3. 打印数据帧（`0x04`）当前不带校验字节，链路异常时主要依赖 BLE 层可靠性与应答超时控制。  
4. 扫描采用 `startLeScan`（旧 API），如后续适配新系统可迁移到 `BluetoothLeScanner`。  
5. 状态解析里 `connectState` 目前写死为 `1`（`BlueHandler.java:305`），如果后续需要严格依赖设备回包连接位，建议改为按协议字段解析。  

---

如果需要，我可以继续补一份《协议字段示例帧文档》（把 `0x00~0x07` 每个命令的数据字段按字节位展开，并给出示例十六进制报文）。