UART Event Example

[中文]

Note

This document is automatically translated using AI. Please excuse any detailed errors. The official English version is still in progress.

Example Description

This example demonstrates how to initialize, configure, calibrate ADC, and how to use ADC single sampling mode to collect and process analog input signals. Before studying this example, it is recommended to master the related content of FreeRTOS queue. The basic explanation and API usage examples can be referred to Queue Management.

Running Method

The complete code of the example can be found in UART Event Example. The configuration instructions, build and burn process before running can be found in the README.md file in the example directory.

For custom configuration items and viewing default values, refer to the Global Variables/Macro Definitions Description section.

Header File Description

The header files used in this example cover FreeRTOS task management, common system tools, and UART drivers and other basic modules, providing support for task creation, UART configuration, data transmission, and other functions.

The header files are classified by function as follows:

  1. FreeRTOS Task Scheduling : Task creation, scheduling and queue operation functions

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/queue.h"

  1. System Tools : Provides system logs, standard input and output, and string processing functions.

#include <stdio.h>
#include <string.h>
#include "esp_log.h"

  1. UART Driver : Provides communication configuration and management for UART peripherals, including peripheral initialization, data sending, receiving, and other operations.

#include "driver/uart.h"

Global Variables/Macro Definitions Description

The macro definitions involved in this example are mainly used to define the related configuration parameters of the UART peripherals and the buffer size.

The macro definitions are classified by function as follows:

  1. UART Configuration

  • Defines the UART unit used. This example uses UART_NUM_0, i.e., UART0 peripheral.

#define EX_UART_NUM UART_NUM_0

  • Configures the UART mode matching function, used to trigger specific operations or events. In this example, when three consecutive identical characters are received, a mode is detected.

#define PATTERN_CHR_NUM    (3)

  1. Buffer Size :

  • Sets the size of the data buffer and read buffer, which are used to store the UART data to be sent and received, respectively. Both are set to 1024 bytes in the example.

#define BUF_SIZE (1024)
#define RD_BUF_SIZE (BUF_SIZE)

  1. Defines global variables:

  • Defines the queue handle variable uart0_queue, used for inter-task communication in FreeRTOS, to pass the received data from the UART receive task to other tasks for processing.

Task Function Description

In this example, a task function uart_event_task() is provided to handle data received from the UART interface, handle error situations (such as overflow, frame errors, etc.), and rewrite or clear the buffer as needed. This function receives UART-related events through the event queue and performs corresponding operations based on different event types.

