ESP Peripherals

This library simplifies the management of peripherals, by pooling and monitoring in a single task, adding basic functions to send and receive events. And it also provides APIs to easily integrate new peripherals.

Note

Note that if you do not intend to integrate new peripherals into esp_peripherals, you are only interested in simple api esp_periph_init, esp_periph_start, esp_periph_stop and esp_periph_destroy. If you want to integrate new peripherals, please refer to Periph Button source code

Examples

#include "esp_log.h"
#include "esp_peripherals.h"
#include "periph_sdcard.h"
#include "periph_button.h"
#include "periph_touch.h"

static const char *TAG = "ESP_PERIPH_TEST";

static esp_err_t _periph_event_handle(audio_event_iface_msg_t *event, void *context)
{
    switch ((int)event->source_type) {
        case PERIPH_ID_BUTTON:
            ESP_LOGI(TAG, "BUTTON[%d], event->event_id=%d", (int)event->data, event->cmd);
            break;
        case PERIPH_ID_SDCARD:
            ESP_LOGI(TAG, "SDCARD status, event->event_id=%d", event->cmd);
            break;
        case PERIPH_ID_TOUCH:
            ESP_LOGI(TAG, "TOUCH[%d], event->event_id=%d", (int)event->data, event->cmd);
            break;
        case PERIPH_ID_WIFI:
            ESP_LOGI(TAG, "WIFI, event->event_id=%d", event->cmd);
            break;
    }
    return ESP_OK;
}

void app_main(void)
{
    // Initialize Peripherals pool
    esp_periph_config_t periph_cfg = {
        .event_handle = _periph_event_handle,
        .user_context = NULL,
    };
    esp_periph_init(&periph_cfg);

    // Setup SDCARD peripheral
    periph_sdcard_cfg_t sdcard_cfg = {
        .root = "/sdcard",
        .card_detect_pin = GPIO_NUM_34,
    };
    esp_periph_handle_t sdcard_handle = periph_sdcard_init(&sdcard_cfg);

    // Setup BUTTON peripheral
    periph_button_cfg_t btn_cfg = {
        .gpio_mask = GPIO_SEL_36 | GPIO_SEL_39
    };
    esp_periph_handle_t button_handle = periph_button_init(&btn_cfg);

    // Setup TOUCH peripheral
    periph_touch_cfg_t touch_cfg = {
        .touch_mask = TOUCH_PAD_SEL4 | TOUCH_PAD_SEL7 | TOUCH_PAD_SEL8 | TOUCH_PAD_SEL9,
        .tap_threshold_percent = 70,
    };
    esp_periph_handle_t touch_handle = periph_touch_init(&touch_cfg);

    // Start all peripheral
    esp_periph_start(button_handle);
    esp_periph_start(sdcard_handle);
    esp_periph_start(touch_handle);
    vTaskDelay(10*1000/portTICK_RATE_MS);

    //Stop button peripheral
    esp_periph_stop(button_handle);
    vTaskDelay(10*1000/portTICK_RATE_MS);

    //Start button again
    esp_periph_start(button_handle);
    vTaskDelay(10*1000/portTICK_RATE_MS);

    //Stop & destroy all peripherals
    esp_periph_destroy();
}

API Reference

Header File

• esp_peripherals/include/esp_peripherals.h

Functions

esp_err_t esp_periph_init(esp_periph_config_t *config)

brief Initialize esp_peripherals, create empty peripherals list. Call this function only 1 time, before esp_periph_start any peripherals. This call will initialize the data needed for esp_peripherals to work, but does not actually create the task. The event_handle is optional if you want to receive events from this callback function. The esp_peripherals task will send all events out to event_iface, can be listen by event_iface by esp_periph_get_event_iface. The user_context will sent esp_periph_event_handle_t as *context parameter.

Return

• ESP_OK
• ESP_FAIL

Parameters

• config: The configurations

esp_err_t esp_periph_start(esp_periph_handle_t periph)

Add the Peripheral to peripherals list, enable and start monitor task (if not)

Note

