ESP32-S3基于ESP-IDF v5.5.2通过QSPI初始化AXS15231B LCD无显示问题

关键排查与修复步骤 #

1. 修正QSPI总线主机参数不匹配问题 #

你的代码中初始化SPI总线用的是SPI2_HOST，但创建面板IO时传入了(esp_lcd_spi_bus_handle_t)LCD_HOST，两者若宏定义不一致会导致通信失效。修改为统一参数：

ESP_ERROR_CHECK(esp_lcd_new_panel_io_spi((esp_lcd_spi_bus_handle_t)SPI2_HOST, &io_config, &io_handle));

2. 调整QSPI DMA缓冲区大小 #

AXS15231B_PANEL_BUS_QSPI_CONFIG最后一个参数是DMA缓冲区大小，过大的值可能引发隐性传输异常。改为更稳妥的典型值：

const spi_bus_config_t buscfg = AXS15231B_PANEL_BUS_QSPI_CONFIG(
    LCD_PCLK, LCD_D0, LCD_D1, LCD_D2, LCD_D3, 4096);

3. 添加型号专属QSPI初始化命令序列 #

仅设置use_qspi_interface = 1不足以让JC3248W535EN进入正确工作模式，需要自定义初始化命令覆盖默认流程：

static const axs15231b_lcd_init_cmd_t axs15231b_qspi_init_cmds[] = {
    // 退出休眠模式
    {0x11, {0}, 0x80},
    // 延迟120ms等待唤醒
    {0x00, {0}, 0x80 + 120},
    // 配置QSPI模式
    {0xBA, {0x06}, 1},
    // 设置16位RGB565像素格式
    {0x3A, {0x55}, 1},
    // 设置显示窗口（适配320x480分辨率）
    {0x2A, {0x00, 0x00, 0x01, 0x3F}, 4}, // 列地址0-319
    {0x2B, {0x00, 0x00, 0x01, 0xDF}, 4}, // 行地址0-479
    // 开启显示
    {0x29, {0}, 0x80},
    // 延迟10ms等待显示稳定
    {0x00, {0}, 0x80 + 10},
};

然后在厂商配置中指定该命令数组：

const axs15231b_vendor_config_t vendor_config = {
    .flags = {.use_qspi_interface = 1},
    .init_cmds = axs15231b_qspi_init_cmds,
    .init_cmds_size = sizeof(axs15231b_qspi_init_cmds) / sizeof(axs15231b_lcd_init_cmd_t)
};

4. 验证引脚电平与硬件连接 #

• 初始化前强制将CS引脚设为高电平（部分面板要求默认高电平）：

gpio_config_t cs_conf = {.pin_bit_mask = 1ULL << LCD_CS, .mode = GPIO_MODE_OUTPUT};
gpio_config(&cs_conf);
gpio_set_level(LCD_CS, 1);

• 手动指定QSPI时钟频率（不超过面板支持的60MHz，建议40MHz）：

const esp_lcd_panel_io_spi_config_t io_config = {
    .cs_gpio_num = LCD_CS,
    .pclk_hz = 40 * 1000 * 1000,
    .lcd_cmd_bits = 8,
    .lcd_param_bits = 8,
    .spi_mode = 0,
    .trans_queue_depth = 10,
};

解答你的疑问 #

1. 是否有人成功在ESP32-S3+ESP-IDF v5.x环境下通过QSPI初始化AXS15231B（JC3248W535EN）？
   是的，已有开发者成功驱动该型号，核心是匹配QSPI通信参数并添加型号专属初始化命令。

2. QSPI总线配置或面板配置中缺少哪些设置？

• 主机参数不匹配导致通信链路失效
• DMA缓冲区大小设置不合理引发隐性传输异常
• 缺少JC3248W535EN专属的QSPI模式初始化命令
• 引脚电平配置不符合面板要求

3. 是否必须使用自定义初始化命令？
   对于JC3248W535EN型号，建议强制使用自定义初始化命令。默认驱动的初始化流程未针对该型号的QSPI模式做适配，仅设置use_qspi_interface = 1无法让面板进入正确工作状态。

最终修改后的核心代码片段 #

static void lcd_init_qspi(void) {
    // 提前初始化CS引脚为高电平
    gpio_config_t cs_conf = {.pin_bit_mask = 1ULL << LCD_CS, .mode = GPIO_MODE_OUTPUT};
    gpio_config(&cs_conf);
    gpio_set_level(LCD_CS, 1);

    const spi_bus_config_t buscfg = AXS15231B_PANEL_BUS_QSPI_CONFIG(
        LCD_PCLK, LCD_D0, LCD_D1, LCD_D2, LCD_D3, 4096);
    ESP_ERROR_CHECK(spi_bus_initialize(SPI2_HOST, &buscfg, SPI_DMA_CH_AUTO));

    esp_lcd_panel_io_handle_t io_handle = NULL;
    const esp_lcd_panel_io_spi_config_t io_config = {
        .cs_gpio_num = LCD_CS,
        .pclk_hz = 40 * 1000 * 1000,
        .lcd_cmd_bits = 8,
        .lcd_param_bits = 8,
        .spi_mode = 0,
        .trans_queue_depth = 10,
        .dc_gpio_num = GPIO_NUM_NC, // QSPI模式无需DC引脚
    };
    ESP_ERROR_CHECK(esp_lcd_new_panel_io_spi((esp_lcd_spi_bus_handle_t)SPI2_HOST, &io_config, &io_handle));

    // 自定义QSPI初始化命令
    static const axs15231b_lcd_init_cmd_t axs15231b_qspi_init_cmds[] = {
        {0x11, {0}, 0x80},
        {0x00, {0}, 0x80 + 120},
        {0xBA, {0x06}, 1},
        {0x3A, {0x55}, 1},
        {0x2A, {0x00, 0x00, 0x01, 0x3F}, 4},
        {0x2B, {0x00, 0x00, 0x01, 0xDF}, 4},
        {0x29, {0}, 0x80},
        {0x00, {0}, 0x80 + 10},
    };

    const axs15231b_vendor_config_t vendor_config = {
        .flags = {.use_qspi_interface = 1},
        .init_cmds = axs15231b_qspi_init_cmds,
        .init_cmds_size = sizeof(axs15231b_qspi_init_cmds) / sizeof(axs15231b_lcd_init_cmd_t)
    };
    const esp_lcd_panel_dev_config_t panel_config = {
        .reset_gpio_num = LCD_RST,
        .rgb_ele_order  = LCD_RGB_ELEMENT_ORDER_RGB,
        .bits_per_pixel = 16,
        .vendor_config  = &vendor_config
    };
    ESP_ERROR_CHECK(esp_lcd_new_panel_axs15231b(io_handle, &panel_config, &panel_handle));
    ESP_ERROR_CHECK(esp_lcd_panel_reset(panel_handle));
    ESP_ERROR_CHECK(esp_lcd_panel_init(panel_handle));
    ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(panel_handle, true));
}

内容的提问来源于stack exchange，提问作者Miguel Garcia Silvestre