From c465b75ed60d447f5fe834308b0c3567eb8848c5 Mon Sep 17 00:00:00 2001 From: Song Ruo Jing Date: Wed, 12 Feb 2025 16:14:49 +0800 Subject: [PATCH] docs(uart): aligned the config order in the programming guide with examples Closes https://github.com/espressif/esp-idf/issues/13182 --- docs/en/api-reference/peripherals/uart.rst | 65 +++++++++---------- docs/zh_CN/api-reference/peripherals/uart.rst | 65 +++++++++---------- 2 files changed, 62 insertions(+), 68 deletions(-) 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: