TP Development Guide_Rev1.0

Revision History

Version	Date	Author	Revision Details
Rev1.0	26-06-02	ZXQ	Created the TP development guide document

1 Introduction

1.1 Document Introduction

This document describes the LTE-EC71X TP (Touch Panel) interface API. The API is declared in:

components/kernel/lierda_api/liot_tp/liot_tp.h.

The TP driver framework supports connecting touch panel controllers through I2C or SPI. It provides unified APIs to the application layer for initialization, touch point reading, gesture reading, interrupt callback, sleep and wakeup, reset, firmware upgrade, and IC information reading.

The current SDK examples support the AXS5106 and CST816D touch panel controllers. The driver files are located at:

components/driver/tp/axs5106/axs5106/liot_tpDev_AXS5106.c
components/driver/tp/axs5106/cst816d/liot_tpDev_CST816D.c

The example code is located at:

examples/demo/src/demo_tp.c.

For different modules and hardware boards, the TP interface pins, I2C channel, I2C address, RST pin, and INT pin must follow the actual hardware schematic and the corresponding Pin Multiplexing Table.

1.2 TP Principle Introduction

A TP is usually composed of a touch panel controller IC, touch sensor, communication bus, reset pin, and interrupt pin. The touch panel controller IC collects touch coordinates, touch events, and gesture information. The main controller reads register data from the controller IC through I2C or SPI.

Typical TP hardware connections are as follows:

I2C/SPI bus: Used to read and write TP controller IC registers.
RST: Resets the TP controller IC. It can be used for initialization, wakeup, or abnormal recovery.
INT: Touch event interrupt signal. When a touch occurs, the TP controller IC drives the interrupt pin to notify the main controller.
Power supply: The TP controller IC power-on timing must meet the requirements of the panel vendor or IC vendor.

Main TP framework features:

Unified device abstraction: Different TP chips are registered to the unified framework through liot_tp_sensor_t.
I2C/SPI adaptive register access: Drivers can access registers through liot_tp_reg_read() and liot_tp_reg_write().
Touch point reading: Supports reading the number of touch points, coordinates, events, weight, and timestamp.
Gesture reading: Supports gesture types such as swipe up, swipe down, swipe left, swipe right, zoom, and long press.
Interrupt callback: Supports registering touch and gesture callbacks. After INT polling is started, data is automatically read.
Low-power control: Supports sleep, wakeup, and work mode switching.
Firmware upgrade: Supports executing firmware upgrade or automatic upgrade through the chip driver.

2 API Function Overview

Function	Description
`liot_tp_init()`	Initializes the TP and returns a TP handle
`liot_tp_deinit()`	Deinitializes the TP
`liot_tp_read_touch()`	Reads touch point data
`liot_tp_read_gesture()`	Reads gesture data
`liot_tp_set_threshold()`	Sets the touch threshold
`liot_tp_sleep()`	Puts the TP into sleep
`liot_tp_wakeup()`	Wakes up the TP
`liot_tp_reset()`	Performs a TP software reset
`liot_tp_hard_reset()`	Performs a hardware reset through the RST pin
`liot_tp_reg_write()`	Writes a TP register, with I2C/SPI adaptive access
`liot_tp_reg_read()`	Reads a TP register, with I2C/SPI adaptive access
`liot_tp_reg_write_byte()`	Writes a TP single-byte register
`liot_tp_reg_read_byte()`	Reads a TP single-byte register
`liot_tp_reg_write_bit()`	Performs a bit write operation on a TP register
`liot_tp_get_event_flags()`	Gets the TP event group handle
`liot_tp_register_int_callback()`	Registers TP interrupt touch/gesture callbacks
`liot_tp_enable_int()`	Starts or stops INT event polling
`liot_tp_update_firmware()`	Executes a TP firmware upgrade
`liot_tp_set_work_mode()`	Sets the TP work mode
`liot_tp_get_ic_info()`	Gets TP IC information
`cst8xxT_set_i2c_config()`	Sets the I2C channel and RST pin required for CST8xxT firmware upgrade
`cst816d_set_i2c_config()`	Sets the I2C channel and RST pin required for CST816D firmware upgrade
`cst816d_auto_update_firmware()`	Automatically upgrades CST816D using built-in firmware
`axs5106_auto_update_firmware()`	Automatically upgrades AXS5106 using built-in firmware

