Merge #19487 #19808

19487: nanocoap: implement extended tokens (RFC 8974) r=benpicco a=benpicco 19808: boards: add ESP32-S3-USB-OTG support r=benpicco a=gschorcht ### Contribution description This PR provides the support for the [ESP32-S3-USB-OTG](https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32s3/esp32-s3-usb-otg/user_guide.html) board. The SD card can only be used in SPI mode at the moment. As soon as PR #19786 is merged, the SD/MMC support can be enabled and the SD card can then be used in SD mode with 4-bit data bus width. The display uses uses the ST7789 driver IC that is compatible with the ST7735. For that purpose the ST7735 driver is extended by a pseudomodule definition `st7789` for the ST7789 which is enabled by the board and enables automatically the `st7789` (e57c48a). Vise versa, board's `Makefile.dep` enables automatically the `st7789` pseudomodule if the `st7735` is used. The pseudomodule `st7789` is just used to increase the upper limit for supported lines. This change is also part of PR #19807. ~The PR includes a very small documentation fix for ESP32-S3-DevKit board that was noticed during the development of this board definition (1155b6a).~ ### Testing procedure The board has been tested with all basic tests for supported hardware including `tests/driver/st3375`: ![IMG_20230707_105556](https://github.com/RIOT-OS/RIOT/assets/31932013/88d4ac11-0c02-4339-a423-7900e1c0904c) - [x] tests/drivers/st3375 - [x] tests/periph/gpio - [x] tests/periph/pwm - [x] tests/periph/spi - [x] tests/periph/uart - [x] tests/sys/usbus_cdc_ecm ### Issues/PRs references Co-authored-by: Benjamin Valentin <[email protected]> Co-authored-by: Gunar Schorcht <[email protected]>
RIOT-OS · Jul 7, 2023 · 72ca81b · 72ca81b
3 parents 8707548 + c01c470 + d68c826
commit 72ca81b
Show file tree

Hide file tree

