esp-iot-solution 中 AXS15231B LCD 驱动演进解析：从 SPI 到 MIPI-DSI 的多接口支持与 ESP-IDF v6.0 兼容

esp-iot-solution 中 AXS15231B LCD 驱动演进解析从 SPI 到 MIPI-DSI 的多接口支持与 ESP-IDF v6.0 兼容【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solutionAXS15231B 是 ESP32 生态中一款同时集成 LCD 控制器与电容触摸控制器的显示芯片本文以 esp_lcd_axs15231b 组件 的 CHANGELOG.md 为主线结合 README.md 与源码实现梳理该驱动从 v1.0.0 到 v2.1.0 的演进脉络并详解其在 I80/SPI/QSPI/MIPI-DSI 四种接口下的初始化流程、触摸数据读取原理以及如何用esp_lcd_touch_get_data()替代已废弃 API。读完本文你将能独立完成 AXS15231B 屏的接入、排障与接口切换。一、驱动版本演进总览CHANGELOG.md 完整记录了该驱动的发布历史核心时间线与能力变化如下版本日期类型关键内容v1.0.02024-02-29Enhancements实现 AXS15231B LCD 控制器驱动初版v1.0.12025-03-09Bugfix修复使用i2c_master时无法设置scl_speed_hz导致 SCL 频率无效的问题v2.0.02025-10-29Enhancements兼容 ESP-IDF v6.0v2.0.12025-12-10Changes文档与测试改用esp_lcd_touch_get_data替换已废弃的esp_lcd_touch_get_coordinatesv2.0.22025-12-10Bugfix修复draw_bitmap未向上传播 tx_color 错误防止 SPI 传输失败时系统死锁v2.1.02026-01-21Enhancements新增 MIPI-DSI 接口支持兼容 ESP-IDF v6.0从版本节奏可以看出该驱动沿着功能补全 → 接口扩展 → 兼容性维护的路径演进v1.0.0 奠定 I80/SPI/QSPI 三种传统并行/串行接口的基础v2.x 系列一方面适配 ESP-IDF v6.0 的 API 变化另一方面通过 v2.1.0 引入 MIPI-DSI 这一面向高带宽、高分辨率场景的新型接口。当前组件版本号为 2.1.0声明依赖idf: 5.3与esp_lcd_touch: ^1见 idf_component.yml。二、组件能力与接口矩阵在进入代码细节前先建立整体认知。驱动覆盖 LCD 面板控制与触摸控制两大部分LCD 侧支持四种通信接口接口特点典型应用场景I80Intel 80808 位并行总线20 MHz 像素时钟中低分辨率、快速刷屏SPI单线串行40 MHz 时钟SPI Mode 3引脚受限场景QSPI四线串行40 MHz 时钟提升串行吞吐MIPI-DSI1 通道数据线720 Mbps/laneDPI 视频模式高分辨率、高帧率触摸侧则固定通过 I2C从机地址0x3B与主控通信单点触控AXS_MAX_TOUCH_NUMBER 1相关常量与配置宏定义在 esp_lcd_axs15231b.h 中。2.1 底层驱动的版本号打印值得注意驱动对象创建成功后会在日志中打印组件版本号ESP_LOGI(TAG, LCD panel create success, version: %d.%d.%d, ESP_LCD_AXS15231B_VER_MAJOR, ESP_LCD_AXS15231B_VER_MINOR, ESP_LCD_AXS15231B_VER_PATCH);该实现位于 esp_lcd_axs15231b.c版本号宏在头文件中定义。排查问题时可通过串口日志快速确认固件中集成的驱动版本与 CHANGELOG 逐条对应。三、LCD 面板初始化四种接口的配置与流程无论使用哪种接口初始化遵循统一范式初始化总线 → 创建 panel IO → 构造 vendor_config 与 panel_config → 创建面板驱动 → reset → init → 亮屏。下面按接口分别说明。3.1 SPI 接口SPI 是默认接口其总线与 IO 配置宏均以 40 MHz 像素时钟、SPI Mode 3 为默认值见 esp_lcd_axs15231b.h 与AXS15231B_PANEL_IO_SPI_CONFIGESP_LOGI(TAG, Initialize SPI bus); const spi_bus_config_t buscfg AXS15231B_PANEL_BUS_SPI_CONFIG(EXAMPLE_PIN_NUM_LCD_PCLK, EXAMPLE_PIN_NUM_LCD_DATA0, EXAMPLE_LCD_H_RES * 80 * sizeof(uint16_t)); ESP_ERROR_CHECK(spi_bus_initialize(EXAMPLE_LCD_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 AXS15231B_PANEL_IO_SPI_CONFIG(EXAMPLE_PIN_NUM_LCD_CS, EXAMPLE_PIN_NUM_LCD_DC, callback, callback_data); ESP_ERROR_CHECK(esp_lcd_new_panel_io_spi((esp_lcd_spi_bus_handle_t)EXAMPLE_LCD_HOST, io_config, io_handle));其中AXS15231B_PANEL_BUS_SPI_CONFIG展开为sclk_io_num、mosi_io_num、max_transfer_sz并将miso_io_num、quadhd_io_num、quadwp_io_num置为 -1即纯写屏场景。随后构造厂商配置与面板配置const axs15231b_vendor_config_t vendor_config { .flags { .use_qspi_interface 0, // 默认 SPI 接口 }, }; const esp_lcd_panel_dev_config_t panel_config { .reset_gpio_num EXAMPLE_PIN_NUM_LCD_RST, .rgb_ele_order LCD_RGB_ELEMENT_ORDER_RGB, // 由 LCD 命令 36h 实现 .bits_per_pixel 16, // 由 LCD 命令 3Ah 实现16/18 .vendor_config vendor_config, }; ESP_ERROR_CHECK(esp_lcd_new_panel_axs15231b(io_handle, panel_config, panel_handle)); esp_lcd_panel_reset(panel_handle); esp_lcd_panel_init(panel_handle); esp_lcd_panel_disp_on_off(panel_handle, true);3.2 QSPI 接口QSPI 与 SPI 的唯一区别在于总线使用 4 根数据线D0~D3且vendor_config.flags.use_qspi_interface必须置 1const spi_bus_config_t buscfg AXS15231B_PANEL_BUS_QSPI_CONFIG(EXAMPLE_PIN_NUM_LCD_PCLK, EXAMPLE_PIN_NUM_LCD_DATA0, EXAMPLE_PIN_NUM_LCD_DATA1, EXAMPLE_PIN_NUM_LCD_DATA2, EXAMPLE_PIN_NUM_LCD_DATA3, EXAMPLE_LCD_H_RES * 80 * sizeof(uint16_t)); ESP_ERROR_CHECK(spi_bus_initialize(EXAMPLE_LCD_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 AXS15231B_PANEL_IO_QSPI_CONFIG(EXAMPLE_PIN_NUM_LCD_CS, callback, callback_data); ESP_ERROR_CHECK(esp_lcd_new_panel_io_spi((esp_lcd_spi_bus_handle_t)EXAMPLE_LCD_HOST, io_config, io_handle));QSPI 模式下AXS15231B_PANEL_IO_QSPI_CONFIG将dc_gpio_num置为 -1无需 DC 线并设置lcd_cmd_bits 32、flags.quad_mode true。这一点与源码中的命令封装逻辑呼应在 esp_lcd_axs15231b.c 中tx_param与tx_color在 QSPI 模式下会将命令字节拼入 32 位操作码——LCD_OPCODE_WRITE_CMD (0x02)用于写命令、LCD_OPCODE_WRITE_COLOR (0x32)用于写像素数据、LCD_OPCODE_READ_CMD (0x0B)用于读从而在一个 32 位指令周期内同时携带操作码 命令。3.3 I80 接口I80 并行接口的配置更为直接AXS15231B_PANEL_IO_I80_CONFIG默认 8 位数据总线、20 MHz 像素时钟、队列深度 10并显式指定 DC 电平的四种状态idle/cmd/dummy/dataESP_LOGI(TAG, Initialize Intel 8080 bus); ESP_ERROR_CHECK(esp_lcd_new_i80_bus(bus_config, i80_bus)); esp_lcd_panel_io_handle_t io_handle NULL; const esp_lcd_panel_io_i80_config_t io_config AXS15231B_PANEL_IO_I80_CONFIG(EXAMPLE_PIN_NUM_LCD_CS, EXAMPLE_PIN_NUM_LCD_DC, example_callback, example_callback_ctx); ESP_ERROR_CHECK(esp_lcd_new_panel_io_i80(i80_bus, io_config, io_handle));I80 场景的vendor_config可以保持默认不设 flags即非 QSPI、非 MIPI仅当需要自定义初始化序列时传入init_cmds。三种接口共用一个esp_lcd_new_panel_axs15231b()入口源码通过vendor_config-flags.use_mipi_interface与use_qspi_interface做接口分流esp_lcd_axs15231b.c且两个标志同时为 1 时会返回ESP_ERR_NOT_SUPPORTED。3.4 MIPI-DSI 接口v2.1.0 新增MIPI-DSI 是 v2.1.0 的核心增强需要芯片支持SOC_MIPI_DSI_SUPPORTED当前仓库中 ESP32-P4 等目标平台满足。其初始化链路与前面三种接口差异显著分为四步第一步为 MIPI PHY 供电。DSI PHY 需要 LDO 供电通过esp_ldo_acquire_channel()申请esp_ldo_channel_config_t ldo_mipi_phy_config { .chan_id EXAMPLE_MIPI_DSI_PHY_PWR_LDO_CHAN, .voltage_mv EXAMPLE_MIPI_DSI_PHY_PWR_LDO_VOLTAGE_MV, }; ESP_ERROR_CHECK(esp_ldo_acquire_channel(ldo_mipi_phy_config, ldo_mipi_phy));第二步创建 DSI 总线与 DBI IO。AXS15231B_PANEL_BUS_DSI_1CH_CONFIG()默认单数据通道、lane_bit_rate_mbps 720esp_lcd_dsi_bus_config_t bus_config AXS15231B_PANEL_BUS_DSI_1CH_CONFIG(); ESP_ERROR_CHECK(esp_lcd_new_dsi_bus(bus_config, mipi_dsi_bus)); esp_lcd_dbi_io_config_t dbi_config AXS15231B_PANEL_IO_DBI_CONFIG(); ESP_ERROR_CHECK(esp_lcd_new_panel_io_dbi(mipi_dsi_bus, dbi_config, mipi_dbi_io));第三步配置 DPI 视频时序并传入 vendor_config。这里需要根据 ESP-IDF 版本选择不同的配置宏——v6.0 中 DPI 配置结构体的颜色格式字段更名因此驱动分别提供AXS15231B_240_960_PANEL_60HZ_DPI_CONFIGIDF 6.0与AXS15231B_240_960_PANEL_60HZ_DPI_CONFIG_CFIDF ≥ 6.0使用in_color_format字段这是兼容 ESP-IDF v6.0在源码层面的直接体现#if ESP_IDF_VERSION ESP_IDF_VERSION_VAL(6, 0, 0) esp_lcd_dpi_panel_config_t dpi_config AXS15231B_240_960_PANEL_60HZ_DPI_CONFIG(LCD_COLOR_PIXEL_FORMAT_RGB888); #else esp_lcd_dpi_panel_config_t dpi_config AXS15231B_240_960_PANEL_60HZ_DPI_CONFIG_CF(LCD_COLOR_PIXEL_FORMAT_RGB888); #endif axs15231b_vendor_config_t vendor_config { .flags { .use_mipi_interface 1, }, .mipi_config { .dsi_bus mipi_dsi_bus, .dpi_config dpi_config, }, };240×960 分辨率下的默认视频时序为h_size 240、v_size 960水平方向hsync_back_porch 66、hsync_pulse_width 10、hsync_front_porch 55垂直方向vsync_back_porch 62、vsync_pulse_width 10、vsync_front_porch 100DPI 时钟 25 MHz头文件注释给出了刷新率计算公式refresh_rate dpi_clock_freq_mhz * 1e6 / (h_res hsync 三参数之和) / (v_res vsync 三参数之和)。MIPI 模式下面板配置的bits_per_pixel设为 24RGB888。第四步创建面板并初始化。与前面接口相同仍走esp_lcd_new_panel_axs15231b()但源码内部检测到use_mipi_interface后会转交esp_lcd_new_panel_axs15231b_mipi()实现在 esp_lcd_axs15231b_mipi.c。MIPI 实现的巧妙之处在于它先创建 ESP-IDF 标准的 MIPI DPI 面板然后保存其原始del/init函数指针再覆写init、reset、mirror、invert_color、disp_on_off等回调把 AXS15231B 的厂商初始化序列插入 DPI 视频模式的前后实现命令模式初始化 视频模式显示的双阶段衔接。init_in_command_mode标志控制初始化命令是在 DPI 面板 init 之前还是之后发送。四、面板功能回调与初始化序列源码解读4.1 默认厂商初始化序列panel_axs15231b_init()在退出睡眠模式LCD_CMD_SLPOUT等待 100 ms后依次下发MADCTL36h与COLMOD3Ah设置色彩方向与像素格式随后执行初始化命令表esp_lcd_axs15231b.c色彩方向映射rgb_ele_order LCD_RGB_ELEMENT_ORDER_RGB时madctl_val 0LCD_RGB_ELEMENT_ORDER_BGR时置LCD_CMD_BGR_BITbits_per_pixel 16对应colmod_val 0x55RGB56518对应0x66RGB666像素按 3 字节 24 bit 送入 framebuffer。MIPI 路径额外支持24对应0x77RGB888。命令表结构axs15231b_lcd_init_cmd_t由{cmd, data, data_bytes, delay_ms}四元组构成默认序列以0xBB/0xA0~0xE5等厂商寄存器配置开场以0x11Sleep Out、0x29Display ON、0x2CRAM Write、0x22All Pixels Off收尾共 30 条命令。自定义覆盖机制若通过vendor_config.init_cmds传入自定义序列且其中出现MADCTL/COLMOD驱动会警告该命令已被使用并会被外部序列覆盖ESP_LOGW并同步更新内部保存的madctl_val/colmod_val。4.2 draw_bitmap 与 v2.0.2 的死锁修复draw_bitmap的流程是先发CASET列地址非 QSPI 模式下再发RASET行地址然后按(x_end - x_start) * (y_end - y_start) * fb_bits_per_pixel / 8计算帧数据长度通过RAMWR (2Ch)或RAMWRC写入像素esp_lcd_axs15231b.c。值得注意的是y_start 0时使用RAMWR否则使用RAMWRC带自动刷屏的 RAM 写命令。v2.0.2 修复的正是这里的问题此前tx_color()的返回值未被检查当 SPI 传输失败如 DMA 超时、总线错误时错误被静默吞掉上层任务可能因此阻塞在等待传输完成信号量上最终导致系统死锁。修复后错误沿ESP_RETURN_ON_ERROR逐级上抛调用方如 LVGL 的 flush 回调能及时感知并进入错误恢复路径。4.3 屏幕方向控制mirror()与swap_xy()均通过改写MADCTL寄存器的MX/MY/MV位实现set_gap()则记录x_gap/y_gap并在draw_bitmap的CASET/RASET计算中叠加偏移。MIPI 路径稍有差异mirror x会打印not supported警告且其mirror y实际使用的是MV位esp_lcd_axs15231b_mipi.c与并行/串行接口的实现不同移植屏幕方向逻辑时需留意。五、触摸控制器I2C 读写与坐标上报5.1 触摸 IO 配置触摸部分通过 I2C 通信从机地址固定为0x3BESP_LCD_TOUCH_IO_I2C_AXS15231B_ADDRESS。驱动提供两个 IO 配置宏基础版ESP_LCD_TOUCH_IO_I2C_AXS15231B_CONFIG()与带时钟参数的..._CONFIG_EX(scl_speed_hz)。后者正是 v1.0.1 修复的落点——此前在i2c_master驱动下该字段缺失导致 SCL 频率取到无效值新增scl_speed_hz字段后用户可显式指定时钟频率避免invalid scl frequency错误。esp_lcd_panel_io_i2c_config_t io_config ESP_LCD_TOUCH_IO_I2C_AXS15231B_CONFIG(); esp_lcd_panel_io_handle_t io_handle NULL; ESP_ERROR_CHECK(esp_lcd_new_panel_io_i2c(i2c_bus_handle, io_config, io_handle)); esp_lcd_touch_config_t tp_cfg { .x_max CONFIG_LCD_HRES, .y_max CONFIG_LCD_VRES, .rst_gpio_num -1, .int_gpio_num -1, .levels { .reset 0, .interrupt 0 }, .flags { .swap_xy 0, .mirror_x 0, .mirror_y 0 }, }; esp_lcd_touch_handle_t tp; esp_lcd_touch_new_i2c_axs15231b(io_handle, tp_cfg, tp);5.2 触摸数据读取链路触摸驱动实现了标准esp_lcd_touch回调read_data/get_xy/del/reset。read_data的底层协议比较特殊先通过 I2C 写入一段 11 字节的读指令头{0xb5, 0xab, 0xa5, 0x5a, 0x00, 0x00, len_hi, len_lo, 0x00, 0x00, 0x00}再连续读取AXS_MAX_TOUCH_NUMBER * 6 2 8字节数据。返回数据按位域结构解析typedef struct { uint8_t gesture; // 手势偏移 0 uint8_t num; // 触点个数偏移 1 uint8_t x_h : 4; // X 高 4 位偏移 2 uint8_t : 2; uint8_t event : 2; // 触摸事件偏移 2 uint8_t x_l; // X 低 8 位偏移 3 uint8_t y_h : 4; // Y 高 4 位偏移 4 uint8_t : 4; uint8_t y_l; // Y 低 8 位偏移 5 } __attribute__((packed)) touch_record_struct_t;坐标合成逻辑为x ((x_h 0x0F) 8) | x_l、y ((y_h 0x0F) 8) | y_lesp_lcd_axs15231b.c数据在临界区保护下写入tp-data.coordsget_xy再从缓冲区读取并清空触点计数。驱动为单点触控设计AXS_MAX_TOUCH_NUMBER 1若需多点需修改该宏并调整缓冲大小。5.3 应用层读取坐标v2.0.1 的 API 迁移触摸数据应在轮询循环中周期调用esp_lcd_touch_read_data(tp)刷新随后用新 API 读取坐标esp_lcd_touch_read_data(tp); uint16_t touch_x[1], touch_y[1], touch_strength[1]; uint8_t touch_cnt 0; esp_lcd_touch_point_data_t points[1] {0}; esp_lcd_touch_get_data(tp, points, touch_cnt, 1); if (touch_cnt 0) { touch_x[0] points[0].x; touch_y[0] points[0].y; touch_strength[0] points[0].strength; }v2.0.1 将文档与测试全部迁移到esp_lcd_touch_get_data()替代已废弃的esp_lcd_touch_get_coordinates()。新 API 采用esp_lcd_touch_point_data_t结构体数组传递坐标与压力值并支持同时上报多个触点。仓库测试用例 test_esp_lcd_axs15231b.c 即以此方式轮询触摸坐标并打印可作为接入新代码的参考模板。注意该组件依赖esp_lcd_touch: ^1新 API 仅在使用 1.x 以上版本的esp_lcd_touch时可用。六、测试与验证体系组件目录下提供了完整的测试与 CI 支撑test_esp_lcd_axs15231b.c覆盖并行/串行接口下的面板初始化、draw_bitmap、屏幕方向设置与触摸坐标读取test_esp_lcd_axs15231b_mipi.cMIPI-DSI 路径的专项测试与 v2.1.0 新增接口同步落地pytest_esp_lcd_axs15231b.py 与 sdkconfig.defaults、sdkconfig.defaults.esp32p4分别为 pytest 硬件测试脚本与不同目标芯片的配置模板。若需在本地验证可将组件作为依赖加入项目后运行idf.py build与idf.py flash monitor观察日志中LCD panel create success与版本号输出。七、版本升级与迁移建议结合 CHANGELOG升级驱动的注意事项可归纳为四点API 层面若旧代码仍调用esp_lcd_touch_get_coordinates需迁移到esp_lcd_touch_get_data并按esp_lcd_touch_point_data_t结构调整坐标读取逻辑接口层面v2.1.0 起支持 MIPI-DSIaxs15231b_vendor_config_t增加了mipi_config联合体与use_mipi_interface标志使用 MIPI 前需确认目标芯片支持SOC_MIPI_DSI_SUPPORTED并完成 DSI PHY 的 LDO 供电配置IDF 兼容层面针对 ESP-IDF v6.0DPI 配置宏已切换为AXS15231B_240_960_PANEL_60HZ_DPI_CONFIG_CF升级 IDF 时注意选用与版本匹配的宏错误处理层面v2.0.2 后draw_bitmap会如实向上传播传输错误应用层 flush 回调应正确处理非ESP_OK返回值避免在 SPI 异常时继续阻塞等待。八、总结AXS15231B 驱动的版本历史完整呈现了一款成熟 LCD/触摸组件的成长路径从 2024 年 v1.0.0 的接口初建到 v1.0.1 的 I2C 时钟修复、v2.0.x 的 ESP-IDF v6.0 适配与 API 迁移、错误传播加固再到 v2.1.0 的 MIPI-DSI 能力上线。对开发者而言CHANGELOG.md 不只是变更流水账更是一份何时该升级、升级后要改什么的迁移手册而 esp_lcd_axs15231b.c 与 esp_lcd_axs15231b_mipi.c 则为理解接口分派、命令封装与触摸协议提供了完整源码级依据。无论是接入新屏、切换接口还是排查显示异常本文梳理的配置宏、初始化序列与回调实现都能作为直接参考。【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考