This peripheral must be created by esp_periph_create

Return

• ESP_OK on success
• ESP_FAIL when any errors

Parameters

• periph: The peripheral

esp_err_t esp_periph_stop(esp_periph_handle_t periph)

Stop monitor the peripheral, the peripheral state still kept. This funciton only temporary disables the peripheral.

Return

• ESP_OK
• ESP_FAIL

Parameters

• periph: The periph

esp_err_t esp_periph_stop_all()

Stop monitor all peripherals, the peripheral state still kept. This funciton only temporary disables the peripheral.

Return

• ESP_OK
• ESP_FAIL

esp_err_t esp_periph_destroy()

This function will stop and kill the monitor task, calling all destroy callback functions of peripheral (so you do not need to destroy the peripheral object manually). And also to remove all memory allocated to the peripherals list, you need to call the esp_periph_init function again if you want to use it.

Return

• ESP_OK
• ESP_FAIL

esp_periph_state_t esp_periph_get_state(esp_periph_handle_t periph)

Get the current state of peripheral.

Return

The peripharal working state

Parameters

• periph: The handle of peripheral

esp_periph_handle_t esp_periph_get_by_id(int periph_id)

Get the peripheral handle by Peripheral ID.

Return

The esp_periph_handle_t

Parameters

• periph_id: as esp_periph_id_t, or any ID you use when call esp_periph_create

esp_err_t esp_periph_send_event(esp_periph_handle_t periph, int event_id, void *data, int data_len)

In addition to sending an event via event_iface, this function will dispatch the event_handle callback if the event_handle callback is provided at esp_periph_init

Return

• ESP_OK
• ESP_FAIL

Parameters

• periph: The periph
• event_id: The event identifier
• data: The data
• data_len: The data length

esp_err_t esp_periph_send_cmd(esp_periph_handle_t periph, int cmd, void *data, int data_len)

When this function is called, the command is passed to the event_iface command queue, and the esp_periph_run_func of this peripheral will be executed in the main peripheral task. This function can be called from any task, basically it only sends a queue to the main peripheral task.

Return

• ESP_OK
• ESP_FAIL

Parameters

• periph: The periph
• cmd: The command
• data: The data
• data_len: The data length

esp_err_t esp_periph_send_cmd_from_isr(esp_periph_handle_t periph, int cmd, void *data, int data_len)

Similar to esp_periph_send_cmd, but it can be called in the hardware interrupt handle.

Return

• ESP_OK
• ESP_FAIL

Parameters

• periph: The periph
• cmd: The command
• data: The data
• data_len: The data length

esp_err_t esp_periph_set_data(esp_periph_handle_t periph, void *data)

Set the user data.

Note

Make sure the data lifetime is sufficient, this function does not copy all data, it only stores the data pointer

Return

• ESP_OK
• ESP_FAIL

Parameters

• periph: The periph
• data: The data

void *esp_periph_get_data(esp_periph_handle_t periph)

Get the userdata stored in the peripheral.

Return

Peripheral data pointer

Parameters

• periph: The periph

esp_err_t esp_periph_start_timer(esp_periph_handle_t periph, TickType_t interval_tick, timer_callback callback)

Each peripheral can initialize a timer, which is by default NULL. When this function is called, the timer for the peripheral is created and it invokes the callback function every interval tick.

Note

- You do not need to stop or destroy the timer, when the esp_periph_destroy function is called, it will stop and destroy all

• This timer using FreeRTOS Timer, with autoreload = true

Return

• ESP_OK
• ESP_FAIL

Parameters

• periph: The periph
• interval_tick: The interval tick
• callback: The callback

esp_err_t esp_periph_stop_timer(esp_periph_handle_t periph)

Stop peripheral timer.

Return

• ESP_OK
• ESP_FAIL

Parameters

• periph: The periph

QueueHandle_t esp_periph_get_queue()

Peripheral using event_iface to control the event, all events send out to event_iface queue. But in case we want to read events directly from the event_iface queue, this function will be useful.

Return

The queue handle

