espressif/touch_sensor_fsm

readme

# Touch Sensor FSM

The ESP32 touch sensor provides a convenient way to detect touch events. However, in environments with strong interference, the hardware judgment logic may fail. This component uses software solutions to provide a more flexible and reliable solution in such environments.

This component provides a finite state machine (FSM) for managing touch sensor data and states. It includes functions for creating, deleting, updating, and controlling the FSM, as well as handling events.

## API Functions

### touch_sensor_fsm_handle_events

```c
esp_err_t touch_sensor_fsm_handle_events(fsm_handle_t handle);
```

This function handles events of a touch sensor FSM. It should be called repeatedly in a task or loop context until it returns a value other than `ESP_OK`. This ensures that all pending events are processed and the FSM operates correctly.

**Parameters:**
- `handle`: Touch sensor handle.

**Returns:**
- `ESP_OK`: Success.
- `ESP_ERR_INVALID_ARG`: Invalid arguments.
- `ESP_ERR_INVALID_STATE`: FSM is not running.

**For example:**

```c
void touch_sensor_task(void *arg)
{
    fsm_handle_t fsm_handle = (fsm_handle_t)arg;

    while (true) {
        esp_err_t err = touch_sensor_fsm_handle_events(fsm_handle);
        if (err != ESP_OK) {
            // Handle error or exit loop
            break;
        }
        // Add a delay if necessary
        vTaskDelay(pdMS_TO_TICKS(10));
    }

    vTaskDelete(NULL);
}
```

By calling this function repeatedly, you ensure that the FSM processes all incoming data and updates its state, which is crucial for accurate touch sensor operation.

## Other API Functions

### Initialization

To create a touch sensor FSM, you need to configure the `fsm_config_t` structure and call `touch_sensor_fsm_create`.

```c
fsm_config_t config = DEFAULTS_TOUCH_SENSOR_FSM_CONFIG();
config.mode = FSM_MODE_POLLING; // or FSM_MODE_USER_PUSH
config.channel_num = 1;
config.channel_list = channel_list;
config.threshold_p = threshold_p;
config.threshold_n = threshold_n;
config.state_cb = state_callback;
config.polling_cb = polling_callback;

fsm_handle_t handle;
esp_err_t ret = touch_sensor_fsm_create(&config, &handle);
if (ret != ESP_OK) {
    // Handle error
}
```

### Control

To start or stop the FSM, use the `touch_sensor_fsm_control` function.

```c
ret = touch_sensor_fsm_control(handle, FSM_CTRL_START, NULL);
if (ret != ESP_OK) {
    // Handle error
}

ret = touch_sensor_fsm_control(handle, FSM_CTRL_STOP, NULL);
if (ret != ESP_OK) {
    // Handle error
}
```

### Update Data

In `FSM_MODE_USER_PUSH` mode, you need to update the data manually.

```c
ret = touch_sensor_fsm_update_data(handle, channel, raw_data, false);
if (ret != ESP_OK) {
    // Handle error
}
```

### Get Data

To get the processed data, use the `touch_sensor_fsm_get_data` function.

```c
uint32_t data[FSM_DATA_MAX];
ret = touch_sensor_fsm_get_data(handle, channel, data);
if (ret != ESP_OK) {
    // Handle error
}
```

### Get State

To get the current state of the touch sensor, use the `touch_sensor_fsm_get_state` function.

```c
fsm_state_t state;
ret = touch_sensor_fsm_get_state(handle, channel, &state);
if (ret != ESP_OK) {
    // Handle error
}
```

### Delete

To delete the FSM, use the `touch_sensor_fsm_delete` function.

```c
ret = touch_sensor_fsm_delete(handle);
if (ret != ESP_OK) {
    // Handle error
}
```

### Handle Events

The `touch_sensor_fsm_handle_events` function should be called repeatedly in a task or loop context to process touch sensor events. It should be called until it returns a value other than `ESP_OK`.

```c
while (1) {
    esp_err_t ret = touch_sensor_fsm_handle_events(handle);
    if (ret != ESP_OK) {
        // Handle error or exit loop
        break;
    }
    vTaskDelay(pdMS_TO_TICKS(config.polling_interval));
}
```

## Working Modes

### Polling Mode

In polling mode (`FSM_MODE_POLLING`), the FSM periodically calls the polling callback to get the raw data. This mode is suitable for applications where the touch sensor data needs to be updated at regular intervals.

### User Push Mode

In user push mode (`FSM_MODE_USER_PUSH`), the user is responsible for updating the raw data by calling the `touch_sensor_fsm_update_data` function. This mode is suitable for applications where the touch sensor data is updated based on external events.

## Limitations

- The touch sensor FSM cannot be used during sleep modes as it relies on periodic updates and processing.