64 tp-触摸控制
作者：江访 | 最后修改：2026-06-26
一、概述
tp 触摸库是 LuatOS 提供的底层触摸驱动库，负责与触摸芯片进行直接通信，获取原始触摸数据。该库支持多种主流触摸芯片，提供基础的触摸事件检测功能，是构建高级触摸应用的基础。
主要特性
- 支持多种触摸芯片："gt9xx"（自动匹配 gt911/gt1158/gt927）、"gt911"、"gt1158"、"gt927"、"gt9157"、"jd9261t"、"jd9261t_inited"、"cst820"、"cst816d"、"cst9220"、"ft3x68"
- 硬件 I2C 和软件 I2C 双支持，软件 I2C 默认每个操作有 5us 的延时，速度会比硬件 I2C 慢
- 提供原始触摸事件数据（按下、抬起、移动）
- 支持多点触摸数据获取，最多支持 10 个触摸点
- 支持坐标旋转方向配置（direction）
- 支持坐标轴镜像翻转配置（swap_xy）
- 支持中断触发类型配置（int_type）
- 支持触摸刷新率和触摸点数配置（refresh_rate / tp_num）
- 支持休眠和唤醒功能（tp.sleep / tp.wakeup）
- 单次初始化保护，tp.init 只能成功调用一次
二、核心示例
1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；
2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；
3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/ui/tp；
硬件 I2C 使用示例
-- 注册触摸回调函数
local function tp_callBack(tp_device, tp_data) -- tp_callBack函数必须此格式
log.info("TP回调", "触摸点数量:", #tp_data)
-- 发布触摸消息，携带触摸事件，x,y坐标三个参数
sys.publish("baseTouchEvent", tp_data[1].event, tp_data[1].x, tp_data[1].y)
end
-- 初始化I2C 0，设置为低速模式
i2c.setup(0, i2c.SLOW)
-- 初始化触摸芯片（GT911）
local tp_device = tp.init("gt911", {
port = 0, -- I2C端口号
pin_rst = 22, -- 复位引脚(有的厂家屏幕和触摸复位在一起，屏幕复位了触摸就不需要再复位，该参数可以不填或者填255)
pin_int = 23 -- 中断引脚
}, tp_callBack)
if tp_device then
log.info("TP初始化", "成功")
else
log.error("TP初始化", "失败")
end
-- UI主协程，触摸事件处理任务
local function ui_main()
while true do
-- 订阅触摸发布的消息，阻塞主循环，收到订阅消息则主循环继续运行
local result, event, arg1, arg2 = sys.waitUntil("baseTouchEvent")
if result then
if event == tp.EVENT_DOWN then
-- 处理按下事件
log.info("任务处理", "触摸按下",arg1, arg2)
end
end
end
end
-- 启用UI主协程
sys.taskInit(ui_main)
软件 I2C 使用示例
-- 注册触摸回调函数
local function tp_callBack(tp_device, tp_data) -- tp_callBack函数必须此格式
log.info("tp_callBack", "触摸点数量:", #tp_data)
-- 发布触摸消息，携带触摸事件，x,y坐标三个参数
sys.publish("baseTouchEvent", tp_data[1].event, tp_data[1].x, tp_data[1].y)
end
-- 创建软件I2C对象
local softI2C = i2c.createSoft(20, 21) -- SCL=20, SDA=21
-- 初始化触摸芯片（使用软件I2C）
local tp_device = tp.init("gt911", {
port = softI2C, -- 软件I2C对象
pin_rst = 22, -- 复位引脚(有的厂家屏幕和触摸复位在一起，屏幕复位了触摸就不需要再复位，引脚可以填255)
pin_int = 23, -- 中断引脚
w = 320, -- 屏幕宽度（可选）
h = 240 -- 屏幕高度（可选）
},tp_callBack)
if tp_device then
log.info("TP软件I2C初始化", "成功")
end
-- UI主协程，触摸事件处理任务
local function ui_main()
while true do
-- 订阅触摸发布的消息，阻塞主循环，收到订阅消息则主循环继续运行
local result, event, arg1, arg2 = sys.waitUntil("baseTouchEvent")
if result then
if event == tp.EVENT_DOWN then
-- 处理按下事件
log.info("任务处理", "触摸按下",arg1, arg2)
end
end
end
end
-- 启用UI主协程
sys.taskInit(ui_main)
三、常量详解
核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用。tp 触摸库定义了以下常量，用于标识触摸事件类型；
3.1 tp.EVENT_NONE
参数含义：空事件，实际不会出现这种事件；
数据类型：number
示例代码：如下方所示，为tp.EVENT_NONE常量的最基本写法；
if tp_data[1].event == tp.EVENT_NONE then
log.info("本次触摸无效")
end
3.2 tp.EVENT_DOWN
参数含义：触摸按下事件
数据类型：number
示例代码：如下方所示，为tp.EVENT_DOWN常量的最基本写法；
if tp_data[1].event == tp.EVENT_DOWN then
log.info("按下位置", tp_data[1].x，tp_data[1].y)
end
3.3 tp.EVENT_UP
参数含义：触摸抬手事件
数据类型：number
示例代码：如下方所示，为tp.EVENT_UP常量的最基本写法；
if tp_data[1].event == tp.EVENT_UP then
log.info("抬起位置", tp_data[1].x，tp_data[1].y)
end
3.4 tp.EVENT_MOVE
参数含义：触摸移动事件
数据类型：number
示例代码：如下方所示，为tp.EVENT_UP常量的最基本写法；
if tp_data[1].event == tp.EVENT_MOVE then
log.info("移动位置", tp_data[1].x，tp_data[1].y)
end
3.5 tp.EVENT_TYPE_DOWN / tp.EVENT_TYPE_UP / tp.EVENT_TYPE_MOVE
参数含义：与 tp.EVENT_DOWN / tp.EVENT_UP / tp.EVENT_MOVE 取值相同的别名常量
数据类型：number
注意事项：这些常量与对应 EVENT 常量取值完全一致，提供 EVENT_TYPE_ 命名风格作为备选
3.6 tp.SWAP_NONE / tp.SWAP_X / tp.SWAP_Y / tp.SWAP_XY
参数含义：坐标轴镜像翻转配置常量
数据类型：number
SWAP_NONE = 0 不翻转
SWAP_X = 1 X轴镜像翻转
SWAP_Y = 2 Y轴镜像翻转
SWAP_XY = 3 XY轴同时翻转
注意事项：用于 param.swap_xy 参数配置
3.7 tp.RISING / tp.FALLING
参数含义：中断触发类型常量
数据类型：number
RISING = 1 上升沿触发
FALLING = 2 下降沿触发
注意事项：用于 param.int_type 参数配置
四、函数详解
tp.init(tp_model, param, tp_callBack)
功能
初始化触摸芯片，配置相应的硬件参数和回调函数。
注意事项
在显示初始化后运行可不填屏幕高度和宽度，会从屏幕初始化数据中获取。在显示初始化前运行需要填屏幕高度和宽度，一般建议在屏幕初始化之后运行。
参数
tp_model
参数含义：触摸芯片型号
数据类型：string
是否必选：是
取值范围："gt9xx"、"gt911"、"gt1158"、"gt927"、"gt9157"、"jd9261t"、"jd9261t_inited"、"cst820"、"cst816d"、"cst9220"、"ft3x68"
注意事项：必须正确指定芯片型号，否则初始化可能失败
注意 gt911、gt1158、gt927 三个型号实际均使用 gt9xx 统一驱动，
也可以直接使用 "gt9xx" 作为通用型号名
参数示例："gt911"
param
参数含义：触摸芯片配置参数表，参数说明如下：
{
参数含义：I2C通信端口，可以是硬件I2C端口号（number类型）或软件I2C对象（userdata类型）
数据类型：number类型或userdata类型
取值范围：有效的硬件I2C端口号或由i2c.createSoft创建的软件I2C对象
是否必选：是
注意事项：如果不知道所接引脚对应是哪个端口，可以查看对应型号的引脚（管脚）复用表，
或者使用LuatIO引脚配置工具查看对应型号的管脚默认定义，LuatIO下载地址：
https://docs.openluat.com/air780epm/common/luatio/
参数示例：0（硬件I2C端口0）或softI2C（软件I2C对象）
参数名称： param.port参数含义：触摸芯片复位引脚GPIO号
数据类型：number
是否必选：否（若不填或填255表示无复位引脚，部分屏幕触摸复位与LCD复位共用）
取值范围：有效的GPIO引脚号
注意事项：如果不知道所接引脚对应是哪个GPIO号，可以查看对应型号的引脚（管脚）复用表，
或者使用LuatIO引脚配置工具查看对应型号的管脚默认定义，LuatIO下载地址：
https://docs.openluat.com/air780epm/common/luatio/
参数示例：22
参数名称： param.pin_rst参数含义：触摸芯片中断引脚
数据类型：number
是否必选：否
取值范围：有效的GPIO引脚号
注意事项：如不传入，默认为不启用中断。
参数示例：23 参数名称： param.pin_int参数含义：屏幕宽度像素值
数据类型：number
是否必选：否
取值范围：大于0的整数，省略此参数则默认值自动从已初始化的LCD获取，
注意事项：填非正整数会报错重启
参数示例：320
参数名称： param.w参数含义：屏幕高度像素值
数据类型：number
是否必选：否
取值范围：大于0的整数，省略此参数则默认值自动从已初始化的LCD获取，
注意事项：填非正整数会报错重启
参数示例：240参数含义：触摸坐标旋转方向
数据类型：number
是否必选：否
取值范围：0（不旋转）、1（90度）、2（180度）、3（270度）
注意事项：省略此参数则默认值自动从已初始化的LCD获取
参数示例：1
参数名称： param.direction参数含义：坐标轴镜像翻转
数据类型：number
是否必选：否
取值范围：tp.SWAP_NONE(0)、tp.SWAP_X(1)、tp.SWAP_Y(2)、tp.SWAP_XY(3)
注意事项：在 direction 旋转之后再应用 swap_xy
参数示例：1
参数名称： param.swap_xy参数含义：中断触发类型
数据类型：number
是否必选：否
取值范围：tp.RISING(1)、tp.FALLING(2)
注意事项：用于配置触摸芯片的中断触发边沿
参数示例：tp.FALLING
参数名称： param.int_type参数含义：触摸芯片读取刷新率
数据类型：number
是否必选：否
注意事项：部分触摸芯片可配置此参数来调整扫描频率
参数示例：10
参数名称： param.refresh_rate参数含义：支持的触摸点数
数据类型：number
是否必选：否
注意事项：部分触摸芯片可配置此参数来限制最大触摸点数
参数示例：5
参数名称： param.tp_num
}数据类型：table
取值范围：参数含义中规定的参数
是否必选：是
注意事项：暂无
tp_callBack
参数含义：注册的触摸事件回调函数，回调函数格式为：
function tp_callBack(tp_device, tp_data)
log.info("tp_callBack", tp_data[1].event, tp_data[1].x, tp_data[1].y)
end
回调函数接收有2个参数，tp_device和tp_data，以下是回调函数返回参数介绍：
参数含义：tp.init返回的触摸对象
数据类型：userdata
取值范围：无限制
是否必选：是
注意事项：此参数可以不用，但必须要写
tp_device
参数含义：tp.init返回的触摸数据
数据类型：table
取值范围：tp_data中最多包含10个子表，tp_data[1]、tp_data[2]、
tp_data[3]……tp_data[10]，也就最多支持触摸芯片同时上报10个触摸点的数据，
每个子表中包含event、track_id、x、y、width、timestamp六个参数，
每个参数说明如下：
{
参数含义：返回的触摸事件类型
数据类型：number
取值范围：tp.EVENT_NONE = 0 空事件,不应出现，
tp.EVENT_DOWN = 1 按下，
tp.EVENT_UP = 2 抬起，
tp.EVENT_MOVE = 3 移动，
注意事项：无
event = ,
参数含义：触摸点跟踪ID，用于识别同一触摸点在不同事件中的连续性
数据类型：number
注意事项：多指触摸时，同一手指的按下、移动、抬起事件共享同一个track_id
track_id = ,
参数含义：返回触摸点数的x坐标
数据类型：number
取值范围：0到屏幕宽度
注意事项：获取的坐标都是正整数，
同样使用该坐标计算产生的结果用于显示也必须是整数，
假设时用了产生了非整数，应该使用math.floor()向下取整后再使用，
否则会报错重启。
x = ,
参数含义：返回触摸点数的y坐标
数据类型：number
取值范围：0到屏幕高度
注意事项：获取的坐标都是正整数，
同样使用该坐标计算产生的结果用于显示也必须是整数，
假设时用了产生了非整数，应该使用math.floor()向下取整后再使用，
否则会报错重启。
y = ,
参数含义：触摸点面积/宽度
数据类型：number
注意事项：部分触摸芯片可返回触摸点的接触面积信息
width = ,
参数含义：返回触摸时对应的时间戳，单位ms，从系统运行开始计算
数据类型：number
取值范围：number
注意事项：该数值大小如果是32位系统，最大为2的32次方，换算下来不超过25天，
如果系统长时间不断电运行，又需要判断按压时间，
可以使用mcu.ticks2(1)返回的第二个参数来作为触摸时间判断依据；
timestamp = ,
}
是否必选：是
注意事项：触摸的产生的关键数据
tp_data
数据类型：function
取值范围：写在tp初始化前面且能调用到的函数
是否必选：否；
注意事项：所有触摸事件都会触发此参数表示的回调函数，并传递2个参数，tp_device和tp_data。
不使用lvgl时，必须传入回调函数处理触摸事件；
使用lvgl时，可不传入回调函数（或传nil），由lvgl自动处理触摸事件。
注意：tp.init 在release分支只能成功调用一次，重复调用会失败并报错"tp has been initialized!!!"。
返回值
local tpinit_result = tp.init(tp_model, param, tp_callback)
tpinit_result
含义说明：返回触摸设备对象
数据类型：userdata
取值范围：初始化成功返回触摸设备对象，初始化失败返回nil;
注意事项：无
返回示例：local tpinit_result = tp.init(tp_model, param, tp_callback)
log.info("tpinit_result ",tpinit_result )
成功会打印：tp_device userdata: 内存地址
失败会打印：tp_device nil
使用示例
-- 注册触摸回调函数
local function tp_callBack(tp_device, tp_data) -- tp_callBack函数必须此格式
log.info("TP回调", "触摸点数量:", #tp_data)
-- 发布触摸消息，携带触摸事件，x,y坐标三个参数
sys.publish("baseTouchEvent", tp_data[1].event, tp_data[1].x, tp_data[1].y)
end
-- 创建软件I2C对象
local softI2C = i2c.createSoft(20, 21) -- SCL=20, SDA=21
-- 初始化触摸芯片（使用软件I2C）
local tp_device = tp.init("gt911", {
port = softI2C, -- 软件I2C对象
pin_rst = 22, -- 复位引脚(有的厂家屏幕和触摸复位在一起，屏幕复位了触摸就不需要再复位，引脚可以填255)
pin_int = 23, -- 中断引脚
w = 320, -- 屏幕宽度（可选）
h = 240 -- 屏幕高度（可选）
},tp_callBack)
if tp_device then
log.info("TP软件I2C初始化", "成功")
end
-- UI主协程，触摸事件处理任务
local function ui_main()
while true do
-- 订阅触摸发布的消息，阻塞主循环，收到订阅消息则主循环继续运行
local result, event, arg1, arg2 = sys.waitUntil("baseTouchEvent")
if result then
if event == tp.EVENT_DOWN then
-- 处理按下事件
log.info("任务处理", "触摸按下",arg1, arg2)
end
end
end
end
-- 启用UI主协程
sys.taskInit(ui_main)
tp.sleep(tp_device)
功能
使触摸设备进入休眠模式。
参数
tp_device
参数含义：tp.init返回的触摸设备对象
数据类型：userdata
是否必选：是
注意事项：必须传入有效的触摸设备对象
返回值
含义说明：休眠操作结果
数据类型：boolean
取值范围：休眠成功返回true，失败返回false
注意事项：无
返回示例：local sleep_result = tp.sleep(tp_device)
log.info("sleep_result ", sleep_result)
使用示例
local function tp_callBack(tp_device, tp_data)
log.info("TP", tp_data[1].x, tp_data[1].y, tp_data[1].event)
sys.publish("TP", tp_device, tp_data)
end
tp_device = tp.init("gt911", {port = 0, pin_rst = 22, pin_int = 23}, tp_callBack)
tp.sleep(tp_device)
tp.wakeup(tp_device)
功能
唤醒触摸设备，使其从休眠模式恢复工作。
参数
tp_device
参数含义：tp.init返回的触摸设备对象
数据类型：userdata
是否必选：是
注意事项：必须传入有效的触摸设备对象
返回值
含义说明：唤醒操作结果
数据类型：boolean
取值范围：唤醒成功返回true，失败返回false
注意事项：无
返回示例：local wakeup_result = tp.wakeup(tp_device)
log.info("wakeup_result ", wakeup_result)
使用示例
local function tp_callBack(tp_device, tp_data)
log.info("TP", tp_data[1].x, tp_data[1].y, tp_data[1].event)
sys.publish("TP", tp_device, tp_data)
end
tp_device = tp.init("gt911", {port = 0, pin_rst = 22, pin_int = 23}, tp_callBack)
tp.sleep(tp_device)
-- 等待一段时间后唤醒
tp.wakeup(tp_device)
五、产品支持说明
支持的产品
tp 触摸库支持所有搭载兼容触摸芯片的 LuatOS 产品，可以查看选型手册对应型号及所使用的固件是否支持 tp 库
不同产品的LuatOS固件，对tp核心库的支持情况如下：
1、Air780EX2/Air700ECP/Air780EPM/Air780EGP 1号固件支持；
2、Air700ECH/Air780EHM/EHV/EGH/EGG/EHU/EHN/Air8000系列 所有固件都支持；
3、Air8101系列 所有固件都支持；
4、Air1601 / Air1602 都支持；
各产品固件支持核心库列表详细说明参考下面链接：
Air780EX2/Air700ECP/Air780EPM/Air780EGP固件支持列表
Air700ECH/Air780EHM/EHV/EGH/EGG/EHU/EHN固件支持列表
支持的触摸芯片
- gt9xx（统一驱动，自动匹配 gt911 / gt1158 / gt927 等型号）
- gt911
- gt1158
- gt927
- gt9157
- jd9261t
- jd9261t_inited（已预初始化的 jd9261t，某些场景下无需软件再发初始化序列）
- cst820
- cst816d
- cst9220
- ft3x68
硬件要求
- 支持 I2C 通信接口
- 需要复位引脚和中断引脚
- 触摸芯片正确连接到 I2C 总线
兼容性说明
- 硬件 I2C 和软件 I2C 均可使用