diff --git a/docs/en/api-reference/peripherals/uart.rst b/docs/en/api-reference/peripherals/uart.rst index 5fea3490cb..89fa0358fd 100644 --- a/docs/en/api-reference/peripherals/uart.rst +++ b/docs/en/api-reference/peripherals/uart.rst @@ -23,9 +23,9 @@ Functional Overview The overview describes how to establish communication between an {IDF_TARGET_NAME} and other UART devices using the functions and data types of the UART driver. A typical programming workflow is broken down into the sections provided below: -1. :ref:`uart-api-setting-communication-parameters` - Setting baud rate, data bits, stop bits, etc. -2. :ref:`uart-api-setting-communication-pins` - Assigning pins for connection to a device -3. :ref:`uart-api-driver-installation` - Allocating {IDF_TARGET_NAME}'s resources for the UART driver +1. :ref:`uart-api-driver-installation` - Allocating {IDF_TARGET_NAME}'s resources for the UART driver +2. :ref:`uart-api-setting-communication-parameters` - Setting baud rate, data bits, stop bits, etc. +3. :ref:`uart-api-setting-communication-pins` - Assigning pins for connection to a device 4. :ref:`uart-api-running-uart-communication` - Sending/receiving data 5. :ref:`uart-api-using-interrupts` - Triggering interrupts on specific communication events 6. :ref:`uart-api-deleting-driver` - Freeing allocated resources if a UART communication is no longer required @@ -39,13 +39,39 @@ Steps 1 to 3 comprise the configuration stage. Step 4 is where the UART starts o The UART driver's functions identify each of the UART controllers using :cpp:type:`uart_port_t`. This identification is needed for all the following function calls. +.. _uart-api-driver-installation: + +Install Drivers +^^^^^^^^^^^^^^^^^^^ + +First of all, install the driver by calling :cpp:func:`uart_driver_install` and specify the following parameters: + +- UART port number +- Size of RX ring buffer +- Size of TX ring buffer +- Event queue size +- Pointer to store the event queue handle +- Flags to allocate an interrupt + +.. _driver-code-snippet: + +The function allocates the required internal resources for the UART driver. + +.. code-block:: c + + // Setup UART buffered IO with event queue + const int uart_buffer_size = (1024 * 2); + QueueHandle_t uart_queue; + // Install UART driver using an event queue here + ESP_ERROR_CHECK(uart_driver_install({IDF_TARGET_UART_EXAMPLE_PORT}, uart_buffer_size, uart_buffer_size, 10, &uart_queue, 0)); + + .. _uart-api-setting-communication-parameters: Set Communication Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -UART communication parameters can be configured all in a single step or individually in multiple steps. - +As the next step, UART communication parameters can be configured all in a single step or individually in multiple steps. Single Step """"""""""" @@ -113,35 +139,6 @@ The same macro :c:macro:`UART_PIN_NO_CHANGE` should be specified for pins that w // Set UART pins(TX: IO4, RX: IO5, RTS: IO18, CTS: IO19) ESP_ERROR_CHECK(uart_set_pin({IDF_TARGET_UART_EXAMPLE_PORT}, 4, 5, 18, 19)); -.. _uart-api-driver-installation: - -Install Drivers -^^^^^^^^^^^^^^^^^^^ - -Once the communication pins are set, install the driver by calling :cpp:func:`uart_driver_install` and specify the following parameters: - -- UART port number -- Size of TX ring buffer -- Size of RX ring buffer -- Pointer to store the event queue handle -- Event queue size -- Flags to allocate an interrupt - -.. _driver-code-snippet: - -The function allocates the required internal resources for the UART driver. - -.. code-block:: c - - // Setup UART buffered IO with event queue - const int uart_buffer_size = (1024 * 2); - QueueHandle_t uart_queue; - // Install UART driver using an event queue here - ESP_ERROR_CHECK(uart_driver_install({IDF_TARGET_UART_EXAMPLE_PORT}, uart_buffer_size, \ - uart_buffer_size, 10, &uart_queue, 0)); - -Once this step is complete, you can connect the external UART device and check the communication. - .. _uart-api-running-uart-communication: diff --git a/docs/zh_CN/api-reference/peripherals/uart.rst b/docs/zh_CN/api-reference/peripherals/uart.rst index 5b55cc1ca7..864b081a6e 100644 --- a/docs/zh_CN/api-reference/peripherals/uart.rst +++ b/docs/zh_CN/api-reference/peripherals/uart.rst @@ -23,9 +23,9 @@ 下文介绍了如何使用 UART 驱动程序的函数和数据类型在 {IDF_TARGET_NAME} 和其他 UART 设备之间建立通信。基本编程流程分为以下几个步骤： -1. :ref:`uart-api-setting-communication-parameters` - 设置波特率、数据位、停止位等 -2. :ref:`uart-api-setting-communication-pins` - 分配连接设备的管脚 -3. :ref:`uart-api-driver-installation` - 为 UART 驱动程序分配 {IDF_TARGET_NAME} 资源 +1. :ref:`uart-api-driver-installation` - 为 UART 驱动程序分配 {IDF_TARGET_NAME} 资源 +2. :ref:`uart-api-setting-communication-parameters` - 设置波特率、数据位、停止位等 +3. :ref:`uart-api-setting-communication-pins` - 分配连接设备的管脚 4. :ref:`uart-api-running-uart-communication` - 发送/接收数据 5. :ref:`uart-api-using-interrupts` - 触发特定通信事件的中断 6. :ref:`uart-api-deleting-driver` - 如无需 UART 通信，则释放已分配的资源 @@ -39,13 +39,39 @@ UART 驱动程序函数通过 :cpp:type:`uart_port_t` 识别不同的 UART 控制器。调用以下所有函数均需此标识。 +.. _uart-api-driver-installation: + +安装驱动程序 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +首先，请调用 :cpp:func:`uart_driver_install` 安装驱动程序并指定以下参数： + +- UART 控制器编号 +- Rx 环形缓冲区的大小 +- Tx 环形缓冲区的大小 +- 事件队列大小 +- 指向事件队列句柄的指针 +- 分配中断的标志 + +.. _driver-code-snippet: + +该函数将为 UART 驱动程序分配所需的内部资源。 + +.. code-block:: c + + // Setup UART buffered IO with event queue + const int uart_buffer_size = (1024 * 2); + QueueHandle_t uart_queue; + // Install UART driver using an event queue here + ESP_ERROR_CHECK(uart_driver_install({IDF_TARGET_UART_EXAMPLE_PORT}, uart_buffer_size, uart_buffer_size, 10, &uart_queue, 0)); + + .. _uart-api-setting-communication-parameters: 设置通信参数 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -UART 通信参数可以在一个步骤中完成全部配置，也可以在多个步骤中单独配置。 - +其次，UART 通信参数可以在一个步骤中完成全部配置，也可以在多个步骤中单独配置。 一次性配置所有参数 """""""""""""""""""""""""""""""" @@ -113,35 +139,6 @@ UART 通信参数可以在一个步骤中完成全部配置，也可以在多个 // Set UART pins(TX: IO4, RX: IO5, RTS: IO18, CTS: IO19) ESP_ERROR_CHECK(uart_set_pin({IDF_TARGET_UART_EXAMPLE_PORT}, 4, 5, 18, 19)); -.. _uart-api-driver-installation: - -安装驱动程序 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -通信管脚设置完成后，请调用 :cpp:func:`uart_driver_install` 安装驱动程序并指定以下参数： - -- UART 控制器编号 -- Tx 环形缓冲区的大小 -- Rx 环形缓冲区的大小 -- 指向事件队列句柄的指针 -- 事件队列大小 -- 分配中断的标志 - -.. _driver-code-snippet: - -该函数将为 UART 驱动程序分配所需的内部资源。 - -.. code-block:: c - - // Setup UART buffered IO with event queue - const int uart_buffer_size = (1024 * 2); - QueueHandle_t uart_queue; - // Install UART driver using an event queue here - ESP_ERROR_CHECK(uart_driver_install({IDF_TARGET_UART_EXAMPLE_PORT}, uart_buffer_size, \ - uart_buffer_size, 10, &uart_queue, 0)); - -此步骤完成后，可连接外部 UART 设备检查通信。 - .. _uart-api-running-uart-communication: diff --git a/examples/peripherals/uart/uart_async_rxtxtasks/main/Kconfig.projbuild b/examples/peripherals/uart/uart_async_rxtxtasks/main/Kconfig.projbuild new file mode 100644 index 0000000000..3068b7abea --- /dev/null +++ b/examples/peripherals/uart/uart_async_rxtxtasks/main/Kconfig.projbuild @@ -0,0 +1,35 @@ +menu "Example Configuration" + + orsource "$IDF_PATH/examples/common_components/env_caps/$IDF_TARGET/Kconfig.env_caps" + + config EXAMPLE_UART_BAUD_RATE + int "UART communication speed" + range 1200 115200 + default 115200 + help + UART communication speed for the example. + + config EXAMPLE_UART_RXD + int "UART RXD pin number" + range ENV_GPIO_RANGE_MIN ENV_GPIO_IN_RANGE_MAX + default 5 + help + GPIO number for UART RX pin. See UART documentation for more information + about available pin numbers for UART. + + config EXAMPLE_UART_TXD + int "UART TXD pin number" + range ENV_GPIO_RANGE_MIN ENV_GPIO_OUT_RANGE_MAX + default 4 + help + GPIO number for UART TX pin. See UART documentation for more information + about available pin numbers for UART. + + config EXAMPLE_TASK_STACK_SIZE + int "Example task stack size" + range 1024 16384 + default 3072 + help + Defines stack size for UART TX and RX tasks. Insufficient stack size can cause crash. + +endmenu diff --git a/examples/peripherals/uart/uart_async_rxtxtasks/main/uart_async_rxtxtasks_main.c b/examples/peripherals/uart/uart_async_rxtxtasks/main/uart_async_rxtxtasks_main.c index cf67cc86f3..d6d48f7ee2 100644 --- a/examples/peripherals/uart/uart_async_rxtxtasks/main/uart_async_rxtxtasks_main.c +++ b/examples/peripherals/uart/uart_async_rxtxtasks/main/uart_async_rxtxtasks_main.c @@ -16,13 +16,13 @@ static const int RX_BUF_SIZE = 1024; -#define TXD_PIN (GPIO_NUM_4) -#define RXD_PIN (GPIO_NUM_5) +#define TXD_PIN (CONFIG_EXAMPLE_UART_TXD) +#define RXD_PIN (CONFIG_EXAMPLE_UART_RXD) void init(void) { const uart_config_t uart_config = { - .baud_rate = 115200, + .baud_rate = CONFIG_EXAMPLE_UART_BAUD_RATE, .data_bits = UART_DATA_8_BITS, .parity = UART_PARITY_DISABLE, .stop_bits = UART_STOP_BITS_1, @@ -72,6 +72,6 @@ static void rx_task(void *arg) void app_main(void) { init(); - xTaskCreate(rx_task, "uart_rx_task", 1024 * 2, NULL, configMAX_PRIORITIES - 1, NULL); - xTaskCreate(tx_task, "uart_tx_task", 1024 * 2, NULL, configMAX_PRIORITIES - 2, NULL); + xTaskCreate(rx_task, "uart_rx_task", CONFIG_EXAMPLE_TASK_STACK_SIZE, NULL, configMAX_PRIORITIES - 1, NULL); + xTaskCreate(tx_task, "uart_tx_task", CONFIG_EXAMPLE_TASK_STACK_SIZE, NULL, configMAX_PRIORITIES - 2, NULL); } diff --git a/examples/peripherals/uart/uart_async_rxtxtasks/pytest_async_rxtxtasks.py b/examples/peripherals/uart/uart_async_rxtxtasks/pytest_async_rxtxtasks.py new file mode 100644 index 0000000000..b039660e56 --- /dev/null +++ b/examples/peripherals/uart/uart_async_rxtxtasks/pytest_async_rxtxtasks.py @@ -0,0 +1,10 @@ +# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD +# SPDX-License-Identifier: CC0-1.0 +import pytest +from pytest_embedded import Dut + + +@pytest.mark.supported_targets +@pytest.mark.generic +def test_uart_async_rxtxtasks_example(dut: Dut) -> None: + dut.expect_exact('TX_TASK: Wrote 11 bytes') diff --git a/examples/peripherals/uart/uart_events/pytest_events.py b/examples/peripherals/uart/uart_events/pytest_events.py new file mode 100644 index 0000000000..fb4a8a4611 --- /dev/null +++ b/examples/peripherals/uart/uart_events/pytest_events.py @@ -0,0 +1,14 @@ +# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD +# SPDX-License-Identifier: CC0-1.0 +import pytest +from pytest_embedded import Dut + + +@pytest.mark.supported_targets +@pytest.mark.generic +def test_uart_events_example(dut: Dut) -> None: + dut.expect_exact('Returned from app_main()') + dut.write('a') + dut.expect_exact('uart_events: [UART DATA]: 2') # dut.write will add an extra '\n' + dut.write('HA') + dut.expect_exact('uart_events: [UART DATA]: 3') # dut.write will add an extra '\n' diff --git a/examples/peripherals/uart/uart_select/pytest_uart_select.py b/examples/peripherals/uart/uart_select/pytest_uart_select.py new file mode 100644 index 0000000000..eb37f26cee --- /dev/null +++ b/examples/peripherals/uart/uart_select/pytest_uart_select.py @@ -0,0 +1,12 @@ +# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD +# SPDX-License-Identifier: CC0-1.0 +import pytest +from pytest_embedded import Dut + + +@pytest.mark.supported_targets +@pytest.mark.generic +def test_uart_select_example(dut: Dut) -> None: + dut.expect_exact('uart_select_example: Timeout has been reached and nothing has been received') + dut.write('a') + dut.expect_exact('uart_select_example: Received: a')