display开发指南

概述

显示屏系统由LCD（液晶显示）、TP（触控面板）和按键三个部分组成。本指南详细介绍这三个部分的适配方法。

显示触控系统架构

快速验证板载显示

社区固件已启用 GPU AT 命令，不需要再复制一套显示 demo。烧录固件并启动开发板后，在 750000 波特率的 UART2 串口执行：

AT+GPU=smoke

该命令创建图层、绘制测试画面、执行像素格式转换并刷新 DPU；串口返回 OK 且开发板屏幕出现测试画面，表示 LCD、帧缓冲、VAU 与 DPU 的基本链路正常。需要验证纯色填充时可执行 AT+GPU=lcd_fill,FF0000；颜色参数为十六进制 RGB 值。若要适配其他屏幕，仍需按后文完成屏幕 IC、接口、分辨率与初始化序列配置。

LCD适配

LCD（Liquid Crystal Display）液晶显示屏需要适配新的屏幕器件。

配置文件介绍

LCD模块支持快速扩展，用户新屏幕适配时需要修改两个配置文件：

• lcd_private.c：提供屏幕驱动的内部私有接口，主要包含LCD的上下电时序控制
• lcd_config.c：提供所有支持的屏幕型号配置表，包括屏幕分辨率、像素格式及屏端操作指令，适配不同屏幕时，只需要用户修改文件“lcd_config.c”中的配置参数即可，主要包括DCS协议规定的通用配置命令，具体可参考下文适配步骤。

LCD配置参数说明

在 lcd_config.c 的 g_lcd_driver_ops 中增加新屏幕配置：

lcd_drv_cfg结构体说明：

bus_type      // 接口类型：MIPI或QSPI
bus_cfg       // 接口配置（MIPI配置消隐区，QSPI配置像素大小）
x_start       // 像素水平方向起始存放像素位置
y_start       // 像素垂直方向起始存放像素位置
fps           // 帧率
lcd_id        // 屏幕ID值
display_on_cmds    // 屏幕初始化配置序列
display_off_cmd    // 屏幕关闭命令
lcd_id_info   // 屏幕ID信息（寄存器地址和长度）

g_lcd_driver_ops配置示意图

参数计算说明：

• bus_type：只支持MIPI或者QSPI，该参数的类型为lcd_bus_type_t。
• bus_cfg：MIPI接口主要配置消隐区大小，QSPI接口主要配置屏幕实际像素大小，因此需要客户结合屏幕手册对该参数进行配置。修改主要涉及sync_info字段，其他配置字段为MIPI协议相关，无需修改，具体可参考

适配步骤

1. 配置屏幕IO管脚

修改 lcd_private.c，根据屏幕上电要求配置： - 复位管脚（rst） - 使能管脚（vci_en）

2. 增加屏幕配置

修改 lcd_config.c，在 g_lcd_driver_ops 中增加新屏幕配置：

// 总线配置示意图
bus_cfg = {
    .sync_info = {
        .hsa = horizontal_sync_active,    // 水平同步前沿
        .hbp = horizontal_back_porch,     // 水平后沿
        .hact = horizontal_active,        // 水平有效像素
        .hfp = horizontal_front_porch,    // 水平前沿
        .vsa = vertical_sync_active,      // 垂直同步前沿
        .vbp = vertical_back_porch,       // 垂直后沿
        .vact = vertical_active,          // 垂直有效像素
        .vfp = vertical_front_porch,      // 垂直前沿
    },
    .pixel_clk = pixel_clock,             // 像素时钟
    .phy_data_rate = phy_data_rate,       // 物理数据率
};

参数计算说明：

• pixel_clk ≥ (hsa + hbp + hact + hfp) × (vsa + vbp + vact + vfp) × 60 / 1000（60fps帧率）
• phy_data_rate = pixel_clk × out_format_bits / 1000（out_format_bits为单像素bit数）

修改pixel_clk_div_num值示意图

bus_cfg配置示意图

参数计算说明：

• x_start：像素水平方向起始存放像素位置。

• y_start：像素垂直方向起始存放像素位置。

• fps：可忽略。

• lcd_id：屏幕ID值，初始化时会读取lcd_id_info.reg_addr的值和该配置比较，获取g_lcd_driver_ops中的配置进行屏幕配置。

• display_on_cmds：屏幕初始化配置序列。

