# LCD1602(IIC) 字符屏

LCD1602 驱动通过 PCF8574/PCF8574A 背包以 4 位时序控制字符液晶。当前支持 16×2 或 20×4，一次只允许配置一个 LCD1602 实例。

先确认当前环境编译了 `FASTBEE_ENABLE_LCD1602`，并在功能配置启用 `lcd1602`。编译能力、驱动初始化和实物显示是三个独立状态。

## 配置

外设类型为 LCD1602（type=52），`pins[0]` 为 SDA，`pins[1]` 为 SCL。选择当前板型可用且与其他 I2C 客户端兼容的引脚；下例 21/22 仅是经典 ESP32 的配置示例。

```json
{
  "id": "lcd1602_01",
  "name": "LCD1602字符屏",
  "type": 52,
  "enabled": false,
  "pinCount": 2,
  "pins": [21, 22],
  "params": {
    "cols": 16,
    "rows": 2,
    "address": 39,
    "backlight": true
  }
}
```

| 参数 | 说明 |
| --- | --- |
| cols / rows | 必须配对为 16/2 或 20/4 |
| address | JSON 数字；39 表示 0x27，63 表示 0x3F；0 请求自动探测 |
| backlight | 初始背光状态 |

自动探测范围为 0x20–0x27、0x38–0x3F；不包含中间其他地址。探测 ACK 只证明该地址有响应，不能识别背包型号。配置导入和增改均检查实例限制及资源冲突。

## 现有显示入口

使用经过登录与开发者模式检查的 `POST /api/peripherals/write`，参数放在表单请求体：

| action | 其他参数 | 作用 |
| --- | --- | --- |
| print | id、text、row、col | 在指定字符位置写入文本 |
| clear | id | 清屏并移动到原点 |
| backlight | id、enabled | 开关背光 |

print 的 text 为 1–128 字节，不能含内嵌 NUL；row/col 从 0 开始且必须在实际屏幕范围内。长文本的实际布局还受字符屏控制器与行地址限制。

显示动作 24/25/26 属于 TM1637，动作 27 属于 LCD/OLED 图形屏。本 LCD1602 入口没有实现这些外设执行动作，也没有把传感器模板自动转换成字符屏规则；不要使用旧文档中的 actionType=25 温度显示示例。

## 失败与恢复

clear、backlight 和 print 均返回真实驱动结果。print 在同一个总线锁内先确认光标命令，再发送字符；光标失败后不继续写文本。

| 结果 | 含义 |
| --- | --- |
| LCD1602\_NOT\_READY / LCD1602\_NOT\_INITIALIZED | 外设禁用或驱动未初始化，拒绝输出 |
| LCD1602\_PRINT\_FAILED | 光标或字符传输未确认 |
| LCD1602\_CLEAR\_UNCONFIRMED | 清屏传输未确认 |
| LCD1602\_BACKLIGHT\_UNCONFIRMED | 背光传输未确认 |

I2C NACK、短写或总线锁失败会使当前协议状态不可信。驱动停止后续写入，需明确重新初始化；不能靠反复提交下一条文本掩盖半字节失败。接口成功只表示 PCF8574 传输得到确认，不能证明 LCD 光学显示或物理背光状态。停用/析构的资源清理也不能当作已验证熄屏。

## 现场验收

确认模块供电、共地、信号电平、I2C 地址和接线后，先测试固定 ASCII 文本，再验证逐行定位、清屏及背光。检查对比度电位器；普通字符 ROM 不提供通用中文字库。对 5V 供电背包，应按实际模块确认 SDA/SCL 上拉电平与 ESP32 兼容。

保留正常显示、NACK/断线拒绝、显式重新初始化后的恢复结果；设备未接线或未授权时保留待验证，不能用 Host 测试或构建结果代替实物结论。

## 相关文档

* [OLED 使用指南](https://www.fastbee.cn/doc/device/v2/peripherals/oled-usage-guide.md)
* [TM1637 数码管](https://www.fastbee.cn/doc/device/v2/peripherals/display-tm1637.md)