esp_periph_id_t esp_periph_get_id(esp_periph_handle_t periph)

Get Peripheral Identify.

Return

The peripheral identify

Parameters

• periph: The periph

esp_err_t esp_periph_set_id(esp_periph_handle_t periph, esp_periph_id_t periph_id)

Set Peripheral identify.

Return

• ESP_OK
• ESP_FAIL

Parameters

• periph: The periph
• periph_id: The periph identifier

audio_event_iface_handle_t esp_periph_get_event_iface()

Return the event_iface used by this esp_peripherals.

Return

The audio event iface handle

esp_periph_handle_t esp_periph_create(int periph_id, const char *tag)

Call this function to initialize a new peripheral.

Return

The peripheral handle

Parameters

• periph_id: The periph identifier
• tag: The tag name, we named it easy to get in debug logs

esp_err_t esp_periph_set_function(esp_periph_handle_t periph, esp_periph_func init, esp_periph_run_func run, esp_periph_func destroy)

Each peripheral has a cycle of sequential operation from initialization, execution of commands to destroy, functions assigned by this function.

Return

• ESP_OK
• ESP_FAIL

Parameters

• periph: The periph
• init: The initialize
• run: The run
• destroy: The destroy

long long esp_periph_tick_get()

Get tick in milliseconds (from ESP32 boot)

Return

Tick in milliseconds

esp_err_t esp_periph_set_callback(esp_periph_event_handle_t cb)

Set event callback function.

Return

• ESP_OK
• ESP_FAIL

Structures

struct esp_periph_config_t

Common peripherals configurations.

Public Members

void *user_context

peripherals context data

esp_periph_event_handle_t event_handle

The Peripheral events handle

Macros

periph_tick_get

Type Definitions

typedef struct esp_periph *esp_periph_handle_t

typedef esp_err_t (*esp_periph_func)(esp_periph_handle_t periph)

typedef esp_err_t (*esp_periph_run_func)(esp_periph_handle_t periph, audio_event_iface_msg_t *msg)

typedef esp_err_t (*esp_periph_event_handle_t)(audio_event_iface_msg_t *event, void *context)

typedef void (*timer_callback)(xTimerHandle tmr)

Enumerations

enum esp_periph_id_t

Peripheral Identify, this must be unique for each peripheral added to the peripherals list.

Values:

PERIPH_ID_BUTTON = AUDIO_ELEMENT_TYPE_PERIPH + 1

PERIPH_ID_TOUCH = AUDIO_ELEMENT_TYPE_PERIPH + 2

PERIPH_ID_SDCARD = AUDIO_ELEMENT_TYPE_PERIPH + 3

PERIPH_ID_WIFI = AUDIO_ELEMENT_TYPE_PERIPH + 4

PERIPH_ID_FLASH = AUDIO_ELEMENT_TYPE_PERIPH + 5

PERIPH_ID_AUXIN = AUDIO_ELEMENT_TYPE_PERIPH + 6

PERIPH_ID_ADC = AUDIO_ELEMENT_TYPE_PERIPH + 7

PERIPH_ID_CONSOLE = AUDIO_ELEMENT_TYPE_PERIPH + 8

PERIPH_ID_BLUETOOTH = AUDIO_ELEMENT_TYPE_PERIPH + 9

PERIPH_ID_LED = AUDIO_ELEMENT_TYPE_PERIPH + 10

PERIPH_ID_SPIFFS = AUDIO_ELEMENT_TYPE_PERIPH + 11

PERIPH_ID_ADC_BTN = AUDIO_ELEMENT_TYPE_PERIPH + 12

PERIPH_ID_IS31FL3216 = AUDIO_ELEMENT_TYPE_PERIPH + 13

enum esp_periph_state_t

Peripheral working state.

Values:

PERIPH_STATE_NULL

PERIPH_STATE_INIT

PERIPH_STATE_RUNNING

PERIPH_STATE_PAUSE

PERIPH_STATE_STOPPING

PERIPH_STATE_ERROR

PERIPH_STATE_STATUS_MAX