Showing 14 changed files with 861 additions and 12 deletions.
diff --git a/boards/esp32s3-usb-otg/Kconfig b/boards/esp32s3-usb-otg/Kconfig
@@ -0,0 +1,38 @@
+# Copyright (c) 2020 HAW Hamburg
+#               2022 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-usb-otg" if BOARD_ESP32S3_USB_OTG
+
+config BOARD_ESP32S3_USB_OTG
+    bool
+    default y
+    select BOARD_COMMON_ESP32S3
+    select CPU_MODEL_ESP32S3_MINI_1X_N8
+    select HAS_ESP_JTAG
+    select HAS_HIGHLEVEL_STDIO
+    select HAS_PERIPH_ADC
+    select HAS_PERIPH_PWM
+    select HAS_PERIPH_SPI
+    select HAS_PERIPH_UART
+    select HAS_PERIPH_USBDEV
+    select HAS_SDCARD_SPI
+    select HAS_TINYUSB_DEVICE
+    select HAVE_MTD_SDCARD_DEFAULT
+    select HAVE_ST7789
+    select MODULE_FATFS_VFS if MODULE_VFS_DEFAULT
+    # Only this board has a requirement to use USB_BOARD_RESET with STDIO_USB_SERIAL_JTAG
+    select MODULE_USB_BOARD_RESET if MODULE_STDIO_USB_SERIAL_JTAG
+    select REQUIRES_USB_STDIO if MODULE_USBUS || MODULE_TINYUSB_DEVICE
+
+choice STDIO_IMPLEMENTATION
+    default MODULE_STDIO_CDC_ACM if MODULE_USBUS
+    default MODULE_STDIO_TINYUSB_CDC_ACM if MODULE_TINYUSB_DEVICE
+    default MODULE_STDIO_USB_SERIAL_JTAG
+endchoice
+
+source "$(RIOTBOARD)/common/esp32s3/Kconfig"
diff --git a/boards/esp32s3-usb-otg/Makefile b/boards/esp32s3-usb-otg/Makefile
@@ -0,0 +1,5 @@
+MODULE = board
+
+DIRS = $(RIOTBOARD)/common/esp32s3
+
+include $(RIOTBASE)/Makefile.base
diff --git a/boards/esp32s3-usb-otg/Makefile.dep b/boards/esp32s3-usb-otg/Makefile.dep
@@ -0,0 +1,32 @@
+ifeq (,$(filter stdio_% slipdev_stdio usbus 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
+
+# default to using fatfs on SD card
+ifneq (,$(filter vfs_default,$(USEMODULE)))
+  USEMODULE += fatfs_vfs
+  USEMODULE += mtd
+endif
+
+ifneq (,$(filter mtd,$(USEMODULE)))
+  USEMODULE += mtd_sdcard_default
+endif
+
+ifneq (,$(filter disp_dev,$(USEMODULE)))
+  USEMODULE += st7789
+endif
+
+ifneq (,$(filter st7735,$(USEMODULE)))
+  USEMODULE += st7789
+endif
diff --git a/boards/esp32s3-usb-otg/Makefile.features b/boards/esp32s3-usb-otg/Makefile.features
@@ -0,0 +1,17 @@
+CPU_MODEL = esp32s3_mini_1x_n8
+
+# common board and CPU features
+include $(RIOTBOARD)/common/esp32s3/Makefile.features
+
+# additional features provided by the board
+FEATURES_PROVIDED += periph_adc
+FEATURES_PROVIDED += periph_pwm
+FEATURES_PROVIDED += periph_spi
+FEATURES_PROVIDED += periph_uart
+FEATURES_PROVIDED += periph_usbdev
+
+# unique features provided by the board
+FEATURES_PROVIDED += esp_jtag
+FEATURES_PROVIDED += highlevel_stdio
+FEATURES_PROVIDED += sdcard_spi
+FEATURES_PROVIDED += tinyusb_device
diff --git a/boards/esp32s3-usb-otg/Makefile.include b/boards/esp32s3-usb-otg/Makefile.include
@@ -0,0 +1,5 @@
+PORT_LINUX ?= /dev/ttyACM0
+
+OPENOCD_CONFIG ?= board/esp32s3-builtin.cfg
+
+include $(RIOTBOARD)/common/esp32s3/Makefile.include
diff --git a/boards/esp32s3-usb-otg/board.c b/boards/esp32s3-usb-otg/board.c
@@ -0,0 +1,26 @@
+/*
+ * 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_usb_otg
+ * @{
+ *
+ * @file
+ * @brief       Board specific initializations for ESP32-S3-USB-OTG boards
+ *
+ * @author      Gunar Schorcht <[email protected]>
+ */
+
+#include "board.h"
+
+void board_init(void)
+{
+#if MODULE_ST7735
+    gpio_init(LCD_BACKLIGHT, GPIO_OUT);
+#endif
+}
diff --git a/boards/esp32s3-usb-otg/doc.txt b/boards/esp32s3-usb-otg/doc.txt
@@ -0,0 +1,185 @@
+/*
+ * 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_usb_otg ESP32-S3-USB-OTG Board
+ * @ingroup     boards_esp32s3
+ * @brief       Support for the ESP32-S3-USB-OTG board
+ * @author      Gunar Schorcht <[email protected]>
+
+\section esp32s3_usb_otg ESP32-S3-USB-OTG
+
+## Table of Contents {#esp32s3_usb_otg_toc}
+
+1. [Overview](#esp32s3_usb_otg_overview)
+2. [Hardware](#esp32s3_usb_otg_hardware)
+    1. [MCU](#esp32s3_usb_otg_mcu)
+    2. [Board Configuration](#esp32s3_usb_otg_board_configuration)
+3. [Flashing the Device](#esp32s3_usb_otg_flashing)
+4. [Using STDIO](esp32s3_usb_otg_stdio)
+
+## Overview {#esp32s3_usb_otg_overview}
+
+The Espressif ESP32-S3-USB-OTG is a development board designed for the
+development of applications that use the USB interface. For this purpose
+it is equipped with two USB type A ports:
+
+- `USB_DEV` male port that is used to connect the board as a USB device to a host.
+- `USB_HOST` female port that is used to connect other USB devices to the board.
+
+\image html "https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/_images/pic_board_top_lable.png" "Espressif ESP32-S3-USB-OTG" width=600px
+
+@note RIOT-OS does only support the `USB_DEV` port, that is the board can only
+      be used as USB device.
+
+The main features of the board are:
+
+| Feature                        | Support        |
+|:-------------------------------|:--------------:|
+| ESP32-S3 SoC                   | yes (1 core)   |
+| 2.4 GHz WiFi 802.11b/g/n       | yes            |
+| Bluetooth5, BLE                | yes            |
+| 8 MByte Flash                  | yes            |
+| USB Type-A Host Interface      | no             |
+| USB Type-A Device Interface    | yes            |
+| SD Card Slot                   | yes (SPI mode) |
+| LCD Color Display 240 x 240    | yes            |
+
+## Hardware {#esp32s3_usb_otg_hardware}
+
+This section describes
+
+- the [MCU](#esp32s3_usb_otg_mcu),
+- the default [board configuration](#esp32s3_usb_otg_board_configuration),
+
+[Back to table of contents](#esp32s3_usb_otg_toc)
+
+### MCU {#esp32s3_usb_otg_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_usb_otg_toc)
+
+### Board Configuration {#esp32s3_usb_otg_board_configuration}
+
+The Espressif ESP32-S3-USB-OTG is a development board that uses the
+ESP32-S3-MINI-1 module. Most important features of the board are
+
+- Micro-SD Card interface
+- 1.3" Color LCD display with ST7789 display controller
+- USB-to-UART bridge
+- `USB_DEV` Type-A male port
+- `USB_HOST` Type-A female port
+
+<center>
+Function          | GPIOs  | Remarks     | Configuration
+:-----------------|:-------|:------------|:----------------------------------
+BTN0              | GPIO0  | OK Button   | |
+BTN1              | GPIO14 | MENU Button | |
+BTN2              | GPIO11 | DW- Button  | |
+BTN3              | GPIO10 | UP+ active  | |
+LED0              | GPIO15 | Green LED   | |
+LED1              | GPIO16 | Yellow LED  | |
+LCD_DC            | GPIO4  | | |
+LCD_EN            | GPIO5  | | |
+LCD_RST           | GPIO8  | | |
+LCD_BL            | GPIO9  | LCD Backlight | |
+ADC_LINE(0)       | GPIO1  | USB_HOST Voltage | \ref esp32_adc_channels "ADC Channels"
+ADC_LINE(1)       | GPIO2  | Battery Voltage  | \ref esp32_adc_channels "ADC Channels"
+PWM_DEV(0):0      | GPIO15 | LED0 | \ref esp32_pwm_channels "PWM Channels"
+PWM_DEV(0):1      | GPIO16 | LED1 | \ref esp32_pwm_channels "PWM Channels"
+SPI_DEV(0):SCK    | GPIO6  | LCD_SCLK | \ref esp32_spi_interfaces "SPI Interfaces" |
+SPI_DEV(0):MOSI   | GPIO7  | LCD_SDA  | \ref esp32_spi_interfaces "SPI Interfaces" |
+SPI_DEV(0):MISO   | GPIO3  | no used  | \ref esp32_spi_interfaces "SPI Interfaces" |
+SPI_DEV(0):CS0    | GPIO5  | LCD_EN   | \ref esp32_spi_interfaces "SPI Interfaces" |
+SPI_DEV(1):SCK    | GPIO36 | SD_CLK   | \ref esp32_spi_interfaces "SPI Interfaces" |
+SPI_DEV(1):MOSI   | GPIO35 | SD_CMD   | \ref esp32_spi_interfaces "SPI Interfaces" |
+SPI_DEV(1):MISO   | GPIO37 | SD_DATA0 | \ref esp32_spi_interfaces "SPI Interfaces" |
+SPI_DEV(1):CS0    | GPIO34 | SD_DATA3 | \ref esp32_spi_interfaces "SPI Interfaces" |
+UART_DEV(0):TxD   | GPIO43 | USB-to-UART bridge | \ref esp32_uart_interfaces "UART interfaces"
+UART_DEV(0):RxD   | GPIO44 | USB-to-UART bridge | \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".
+
+The corresponding board schematic can be found
+[here](https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/_static/esp32-s3-usb-otg/schematics/SCH_ESP32-S3_USB_OTG.pdf)
+
+[Back to table of contents](#esp32s3_usb_otg_toc)
+
+## Flashing the Device {#esp32s3_usb_otg_flashing}
+
+There are two options to flash the board:
+
+1. USB Serial/JTAG interface using the `USB_DEV` port (default)
+2. UART-to-UART bridge
+
+### Flashing the device using the USB Serial/JTAG interface (`USB_DEV` port)
+
+To flash the board via the USB Serial/JTAG interface just connect the board
+with the `USB_DEV` port to your host computer and use the following command:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+BOARD=esp32s3_usb_otg make flash ...
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Usually the make system resets the board before flashing to enable the
+USB Serial/JTAG controller and to reboot the ESP32-S3 in download mode.
+
+In some very special cases this reset does not work and the programmer cannot
+connect to the card, so the flashing is aborted with a timeout:
+```
+Serial port /dev/ttyACM0
+Connecting...
+...
+serial.serialutil.SerialTimeoutException: Write timeout
+```
+This can happen either if RIOT is not yet installed or if the USB port was
+previously used with the USB OTG controller, for example with USBUS or tinyUSB.
+In this case, restart the board manually into 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.
+
+@note If the USB port was previously used with the USB OTG controller, an
+      automatic restart of the ESP32-S3 with the flashed application is not
+      possible. In this case the board must be reset manually using the RESET
+      button. In all other cases the ESP32-S3 automatically restarts with
+      the flashed application.
+
+### Flashing the device using USB-to-UART bridge
+
+Flashing RIOT using the USB-to-UART bridge is quite easy. The board has a
+Micro-USB connector with reset/boot/flash logic. Just connect the board to
+your host computer and type using the programming port:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+BOARD=esp32s3-usb-otg make flash ... PORT=/dev/ttyUSB0
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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_usb_otg_toc)
+
+## Using STDIO {#esp32s3_usb_otg_stdio}
+
+By default, the `USB_DEV` port and the USB Serial/JTAG interface are used for
+the STDIO (module `stdio_usb_serial_jtag`). 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 USB-to-UART bridge and `UART_DEV(0)` could be used for the
+STDIO. Simply add `stdio_uart` to the list of used modules for this purpose:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+BOARD=esp32s3-usb-otg USEMODULE=stdio_uart make flash ...
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ */