ESP IoT Solution 组件实战基于 esp_lcd_touch_ili2118 驱动 ILI2118 触摸屏版本演进与 I2C 配置全解析【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution导读esp_lcd_touch_ili2118是 ESP IoT Solution 仓库中为 ILI2118ILITEK电容触摸控制器提供的官方驱动组件基于esp_lcd_touch抽象层实现通过 I2C 总线与主机通信。本文以该组件的 CHANGELOG.md 为脉络结合头文件、驱动源码与测试用例完整讲解其版本演进历程、底层寄存器协议、I2C 配置宏参数含义以及中断/轮询两种读取触摸数据的实战方案。读完本文你将能够独立完成 ILI2118 触摸屏在 ESP-IDF≥5.0工程中的接入、初始化、坐标读取与问题排查。组件概览一个面向 ILI2118 的 I2C 触摸驱动触摸控制器通信接口组件名称版本ILI2118ILI2118AI2Cesp_lcd_touch_ili2118v0.1.2组件核心实现位于 esp_lcd_touch_ili2118.c对外 API 与配置宏定义在 include/esp_lcd_touch_ili2118.h。从 idf_component.yml 可以看到其依赖约束idf: 5.0要求 ESP-IDF 5.0 及以上版本esp_lcd_touch: ^1依赖esp_lcd_touch抽象层组件public 依赖驱动最终注册为esp_lcd_touch_handle_tcmake_utilities: 0.*用于组件版本号自动管理对应 CMakeLists.txt 中的cu_pkg_define_version。从源码结构看该驱动实现了esp_lcd_touch接口的三要素read_data读原始触摸数据、get_xy取坐标与压力、del反初始化因此任何基于esp_lcd_touch的 GUI 或手势框架都可以直接复用。版本演进CHANGELOG 揭示的三个关键节点v0.0.12025-01-07驱动从零实现首个版本完成了 ILI2118 触摸控制器的完整驱动移植包含基于 I2C 的底层寄存器读写触摸坐标解析与屏幕分辨率换算中断 GPIO 配置与回调注册触摸信息固件版本、协议版本、原始分辨率读取。v0.1.12025-12-09API 迁移弃用旧接口该版本将文档与测试从已弃用的esp_lcd_touch_get_coordinates迁移到新接口esp_lcd_touch_get_data。新接口配合esp_lcd_touch_point_data_t结构体一次调用即可同时取得 x、y 坐标与触摸力度strength语义更清晰且不再需要分别传入touch_x/touch_y/touch_strength三个数组。这一迁移在 README.md 与 test_esp_lcd_touch_ili2118.c 中均已落地。v0.1.22026-04-21I2C 频率默认化开箱即用为配置宏ESP_LCD_TOUCH_IO_I2C_ILI2118A_CONFIG()补充了默认的 I2C 时钟频率100 kHz开发者无需手工指定scl_speed_hz即可完成 IO 层配置进一步降低了接入门槛。I2C 通信配置核心宏逐字段拆解esp_lcd_touch_ili2118通过 include/esp_lcd_touch_ili2118.h 中的两个宏完成与esp_lcd_panel_io_i2c_config_t的对接#define ESP_LCD_TOUCH_IO_I2C_ILI2118A_ADDRESS (0x4C 1) #define ESP_LCD_TOUCH_IO_I2C_ILI2118A_CONFIG() \ { \ .scl_speed_hz 100000, \ .dev_addr ESP_LCD_TOUCH_IO_I2C_ILI2118A_ADDRESS, \ .control_phase_bytes 1, \ .lcd_cmd_bits 16, \ .flags { \ .disable_control_phase 1, \ } \ }各字段含义与取值依据dev_addr 0x4C 1 0x26ILI2118A 的 7 位 I2C 从机地址。0x4C 是常见的 8 位写地址写法含 R/W 位右移一位得到标准 7 位地址这也是 ESP LCD 面板 IO 层约定的地址格式。scl_speed_hz 100000默认 SCL 时钟 100 kHz标准模式。v0.1.2 起由宏内建开发者仍可在初始化后自行覆盖。从 test_apps/main/test_esp_lcd_touch_ili2118.c 可以看到测试环境将总线配置为 90 kHzTEST_I2C_CLK_SPEED 90 * 1000说明该器件对 100 kHz 附近的标准速率均能稳定工作。control_phase_bytes 1、lcd_cmd_bits 16、disable_control_phase 1三者配合实现“无控制阶段、直接以 16 bit 命令/寄存器地址发起 I2C 读”的访问模式。ILI2118A 的寄存器采用 16 bit 地址编码例如 0x0011 读取触摸数据通过面板 IO 的rx_param/tx_param接口即可完成单次事务无需额外的控制字节相位。底层协议寄存器、魔数与坐标换算寄存器命令集源码顶部esp_lcd_touch_ili2118.c定义了驱动用到的全部寄存器命令宏值用途ILITEK_TP_CMD_READ_SUB_DATA0x11读取触摸子数据当前触点ILITEK_TP_CMD_GET_RESOLUTION0x20读取触摸屏原始分辨率ILITEK_TP_CMD_GET_FIRMWARE_VERSION0x40读取固件版本4 字节ILITEK_TP_CMD_GET_PROTOCOL_VERSION0x42读取协议版本2 字节触摸数据帧解析read_data()esp_lcd_touch_ili2118.c通过esp_lcd_panel_io_rx_param一次性读取 53 字节ILI2118_BUF_SIZE数据并以帧头魔数区分两种数据格式0x5A魔数帧有效坐标位于buf[1]..buf[3]其中raw_x ((buf[1] 0xF0) 4) | buf[2]raw_y ((buf[1] 0x0F) 8) | buf[3]0x99魔数帧有效坐标位于buf[6]..buf[8]其中 x/y 的拼接方式对调raw_y ((buf[6] 0xF0) 4) | buf[7]raw_x ((buf[6] 0x0F) 8) | buf[8]任何坐标字节为0xFFILI2118_INVALID_COORD时判定为无效触点不产生触摸事件。原始坐标到屏幕坐标的换算控制器上报的原始分辨率上限为 2048×2048TOUCH_MAX_WIDTH/TOUCH_MAX_HEIGHT驱动将其等比映射到应用配置的屏幕分辨率tp-data.coords[0].x (raw_x * tp-config.x_max) / TOUCH_MAX_WIDTH; tp-data.coords[0].y (raw_y * tp-config.y_max) / TOUCH_MAX_HEIGHT;因此esp_lcd_touch_config_t中的x_max/y_max应填写 LCD 面板的实际水平/垂直分辨率如 480×480保证触摸坐标与显示像素一一对应。设备信息自检read_info()esp_lcd_touch_ili2118.c在初始化时自动读取固件版本、协议版本、原始分辨率与通道数并通过日志打印Touch info: 480x480, protocol v1.0, firmware v1.0.0.0该输出可用于快速验证 I2C 链路与器件是否正常工作。工程接入与完整初始化流程添加依赖推荐通过 ESP-IDF 组件管理器添加idf.py add-dependency espressif/esp_lcd_touch_ili2118*或在工程根目录的idf_component.yml中声明依赖版本号以 CHANGELOG.md 记录的最新版 v0.1.2 为准亦可使用*自动获取最新dependencies: espressif/esp_lcd_touch_ili2118: ^0.1.2初始化代码以 README 示例为蓝本#include esp_lcd_touch_ili2118.h /* 1. I2C 面板 IO 配置v0.1.2 起频率已内建默认值 100 kHz */ esp_lcd_panel_io_i2c_config_t io_config ESP_LCD_TOUCH_IO_I2C_ILI2118A_CONFIG(); /* 2. 触摸参数配置分辨率与 LCD 对齐本例 RST/INT 不启用 */ esp_lcd_touch_config_t tp_cfg { .x_max CONFIG_LCD_HRES, /* 例如 480 */ .y_max CONFIG_LCD_VRES, /* 例如 480 */ .rst_gpio_num -1, .int_gpio_num -1, .levels { .reset 0, .interrupt 0, }, .flags { .swap_xy 0, .mirror_x 0, .mirror_y 0, }, }; /* 3. 创建触摸句柄 */ esp_lcd_touch_handle_t tp; esp_lcd_touch_new_i2c_ili2118(io_handle, tp_cfg, tp);提示io_handle需由esp_lcd_new_panel_io_i2c()基于同一个esp_lcd_i2c_bus_handle_t创建可与 LCD 面板共用 I2C 总线若启用中断可在tp_cfg.interrupt_callback中注册回调驱动会自动配置int_gpio_num的上升/下降沿中断由levels.interrupt决定。读取与消费触摸数据v0.1.1 起的新接口/* 周期性调用将触摸数据读入 RAM轮询或中断回调中均可 */ esp_lcd_touch_read_data(tp); /* 取出坐标与力度 */ esp_lcd_touch_point_data_t points[1] {0}; uint8_t touch_cnt 0; esp_lcd_touch_get_data(tp, points, touch_cnt, 1); if (touch_cnt 0) { ESP_LOGI(TAG, Touch position: [%d, %d], strength %d, count %d, points[0].x, points[0].y, points[0].strength, touch_cnt); }这是 v0.1.1 引入的标准用法esp_lcd_touch_get_data取代旧版esp_lcd_touch_get_coordinates一次调用同时返回坐标、力度与触点数量并自动清空内部缓冲避免重复消费。测试验证中断模式与轮询模式组件的单元测试位于 test_apps/main/test_esp_lcd_touch_ili2118.c包含两个典型场景[ili2118a][intr]中断模式注册touch_interrupt_callback在 ISR 中通过信号量唤醒任务触发后调用esp_lcd_touch_read_data读取数据3 秒窗口、30 ms 超时轮询信号量。该用例还验证了 ISR 安全的内存交互portYIELD_FROM_ISR。[ili2118a][poll]轮询模式不注册回调以固定 30 ms 周期循环调用esp_lcd_touch_read_dataesp_lcd_touch_get_data。测试环境参数sdkconfig.defaults可作为自定义工程模板GPIO18/GPIO8 分别作 SCL/SDAGPIO1/GPIO0 作 INT/RST分辨率 480×480。此外测试基架通过setUp/tearDown对比MALLOC_CAP_8BIT/MALLOC_CAP_32BIT堆水位检测驱动是否存在内存泄漏可直接复用该模式校验自定义工程。常见问题排查清单现象排查方向初始化日志无 “Touch info:” 输出检查 I2C 地址0x26与 SCL/SDA 接线、上拉电阻确认esp_lcd_new_panel_io_i2c已先于驱动创建执行触摸无响应确认x_max/y_max与 LCD 分辨率一致检查read_data调用频率是否足够建议 ≤ 30 ms 周期坐标反向或错位调整tp_cfg.flags中的swap_xy/mirror_x/mirror_y中断模式不进回调核对levels.interrupt电平与硬件实际触发沿确认int_gpio_num已正确配置总结esp_lcd_touch_ili2118以三个版本完成了从“驱动实现”到“API 现代化”再到“配置开箱即用”的演进v0.0.1 奠定了基于 I2C 的寄存器读写与坐标换算框架v0.1.1 全面迁移至esp_lcd_touch_get_data新接口v0.1.2 内建 100 kHz 默认 I2C 频率。结合 include/esp_lcd_touch_ili2118.h、esp_lcd_touch_ili2118.c 与测试用例开发者可以快速将 ILI2118 触摸屏接入 ESP-IDF 工程并依据本文的排查清单独立定位链路、配置与坐标映射问题。【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ESP IoT Solution 组件实战：基于 esp_lcd_touch_ili2118 驱动 ILI2118 触摸屏（版本演进与 I2C 配置全解析）
ESP IoT Solution 组件实战基于 esp_lcd_touch_ili2118 驱动 ILI2118 触摸屏版本演进与 I2C 配置全解析【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution导读esp_lcd_touch_ili2118是 ESP IoT Solution 仓库中为 ILI2118ILITEK电容触摸控制器提供的官方驱动组件基于esp_lcd_touch抽象层实现通过 I2C 总线与主机通信。本文以该组件的 CHANGELOG.md 为脉络结合头文件、驱动源码与测试用例完整讲解其版本演进历程、底层寄存器协议、I2C 配置宏参数含义以及中断/轮询两种读取触摸数据的实战方案。读完本文你将能够独立完成 ILI2118 触摸屏在 ESP-IDF≥5.0工程中的接入、初始化、坐标读取与问题排查。组件概览一个面向 ILI2118 的 I2C 触摸驱动触摸控制器通信接口组件名称版本ILI2118ILI2118AI2Cesp_lcd_touch_ili2118v0.1.2组件核心实现位于 esp_lcd_touch_ili2118.c对外 API 与配置宏定义在 include/esp_lcd_touch_ili2118.h。从 idf_component.yml 可以看到其依赖约束idf: 5.0要求 ESP-IDF 5.0 及以上版本esp_lcd_touch: ^1依赖esp_lcd_touch抽象层组件public 依赖驱动最终注册为esp_lcd_touch_handle_tcmake_utilities: 0.*用于组件版本号自动管理对应 CMakeLists.txt 中的cu_pkg_define_version。从源码结构看该驱动实现了esp_lcd_touch接口的三要素read_data读原始触摸数据、get_xy取坐标与压力、del反初始化因此任何基于esp_lcd_touch的 GUI 或手势框架都可以直接复用。版本演进CHANGELOG 揭示的三个关键节点v0.0.12025-01-07驱动从零实现首个版本完成了 ILI2118 触摸控制器的完整驱动移植包含基于 I2C 的底层寄存器读写触摸坐标解析与屏幕分辨率换算中断 GPIO 配置与回调注册触摸信息固件版本、协议版本、原始分辨率读取。v0.1.12025-12-09API 迁移弃用旧接口该版本将文档与测试从已弃用的esp_lcd_touch_get_coordinates迁移到新接口esp_lcd_touch_get_data。新接口配合esp_lcd_touch_point_data_t结构体一次调用即可同时取得 x、y 坐标与触摸力度strength语义更清晰且不再需要分别传入touch_x/touch_y/touch_strength三个数组。这一迁移在 README.md 与 test_esp_lcd_touch_ili2118.c 中均已落地。v0.1.22026-04-21I2C 频率默认化开箱即用为配置宏ESP_LCD_TOUCH_IO_I2C_ILI2118A_CONFIG()补充了默认的 I2C 时钟频率100 kHz开发者无需手工指定scl_speed_hz即可完成 IO 层配置进一步降低了接入门槛。I2C 通信配置核心宏逐字段拆解esp_lcd_touch_ili2118通过 include/esp_lcd_touch_ili2118.h 中的两个宏完成与esp_lcd_panel_io_i2c_config_t的对接#define ESP_LCD_TOUCH_IO_I2C_ILI2118A_ADDRESS (0x4C 1) #define ESP_LCD_TOUCH_IO_I2C_ILI2118A_CONFIG() \ { \ .scl_speed_hz 100000, \ .dev_addr ESP_LCD_TOUCH_IO_I2C_ILI2118A_ADDRESS, \ .control_phase_bytes 1, \ .lcd_cmd_bits 16, \ .flags { \ .disable_control_phase 1, \ } \ }各字段含义与取值依据dev_addr 0x4C 1 0x26ILI2118A 的 7 位 I2C 从机地址。0x4C 是常见的 8 位写地址写法含 R/W 位右移一位得到标准 7 位地址这也是 ESP LCD 面板 IO 层约定的地址格式。scl_speed_hz 100000默认 SCL 时钟 100 kHz标准模式。v0.1.2 起由宏内建开发者仍可在初始化后自行覆盖。从 test_apps/main/test_esp_lcd_touch_ili2118.c 可以看到测试环境将总线配置为 90 kHzTEST_I2C_CLK_SPEED 90 * 1000说明该器件对 100 kHz 附近的标准速率均能稳定工作。control_phase_bytes 1、lcd_cmd_bits 16、disable_control_phase 1三者配合实现“无控制阶段、直接以 16 bit 命令/寄存器地址发起 I2C 读”的访问模式。ILI2118A 的寄存器采用 16 bit 地址编码例如 0x0011 读取触摸数据通过面板 IO 的rx_param/tx_param接口即可完成单次事务无需额外的控制字节相位。底层协议寄存器、魔数与坐标换算寄存器命令集源码顶部esp_lcd_touch_ili2118.c定义了驱动用到的全部寄存器命令宏值用途ILITEK_TP_CMD_READ_SUB_DATA0x11读取触摸子数据当前触点ILITEK_TP_CMD_GET_RESOLUTION0x20读取触摸屏原始分辨率ILITEK_TP_CMD_GET_FIRMWARE_VERSION0x40读取固件版本4 字节ILITEK_TP_CMD_GET_PROTOCOL_VERSION0x42读取协议版本2 字节触摸数据帧解析read_data()esp_lcd_touch_ili2118.c通过esp_lcd_panel_io_rx_param一次性读取 53 字节ILI2118_BUF_SIZE数据并以帧头魔数区分两种数据格式0x5A魔数帧有效坐标位于buf[1]..buf[3]其中raw_x ((buf[1] 0xF0) 4) | buf[2]raw_y ((buf[1] 0x0F) 8) | buf[3]0x99魔数帧有效坐标位于buf[6]..buf[8]其中 x/y 的拼接方式对调raw_y ((buf[6] 0xF0) 4) | buf[7]raw_x ((buf[6] 0x0F) 8) | buf[8]任何坐标字节为0xFFILI2118_INVALID_COORD时判定为无效触点不产生触摸事件。原始坐标到屏幕坐标的换算控制器上报的原始分辨率上限为 2048×2048TOUCH_MAX_WIDTH/TOUCH_MAX_HEIGHT驱动将其等比映射到应用配置的屏幕分辨率tp-data.coords[0].x (raw_x * tp-config.x_max) / TOUCH_MAX_WIDTH; tp-data.coords[0].y (raw_y * tp-config.y_max) / TOUCH_MAX_HEIGHT;因此esp_lcd_touch_config_t中的x_max/y_max应填写 LCD 面板的实际水平/垂直分辨率如 480×480保证触摸坐标与显示像素一一对应。设备信息自检read_info()esp_lcd_touch_ili2118.c在初始化时自动读取固件版本、协议版本、原始分辨率与通道数并通过日志打印Touch info: 480x480, protocol v1.0, firmware v1.0.0.0该输出可用于快速验证 I2C 链路与器件是否正常工作。工程接入与完整初始化流程添加依赖推荐通过 ESP-IDF 组件管理器添加idf.py add-dependency espressif/esp_lcd_touch_ili2118*或在工程根目录的idf_component.yml中声明依赖版本号以 CHANGELOG.md 记录的最新版 v0.1.2 为准亦可使用*自动获取最新dependencies: espressif/esp_lcd_touch_ili2118: ^0.1.2初始化代码以 README 示例为蓝本#include esp_lcd_touch_ili2118.h /* 1. I2C 面板 IO 配置v0.1.2 起频率已内建默认值 100 kHz */ esp_lcd_panel_io_i2c_config_t io_config ESP_LCD_TOUCH_IO_I2C_ILI2118A_CONFIG(); /* 2. 触摸参数配置分辨率与 LCD 对齐本例 RST/INT 不启用 */ esp_lcd_touch_config_t tp_cfg { .x_max CONFIG_LCD_HRES, /* 例如 480 */ .y_max CONFIG_LCD_VRES, /* 例如 480 */ .rst_gpio_num -1, .int_gpio_num -1, .levels { .reset 0, .interrupt 0, }, .flags { .swap_xy 0, .mirror_x 0, .mirror_y 0, }, }; /* 3. 创建触摸句柄 */ esp_lcd_touch_handle_t tp; esp_lcd_touch_new_i2c_ili2118(io_handle, tp_cfg, tp);提示io_handle需由esp_lcd_new_panel_io_i2c()基于同一个esp_lcd_i2c_bus_handle_t创建可与 LCD 面板共用 I2C 总线若启用中断可在tp_cfg.interrupt_callback中注册回调驱动会自动配置int_gpio_num的上升/下降沿中断由levels.interrupt决定。读取与消费触摸数据v0.1.1 起的新接口/* 周期性调用将触摸数据读入 RAM轮询或中断回调中均可 */ esp_lcd_touch_read_data(tp); /* 取出坐标与力度 */ esp_lcd_touch_point_data_t points[1] {0}; uint8_t touch_cnt 0; esp_lcd_touch_get_data(tp, points, touch_cnt, 1); if (touch_cnt 0) { ESP_LOGI(TAG, Touch position: [%d, %d], strength %d, count %d, points[0].x, points[0].y, points[0].strength, touch_cnt); }这是 v0.1.1 引入的标准用法esp_lcd_touch_get_data取代旧版esp_lcd_touch_get_coordinates一次调用同时返回坐标、力度与触点数量并自动清空内部缓冲避免重复消费。测试验证中断模式与轮询模式组件的单元测试位于 test_apps/main/test_esp_lcd_touch_ili2118.c包含两个典型场景[ili2118a][intr]中断模式注册touch_interrupt_callback在 ISR 中通过信号量唤醒任务触发后调用esp_lcd_touch_read_data读取数据3 秒窗口、30 ms 超时轮询信号量。该用例还验证了 ISR 安全的内存交互portYIELD_FROM_ISR。[ili2118a][poll]轮询模式不注册回调以固定 30 ms 周期循环调用esp_lcd_touch_read_dataesp_lcd_touch_get_data。测试环境参数sdkconfig.defaults可作为自定义工程模板GPIO18/GPIO8 分别作 SCL/SDAGPIO1/GPIO0 作 INT/RST分辨率 480×480。此外测试基架通过setUp/tearDown对比MALLOC_CAP_8BIT/MALLOC_CAP_32BIT堆水位检测驱动是否存在内存泄漏可直接复用该模式校验自定义工程。常见问题排查清单现象排查方向初始化日志无 “Touch info:” 输出检查 I2C 地址0x26与 SCL/SDA 接线、上拉电阻确认esp_lcd_new_panel_io_i2c已先于驱动创建执行触摸无响应确认x_max/y_max与 LCD 分辨率一致检查read_data调用频率是否足够建议 ≤ 30 ms 周期坐标反向或错位调整tp_cfg.flags中的swap_xy/mirror_x/mirror_y中断模式不进回调核对levels.interrupt电平与硬件实际触发沿确认int_gpio_num已正确配置总结esp_lcd_touch_ili2118以三个版本完成了从“驱动实现”到“API 现代化”再到“配置开箱即用”的演进v0.0.1 奠定了基于 I2C 的寄存器读写与坐标换算框架v0.1.1 全面迁移至esp_lcd_touch_get_data新接口v0.1.2 内建 100 kHz 默认 I2C 频率。结合 include/esp_lcd_touch_ili2118.h、esp_lcd_touch_ili2118.c 与测试用例开发者可以快速将 ILI2118 触摸屏接入 ESP-IDF 工程并依据本文的排查清单独立定位链路、配置与坐标映射问题。【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考