• display_off_cmd～sleep_out_cmd需要对照当前屏幕命令去实现。

• lcd_id_info.reg_addr：读取屏幕ID寄存器地址。

• lcd_id_info.read_len：屏幕ID长度。

3. 适配GUI屏幕分辨率

修改 graphic_hardware_config_wearable.h：

#define RESOLUTION_WIDTH  {新屏幕宽度}
#define RESOLUTION_HEIGHT {新屏幕高度}

屏幕初始化配置序列格式：

第一个参数：1表示dcs命令，0表示Gen命令

第二个参数：命令长度（命令+参数）

第三个参数：命令内容

第四个参数：命令发送完成后延迟时间（单位：ms）

QSPI屏幕额外配置：

在 target_config.py 中：

• 删除MIPI_ULPS_SUPPORT宏
• 增加SUPPORT_GPU_QSPI宏

MIPI VIDEO屏幕额外配置：

在 target_config.py 中：

• 删除MIPI_ULPS_SUPPORT宏
• 增加GPU_SUPPORT_VIDEO_MODE宏

适配GUI屏幕分辨率： 需要修改如下文件“/src/middleware/services/gui/hal/common/include/graphic_hardware_config_wearable.h”中的RESOLUTION_WIDTH和RESOLUTION_HEIGHT，默认分支配置为454×454，修改为新屏幕大小（QSPI等其他规格，请修改对应分支）。

LCD驱动架构

TP适配

TP（Touch Panel）触控面板支持型号有ztw622、ztw523。

驱动概述

驱动目录结构：

• application/3322/input_wear/peripheral/touch/ - 触控公共处理源文件
• application/3322/input_wear/peripheral/touch/ztw523_touch/ - ztw523型号触控源文件
• application/3322/input_wear/peripheral/touch/ztw622_touch/ - ztw622型号触控源文件

适配步骤

1. 新建触控型号目录

触控在项目实际使用中仅编译一种型号的源文件，适配新型号时需要新建目录：

application/3322/input_wear/peripheral/touch/xxx_touch/

2. 配置I2C和管脚

参考头文件 product_evb_standard.h：

#define TOUCH_I2C_BUS I2C_BUS_1
#define TOUCH_INT_GPIO S_AGPIO0
#define TOUCH_RESET_GPIO S_AGPIO6

3. 配置从机地址

参考头文件 touch_ctrl.h：

#define TOUCH_I2C_ADDR 0x20

4. 适配触控通信接口

不同芯片的I2C交互方式不同，用户需要对比触控手册适配I2C通信接口（以下为函数签名示例，实际实现需根据触控芯片手册）：

ext_errno tp_i2c_data_read(uint16_t reg_addr, uint8_t *data_buf, uint32_t data_len);  // 实现于drivers/drivers/driver/touch/xxx_touch/xxx_ctrl.c
ext_errno tp_i2c_cmd_write(uint16_t cmd);
ext_errno tp_i2c_reg_write(uint16_t reg_addr, uint16_t reg_cfg);
ext_errno tp_i2c_data_write(uint16_t reg_addr, uint8_t *data_buf, uint32_t data_len);

5. 适配触控初始化和中断

ext_errno ztw523_init(void);  // 实现于drivers/drivers/driver/touch/ztw523_touch/ztw523_drv1.c
ext_errno ztw523_irq_callback(uint8_t *data_buf, uint8_t data_len);  // 中断处理，获取报点信息

6. 适配触控芯片上电时序

ext_errno ztw523_reset(void);  // 对比触控手册适配上电时序

7. 注册触控公共API

完成.touch_init和.touch_get_tpinfo即可支持基础报点功能：

touch_peripheral_api g_ztw523_api = {
    .touch_init = ztw523_drv_init,
    .touch_deinit = ztw523_drv_deinit,
    .touch_get_tpinfo = ztw523_drv_get_info,
    .touch_suspend = ztw523_drv_suspend,
    .touch_resume = ztw523_drv_resume,
    .touch_sleep = ztw523_drv_sleep,
    .touch_bus_init = touch_host_peripheral_init,
    .register_callback = ztw523_register_handle,
    .unregister_callback = ztw523_unregister_handle,
};

8. 完善其他接口

完成上述接口后，完善剩余接口实现完整功能。

TP触控架构

按键适配

按键模块支持GPIO按键扩展，最多可扩展7个。

