Merge branch 'docs/translate_uart' into 'master'

docs: translate uart

Closes DOC-3037

See merge request espressif/esp-idf!21184

Author: suda-morris

docs/en/api-reference/peripherals/uart.rst

@@ -5,24 +5,24 @@ Universal Asynchronous Receiver/Transmitter (UART)
 
 {IDF_TARGET_UART_EXAMPLE_PORT:default = "UART_NUM_1", esp32 = "UART_NUM_2", esp32s3 = "UART_NUM_2"}
 
-Overview
---------
+Introduction
+------------
 
-A Universal Asynchronous Receiver/Transmitter (UART) is a hardware feature that handles communication (i.e., timing requirements and data framing) using widely-adopted asynchronous serial communication interfaces, such as RS232, RS422, RS485. A UART provides a widely adopted and cheap method to realize full-duplex or half-duplex data exchange among different devices.
+A Universal Asynchronous Receiver/Transmitter (UART) is a hardware feature that handles communication (i.e., timing requirements and data framing) using widely-adopted asynchronous serial communication interfaces, such as RS232, RS422, and RS485. A UART provides a widely adopted and cheap method to realize full-duplex or half-duplex data exchange among different devices.
 
-The {IDF_TARGET_NAME} chip has {IDF_TARGET_UART_NUM} UART controllers (also referred to as port), each featuring an identical set of registers to simplify programming and for more flexibility.
+The {IDF_TARGET_NAME} chip has {IDF_TARGET_UART_NUM} UART controllers (also referred to as port), each featuring an identical set of registers to simplify programming and add flexibility.
 
-Each UART controller is independently configurable with parameters such as baud rate, data bit length, bit ordering, number of stop bits, parity bit etc. All the controllers are compatible with UART-enabled devices from various manufacturers and can also support Infrared Data Association protocols (IrDA).
+Each UART controller is independently configurable with parameters such as baud rate, data bit length, bit ordering, number of stop bits, parity bit, etc. All the controllers are compatible with UART-enabled devices from various manufacturers and can also support Infrared Data Association (IrDA) protocols.
 
 Functional Overview
 -------------------
 
-The following 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. The overview reflects a typical programming workflow and is broken down into the sections provided below:
+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.
-4. :ref:`uart-api-running-uart-communication` - Sending / receiving data
+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
+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
 
@@ -33,7 +33,7 @@ The UART driver's functions identify each of the UART controllers using :cpp:typ
 
 .. _uart-api-setting-communication-parameters:
 
-Setting Communication Parameters
+Set Communication Parameters
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 UART communication parameters can be configured all in a single step or individually in multiple steps.
@@ -89,12 +89,12 @@ Each of the above functions has a ``_get_`` counterpart to check the currently s
 
 .. _uart-api-setting-communication-pins:
 
-Setting Communication Pins
+Set Communication Pins
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 After setting communication parameters, configure the physical GPIO pins to which the other UART device will be connected. For this, call the function :cpp:func:`uart_set_pin` and specify the GPIO pin numbers to which the driver should route the Tx, Rx, RTS, and CTS signals. If you want to keep a currently allocated pin number for a specific signal, pass the macro :c:macro:`UART_PIN_NO_CHANGE`.
 
-The same macro should be specified for pins that will not be used.
+The same macro :c:macro:`UART_PIN_NO_CHANGE` should be specified for pins that will not be used.
 
 .. code-block:: c
 
@@ -103,7 +103,7 @@ The same macro should be specified for pins that will not be used.
 
 .. _uart-api-driver-installation:
 
-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:
@@ -129,7 +129,7 @@ Once this step is complete, you can connect the external UART device and check t
 
 .. _uart-api-running-uart-communication:
 
-Running UART Communication
+Run UART Communication
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Serial communication is controlled by each UART controller's finite state machine (FSM).
@@ -146,11 +146,11 @@ The process of receiving data is similar, but the steps are reversed:
 2. FSM writes the data into Rx FIFO buffer
 3. Read the data from Rx FIFO buffer
 
-Therefore, an application will be limited to writing and reading data from a respective buffer using :cpp:func:`uart_write_bytes` and :cpp:func:`uart_read_bytes` respectively, and the FSM will do the rest.
+Therefore, an application will only write and read data from a specific buffer using :cpp:func:`uart_write_bytes` and :cpp:func:`uart_read_bytes` respectively, and the FSM will do the rest.
 
 
-Transmitting
-""""""""""""
+Transmit Data
+"""""""""""""
 
 After preparing the data for transmission, call the function :cpp:func:`uart_write_bytes` and pass the data buffer's address and data length to it. The function will copy the data to the Tx ring buffer (either immediately or after enough space is available), and then exit. When there is free space in the Tx FIFO buffer, an interrupt service routine (ISR) moves the data from the Tx ring buffer to the Tx FIFO buffer in the background. The code below demonstrates the use of this function.
 
@@ -178,8 +178,8 @@ There is a 'companion' function :cpp:func:`uart_wait_tx_done` that monitors the
     ESP_ERROR_CHECK(uart_wait_tx_done(uart_num, 100)); // wait timeout is 100 RTOS ticks (TickType_t)
 
 