The execution logic of this function is as follows:

  1. Define variables:

  • Define the UART event handle event, which is used to store the event information received from the UART queue. This variable is updated each time a UART event is processed, ensuring that the task can perform corresponding operations based on different event types.

  • Define buffered_size, which is used to store the current data length in the UART receive buffer, helping to determine the available data size in the buffer, or used to clear the buffer and ensure the normal progress of subsequent data transmission.

  • Define the variable dtmp and dynamically allocate memory for it, which is used as the receive buffer to store the received data. The size is RD_BUF_SIZE.

  1. Call xQueueReceive() to block and wait for UART events. For further explanation and usage examples, refer to Queue Data Reception.

  2. After receiving the event, enter the event handling process and perform corresponding operations according to the event type. Some event descriptions can be referred to Using Interrupts:

  • Clear all data in the receive buffer dtmp to ensure that the buffer content will not be affected by the previous residual data before processing new UART data.

  • UART Data Reception: UART_DATA, triggered when UART receives valid data and writes it into the driver layer’s receive buffer.

    • Print log output data size.

    • Call uart_read_bytes() to read the received data and store it in the dtmp buffer. For further introduction and parameter description, refer to UART API.

    • Call uart_write_bytes() to write back the received data to the UART sender for echo testing. For further introduction and parameter description, refer to UART API.

    Note

    Echo testing is not a necessary step in application logic, but a common debugging method in UART example code. Its function is to verify whether the communication link is normal, facilitate debugging, and check the integrity of data transmission.

  • Hardware FIFO Overflow: UART_FIFO_OVF, triggered when the hardware FIFO receives too much data and the buffer overflows.

    • Invoke uart_flush_input() to clear the receive buffer. For further introduction and parameter description, please refer to UART API.

    • Invoke xQueueReset() to reset the event queue.

  • Ring buffer full: UART_BUFFER_FULL, triggered when the ring buffer configured by the driver layer is full and cannot continue to write new received data.

    • Invoke uart_flush_input() to clear the receive buffer. For further introduction and parameter description, please refer to UART API.

    • Invoke xQueueReset() to reset the event queue.

  • UART receive interrupt: UART_BREAK, triggered when the receiving end detects that the low level on the bus lasts longer than 1 frame cycle.

    • Print log prompts.

  • UART parity error: UART_PARITY_ERR, triggered when an error is found in the parity bit check of the received data frame.

    • Print log prompts.

  • UART frame error: UART_FRAME_ERR, triggered when the format of the received data frame is abnormal (such as stop bit error).

    • Print log prompts.

  • UART mode match: UART_PATTERN_DET, triggered when a pre-configured continuous specific character pattern (defined by PATTERN_CHR_NUM) appears in the received data stream.

    • Invoke uart_get_buffered_data_len() to check the number of bytes available in the FIFO buffer, and save it to the variable buffered_size. For further introduction and parameter description, please refer to UART API.

    • Invoke uart_pattern_pop_pos() to get the position of the pattern match, and save it to the variable pos. For further introduction and parameter description, please refer to UART API.

    • Judge the position:

      Note

      If pos == -1 it means that the pattern queue is full and cannot record the matching position.

      • If a pattern is detected but the pattern queue is full, invoke uart_flush_input() to clear the buffer. For further introduction and parameter description, please refer to UART API.

      • Pattern queue not full:

        • Call uart_read_bytes() to read the data before the pattern match position and save it to the buffer dtmp. For further introduction and parameter description, please refer to UART API.

        • Define a temporary array pat and initialize it to 0, which is used to store the matched pattern characters. The array length is PATTERN_CHR_NUM + 1, where the extra 1 byte is used to store the string terminator '\0', ensuring that it can be used as a valid string in subsequent processing and log output.

        • Call uart_read_bytes() to read the pattern characters and save them to the array pat. For further introduction and parameter description, please refer to UART API.

        • Print logs, output the received data and the matched pattern content.

  • Other events:

    • Print log output event type.

  1. Release memory and delete tasks:

  • When the task ends, release the dynamically allocated memory dtmp, and set the pointer dtmp to NULL.

  • Call vTaskDelete() to delete the current task. For further explanation and usage examples, please refer to Deleting Tasks.

Main Function Description

This function demonstrates the basic usage of UART peripherals in ESP-IDF. The main functions include: configuring UART parameters, installing and initializing drivers, setting communication pins and pattern detection functions, and finally creating event handling tasks to manage serial data reception.

  1. Call esp_log_level_set() to set the log level for subsequent debugging and information output.

  2. Install UART driver.

  3. Configure and apply UART parameters.

  4. Set communication pins.

  5. Enable pattern detection function:

  • Invoke uart_enable_pattern_det_baud_intr() to enable the UART baud rate-based pattern detection feature, which can be used to quickly identify data frame boundaries, command separators, or specific protocol markers, facilitating tasks to parse and process received data. For further introduction and parameter description, please refer to UART API.

  • Invoke uart_pattern_queue_reset() to reset the pattern matching queue and set the maximum number of pattern positions that can be recorded. Ensure that only the latest matching information is retained in the queue to avoid queue overflow or recording too many historical positions affecting performance. For further introduction and parameter description, please refer to UART API.

  1. Invoke xTaskCreate() to create an event handling task. For further explanation and usage examples, please refer to Creating Tasks Dynamically.