Add esp32 uart echo example

Author: erhankur

.github/workflows/build-esp.yml

@@ -19,7 +19,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        example: [esp32-led-blink-sdk, esp32-led-strip-sdk]
+        example: [esp32-led-blink-sdk, esp32-led-strip-sdk, esp32-uart-echo]
 
     steps:
       - name: Checkout repo

.gitignore

@@ -8,4 +8,4 @@ build/
 */sdkconfig.old
 */managed_components
 */dependencies.lock
-
+*/.cache/

README.md

@@ -22,6 +22,7 @@ Each example in this repository contains build and deployment instructions, howe
 | ---- | -------- | --- | ----------- | ----- |
 | [esp32-led-blink-sdk](./esp32-led-blink-sdk) | ESP32-C6-Bug | ESP-IDF SDK | Blink an LED repeatedly with Swift & the ESP-IDF. | <img width="300" src="esp32-led-blink-sdk/assets/images/ledon.jpg"> |
 | [esp32-led-strip-sdk](./esp32-led-strip-sdk) | ESP32-C6-DevKitC-1 | ESP-IDF SDK | Control NeoPixel LEDs with Swift & the ESP-IDF. | <img width="300" src="https://github.com/swiftlang/swift-embedded-examples/assets/1186214/15f8a3e0-953e-426d-ad2d-3902baf859be"> |
+| [esp32-uart-echo](./esp32-uart-echo) | ESP32-C6 | ESP-IDF SDK | UART echo example using Swift's `print()` and `readLine()`. | |
 | [harmony](./harmony) | Raspberry Pi Pico W | Pico SDK | A bluetooth speaker and ferrofluidic music visualizer. Firmware, Electrical, and Mechanical designs fully available. | <img width="300" src="harmony/assets/hero.jpg"> |
 | [nrfx-blink-sdk](./nrfx-blink-sdk) | nRF52840-DK | Zephyr SDK | Blink an LED repeatedly with Swift & Zephyr. | <img width="300" src="https://github.com/swiftlang/swift-embedded-examples/assets/1186214/ae3ff153-dd33-4460-8a08-4eac442bf7b0"> |
 | [nuttx-riscv-blink](./nuttx-riscv-blink) | QEMU | NuttX | Blink a virualized led in QEMU using the Apache NuttX RTOS | |

esp32-uart-echo/CMakeLists.txt

@@ -0,0 +1,4 @@
+cmake_minimum_required(VERSION 3.29)
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+idf_build_set_property(MINIMAL_BUILD ON)
+project(main)

esp32-uart-echo/README.md

