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 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
Please refer to player/pipeline_http_mp3/main/play_http_mp3_example.c.
API Reference
Header File
Functions
-
esp_periph_set_handle_t esp_periph_set_init(esp_periph_config_t *config)
Initialize esp_peripheral sets, create empty peripherals list. Call this function before starting any peripherals (with
esp_periph_start
). This call will initialize the data needed for esp_peripherals to work, but does not actually create the task. Theevent_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 byesp_periph_get_event_iface
. Theuser_context
will sentesp_periph_event_handle_t
as *context parameter.- 参数
config – [in] The configurations
- 返回
The peripheral sets instance
-
esp_err_t esp_periph_set_destroy(esp_periph_set_handle_t periph_set_handle)
This function will stop and kill the monitor task, calling all destroy callback functions of the peripheral (so you do not need to destroy the peripheral object manually). It will also remove all memory allocated to the peripherals list, so you need to call the
esp_periph_set_init
function again if you want to use it.- 参数
periph_set_handle – The esp_periph_set_handle_t instance
- 返回
ESP_OK
ESP_FAIL
-
esp_err_t esp_periph_set_stop_all(esp_periph_set_handle_t periph_set_handle)
Stop monitoring all peripherals, the peripheral state is still kept. This funciton only temporary disables the peripheral.
- 参数
periph_set_handle – The esp_periph_set_handle_t instance
- 返回
ESP_OK
ESP_FAIL
-
esp_periph_handle_t esp_periph_set_get_by_id(esp_periph_set_handle_t periph_set_handle, int periph_id)
Get the peripheral handle by Peripheral ID.
- 参数
periph_set_handle – The esp_periph_set_handle_t instance
periph_id – [in] as esp_periph_id_t, or any ID you use when calling
esp_periph_create
- 返回
The esp_periph_handle_t
-
audio_event_iface_handle_t esp_periph_set_get_event_iface(esp_periph_set_handle_t periph_set_handle)
Return the event_iface used by this esp_peripherals.
- 参数
periph_set_handle – The esp_periph_set_handle_t instance
- 返回
The audio event iface handle
-
esp_err_t esp_periph_set_register_callback(esp_periph_set_handle_t periph_set_handle, esp_periph_event_handle_t cb, void *user_context)
Register peripheral sets event callback function.
- 参数
periph_set_handle – The esp_periph_set_handle_t instance
cb – The event handle callback function
user_context – The user context pointer
- 返回
ESP_OK
ESP_FAIL
-
QueueHandle_t esp_periph_set_get_queue(esp_periph_set_handle_t periph_set_handle)
Peripheral is using event_iface to control the event, all events are send out to event_iface queue. This function will be useful in case we want to read events directly from the event_iface queue.
- 参数
periph_set_handle – The esp_periph_set_handle_t instance
- 返回
The queue handle
-
esp_err_t esp_periph_set_list_init(esp_periph_set_handle_t periph_set_handle)
Call this function to initialize all the listed peripherals.
备注
Work with no task peripheral set only
- 参数
periph_set_handle – The esp_periph_set_handle_t instance
- 返回
ESP_OK
ESP_FAIL
-
esp_err_t esp_periph_set_list_run(esp_periph_set_handle_t periph_set_handle, audio_event_iface_msg_t msg)
Call this function to run all the listed peripherals.
备注
Work with no task peripheral set only
- 参数
periph_set_handle – The esp_periph_set_handle_t instance
msg – The audio_event_iface_msg_t handle message
- 返回
ESP_OK
ESP_FAIL
-
esp_err_t esp_periph_set_list_destroy(esp_periph_set_handle_t periph_set_handle)
Call this function to destroy all the listed peripherals.
备注
Work with no task peripheral set only
- 参数
periph_set_handle – The esp_periph_set_handle_t instance
- 返回
ESP_OK
ESP_FAIL
-
esp_err_t esp_periph_remove_from_set(esp_periph_set_handle_t periph_set_handle, esp_periph_handle_t periph)
Call this function to remove periph from periph_set.
- 参数
periph_set_handle – The esp_periph_set_handle_t instance
periph – The esp_periph_handle_t instance
- 返回
ESP_OK
ESP_FAIL
-
esp_err_t esp_periph_alloc_periph_id(esp_periph_set_handle_t periph_set_handle, int *periph_id)
Allocated a peripheral ID from the periph_set.
备注
This function can apply for a peripheral ID to realize a customized peripheral module. The requested peripheral ID will not be included in
esp_periph_id_t
- 参数
periph_set_handle – [in] The esp_periph_set_handle_t instance
periph_id – [out] The peripheral identifier
- 返回
ESP_OK
ESP_FAIL
-
esp_err_t esp_periph_set_change_waiting_time(esp_periph_set_handle_t periph_set_handle, int time_ms)
Call this function to change periph_set waiting time.
- 参数
periph_set_handle – The esp_periph_set_handle_t instance
time_ms – The waiting time
- 返回
ESP_OK
ESP_FAIL
-
esp_periph_handle_t esp_periph_create(int periph_id, const char *tag)
Call this function to initialize a new peripheral.
- 参数
periph_id – [in] The periph identifier
tag – [in] The tag name, we named it easy to get in debug logs
- 返回
The peripheral handle
-
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 operations from initialization, execution of commands to destroying the peripheral. These operations are represented by functions passed as call parameters to this function.
- 参数
periph – [in] The periph
init – [in] The initialize
run – [in] The run
destroy – [in] The destroy
- 返回
ESP_OK
ESP_FAIL
-
esp_err_t esp_periph_start(esp_periph_set_handle_t periph_set_handle, esp_periph_handle_t periph)
Add the peripheral to peripherals list, enable and start monitor task (if task stack size > 0)
备注
This peripheral must be first created by calling
esp_periph_create
- 参数
periph_set_handle – [in] The esp_periph_set_handle_t instance
periph – [in] The peripheral instance
- 返回
ESP_OK on success
ESP_FAIL when any errors
-
esp_err_t esp_periph_stop(esp_periph_handle_t periph)
Stop monitoring the peripheral, the peripheral state is still kept. This funciton only temporary disables the peripheral.
- 参数
periph – [in] The periph
- 返回
ESP_OK
ESP_FAIL
-
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.- 参数
periph – [in] The periph
cmd – [in] The command
data – The data
data_len – [in] The data length
- 返回
ESP_OK
ESP_FAIL
-
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.- 参数
periph – [in] The periph
cmd – [in] The command
data – The data
data_len – [in] The data length
- 返回
ESP_OK
ESP_FAIL
-
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 atesp_periph_init
- 参数
periph – [in] The peripheral
event_id – [in] The event identifier
data – The data
data_len – [in] The data length
- 返回
ESP_OK
ESP_FAIL
-
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.
备注
You do not need to stop or destroy the timer, when the
esp_periph_destroy
function is called, it will stop and destroy allThis timer using FreeRTOS Timer, with autoreload = true
- 参数
periph – [in] The peripheral
interval_tick – [in] The interval tick
callback – [in] The callback
- 返回
ESP_OK
ESP_FAIL
-
esp_err_t esp_periph_stop_timer(esp_periph_handle_t periph)
Stop peripheral timer.
- 参数
periph – [in] The peripheral
- 返回
ESP_OK
ESP_FAIL
-
esp_err_t esp_periph_set_data(esp_periph_handle_t periph, void *data)
Set the user data.
备注
Make sure the
data
lifetime is sufficient, this function does not copy all data, it only stores the data pointer- 参数
periph – [in] The peripheral
data – The data
- 返回
ESP_OK
ESP_FAIL
-
void *esp_periph_get_data(esp_periph_handle_t periph)
Get the user data stored in the peripheral.
- 参数
periph – [in] The peripheral
- 返回
Peripheral data pointer
-
esp_periph_state_t esp_periph_get_state(esp_periph_handle_t periph)
Get the current state of peripheral.
- 参数
periph – [in] The handle of peripheral
- 返回
The peripharal working state
-
esp_periph_id_t esp_periph_get_id(esp_periph_handle_t periph)
Get Peripheral identifier.
- 参数
periph – [in] The peripheral
- 返回
The peripheral identifier
-
esp_err_t esp_periph_set_id(esp_periph_handle_t periph, esp_periph_id_t periph_id)
Set Peripheral identifier.
- 参数
periph – [in] The peripheral
periph_id – [in] The peripheral identifier
- 返回
ESP_OK
ESP_FAIL
-
esp_err_t esp_periph_init(esp_periph_handle_t periph)
Call this to execute
init
function of peripheral instance.- 参数
periph – The peripheral handle
- 返回
ESP_OK
ESP_FAIL
-
esp_err_t esp_periph_run(esp_periph_handle_t periph)
Call this to execute
run
function of peripheral instance.- 参数
periph – The peripheral handle
- 返回
ESP_OK
ESP_FAIL
-
esp_err_t esp_periph_destroy(esp_periph_handle_t periph)
Call this to execute
destroy
function of peripheral instance.- 参数
periph – The peripheral handle
- 返回
ESP_OK
ESP_FAIL
-
esp_err_t esp_periph_register_on_events(esp_periph_handle_t periph, esp_periph_event_t *evts)
Rigster peripheral on event handle.
- 参数
periph – The peripheral handle
evts – The esp_periph_event_t handle
- 返回
ESP_OK
ESP_FAIL
Structures
-
struct esp_periph_config_t
Common peripherals configurations.
-
struct esp_periph_event
peripheral events
Public Members
-
void *user_ctx
peripheral context data
-
esp_periph_event_handle_t cb
peripheral callback function
-
audio_event_iface_handle_t iface
peripheral event
-
void *user_ctx
Macros
-
DEFAULT_ESP_PERIPH_STACK_SIZE
-
DEFAULT_ESP_PERIPH_TASK_PRIO
-
DEFAULT_ESP_PERIPH_TASK_CORE
-
DEFAULT_ESP_PERIPH_SET_CONFIG()
-
periph_tick_get
Type Definitions
-
typedef struct esp_periph_sets *esp_periph_set_handle_t
-
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)
-
typedef struct esp_periph_event esp_periph_event_t
peripheral events
Enumerations
-
enum esp_periph_id_t
Peripheral Identify, this must be unique for each peripheral added to the peripherals list.
Values:
-
enumerator PERIPH_ID_BUTTON
-
enumerator PERIPH_ID_TOUCH
-
enumerator PERIPH_ID_SDCARD
-
enumerator PERIPH_ID_WIFI
-
enumerator PERIPH_ID_FLASH
-
enumerator PERIPH_ID_AUXIN
-
enumerator PERIPH_ID_ADC
-
enumerator PERIPH_ID_CONSOLE
-
enumerator PERIPH_ID_BLUETOOTH
-
enumerator PERIPH_ID_LED
-
enumerator PERIPH_ID_SPIFFS
-
enumerator PERIPH_ID_ADC_BTN
-
enumerator PERIPH_ID_IS31FL3216
-
enumerator PERIPH_ID_GPIO_ISR
-
enumerator PERIPH_ID_WS2812
-
enumerator PERIPH_ID_AW2013
-
enumerator PERIPH_ID_LCD
-
enumerator PERIPH_ID_CUSTOM_BASE
-
enumerator PERIPH_ID_BUTTON