3 Type Descriptions

3.1 liot_tp_handle_t

The TP handle type is defined as follows:

Definition

typedef void *liot_tp_handle_t;

Parameters

liot_tp_handle_t: TP device handle returned by liot_tp_init() and passed to other TP API calls.

3.2 liot_errcode_tp_e

Error codes for TP API execution results.

Definition

typedef enum {
    LIOT_TP_SUCCESS = LIOT_SUCCESS,
    LIOT_TP_ERR_INIT = (0x10) | LIOT_COMPONENT_STATE_INFO,
    LIOT_TP_ERR_BUS,
    LIOT_TP_ERR_PARAM,
    LIOT_TP_ERR_HANDLE,
    LIOT_TP_ERR_TIMEOUT,
    LIOT_TP_ERR_NOT_SUPPORTED,
} liot_errcode_tp_e;

Parameters

LIOT_TP_SUCCESS: Function executed successfully.
LIOT_TP_ERR_INIT: Initialization failed.
LIOT_TP_ERR_BUS: Bus access failed.
LIOT_TP_ERR_PARAM: Parameter error.
LIOT_TP_ERR_HANDLE: Handle error.
LIOT_TP_ERR_TIMEOUT: Operation timed out.
LIOT_TP_ERR_NOT_SUPPORTED: The current device or driver does not support this operation.

3.3 liot_tp_event_e

The touch event type enumeration is defined as follows:

Definition

typedef enum {
    LIOT_TP_EVT_DOWN = 0,
    LIOT_TP_EVT_UP,
    LIOT_TP_EVT_MOVE,
    LIOT_TP_EVT_NONE,
} liot_tp_event_e;

Parameters

LIOT_TP_EVT_DOWN: Press event.
LIOT_TP_EVT_UP: Release event.
LIOT_TP_EVT_MOVE: Move event.
LIOT_TP_EVT_NONE: No touch event.

3.4 liot_tp_gesture_e

The gesture type enumeration is defined as follows:

Definition

typedef enum {
    LIOT_TP_GESTURE_NONE = 0,
    LIOT_TP_GESTURE_UP,
    LIOT_TP_GESTURE_DOWN,
    LIOT_TP_GESTURE_LEFT,
    LIOT_TP_GESTURE_RIGHT,
    LIOT_TP_GESTURE_ZOOM_IN,
    LIOT_TP_GESTURE_ZOOM_OUT,
    LIOT_TP_GESTURE_LONG_PRESS,
} liot_tp_gesture_e;

Parameters

LIOT_TP_GESTURE_NONE: No gesture.
LIOT_TP_GESTURE_UP: Swipe up.
LIOT_TP_GESTURE_DOWN: Swipe down.
LIOT_TP_GESTURE_LEFT: Swipe left.
LIOT_TP_GESTURE_RIGHT: Swipe right.
LIOT_TP_GESTURE_ZOOM_IN: Zoom in.
LIOT_TP_GESTURE_ZOOM_OUT: Zoom out.
LIOT_TP_GESTURE_LONG_PRESS: Long press.

3.5 liot_tp_interface_e

The TP communication interface type enumeration is defined as follows:

Definition

typedef enum {
    LIOT_TP_IF_I2C = 0,
    LIOT_TP_IF_SPI,
} liot_tp_interface_e;

Parameters

LIOT_TP_IF_I2C: The TP communicates through the I2C interface.
LIOT_TP_IF_SPI: The TP communicates through the SPI interface.

3.6 liot_tp_point_t

The touch point data structure is defined as follows:

Definition

typedef struct {
    uint8_t  id;
    liot_tp_event_e event;
    uint16_t x;
    uint16_t y;
    uint8_t  weight;
    uint32_t timestamp_ms;
} liot_tp_point_t;

