跳转至

tp - 触摸库

作者:江访

一、概述

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

主要特性

  • 支持多种触摸芯片(GT911、GT9157、JD9261T 等)
  • 硬件 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].xtp_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].xtp_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].xtp_data[1].y)
        end

四、函数详解

tp.init(tp_model, param, tp_callBack)

功能

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

注意事项

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

参数

tp_model

参数含义:触摸芯片型号
数据类型:string
是否必选:是
取值范围:"gt911", "gt9157", "jd9261t"
注意事项:必须正确指定芯片型号,否则初始化可能失败
参数示例:"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个触摸点的数据,
                    每个子表中包含eventxytimestamp四个参数,每个参数说明如下:
                    {
                        参数含义:返回的触摸事件类型
                        数据类型: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位系统,最大为232次方,换算下来不超过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 芯片

硬件要求

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

兼容性说明

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