# K230 Touch API Reference

## Overview

The K230’s touch capabilities consist of two parts:

- Touch device management: dynamically register/delete touch devices through canmv_misc
- Touch read and write HAL: read touch point and device information through drv_touch instance

Related header files:

- `src/rtsmart/libs/rtsmart_hal/components/canmv_misc/canmv_misc.h`
- `src/rtsmart/libs/rtsmart_hal/drivers/touch/drv_touch.h`

## Key data structures

### `struct drv_touch_config_t`

Used to pass in hardware configuration when creating a touch device:

- `touch_dev_index`: device index
- `range_x` / `range_y`: coordinate range (0 can be left to the system default)
- `pin_intr` / `intr_value`: Interrupt pin and active level (available when no interrupt is available `-1`)
- `pin_reset` / `reset_value`: Reset pin and effective level (`-1` is available when there is no reset)
- `i2c_bus_index` / `i2c_bus_speed`: I2C bus number and speed

### `struct drv_touch_data`

Single touch point data:

- `event`: event type (`NONE`/`UP`/`DOWN`/`MOVE`)
- `track_id`: Contact tracing ID
- `x_coordinate`/`y_coordinate`: Contact coordinates
- `width`: contact width
- `timestamp`: timestamp

### `struct drv_touch_info`

Device capability information:

- `type`: touch type
- `vendor`: Manufacturer information
- `point_num`: Maximum number of contacts
- `range_x` / `range_y`: coordinate range

## Device Management API (canmv_misc)

### `canmv_misc_create_touch_device`

```c
int canmv_misc_create_touch_device(struct drv_touch_config_t* cfg);
```

Press `cfg` to register a touch device.

- Return value: `0` success, non-`0` failure.

### `canmv_misc_delete_touch_device`

```c
int canmv_misc_delete_touch_device(int index);
```

Unregister touch device by index.

- Return value: `0` success, non-`0` failure.

## Read and write HAL API (drv_touch)

### `drv_touch_inst_create`

```c
int drv_touch_inst_create(int id, drv_touch_inst_t** inst);
```

Create a touch instance.

- Common errors: `-1` parameter error, `-2` device ID is invalid, `-3` has insufficient memory.

### `drv_touch_inst_destroy`

```c
void drv_touch_inst_destroy(drv_touch_inst_t** inst);
```

Destroy the instance and release resources.

### `drv_touch_read`

```c
int drv_touch_read(drv_touch_inst_t* inst, struct drv_touch_data* touch_data, int max_points);
```

Read touch points.

- Return value: `>0` represents the number of contacts, `0` has no event, `<0` is an error (common `-1/-2`).

### `drv_touch_get_info`

```c
int drv_touch_get_info(drv_touch_inst_t* inst, struct drv_touch_info* info);
```

Query device capability information.

### `drv_touch_get_config`

```c
int drv_touch_get_config(drv_touch_inst_t* inst, struct drv_touch_config_t* cfg);
```

Query the current device configuration.

### `drv_touch_reset`

```c
int drv_touch_reset(drv_touch_inst_t* inst);
```

Perform a touch device reset.

### `drv_touch_get_default_rotate`

```c
int drv_touch_get_default_rotate(drv_touch_inst_t* inst, int* rotate);
```

Read the default rotation configuration (`0/90/180/270/swap_xy`).

## Recommended calling process

1. If you need to dynamically create a device, call `canmv_misc_create_touch_device()` first.
1. Call `drv_touch_inst_create()` to open the instance.
1. First call `drv_touch_get_info()` / `drv_touch_get_config()` to confirm the capability and coordinate range.
1. Call `drv_touch_read()` cyclically to read contact events.
1. Call `drv_touch_inst_destroy()` on exit.
1. If it is a dynamically created device, `canmv_misc_delete_touch_device()` is called last.

## Reference example

- `src/rtsmart/examples/peripheral/touch/test_touch.c`