驱动概述

按键适配主要涉及文件：

• button_feature.c
• button_feature.h

适配步骤

1. 配置按键引脚映射

修改button_feature.c中的g_brandy_button_pin_map：

button_map_t g_brandy_button_pin_map[BUTTON_PIN_MAP_MAX] = {
    { PIN_NONE, BUTTON_PWR },    // 电源键（默认支持）
    { PIN_NONE, BUTTON_1 },      // 第一个GPIO按键
    { PIN_NONE, BUTTON_2 },      // 第二个GPIO按键
    { PIN_NONE, BUTTON_3 },
    { PIN_NONE, BUTTON_4 },
    { PIN_NONE, BUTTON_5 },
    { PIN_NONE, BUTTON_6 },
    { PIN_NONE, BUTTON_7 },
};

将PIN_NONE替换为实际使用的GPIO管脚，例如：

{ S_MGPIO25, BUTTON_1 },

2. 配置GPIO管脚IE（低功耗版本）

在 board_evb.h 中修改对应管脚的 IE 配置：

// 原始配置
{ HAL_PIO_FUNC_GPIO, HAL_PIO_DRIVE_MAX, HAL_PIO_PULL_MAX, HAL_PIO_IE_DISABLE },

// 修改为（开启输入使能）
{ HAL_PIO_FUNC_GPIO, HAL_PIO_DRIVE_MAX, HAL_PIO_PULL_MAX, HAL_PIO_IE_ENABLE },

3. 新增按键事件枚举

在button_feature.h中新增按键事件枚举：

typedef enum {
    /* power key */
    BUTTON_PWR_START = 0,
    BUTTON_PWR_CLICKUP,
    BUTTON_PWR_CLICKUP_2,
    BUTTON_PWR_LONGPRESS_1S,
    BUTTON_PWR_LONGPRESS_5S,
    BUTTON_PWR_INVALID,

    /* function key */
    BUTTON1_START,
    BUTTON1_CLICKUP,
    BUTTON1_CLICKUP_2,
    BUTTON1_LONGPRESS_1S,
    BUTTON1_LONGPRESS_5S,
    BUTTON1_INVALID,

    /* new key */
    BUTTON2_START,
    BUTTON2_CLICKUP,
    BUTTON2_CLICKUP_2,
    BUTTON2_LONGPRESS_1S,
    BUTTON2_LONGPRESS_5S,
    BUTTON2_INVALID,

    BUTTON_BUTT
} event_button_t;

4. 实现按键事件处理

在button_feature.c的button_event_get接口中新增事件处理：

static event_button_t button_event_get(button_id_t id, button_report_state_t state)
{
    event_button_t event = BUTTON_PWR_START;

    if (id == BUTTON_1) {
        event = BUTTON1_START;
    }

    /* new key */
    if (id == BUTTON_2) {
        event = BUTTON2_START;
    }
    // ... 更多按键处理
    return event;
}

说明： 若只适配一个GPIO按键，完成步骤1和2即可。

按键事件类型

事件类型	说明
CLICKUP	单击抬起
CLICKUP_2	双击
LONGPRESS_1S	长按1秒
LONGPRESS_5S	长按5秒
INVALID	无效事件

按键模块架构

显示触控整体架构

常见问题

LCD常见问题

问题	解决方案
QSPI屏幕适配	删除MIPI_ULPS_SUPPORT宏，增加SUPPORT_GPU_QSPI宏
MIPI VIDEO屏幕适配	删除MIPI_ULPS_SUPPORT宏，增加GPU_SUPPORT_VIDEO_MODE宏
屏幕撕裂	调整Tear_Scanline，在初始化序列中添加0x44命令
低带宽黑屏	增加消隐区配置

屏幕撕裂解决示意：

低带宽问题解决：

TP常见问题

问题	解决方案
通信nack	检查上电时序、bus id、slave地址是否正确
中断不上报	检查中断管脚适配和连接是否正常
坐标信息错误	对比触控手册确保获取方式正确
报点异常	确保中断处理时间不过长

按键常见问题

问题	解决方案
按键无响应	检查GPIO管脚配置和IE设置
多按键冲突	检查GPIO管脚是否被其他功能占用
低功耗下失效	确保GPIO管脚IE配置正确
事件误触发	调整消抖时间和按键事件阈值