Guides › Tutorial · UART

ESP32 UART echo with ESP-IDF, built in the browser

A second UART on the ESP32 that sends back everything it receives, and logs it. You will wire a USB-to-serial adapter, read the code, build it, flash the board and type to it. No local ESP-IDF needed.

ESP-IDF v6.1 · ESP32 · about 15 minutes · updated 27 October 2026

What you need

• An ESP32 development board and its USB cable.
• A 3.3 V USB-to-serial adapter (CP2102, CH340, FT232 or similar) and three jumper wires. A 5 V adapter can damage the ESP32's pins.
• Desktop Chrome or Edge (flashing uses Web Serial), and a serial terminal for the adapter, for example PuTTY, the Arduino IDE Serial Monitor or screen.

Wiring

The example uses UART2 of the ESP32 on two free GPIOs. Cross TX and RX, and connect the grounds:

Do not connect GPIO4 to GPIO5 directly as a "loopback": the board would echo its own echo forever. The point of the adapter is that your typing is the only thing arriving on RX.

1. Open the example

In MCUForge Studio choose Project › Open Example... and open Communication › uart_echo. Make sure the target at the top is ESP32. The project has the usual ESP-IDF layout: CMakeLists.txt, main/uart_echo_example_main.c and main/Kconfig.projbuild, which defines the pins, port and baud rate.

2. The code, line by line

The settings come from Kconfig (menuconfig) instead of being hard-coded. For the ESP32 the defaults are UART port 2, 115200 baud, TX on GPIO4 and RX on GPIO5:

#define ECHO_TEST_TXD        (CONFIG_EXAMPLE_UART_TXD)        // 4
#define ECHO_TEST_RXD        (CONFIG_EXAMPLE_UART_RXD)        // 5
#define ECHO_UART_PORT_NUM   (CONFIG_EXAMPLE_UART_PORT_NUM)   // 2 on ESP32
#define ECHO_UART_BAUD_RATE  (CONFIG_EXAMPLE_UART_BAUD_RATE)  // 115200

The work happens in a FreeRTOS task. First it describes the line format: 8 data bits, no parity, 1 stop bit, no hardware flow control.

uart_config_t uart_config = {
    .baud_rate = ECHO_UART_BAUD_RATE,
    .data_bits = UART_DATA_8_BITS,
    .parity    = UART_PARITY_DISABLE,
    .stop_bits = UART_STOP_BITS_1,
    .flow_ctrl = UART_HW_FLOWCTRL_DISABLE,
    .source_clk = UART_SCLK_DEFAULT,
};

Then it installs the driver with a 2 KB receive buffer (and no transmit buffer, so writes wait until the bytes are out), applies the format and routes the UART to the chosen pins:

uart_driver_install(ECHO_UART_PORT_NUM, BUF_SIZE * 2, 0, 0, NULL, intr_alloc_flags);
uart_param_config(ECHO_UART_PORT_NUM, &uart_config);
uart_set_pin(ECHO_UART_PORT_NUM, ECHO_TEST_TXD, ECHO_TEST_RXD, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);

The loop reads whatever arrived within 20 ms, writes the same bytes back, and logs them on the main console (UART0, the USB port):

int len = uart_read_bytes(ECHO_UART_PORT_NUM, data, BUF_SIZE - 1, 20 / portTICK_PERIOD_MS);
uart_write_bytes(ECHO_UART_PORT_NUM, (const char *) data, len);
if (len) {
    data[len] = '\0';
    ESP_LOGI(TAG, "Recv str: %s", (char *) data);
}

app_main only starts that task: xTaskCreate(echo_task, "uart_echo_task", ...).

3. Build

Press Build. The project is compiled on the server with ESP-IDF v6.1; the Build Console shows the output and errors appear in Problems. The first build of a project takes a minute or two, later ones are faster.

4. Flash

Connect the ESP32 with its USB cable, choose Device › Connect, pick the board's port in the Chrome dialog, then Device › Flash. Open the Serial Monitor tab to see the board's log (UART0).

5. Test

Open the adapter's port in your serial terminal at 115200 baud, 8N1. Type hello:

• the terminal shows hello again: that is the echo coming back from GPIO4;
• the MCUForge Serial Monitor shows I (...) UART TEST: Recv str: hello.

If nothing comes back

• Swap TX and RX on the adapter: crossing them is the most common mistake.
• Check that both ends use 115200 baud and that GND is connected.
• Make sure the adapter's port is not the board's own USB port.
• On another chip (S3, C3, C6...) the default port and pins differ: see main/Kconfig.projbuild.

Next steps

• Change the baud rate: open sdkconfig (the first build creates it), search for EXAMPLE_UART_BAUD_RATE (Echo Example Configuration), set for example 9600, rebuild and flash, and set the same speed in your terminal.
• Turn the echo into a command parser: compare data with a command and answer differently.
• Download the project as a ZIP to continue in a local ESP-IDF setup; the structure is the same.