Parameters

Type	Parameter	Description
uint8_t	id	Touch point ID
liot_tp_event_e	event	Touch event type
uint16_t	x	X coordinate
uint16_t	y	Y coordinate
uint8_t	weight	Touch weight or pressure value
uint32_t	timestamp_ms	Timestamp, unit: ms

3.7 liot_tp_touch_data_t

The touch data structure is defined as follows:

Definition

typedef struct {
    uint8_t        touch_cnt;
    liot_tp_point_t point[5];
} liot_tp_touch_data_t;

Parameters

Type	Parameter	Description
uint8_t	touch_cnt	Number of currently valid touch points
liot_tp_point_t[5]	point	Touch point array, up to 5 points

3.8 liot_tp_gesture_data_t

The gesture data structure is defined as follows:

Definition

typedef struct {
    liot_tp_gesture_e gesture;
    uint32_t timestamp_ms;
} liot_tp_gesture_data_t;

Parameters

Type	Parameter	Description
liot_tp_gesture_e	gesture	Gesture type
uint32_t	timestamp_ms	Timestamp, unit: ms

3.9 liot_tp_work_mode_e

The TP work mode enumeration is defined as follows:

Definition

typedef enum {
    LIOT_TP_MODE_NORMAL = 0,
    LIOT_TP_MODE_GESTURE,
    LIOT_TP_MODE_LOW_POWER,
    LIOT_TP_MODE_DEEP_SLEEP,
    LIOT_TP_MODE_FACTORY_TEST,
} liot_tp_work_mode_e;

Parameters

LIOT_TP_MODE_NORMAL: Normal work mode.
LIOT_TP_MODE_GESTURE: Gesture mode.
LIOT_TP_MODE_LOW_POWER: Low-power mode.
LIOT_TP_MODE_DEEP_SLEEP: Deep sleep mode.
LIOT_TP_MODE_FACTORY_TEST: Factory test mode.

3.10 liot_tp_sensor_func_t

The TP sensor driver function table is defined as follows:

Definition

typedef struct {
    int (*init)(liot_tp_handle_t handle);
    int (*deinit)(liot_tp_handle_t handle);
    int (*read_touch)(liot_tp_handle_t handle, liot_tp_touch_data_t *data);
    int (*read_gesture)(liot_tp_handle_t handle, liot_tp_gesture_data_t *data);
    int (*set_threshold)(liot_tp_handle_t handle, uint8_t threshold);
    int (*enter_sleep)(liot_tp_handle_t handle);
    int (*wakeup)(liot_tp_handle_t handle);
    int (*reset)(liot_tp_handle_t handle);
    int (*exit_sleep)(liot_tp_handle_t handle);
    int (*update_firmware)(liot_tp_handle_t handle, const uint8_t *fw_data, uint32_t fw_len);
    int (*update_firmware_auto)(liot_tp_handle_t handle);
    int (*set_work_mode)(liot_tp_handle_t handle, liot_tp_work_mode_e mode);
    int (*get_ic_info)(liot_tp_handle_t handle, uint8_t *buf, uint16_t buf_len);
} liot_tp_sensor_func_t;

Parameters

Parameter	Description
init	Chip driver initialization
deinit	Chip driver deinitialization
read_touch	Reads touch point data
read_gesture	Reads gesture data
set_threshold	Sets the touch threshold
enter_sleep	Enters sleep
wakeup	Wakes up
reset	Software reset
exit_sleep	Exits sleep
update_firmware	Upgrades using specified firmware data
update_firmware_auto	Automatically upgrades using built-in firmware
set_work_mode	Sets the work mode
get_ic_info	Gets IC information

3.11 liot_tp_sensor_t

The TP sensor device is defined as follows:

Definition

typedef struct {
    uint8_t  chip_id;
    uint8_t  max_points;
    uint16_t width;
    uint16_t height;
    bool     gesture_support;
    liot_tp_sensor_func_t func;
} liot_tp_sensor_t;

