Merge #19088

19088: boards: add esp32s3-pros3 support r=benpicco a=gschorcht

### Contribution description

This PR provides the support for [ESP32 ProS3](https://esp32s3.com/pros3.html#home) board from Unexpected Maker.

This board doesn't have a USB-to-Serial chip on board. Therefore, USB Serial/JTAG is used for STDIO and the board is flashed via the USB Seral/JTAG interface by default.

### Testing procedure

Flashing `tests/shell` should work.

### Issues/PRs references

Co-authored-by: Gunar Schorcht <gunar@schorcht.net>

boards/common/makefiles/stdio_tinyusb_cdc_acm.dep.mk

@@ -8,4 +8,9 @@ ifeq (,$(filter stdio_% slipdev_stdio,$(USEMODULE)))
   endif
 
   FEATURES_REQUIRED += highlevel_stdio
+
+  # Enforce tests to wait a bit for the serial port after reset
+  TERM_DELAY ?= 2
+  TESTRUNNER_CONNECT_DELAY ?= $(TERM_DELAY)
+  $(call target-export-variables,test,TESTRUNNER_CONNECT_DELAY)
 endif

boards/esp32s3-pros3/Kconfig

@@ -0,0 +1,36 @@
+# Copyright (c) 2020 HAW Hamburg
+#               2023 Gunar Schorcht
+#
+# This file is subject to the terms and conditions of the GNU Lesser
+# General Public License v2.1. See the file LICENSE in the top level
+# directory for more details.
+
+config BOARD
+    default "esp32s3-pros3" if BOARD_ESP32S3_PROS3
+
+config BOARD_ESP32S3_PROS3
+    bool
+    default y
+    select BOARD_COMMON_ESP32S3
+    select CPU_MODEL_ESP32S3
+    select HAS_ARDUINO
+    select HAS_ESP_JTAG
+    select HAS_ESP_SPI_RAM
+    select HAS_HIGHLEVEL_STDIO
+    select HAS_PERIPH_ADC
+    select HAS_PERIPH_I2C
+    select HAS_PERIPH_PWM
+    select HAS_PERIPH_SPI
+    select HAS_PERIPH_USBDEV
+    select HAS_TINYUSB_DEVICE
+    select MODULE_USB_BOARD_RESET if TEST_KCONFIG && MODULE_STDIO_USB_SERIAL_JTAG
+
+choice STDIO_IMPLEMENTATION
+    bool "STDIO implementation"
+    depends on TEST_KCONFIG
+    default MODULE_STDIO_CDC_ACM if MODULE_USBUS
+    default MODULE_STDIO_TINYUSB_CDC_ACM if MODULE_TINYUSB_DEVICE
+    default MODULE_STDIO_USB_SERIAL_JTAG if !MODULE_USBUS && !MODULE_TINYUSB_DEVICE
+endchoice
+
+source "$(RIOTBOARD)/common/esp32s3/Kconfig"

boards/esp32s3-pros3/Makefile

@@ -0,0 +1,5 @@
+MODULE = board
+
+DIRS = $(RIOTBOARD)/common/esp32s3
+
+include $(RIOTBASE)/Makefile.base

boards/esp32s3-pros3/Makefile.dep

@@ -0,0 +1,14 @@
+ifeq (,$(filter stdio_% slipdev_stdio usbus tinyusb_device,$(USEMODULE)))
+  # Use stdio_usb_serial_jtag if no other stdio is requested explicitly
+  # and neither USBUS nor tinyusb_device are used
+  USEMODULE += stdio_usb_serial_jtag
+  # Even if only stdio_usb_serial_jtag is enabled, usb_board_reset is enabled
+  # since there should be a CDC ACM interface in any case. This is necessary,
+  # for example, to reset the board if stdio_cdc_acm or stdio_tinyusb_cdc_acm
+  # was previously used.
+  USEMODULE += usb_board_reset
+  include $(RIOTMAKE)/tools/usb_board_reset.mk
+endif
+
+include $(RIOTBOARD)/common/esp32s3/Makefile.dep
+include $(RIOTBOARD)/common/makefiles/stdio_cdc_acm.dep.mk

boards/esp32s3-pros3/Makefile.features

@@ -0,0 +1,19 @@
+# the board uses a ESP32-S3 with a 16MB QSPI Flash and a 8MB QSPI PSRAM
+CPU_MODEL = esp32s3
+FEATURES_PROVIDED += esp_spi_ram
+
+# common board and CPU features
+include $(RIOTBOARD)/common/esp32s3/Makefile.features
+
+# peripherals provided by the board
+FEATURES_PROVIDED += periph_adc
+FEATURES_PROVIDED += periph_i2c
+FEATURES_PROVIDED += periph_pwm
+FEATURES_PROVIDED += periph_spi
+FEATURES_PROVIDED += periph_usbdev
+
+# other features provided by the board
+FEATURES_PROVIDED += arduino
+FEATURES_PROVIDED += esp_jtag
+FEATURES_PROVIDED += highlevel_stdio
+FEATURES_PROVIDED += tinyusb_device

boards/esp32s3-pros3/Makefile.include

@@ -0,0 +1,8 @@
+# The board uses a ESP32-S3 with a 16MB QSPI Flash and a 8MB QSPI PSRAM
+FLASH_SIZE ?= 16
+
+PORT_LINUX ?= /dev/ttyACM0
+
+OPENOCD_CONFIG ?= board/esp32s3-builtin.cfg
+
+include $(RIOTBOARD)/common/esp32s3/Makefile.include

boards/esp32s3-pros3/doc.txt

@@ -0,0 +1,192 @@
+/*
+ * Copyright (C) 2023 Gunar Schorcht
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @defgroup    boards_esp32s3_pros3 ESP32 ProS3 Board
+ * @ingroup     boards_esp32s3
+ * @brief       Support for the ESP32 ProS3 board
+ * @author      Gunar Schorcht <gunar@schorcht.net>
+
+\section esp32s3_pros3 ESP32 ProS3
+
+## Table of Contents {#esp32s3_pros3_toc}
+
+1. [Overview](#esp32s3_pros3_overview)
+2. [Hardware](#esp32s3_pros3_hardware)
+    1. [MCU](#esp32s3_pros3_mcu)
+    2. [Board Configuration](#esp32s3_pros3_board_configuration)
+    3. [Board Pinout](#esp32s3_pros3_pinout)
+3. [Flashing the Device](#esp32s3_pros3_flashing)
+4. [Using STDIO](#esp32s3_pros3_stdio)
+
+## Overview {#esp32s3_pros3_overview}
+
+The ESP32 ProS3 is one of the ESP32-S3 boards from Unexpected Maker.
+\image html https://esp32s3.com/images/main_features_pros3.jpg "ESP32 ProS3" width=800px
+
+The main features of the board are:
+
+- ESP32-S3 SoC with 2.4 GHz WiFi 802.11b/g/n and Bluetooth5, BLE
+- 16 MByte Flash
+- 4 MByte SPI RAM
+- RGB LED WS2812B
+- Native USB and USB Serial JTAG
+- LiPo Battery Charging and PicoBlade connector
+- VBAT and 5V Sensing Pins
+- 3D High Gain Antenna
+
+[Back to table of contents](#esp32s3_pros3_toc)
+
+## Hardware {#esp32s3_pros3_hardware}
+
+This section describes
+
+- the [MCU](#esp32s3_pros3_mcu),
+- the default [board configuration](#esp32s3_pros3_board_configuration),
+- the [board pinout](#esp32s3_pros3_pinout).
+
+[Back to table of contents](#esp32s3_pros3_toc)
+
+### MCU {#esp32s3_pros3_mcu}
+
+Most features of the board are provided by the ESP32-S3 SoC. For detailed
+information about the ESP32-S3 SoC variant (family) and ESP32x SoCs,
+see section \ref esp32_mcu_esp32 "ESP32 SoC Series".
+
+[Back to table of contents](#esp32s3_pros3_toc)
+
+### Board Configuration {#esp32s3_pros3_board_configuration}
+
+ESP32 ProS3 boards have no special hardware on board with the exception
+of a single pin RGB-LED WS2812B that uses a special bit-oriented protocol to
+control the RGB-LED by 24-bit RGB values which is not supported yet.
+
+Most GPIOs are broken out on the board for flexibility. The default board
+configuration provides:
+
+- 10 x ADC channels at maximum
+- 1 x SPI
+- 1 x I2C
+- 1 x UART
+- 2 x PWM, 4 channels each
+- 1 x RGB-LED
+
+For flexibility, some GPIOs are used in different peripheral configurations,
+but they can only be used for one peripheral at a time. For example, GPIO9
+is used in the ADC channel definition and the definition of the SCL signal
+for I2C_DEV(0).
+
+This is possible because GPIOs are only used for a specific peripheral
+interface when either
+
+- the corresponding peripheral module is used, e.g. `periph_i2c`, or
+- the corresponding init function is called, e.g. `adc_init`.
+
+That is, the purpose for which a GPIO is used depends on which module
+or function is used first.
+
+For example, if module `periph_i2c` is not used, the GPIOs listed in I2C
+configuration can be used for the other purposes, that is, GPIO9 can be
+used as ADC channel.
+
+The following table shows the default board configuration, which is sorted
+according to the defined functionality of GPIOs. This configuration can be
+overridden by \ref esp32_application_specific_configurations
+"application-specific configurations".
+
+<center>
+Function        | GPIOs  | Remarks | Configuration
+:---------------|:-------|:--------|:----------------------------------
+BTN0            | GPIO0  | labeled as BOOT button | |
+ADC_LINE(n)     | GPIO1, GPIO2, GPIO3, GPIO4, GPIO5, GPIO6, GPIO7, GPIO8, GPIO9, GPIO10 | | \ref esp32_adc_channels "ADC Channels"
+PWM_DEV(0)      | GPIO12, GPIO13, GPIO14, GPIO15, GPIO16 | - | \ref esp32_pwm_channels "PWM Channels"
+PWM_DEV(1)      | GPIO6, GPIO7, GPIO21, GPIO38 | - | \ref esp32_pwm_channels "PWM Channels"
+I2C_DEV(0) SCL  | GPIO9  | | \ref esp32_i2c_interfaces "I2C Interfaces"
+I2C_DEV(0) SDA  | GPIO8  | | \ref esp32_i2c_interfaces "I2C Interfaces"
+SPI_DEV(0) CLK  | GPIO36 | SPI2_HOST (FSPI) is used | \ref esp32_spi_interfaces "SPI Interfaces"
+SPI_DEV(0) MISO | GPIO37 | SPI2_HOST (FSPI) is used | \ref esp32_spi_interfaces "SPI Interfaces"
+SPI_DEV(0) MOSI | GPIO35 | SPI2_HOST (FSPI) is used | \ref esp32_spi_interfaces "SPI Interfaces"
+SPI_DEV(0) CS0  | GPIO34 | SPI2_HOST (FSPI) is used | \ref esp32_spi_interfaces "SPI Interfaces"
+UART_DEV(0) TxD | GPIO43 | Console (configuration is fixed) | \ref esp32_uart_interfaces "UART interfaces"
+UART_DEV(0) RxD | GPIO44 | Console (configuration is fixed) | \ref esp32_uart_interfaces "UART interfaces"
+</center>
+\n
+
+For detailed information about the peripheral configurations of ESP32-S3
+boards, see section \ref esp32_peripherals "Common Peripherals".
+
+[Back to table of contents](#esp32s3_pros3_toc)
+
+### Board Pinout {#esp32s3_pros3_pinout}
+
+The following figure shows the pinout as configured by board definition.
+
+@image html https://esp32s3.com/images/pins_pros3.jpg "ESP32 ProS3C-1 Pinout" width=900px
+
+The corresponding board schematic can be found [here]
+(https://github.com/UnexpectedMaker/esp32s3/raw/main/schematics/schematic-pros3.pdf)
+
+[Back to table of contents](#esp32s3_pros3_toc)
+
+## Flashing the Device {#esp32s3_pros3_flashing}
+
+Since the board does not have a USB-to-Serial chip, the easiest way to flash
+the board is using the USB Serial/JTAG interface. Just connect the board to
+your host computer and use the following command:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+BOARD=esp32s3-pros3 make flash ...
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+@note Usually the make system resets the board before flashing to enable the
+USB Serial/JTAG interface. In some special cases this reset does not work so
+that the programmer cannot connect to the board and the flashing is aborted
+with a timeout:
+```
+Serial port /dev/ttyACM0
+Connecting...
+...
+serial.serialutil.SerialTimeoutException: Write timeout
+```
+This can happen for example if the board is not yet flashed with RIOT or the
+USB interface is used for another purpose. In this case, restart the board
+manually in download mode by pressing and releasing the RESET button while
+holding down the BOOT button. In download mode, the USB Serial/JTAG interface is
+always available.
+
+Alternatively, an external USB-to-Serial adapter can be used. In this case,
+the USB-to-Serial adapter has to be connected to TxD (GPIO43) and RxD (GPIO44)
+of the UART0 interface. Before RIOT can be flashed, the board has to be
+switched to download mode. To do this, press and release the RESET button
+while holding down the BOOT button. Once the board is in download mode, use
+the following command to flash RIOT:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+BOARD=esp32s3-pros3 make flash ...
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For detailed information about ESP32-S3 as well as configuring and compiling
+RIOT for ESP32-S3 boards, see \ref esp32_riot.
+
+[Back to table of contents](#esp32s3_pros3_toc)
+
+## Using STDIO {#esp32s3_pros3_stdio}
+
+Since the board does not have a USB-to-Serial chip, the USB Serial/JTAG
+interface is used by default for the STDIO (module `stdio_usb_serial_jtag`)
+which provides an USB CDC ACM interface.
+
+If the USB port is used by the USBUS stack or the tinyUSB stack, implicitly
+the module `stdio_cdc_acm` or `stdio_tinyusb_cdc_acm` is used for the STDIO
+via the USB CDC ACM interface.
+
+Alternatively, the UART interface could be used with an external USB-to-Serial
+adapter. Simply add `stdio_uart` to the list of used modules for this purpose:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+BOARD=esp32s3-pros3 USEMODULE=stdio_uart make flash ...
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ */

boards/esp32s3-pros3/include/arduino_board.h

@@ -0,0 +1,38 @@
+/*
+ * Copyright (C)  2023 Gunar Schorcht
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     boards_esp32s3_pros3
+ * @{
+ *
+ * @file
+ * @brief       Board specific configuration for the Arduino API
+ *
+ * @author      Gunar Schorcht <gunar@schorcht.net>
+ */
+
+#ifndef ARDUINO_BOARD_H
+#define ARDUINO_BOARD_H
+
+#include "arduino_board_common.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief   The on-board LED is not available
+ */
+#define ARDUINO_LED         (0)
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ARDUINO_BOARD_H */
+/** @} */

boards/esp32s3-pros3/include/arduino_pinmap.h

@@ -0,0 +1,63 @@
+/*
+ * Copyright (C)  2023 Gunar Schorcht
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     boards_esp32s3_pros3
+ * @{
+ *
+ * @file
+ * @brief       Mapping from MCU pins to Arduino pins
+ *
+ * @author      Gunar Schorcht <gunar@schorcht.net>
+ */
+
+#ifndef ARDUINO_PINMAP_H
+#define ARDUINO_PINMAP_H
+
+#include "periph/gpio.h"
+#include "periph/adc.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @name   Mapping of MCU pins to Arduino pins
+ * @{
+ */
+#define ARDUINO_PIN_0   GPIO44      /**< Arduino Uno pin 0 (RxD) */
+#define ARDUINO_PIN_1   GPIO43      /**< Arduino Uno pin 1 (TxD) */
+#define ARDUINO_PIN_2   GPIO0       /**< Arduino Uno pin 2 */
+#define ARDUINO_PIN_3   GPIO12      /**< Arduino Uno pin 3 (PWM) */
+#define ARDUINO_PIN_4   GPIO6       /**< Arduino Uno pin 4 */
+#define ARDUINO_PIN_5   GPIO13      /**< Arduino Uno pin 5 (PWM) */
+#define ARDUINO_PIN_6   GPIO14      /**< Arduino Uno pin 6 (PWM) */
+#define ARDUINO_PIN_7   GPIO7       /**< Arduino Uno pin 7 */
+#define ARDUINO_PIN_8   GPIO16       /**< Arduino Uno pin 8 */
+#define ARDUINO_PIN_9   GPIO15      /**< Arduino Uno pin 9 (PWM) */
+
+#define ARDUINO_PIN_10  GPIO34      /**< Arduino Uno pin 10 (CS0 / PWM)  */
+#define ARDUINO_PIN_11  GPIO35      /**< Arduino Uno pin 11 (MOSI / PWM) */
+#define ARDUINO_PIN_12  GPIO37      /**< Arduino Uno pin 12 (MISO) */
+#define ARDUINO_PIN_13  GPIO36      /**< Arduino Uno pin 13 (SCK)  */
+
+#define ARDUINO_PIN_A0  GPIO1       /**< Arduino Uno pin A0 */
+#define ARDUINO_PIN_A1  GPIO2       /**< Arduino Uno pin A1 */
+#define ARDUINO_PIN_A2  GPIO4       /**< Arduino Uno pin A2 */
+#define ARDUINO_PIN_A3  GPIO5       /**< Arduino Uno pin A3 */
+
+#define ARDUINO_PIN_A4  GPIO8       /**< Arduino Uno pin A4 (SDA) */
+#define ARDUINO_PIN_A5  GPIO9       /**< Arduino Uno pin A5 (SCL) */
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ARDUINO_PINMAP_H */
+/** @} */