first commit

Communication_Protocol.md

@@ -0,0 +1,179 @@
+# lyfPrinter 热敏打印机通讯协议（整理版，基于文档 V1.1）
+
+> 来源：*lyfPrinter 热敏打印机协议文档*（V1.1，2026-01-03：增加标签纸打印指令）
+
+---
+
+## 1. 帧格式（命令/响应一致）
+
+一帧数据由以下字段顺序组成：
+
+- **设备地址**（1B）
+- **功能码**（1B）
+- **数据长度**（2B）
+- **数据区**（NB）
+- **和校验**（1B）
+
+> 文档定义：命令格式=设备地址(1B)+功能码(1B)+数据长度(2B)+数据(NB)+和校验(1B)。
+
+### 1.1 和校验（Checksum）
+
+**和校验 = 设备地址 + 功能码 + 数据长度(2B) + 数据区(NB) 的总和取低 8 位**
+
+也就是：
+
+```text
+checksum = (addr + func + len_hi + len_lo + sum(data_bytes)) & 0xFF
+```
+
+### 1.2 十六进制写法 vs 实际发送
+
+文档示例里常写成带空格的十六进制，如：
+
+```text
+01 00 00 01 01 03
+```
+
+这只是**便于阅读**。实际发送时需要发**原始字节流**（bytes），等价于：
+
+```text
+0x01 0x00 0x00 0x01 0x01 0x03
+```
+
+---
+
+## 2. 指令列表
+
+> 说明：下面“send/recv”都是“帧格式”中的 **数据区**含义（其它字段按帧格式固定存在）。
+> 文档中设备地址示例均为 `0x01`。
+
+---
+
+### 2.1 电源开关控制（0x00）
+
+**send 数据区（1B）**  
+- `0x00`：关  
+- `0x01`：开  
+
+**recv 数据区（1B）**  
+- `0x00`：失败  
+- `0x01`：成功  
+
+**示例**
+- 打开电源：`01 00 00 01 01 03`
+- 关闭电源：`01 00 00 01 00 02`
+
+---
+
+### 2.2 获取设备状态（0x01）
+
+**send 数据区**：无（长度为 0）
+
+**recv 数据区**
+- 纸张状态（1B）：`0x00` 无纸 / `0x01` 有纸
+- 电池电量（1B）：0~100
+- 打印头温度（3B）：
+  - 第 1 字节为符号位：`0x2B` 正号 / `0x2D` 负号
+  - 保留 1 位小数（范围 -20℃~80℃）
+  - *注：文档未进一步明确后 2 字节的编码方式，需结合实际设备/固件实现确认。*
+
+**示例**
+- 获取设备状态：`01 01 00 00 02`
+
+---
+
+### 2.3 设置走纸距离（0x02）
+
+**send 数据区**
+- 走纸方向（1B）：`0x2B` 正向 / `0x2D` 反向
+- 走纸距离（2B）：单位 mm
+
+**recv 数据区（1B）**
+- `0x00`：失败
+- `0x01`：成功
+
+**示例**
+- 设置走纸 5mm：`01 02 00 03 2B 00 05 36`
+
+---
+
+### 2.4 设置打印参数（0x03）
+
+> 包含：打印速度（切换 STB 同时加热数量）、打印浓度（调整加热时间）
+
+**send 数据区**
+- 加热模式（1B，等级 1~4）
+  - `0x01`：分 6 次加热
+  - `0x02`：分 3 次加热
+  - `0x03`：分 2 次加热
+  - `0x04`：分 1 次加热（功率太大暂不支持）
+- 电机运行速度（1B）：单位 ms，范围 1~10ms
+- 打印浓度/加热时间（2B）：单位 us，建议范围 1000~2500（不推荐超过 2500us 长时间加热）
+  - 1000：较淡
+  - 1500：中等
+  - 2000：浓
+  - 2500：最深
+
+**recv 数据区（1B）**
+- `0x00`：失败
+- `0x01`：成功
+
+**示例**
+- 模式 1、速度 1ms、加热 2000us：`01 03 00 04 01 01 07 D0 E0`
+
+---
+
+### 2.5 发送打印数据（0x04）
+
+**send 数据区**
+- 打印数据（NB）
+  - 一次最多 **240 字节**
+  - **一行 48 字节**，因此一次最多 **5 行**
+
+**recv 数据区（1B）**
+- `0x00`：失败
+- `0x01`：成功（打印机已完成当前数据打印，可接收下一帧）
+
+> 实际打印流程通常是：发送一帧 0x04 → 等待 recv 处理状态=0x01 → 再发下一帧。
+
+---
+
+### 2.6 标签纸定位走纸（0x05）【V1.1 增加】
+
+**send 数据区（1B）**：固定 `0x01`  
+**recv 数据区（1B）**：固定 `0x01`
+
+**示例**
+- 执行标签纸走纸定位：`01 05 00 01 01 08`
+
+---
+
+### 2.7 查询标签纸偏移（0x06）【掉电保存】
+
+**send 数据区（1B）**：固定 `0x01`
+
+**recv 数据区（1B）**
+- 标签纸偏移值：单位 mm，1B，保留 1 位小数，最大 25.4mm  
+- *从“12.8mm → 0x80”的示例可推断：偏移字节 ≈ 偏移(mm)×10（0.1mm 为 1 LSB）*
+
+**示例**
+- 查询标签纸偏移：`01 06 00 01 01 09`
+
+---
+
+### 2.8 设置标签纸偏移（0x07）【掉电保存】
+
+**send 数据区（1B）**
+- 标签纸偏移值：单位 mm，1B，保留 1 位小数，最大 25.4mm
+
+**recv 数据区（1B）**：固定 `0x01`
+
+**示例**
+- 设置标签纸偏移 12.8mm：`01 07 00 01 80 89`
+
+---
+
+## 3. 安全警告（文档原意）
+
+- 电源开关不要长时间打开；打印结束后及时关断，否则可能导致打印头损坏。
+