Parameters

Type	Parameter	Description
uint8_t	chip_id	Touch IC chip ID
uint8_t	max_points	Maximum number of touch points
uint16_t	width	Touch panel width
uint16_t	height	Touch panel height
bool	gesture_support	Whether gestures are supported
liot_tp_sensor_func_t	func	Chip driver function table

3.12 liot_tp_i2c_config_t

The TP I2C interface configuration structure is defined as follows:

Definition

typedef struct {
    liot_i2c_channel_e num;
    int8_t sda;
    int8_t scl;
    uint8_t addr;
    uint8_t scl_func;
    uint8_t sda_func;
} liot_tp_i2c_config_t;

Parameters

Type	Parameter	Description
liot_i2c_channel_e	num	I2C channel number
int8_t	sda	SDA pin number
int8_t	scl	SCL pin number
uint8_t	addr	TP I2C 7-bit slave address
uint8_t	scl_func	SCL pin multiplexing function. 0 means the default `L_PIN_FUNC_2` is used
uint8_t	sda_func	SDA pin multiplexing function. 0 means the default `L_PIN_FUNC_2` is used

3.13 liot_tp_spi_config_t

The TP SPI interface configuration structure is defined as follows:

Definition

typedef struct {
    liot_spi_port_e num;
    liot_spi_cpol_pol_e cpol;
    liot_spi_cpha_pol_e cpha;
    liot_spi_clk_e speed;
} liot_tp_spi_config_t;

Parameters

Type	Parameter	Description
liot_spi_port_e	num	SPI bus number
liot_spi_cpol_pol_e	cpol	SPI clock polarity
liot_spi_cpha_pol_e	cpha	SPI clock phase
liot_spi_clk_e	speed	SPI clock frequency

3.14 liot_tp_rst_config_t

The TP reset pin configuration structure is defined as follows:

Definition

typedef struct {
    int8_t pin;
    uint16_t delay_ms;
    bool active_low;
} liot_tp_rst_config_t;

Parameters

Type	Parameter	Description
int8_t	pin	RST pin number. A value less than 0 means it is not configured
uint16_t	delay_ms	Delay after reset, unit: ms
bool	active_low	Whether reset is active low

3.15 liot_tp_int_config_t

The TP interrupt pin configuration structure is defined as follows:

Definition

typedef struct {
    int8_t pin;
    liot_intsig_e signal;
    liot_gpio_pull_mode_e pull;
} liot_tp_int_config_t;

Parameters

Type	Parameter	Description
int8_t	pin	INT pin number. A value less than 0 means it is not configured
liot_intsig_e	signal	Interrupt trigger mode, such as `L_INT_EDGE_FALL`, `L_INT_EDGE_RISE`, or `L_INT_EDGE_BOTH`
liot_gpio_pull_mode_e	pull	GPIO pull-up/pull-down configuration, such as `LIOT_FORCE_PULL_UP`

3.16 liot_tp_config_t

The complete TP configuration structure is defined as follows:

Definition

typedef struct {
    liot_tp_interface_e interface_type;

    union {
        liot_tp_i2c_config_t i2c;
        liot_tp_spi_config_t spi;
    };

    liot_tp_rst_config_t rst;
    liot_tp_int_config_t int_pin;
    liot_tp_sensor_t *sensor;
    bool fw_auto_update;
} liot_tp_config_t;

Parameters

Type	Parameter	Description
liot_tp_interface_e	interface_type	TP communication interface type
liot_tp_i2c_config_t	i2c	I2C interface configuration. Valid when `interface_type` is `LIOT_TP_IF_I2C`
liot_tp_spi_config_t	spi	SPI interface configuration. Valid when `interface_type` is `LIOT_TP_IF_SPI`
liot_tp_rst_config_t	rst	RST reset pin configuration
liot_tp_int_config_t	int_pin	INT interrupt pin configuration
liot_tp_sensor_t *	sensor	TP chip driver object
bool	fw_auto_update	Whether to automatically upgrade firmware during initialization. true means automatic upgrade, and false means skip