@@ -0,0 +1,69 @@
+# esp32-uart-echo
+
+This example demonstrates how to use the ESP-IDF UART driver from Swift to create a simple echo application. It wraps the ESP-IDF UART APIs in a Swift-friendly `Uart` struct and redirects Swift's standard I/O (`print()` and `readLine()`) to a custom UART port. This example is specifically made for the RISC-V MCUs from Espressif (the Xtensa MCUs are not currently supported by Swift).
+
+## Features
+
+- Swift wrapper around ESP-IDF UART driver APIs
+- Redirect `stdin`/`stdout`/`stderr` to a custom UART port
+- Use Swift's native `readLine()` and `print()` for UART communication
+- Simple echo functionality: receives data and sends it back
+
+## Requirements
+
+- Set up the [ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/) development environment. Follow the steps in the [ESP32-C6 "Get Started" guide](https://docs.espressif.com/projects/esp-idf/en/v5.4/esp32c6/get-started/index.html).
+  - Make sure you specifically set up development for RISC-V based Espressif chips, and not the Xtensa based products.
+
+- Before trying to use Swift with the ESP-IDF SDK, make sure your environment works and can build the provided C/C++ sample projects, in particular:
+  - Try building and running the "get-started/hello_world" example from ESP-IDF written in C.
+
+## Building
+
+- Make sure you have a recent nightly Swift toolchain that has Embedded Swift support.
+- If needed, run export.sh to get access to the idf.py script from ESP-IDF.
+- Specify the target board type by using `idf.py set-target`. Any RISC-V based Espressif chip is supported.
+
+```console
+$ cd esp32-uart-echo
+$ . <path-to-esp-idf>/export.sh
+$ idf.py set-target esp32c6 # or esp32c3, esp32p4, etc.
+$ idf.py build
+```
+
+## Running
+
+This example uses ESP32-C6 as a reference, but any RISC-V based Espressif chip can be used. Adjust the GPIO pins according to your development kit.
+
+- Connect your board over a USB cable to your computer.
+- Connect a USB-UART converter to the configured UART pins (example for ESP32-C6):
+  - TX (GPIO20) -> RX on USB-UART converter
+  - RX (GPIO19) -> TX on USB-UART converter
+  - GND -> GND on USB-UART converter
+- Use `idf.py` to upload the firmware:
+
+```console
+$ idf.py flash
+```
+
+- Open a serial terminal (e.g., `picocom`, `minicom`, or `screen`) connected to the USB-UART converter at 115200 baud:
+
+```console
+$ picocom -b 115200 /dev/ttyUSB0
+```
+
+- Type text and press Enter. The text will be echoed back to you.
+
+## Configuration
+
+The default UART configuration in `Main.swift`:
+
+- **Port**: UART1
+- **TX Pin**: GPIO20
+- **RX Pin**: GPIO19
+- **Baud Rate**: 115200
+
+To change these settings, modify the `Uart` initialization in `Main.swift`:
+
+```swift
+let uart = Uart(portNum: 1, txPin: 20, rxPin: 19, baudRate: 115200)
+```

esp32-uart-echo/main/BridgingHeader.h

@@ -0,0 +1,52 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2023 Apple Inc. and the Swift project authors.
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef BRIDGING_HEADER_H
+#define BRIDGING_HEADER_H
+
+#include <stdio.h>
+#include <string.h>
+
+#include "sdkconfig.h"
+#include "driver/uart.h"
+#include "driver/uart_vfs.h"
+
+// Wrapper for uart_set_pin that works across ESP-IDF versions
+static inline esp_err_t set_uart_pin(uart_port_t uart_num, int tx_io_num, int rx_io_num, int rts_io_num, int cts_io_num) {
+#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 0, 0)
+    return _uart_set_pin6(uart_num, tx_io_num, rx_io_num, rts_io_num, cts_io_num, -1, -1);
+#else
+    return uart_set_pin(uart_num, tx_io_num, rx_io_num, rts_io_num, cts_io_num);
+#endif
+}
+
+// Helper functions to access stdin/stdout/stderr (which are macros in C)
+static inline void set_stdin(FILE *f) {
+    stdin = f;
+}
+
+static inline void set_stdout(FILE *f) {
+    stdout = f;
+}
+
+static inline void set_stderr(FILE *f) {
+    stderr = f;
+}
+
+static inline FILE* get_stdout(void) {
+    return stdout;
+}
+
+static inline FILE* get_stdin(void) {
+    return stdin;
+}
+
+#endif /* BRIDGING_HEADER_H */

esp32-uart-echo/main/CMakeLists.txt

@@ -0,0 +1,98 @@
+# Register the app as an IDF component
+idf_component_register(
+    SRCS /dev/null # We don't have any C++ sources
+    PRIV_INCLUDE_DIRS "."
+    LDFRAGMENTS "linker.lf"
+    PRIV_REQUIRES esp_driver_uart vfs
+)
+
+idf_build_get_property(target IDF_TARGET)
+idf_build_get_property(arch IDF_TARGET_ARCH)
+
+if("${arch}" STREQUAL "xtensa")
+    message(FATAL_ERROR "Not supported target: ${target}")
+endif()
+
+# Extract -march and -mabi flags
+set(march_flag "")
+set(mabi_flag "")
+
+# Method 1: Read from IDF's cflags response file (IDF 6.0+)
+if(DEFINED IDF_TOOLCHAIN_BUILD_DIR AND EXISTS "${IDF_TOOLCHAIN_BUILD_DIR}/cflags")
+    file(STRINGS "${IDF_TOOLCHAIN_BUILD_DIR}/cflags" cflags_lines)
+    foreach(line IN LISTS cflags_lines)
+        if(line MATCHES "^-march=")
+            set(march_flag "${line}")
+        elseif(line MATCHES "^-mabi=")
+            set(mabi_flag "${line}")
+        endif()
+    endforeach()
+endif()
+
+# Method 2: Fallback to parsing CMAKE_C_FLAGS directly (older IDF versions)
+if(NOT march_flag OR NOT mabi_flag)
+    string(REGEX MATCH "-march=[^ ]+" march_flag_fallback "${CMAKE_C_FLAGS}")
+    string(REGEX MATCH "-mabi=[^ ]+" mabi_flag_fallback "${CMAKE_C_FLAGS}")
+    if(NOT march_flag AND march_flag_fallback)
+        set(march_flag "${march_flag_fallback}")
+    endif()
+    if(NOT mabi_flag AND mabi_flag_fallback)
+        set(mabi_flag "${mabi_flag_fallback}")
+    endif()
+endif()
+
+# Default mabi if not found
+if(NOT mabi_flag)
+    set(mabi_flag "-mabi=ilp32")
+endif()
+
+# Strip Espressif custom extensions not supported by Swift
+if(march_flag)
+    string(REGEX REPLACE "_x[^ ]*" "" march_flag "${march_flag}")
+endif()
+
+# Clear the default COMPILE_OPTIONS which include a lot of C/C++ specific compiler flags that the Swift compiler will not accept
+get_target_property(var ${COMPONENT_LIB} COMPILE_OPTIONS)
+set_target_properties(${COMPONENT_LIB} PROPERTIES COMPILE_OPTIONS "")
+
+# Compute -Xcc flags to set up the C and C++ header search paths for Swift (for bridging header).
+set(SWIFT_INCLUDES)
+foreach(dir ${CMAKE_C_IMPLICIT_INCLUDE_DIRECTORIES})
+    string(CONCAT SWIFT_INCLUDES ${SWIFT_INCLUDES} "-Xcc ")
+    string(CONCAT SWIFT_INCLUDES ${SWIFT_INCLUDES} "-I${dir} ")
+endforeach()
+foreach(dir ${CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES})
+    string(CONCAT SWIFT_INCLUDES ${SWIFT_INCLUDES} "-Xcc ")
+    string(CONCAT SWIFT_INCLUDES ${SWIFT_INCLUDES} "-I${dir} ")
+endforeach()
+
+# Swift compiler flags to build in Embedded Swift mode, optimize for size, choose the right ISA, ABI, etc.
+target_compile_options(${COMPONENT_LIB} PUBLIC "$<$<COMPILE_LANGUAGE:Swift>:SHELL:
+        -target riscv32-none-none-eabi
+        -Xfrontend -function-sections -enable-experimental-feature Embedded -wmo -parse-as-library -Osize
+        -Xcc ${march_flag} -Xcc ${mabi_flag} -Xcc -fno-pic -Xcc -fno-pie
+        
+        -pch-output-dir /tmp
+        -Xfrontend -enable-single-module-llvm-emission
+        
+        ${SWIFT_INCLUDES}
+
+        -import-bridging-header ${CMAKE_CURRENT_LIST_DIR}/BridgingHeader.h
+    >")
+
+
+
+# Enable Swift support in CMake, force Whole Module builds (required by Embedded Swift), and use "CMAKE_Swift_COMPILER_WORKS" to
+# skip the trial compilations which don't (yet) correctly work when cross-compiling.
+set(CMAKE_Swift_COMPILER_WORKS YES)
+set(CMAKE_Swift_COMPILATION_MODE_DEFAULT wholemodule)
+set(CMAKE_Swift_COMPILATION_MODE wholemodule)
+enable_language(Swift)
+
+# List of Swift source files to build.
+target_sources(${COMPONENT_LIB}
+    PRIVATE
+    Main.swift
+    Uart.swift
+    SwiftStubs.c
+)

esp32-uart-echo/main/Main.swift

@@ -0,0 +1,25 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors.
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+// The code will echo the input from the UART back to the sender.
+@_cdecl("app_main")
+func main() {
+  print("Hello from Swift on ESP32-C6!") // This will be printed to the console
+
+  // Initialize UART1 with TX on GPIO20 and RX on GPIO19
+  let uart = Uart(portNum: 1, txPin: 20, rxPin: 19)
+
+  uart.redirectStdio()
+
+  while let line = readLine(strippingNewline: false) {
+      print(line, terminator: "")
+  }
+}

esp32-uart-echo/main/SwiftStubs.c

@@ -0,0 +1,57 @@
+#include <stdio.h>
+#include <stdint.h>
+#include <stdbool.h>
+#include <string.h>
+
+// --- Stub implementations for missing Swift stdlib Unicode functions ---
+// These are required when using String operations in Embedded Swift
+bool _swift_stdlib_isExtendedPictographic(uint32_t scalar) {
+    return false;
+}
+
+bool _swift_stdlib_isInCB_Consonant(uint32_t scalar) {
+    return false;
+}
+
+uint8_t _swift_stdlib_getGraphemeBreakProperty(uint32_t scalar) {
+    return 0;
+}
+
+uint16_t _swift_stdlib_getNormData(uint32_t scalar) {
+    return 0;
+}
+
+uint32_t _swift_stdlib_getComposition(uint32_t first, uint32_t second) {
+    return 0xFFFFFFFF;  // No composition
+}
+
+const uint8_t* _swift_stdlib_nfd_decompositions = NULL;
+
+uint32_t _swift_stdlib_getDecompositionEntry(uint32_t scalar) {
+    return 0;
+}
+
+// --- readLine() hook ---
+// Swift calls swift_stdlib_readLine_stdin(&utf8Start) and frees with _swift_stdlib_free.
+// So we malloc() and return count.
+int swift_stdlib_readLine_stdin(uint8_t **outBuf) {
+    if (!outBuf) {
+        return -1;
+    }
+
+    // Read from stdin
+    char temp[256];
+    if (fgets(temp, sizeof(temp), stdin) == NULL) {
+        // EOF or error
+        return 0;
+    }
+
+    // Copy data to the output buffer
+    size_t len = strlen(temp);
+    *outBuf = malloc(len);
+    if (!*outBuf) {
+        return -1;
+    }
+    memcpy(*outBuf, temp, len);
+    return (int)len;
+}