tp - 触摸库

作者：江访

一、概述

tp 触摸库是 LuatOS 提供的底层触摸驱动库，负责与触摸芯片进行直接通信，获取原始触摸数据。该库支持多种主流触摸芯片，提供基础的触摸事件检测功能，是构建高级触摸应用的基础。

主要特性

• 支持多种触摸芯片（GT911、GT9157、JD9261T、cst820等）
• 硬件 I2C 和软件 I2C 双支持，软件 I2C 默认每个操作有 5us 的延时，速度会比硬件 I2C 慢
• 提供原始触摸事件数据（按下、抬起、移动）
• 支持多点触摸数据获取

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考 LuatOS 仓库 中各个产品目录下的 demo/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
取值范围：0
示例代码：如下方所示，为tp.EVENT_NONE常量的最基本写法；
        if tp_data[1].event == tp.EVENT_NONE then
            log.info("本次触摸无效")
        end

3.2 tp.EVENT_DOWN

参数含义：触摸按下事件
数据类型：number
取值范围：1
示例代码：如下方所示，为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
取值范围：2
示例代码：如下方所示，为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
取值范围：3
示例代码：如下方所示，为tp.EVENT_UP常量的最基本写法；
        if tp_data[1].event == tp.EVENT_MOVE then
            log.info("移动位置", tp_data[1].x，tp_data[1].y)
        end

四、函数详解

tp.init(tp_model, param, tp_callBack)

功能

初始化触摸芯片，配置相应的硬件参数和回调函数。

注意事项

在显示初始化后运行可不填屏幕高度和宽度，会从屏幕初始化数据中获取。在显示初始化前运行需要填屏幕高度和宽度，一般建议在屏幕初始化之后运行。

参数

tp_model

参数含义：触摸芯片型号
数据类型：string
是否必选：是
取值范围："gt911", "gt9157", "jd9261t", "cst820"
注意事项：必须正确指定芯片型号，否则初始化可能失败
参数示例："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对象）
            port =  ,

            参数含义：触摸芯片复位引脚GPIO号
            数据类型：number
            是否必选：是
            取值范围：有效的GPIO引脚号
            注意事项：如果不知道所接引脚对应是哪个GPIO号，可以查看对应型号的引脚（管脚）复用表，
                    或者使用LuatIO引脚配置工具查看对应型号的管脚默认定义，LuatIO下载地址：
                    https://docs.openluat.com/air780epm/common/luatio/
            参数示例：22
            pin_rst =  ,

            参数含义：触摸芯片中断引脚
            数据类型：number
            是否必选：是
            取值范围：有效的GPIO引脚号
            注意事项：如果不知道所接引脚对应是哪个端口，可以查看对应型号的引脚（管脚）复用表，
                    或者使用LuatIO引脚配置工具查看对应型号的管脚默认定义，LuatIO下载地址：
                    https://docs.openluat.com/air780epm/common/luatio/
            参数示例：23
            pin_int =  ,

            参数含义：屏幕宽度像素值
            数据类型：number
            是否必选：否
            取值范围：大于0的整数，省略此参数则默认值自动从已初始化的LCD获取，
            注意事项：填非正整数会报错重启
            参数示例：320
            w =  ,

            参数含义：屏幕高度像素值
            数据类型：number
            是否必选：否
            取值范围：大于0的整数，省略此参数则默认值自动从已初始化的LCD获取，
            注意事项：填非正整数会报错重启
            参数示例：240
            h =  ,
        }
数据类型：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、x、y、timestamp四个参数，每个参数说明如下：
                    {
                        参数含义：返回的触摸事件类型
                        数据类型：number
                        取值范围：tp.EVENT_NONE = 0 空事件,不应出现，
                                 tp.EVENT_DOWN = 1 按下，
                                 tp.EVENT_UP = 2 抬起，
                                 tp.EVENT_MOVE = 3 移动，
                        注意事项：无
                        event  = ,

                        参数含义：返回触摸点数的x坐标
                        数据类型：number
                        取值范围：0到屏幕宽度
                        注意事项：获取的坐标都是正整数，
                                 同样使用该坐标计算产生的结果用于显示也必须是整数，
                                 假设时用了产生了非整数，应该使用math.floor()向下取整后再使用，
                                 否则会报错重启。
                        x  = ,

                        参数含义：返回触摸点数的y坐标
                        数据类型：number
                        取值范围：0到屏幕高度
                        注意事项：获取的坐标都是正整数，
                                 同样使用该坐标计算产生的结果用于显示也必须是整数，
                                 假设时用了产生了非整数，应该使用math.floor()向下取整后再使用，
                                 否则会报错重启。
                        y  = ,

                        参数含义：返回触摸时对应的时间戳，单位ms，从系统运行开始计算
                        数据类型：number
                        取值范围：number
                        注意事项：该数值大小如果是32位系统，最大为2的32次方，换算下来不超过25天，
                                 如果系统长时间不断电运行，又需要判断按压时间，
                                 可以使用mcu.ticks2(1)返回的第二个参数来作为触摸时间判断依据；
                        timestamp = ,
                        }         
            是否必选：是
            注意事项：触摸的产生的关键数据
            tp_data

数据类型：function
取值范围：写在tp初始化前面且能调用到的函数
是否必选：是；
注意事项：所有触摸事件都会触发此参数表示的回调函数，并传递2个参数，tp_device和tp_data。

返回值

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 触摸库支持所有搭载兼容触摸芯片的 LuatOS 产品，可以查看选型手册对应型号及所使用的固件是否支持 tp 库

支持的触摸芯片

• GT911 芯片
• GT9157 芯片
• JD9261T 芯片
• CST820 芯片

硬件要求

• 支持 I2C 通信接口
• 需要复位引脚和中断引脚
• 触摸芯片正确连接到 I2C 总线

兼容性说明

• 硬件 I2C 和软件 I2C 均可使用