4 API Function Details

4.1 liot_tp_init

This function initializes the TP and should be called before using other TP APIs. Before calling it, configure I2C/SPI, RST, INT pins, and the TP chip driver object according to the actual hardware.

Declaration

liot_tp_handle_t liot_tp_init(liot_tp_config_t *config);

Parameters

config: [In] TP configuration parameters.

Return Values

liot_tp_handle_t: TP handle.
NULL: Initialization failed.

4.2 liot_tp_deinit

This function deinitializes the TP.

Declaration

liot_errcode_tp_e liot_tp_deinit(liot_tp_handle_t handle);

Parameters

handle: [In] TP handle.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.3 liot_tp_read_touch

This function reads TP touch point data.

Declaration

liot_errcode_tp_e liot_tp_read_touch(liot_tp_handle_t handle,
                                     liot_tp_touch_data_t *data);

Parameters

handle: [In] TP handle.

data: [Out] Output buffer for touch data.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.4 liot_tp_read_gesture

This function reads TP gesture data.

Declaration

liot_errcode_tp_e liot_tp_read_gesture(liot_tp_handle_t handle,
                                       liot_tp_gesture_data_t *data);

Parameters

handle: [In] TP handle.

data: [Out] Output buffer for gesture data.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.5 liot_tp_set_threshold

This function sets the TP touch threshold. The meaning of the threshold is determined by the specific TP chip driver. Some TP drivers may not support directly setting the threshold.

Declaration

liot_errcode_tp_e liot_tp_set_threshold(liot_tp_handle_t handle,
                                        uint8_t threshold);

Parameters

handle: [In] TP handle.

threshold: [In] Touch threshold. Usually, a smaller value means higher sensitivity.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.6 liot_tp_sleep

This function puts the TP into sleep.

Declaration

liot_errcode_tp_e liot_tp_sleep(liot_tp_handle_t handle);

Parameters

handle: [In] TP handle.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.7 liot_tp_wakeup

This function wakes up the TP.

Declaration

liot_errcode_tp_e liot_tp_wakeup(liot_tp_handle_t handle);

Parameters

handle: [In] TP handle.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.8 liot_tp_reset

This function performs a TP software reset.

Declaration

liot_errcode_tp_e liot_tp_reset(liot_tp_handle_t handle);

Parameters

handle: [In] TP handle.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.9 liot_tp_hard_reset

This function performs a TP hardware reset through the RST pin.

Declaration

liot_errcode_tp_e liot_tp_hard_reset(liot_tp_handle_t handle);

Parameters

handle: [In] TP handle.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

Note: Before using this function, correctly configure rst.pin, rst.delay_ms, and rst.active_low in liot_tp_config_t.

4.10 liot_tp_reg_write

This function writes TP registers. The interface type is automatically selected as I2C or SPI according to the initialization configuration.

Declaration

int liot_tp_reg_write(liot_tp_handle_t handle, uint8_t reg,
                      const uint8_t *data, uint16_t len);

Parameters

handle: [In] TP handle.

reg: [In] Register address.

data: [In] Data buffer to be written.

len: [In] Length of data to be written. Unit: bytes.

Return Values

0: Write succeeded.
-1: Write failed.

4.11 liot_tp_reg_read

This function reads TP registers. The interface type is automatically selected as I2C or SPI according to the initialization configuration.

Declaration

int liot_tp_reg_read(liot_tp_handle_t handle, uint8_t reg,
                     uint8_t *data, uint16_t len);

Parameters

handle: [In] TP handle.

reg: [In] Register address.

data: [Out] Output buffer for read data.

len: [In] Length of data to be read. Unit: bytes.

Return Values

0: Read succeeded.
-1: Read failed.

4.12 liot_tp_reg_write_byte

This function writes a TP single-byte register.

Declaration

liot_errcode_tp_e liot_tp_reg_write_byte(liot_tp_handle_t handle,
                                         uint8_t reg,
                                         uint8_t value);

Parameters