-Receiving
-"""""""""
+Receive Data
+""""""""""""
 
 Once the data is received by the UART and saved in the Rx FIFO buffer, it needs to be retrieved using the function :cpp:func:`uart_read_bytes`. Before reading data, you can check the number of bytes available in the Rx FIFO buffer by calling :cpp:func:`uart_get_buffered_data_len`. An example of using these functions is given below.
 
@@ -214,10 +214,10 @@ The UART controller supports a number of communication modes. A mode can be sele
 
 .. _uart-api-using-interrupts:
 
-Using Interrupts
+Use Interrupts
 ^^^^^^^^^^^^^^^^
 
-There are many interrupts that can be generated following specific UART states or detected errors. The full list of available interrupts is provided in *{IDF_TARGET_NAME} Technical Reference Manual* > *UART Controller (UART)* > *UART Interrupts* and *UHCI Interrupts* [`PDF <{IDF_TARGET_TRM_EN_URL}#uart>`__]. You can enable or disable specific interrupts by calling :cpp:func:`uart_enable_intr_mask` or :cpp:func:`uart_disable_intr_mask` respectively.
+There are many interrupts that can be generated depending on specific UART states or detected errors. The full list of available interrupts is provided in *{IDF_TARGET_NAME} Technical Reference Manual* > *UART Controller (UART)* > *UART Interrupts* and *UHCI Interrupts* [`PDF <{IDF_TARGET_TRM_EN_URL}#uart>`__]. You can enable or disable specific interrupts by calling :cpp:func:`uart_enable_intr_mask` or :cpp:func:`uart_disable_intr_mask` respectively.
 
 The :cpp:func:`uart_driver_install` function installs the driver's internal interrupt handler to manage the Tx and Rx ring buffers and provides high-level API functions like events (see below).
 
@@ -231,7 +231,7 @@ The API provides a convenient way to handle specific interrupts discussed in thi
     - Enable the interrupts using the functions :cpp:func:`uart_enable_tx_intr` and :cpp:func:`uart_enable_rx_intr`
     - Disable these interrupts using the corresponding functions :cpp:func:`uart_disable_tx_intr` or :cpp:func:`uart_disable_rx_intr`
 
-- **Pattern detection**: An interrupt triggered on detecting a 'pattern' of the same character being received/sent repeatedly for a number of times. This functionality is demonstrated in the example :example:`peripherals/uart/uart_events`. It can be used, e.g., to detect a command string followed by a specific number of identical characters (the 'pattern') added at the end of the command string. The following functions are available:
+- **Pattern detection**: An interrupt triggered on detecting a 'pattern' of the same character being received/sent repeatedly. This functionality is demonstrated in the example :example:`peripherals/uart/uart_events`. It can be used, e.g., to detect a command string with a specific number of identical characters (the 'pattern') at the end. The following functions are available:
 
     - Configure and enable this interrupt using :cpp:func:`uart_enable_pattern_det_intr`
     - Disable the interrupt using :cpp:func:`uart_disable_pattern_det_intr`
@@ -251,7 +251,7 @@ Deleting a Driver
 If the communication established with :cpp:func:`uart_driver_install` is no longer required, the driver can be removed to free allocated resources by calling :cpp:func:`uart_driver_delete`.
 
 
-Overview of RS485 specific communication options
+Overview of RS485 Specific Communication 0ptions
 ------------------------------------------------
 
 .. note::
@@ -268,7 +268,7 @@ The collision detection feature allows handling collisions when their interrupts
 
 The collision detection feature can work with circuit A and circuit C (see Section `Interface Connection Options`_). In the case of using circuit A or B, the RTS pin connected to the DE pin of the bus driver should be controlled by the user application. Use the function :cpp:func:`uart_get_collision_flag` to check if the collision detection flag has been raised.
 
-The {IDF_TARGET_NAME} UART controllers themselves do not support half-duplex communication as they cannot provide automatic control of the RTS pin connected to the ~RE/DE input of RS485 bus driver. However, half-duplex communication can be achieved via software control of the RTS pin by the UART driver. This can be enabled by selecting the :cpp:enumerator:`UART_MODE_RS485_HALF_DUPLEX` mode when calling :cpp:func:`uart_set_mode`.
+The {IDF_TARGET_NAME} UART controllers themselves do not support half-duplex communication as they cannot provide automatic control of the RTS pin connected to the RE/DE input of RS485 bus driver. However, half-duplex communication can be achieved via software control of the RTS pin by the UART driver. This can be enabled by selecting the :cpp:enumerator:`UART_MODE_RS485_HALF_DUPLEX` mode when calling :cpp:func:`uart_set_mode`.
 
 Once the host starts writing data to the Tx FIFO buffer, the UART driver automatically asserts the RTS pin (logic 1); once the last bit of the data has been transmitted, the driver de-asserts the RTS pin (logic 0). To use this mode, the software would have to disable the hardware flow control function. This mode works with all the used circuits shown below.
 
@@ -400,7 +400,7 @@ The UART peripherals have dedicated IO_MUX pins to which they are connected dire
 
 1. :c:macro:`UART_NUM_2_TXD_DIRECT_GPIO_NUM` returns the IO_MUX pin number of UART channel 2 TXD pin (pin 17)
 2. :c:macro:`UART_GPIO19_DIRECT_CHANNEL` returns the UART number of GPIO 19 when connected to the UART peripheral via IO_MUX (this is UART_NUM_0)
-3. :c:macro:`UART_CTS_GPIO19_DIRECT_CHANNEL` returns the UART number of GPIO 19 when used as the UART CTS pin via IO_MUX (this is UART_NUM_0). Similar to the above macro but specifies the pin function which is also part of the IO_MUX assignment.
+3. :c:macro:`UART_CTS_GPIO19_DIRECT_CHANNEL` returns the UART number of GPIO 19 when used as the UART CTS pin via IO_MUX (this is UART_NUM_0). It is similar to the above macro but specifies the pin function which is also part of the IO_MUX assignment.
 
 .. include-build-file:: inc/uart_channel.inc