# 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. 安全警告（文档原意）

- 电源开关不要长时间打开；打印结束后及时关断，否则可能导致打印头损坏。