handle: [In] TP handle.

reg: [In] Register address.

value: [In] Value to be written.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.13 liot_tp_reg_read_byte

This function reads a TP single-byte register.

Declaration

liot_errcode_tp_e liot_tp_reg_read_byte(liot_tp_handle_t handle,
                                        uint8_t reg,
                                        uint8_t *value);

Parameters

handle: [In] TP handle.

reg: [In] Register address.

value: [Out] Output pointer for the read value.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.14 liot_tp_reg_write_bit

This function performs a read-modify-write bit operation on a TP register.

Declaration

liot_errcode_tp_e liot_tp_reg_write_bit(liot_tp_handle_t handle,
                                        uint8_t reg,
                                        uint8_t mask,
                                        uint8_t value);

Parameters

handle: [In] TP handle.

reg: [In] Register address.

mask: [In] Bit mask.

value: [In] Value to be written.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.15 liot_tp_get_event_flags

This function gets the TP event group handle. When an INT interrupt is triggered, the corresponding event bit is set.

Declaration

osEventFlagsId_t liot_tp_get_event_flags(liot_tp_handle_t handle);

Parameters

handle: [In] TP handle.

Return Values

osEventFlagsId_t: TP event group handle.

4.16 liot_tp_register_int_callback

This function registers TP interrupt callback functions. After registration, when INT polling is started, callbacks can be invoked automatically after touch or gesture events occur.

Declaration

liot_errcode_tp_e liot_tp_register_int_callback(liot_tp_handle_t handle,
        void (*touch_cb)(liot_tp_touch_data_t *data, void *ctx),
        void (*gesture_cb)(liot_tp_gesture_data_t *data, void *ctx),
        void *touch_ctx,
        void *gesture_ctx);

Parameters

handle: [In] TP handle.

touch_cb: [In] Touch event callback function. It can be NULL.

gesture_cb: [In] Gesture event callback function. It can be NULL.

touch_ctx: [In] Touch event callback context.

gesture_ctx: [In] Gesture event callback context.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.17 liot_tp_enable_int

This function starts or stops INT event polling. After it is started, INT interrupts automatically read TP data and notify the application layer through callbacks or event groups.

Declaration

liot_errcode_tp_e liot_tp_enable_int(liot_tp_handle_t handle, int enable);

Parameters

handle: [In] TP handle.

enable: [In] Enable flag. true means start, and false means stop.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.18 liot_tp_update_firmware

This function executes a TP firmware upgrade.

Declaration

liot_errcode_tp_e liot_tp_update_firmware(liot_tp_handle_t handle,
        const uint8_t *fw_data, uint32_t fw_len);

Parameters

handle: [In] TP handle.

fw_data: [In] Firmware data pointer.

fw_len: [In] Firmware data length. Unit: bytes.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.19 liot_tp_set_work_mode

This function sets the TP work mode.

Declaration

liot_errcode_tp_e liot_tp_set_work_mode(liot_tp_handle_t handle,
        liot_tp_work_mode_e mode);

Parameters

handle: [In] TP handle.

mode: [In] Work mode. See section 3.9.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.20 liot_tp_get_ic_info

This function gets TP IC information. The output data format is determined by the specific TP chip driver.

Declaration

liot_errcode_tp_e liot_tp_get_ic_info(liot_tp_handle_t handle,
        uint8_t *buf, uint16_t buf_len);

Parameters

handle: [In] TP handle.

buf: [Out] Output buffer for IC information.

buf_len: [In] Output buffer length. Unit: bytes.

Return Values

liot_errcode_tp_e: Execution result code. See section 3.2.

4.21 cst816d_set_i2c_config

This function sets the I2C channel and RST pin required for CST816D firmware upgrade. CST816D firmware upgrade must switch to the BOOT address 0x6A.

Declaration

void cst816d_set_i2c_config(liot_i2c_channel_e i2c_ch, int8_t rst_pin);

Parameters

i2c_ch: [In] I2C channel number.

rst_pin: [In] RST pin number.

Return Values

None.

4.22 cst816d_auto_update_firmware

This function automatically upgrades CST816D using built-in firmware. The built-in firmware is selected through liot_tp_cst816d_fw.h.

Declaration

int cst816d_auto_update_firmware(liot_tp_handle_t handle);

Parameters

handle: [In] TP handle.

Return Values

0: Upgrade succeeded.
-1: Upgrade failed.

4.23 axs5106_auto_update_firmware

This function automatically upgrades AXS5106 using built-in firmware. The upgrade process includes version comparison, CRC check, Flash erase, firmware writing, and CRC verification.

Declaration

int axs5106_auto_update_firmware(liot_tp_handle_t handle);

Parameters

handle: [In] TP handle.

Return Values

0: Upgrade succeeded.
-1: Upgrade failed.

5 Code Examples

5.1 Example Code Reference

examples/demo/src/demo_tp.c.

The following example shows how to initialize AXS5106 or CST816D over I2C and obtain touch and gesture data through INT callbacks.

#include <stdio.h>
#include <string.h>
#include "cmsis_os2.h"
#include "liot_os.h"
#include "liot_tp.h"
#include "lierda_app_main.h"
#include "liot_sleep.h"

/* Sensor selection: set the sensor to be used to 1, and set the others to 0 */
#define LIOT_TP_DEMO_TEST_AXS5106 1
#define LIOT_TP_DEMO_TEST_CST816D 0

#if LIOT_TP_DEMO_TEST_CST816D == 1
#define TP_I2C_NUM          1
#define TP_I2C_ADDR         0x15
#define TP_SDA_PIN          66
#define TP_SCL_PIN          67
#define TP_SCL_FUNC         L_PIN_FUNC_2
#define TP_SDA_FUNC         L_PIN_FUNC_2
#define TP_RST_PIN          20
#define TP_RST_DELAY_MS     100
#define TP_RST_ACTIVE_LOW   1
#define TP_INT_PIN          19
#define TP_FW_AUTO_UPDATE   1
#elif LIOT_TP_DEMO_TEST_AXS5106 == 1
#define TP_I2C_NUM          0
#define TP_I2C_ADDR         0x63
#define TP_SDA_PIN          62
#define TP_SCL_PIN          49
#define TP_SCL_FUNC         L_PIN_FUNC_2
#define TP_SDA_FUNC         L_PIN_FUNC_2
#define TP_RST_PIN          56
#define TP_RST_DELAY_MS     100
#define TP_RST_ACTIVE_LOW   1
#define TP_INT_PIN          55
#define TP_FW_AUTO_UPDATE   1
#endif

LIOT_ADD_TP_DEV(g_liot_tp_cst816d);
LIOT_ADD_TP_DEV(g_liot_tp_axs5106);

#if LIOT_TP_DEMO_TEST_CST816D == 1
#define TP_SENSOR  g_liot_tp_cst816d
#elif LIOT_TP_DEMO_TEST_AXS5106 == 1
#define TP_SENSOR  g_liot_tp_axs5106
#endif

static void tp_touch_callback(liot_tp_touch_data_t *data, void *ctx)
{
    (void)ctx;
    for (uint8_t i = 0; i < data->touch_cnt; i++) {
        liot_trace("[TP] touch%d: evt=%d x=%d y=%d",
                   data->point[i].id,
                   data->point[i].event,
                   data->point[i].x,
                   data->point[i].y);
    }
}

static void tp_gesture_callback(liot_tp_gesture_data_t *data, void *ctx)
{
    (void)ctx;
    liot_trace("[TP] gesture: %d @%lu",
               data->gesture, (unsigned long)data->timestamp_ms);
}

void liot_tp_demo_thread(void *argv)
{
    (void)argv;
    osDelay(500);

    Liot_AonPowerCtl(true);
    Liot_SetVoltage(L_DOMAIN_ALL, L_VOLT_3_30V);
    LiotSleepModeCfg_t mode_cfg = {LIOT_SLEEP_MODE_NORMAL};
    Liot_SleepSetMode(&mode_cfg);

    liot_tp_config_t tp_cfg = {
        .interface_type = LIOT_TP_IF_I2C,
        .i2c = {
            .num      = TP_I2C_NUM,
            .sda      = TP_SDA_PIN,
            .scl      = TP_SCL_PIN,
            .addr     = TP_I2C_ADDR,
            .scl_func = TP_SCL_FUNC,
            .sda_func = TP_SDA_FUNC,
        },
        .rst = {
            .pin        = TP_RST_PIN,
            .delay_ms   = TP_RST_DELAY_MS,
            .active_low = TP_RST_ACTIVE_LOW,
        },
        .int_pin = {
            .pin    = TP_INT_PIN,
            .signal = L_INT_EDGE_FALL,
            .pull   = LIOT_FORCE_PULL_UP,
        },
        .sensor = &TP_SENSOR,
        .fw_auto_update = TP_FW_AUTO_UPDATE,
    };

    liot_tp_handle_t tp = liot_tp_init(&tp_cfg);
    if (!tp) {
        liot_trace("[TP] init failed");
        return;
    }

    uint8_t ic_info[4] = {0};
    if (liot_tp_get_ic_info(tp, ic_info, sizeof(ic_info)) == LIOT_TP_SUCCESS) {
        liot_trace("[TP] IC info: chip_id=0x%x fw_ver=0x%x proj_id=0x%x lpm=0x%x",
                   ic_info[0], ic_info[1], ic_info[2], ic_info[3]);
    }

    liot_tp_register_int_callback(tp,
                                  tp_touch_callback,
                                  tp_gesture_callback,
                                  NULL, NULL);

    liot_tp_enable_int(tp, true);

    while (1) {
        osDelay(1000);
    }
}

5.2 Usage Process

Select the TP chip driver according to the actual hardware, such as g_liot_tp_axs5106 or g_liot_tp_cst816d.
Configure the TP communication interface. For I2C, configure the channel number, SDA, SCL, I2C address, and pin multiplexing function.
Configure the RST and INT pins.
Call liot_tp_init() to initialize the TP.
Call liot_tp_get_ic_info() as needed to confirm IC communication and firmware version.
Register touch and gesture callbacks.
Call liot_tp_enable_int(tp, true) to start INT event polling.
Process touch coordinates and gesture events in the callback functions.

6 FAQs

6.1 Which TP chips are supported by the current SDK?

The current example drivers support AXS5106 and CST816D. For details, refer to the driver files in the components/driver/tp directory.

6.2 Does TP use I2C or SPI?

The TP framework supports both I2C and SPI interface types, selected through liot_tp_config_t.interface_type. The current demo uses I2C.

6.3 What are the I2C addresses of AXS5106 and CST816D?

The AXS5106 example address is 0x63, and the CST816D normal mode address is 0x15. The CST816D firmware upgrade BOOT address is 0x6A.

6.4 How should initialization failure be debugged?

First check the TP power supply, RST timing, I2C channel, SDA/SCL pins, pin multiplexing, I2C address, INT/RST pin numbers, and whether the selected sensor matches the actual chip.

6.5 Why is there no touch callback?

Confirm that the INT pin is connected correctly, the trigger mode is correct, liot_tp_register_int_callback() has been called to register callbacks, and liot_tp_enable_int(tp, true) has been called to start INT event polling.

6.6 Do all TPs support setting the touch threshold?

No. Whether liot_tp_set_threshold() takes effect depends on the specific TP chip driver. The current AXS5106 and CST816D drivers do not support directly setting the touch threshold.

6.7 Do all TPs support gestures?

No. Gesture support depends on the specific TP chip and driver. Refer to liot_tp_sensor_t.gesture_support and the corresponding driver implementation.

6.8 How is automatic firmware upgrade controlled?

It is controlled through liot_tp_config_t.fw_auto_update. When set to true, the initialization process can execute automatic upgrade. When set to false, automatic upgrade is skipped. For built-in firmware selection, refer to the corresponding firmware header file.