diff --git a/boards/lilygo/tdongle_s3/Kconfig b/boards/lilygo/tdongle_s3/Kconfig new file mode 100644 index 000000000000..2da6bfecb7c9 --- /dev/null +++ b/boards/lilygo/tdongle_s3/Kconfig @@ -0,0 +1,7 @@ +# Copyright (c) 2025 Stefan Golinschi +# SPDX-License-Identifier: Apache-2.0 + +config HEAP_MEM_POOL_ADD_SIZE_BOARD + int + default 4096 if BOARD_TDONGLE_S3_ESP32S3_PROCPU + default 256 if BOARD_TDONGLE_S3_ESP32S3_APPCPU diff --git a/boards/lilygo/tdongle_s3/Kconfig.sysbuild b/boards/lilygo/tdongle_s3/Kconfig.sysbuild new file mode 100644 index 000000000000..6173838df77f --- /dev/null +++ b/boards/lilygo/tdongle_s3/Kconfig.sysbuild @@ -0,0 +1,10 @@ +# Copyright(c) 2025 Stefan Golinschi < stefan.golinschi @gmail.com> +# SPDX - License - Identifier : Apache - 2.0 + +choice BOOTLOADER + default BOOTLOADER_MCUBOOT +endchoice + +choice BOOT_SIGNATURE_TYPE + default BOOT_SIGNATURE_TYPE_NONE +endchoice diff --git a/boards/lilygo/tdongle_s3/Kconfig.tdongle_s3 b/boards/lilygo/tdongle_s3/Kconfig.tdongle_s3 new file mode 100644 index 000000000000..12f013272e00 --- /dev/null +++ b/boards/lilygo/tdongle_s3/Kconfig.tdongle_s3 @@ -0,0 +1,7 @@ +# Copyright (c) 2025 Stefan Golinschi +# SPDX-License-Identifier: Apache-2.0 + +config BOARD_TDONGLE_S3 + select SOC_ESP32S3_WROOM_N16R8 + select SOC_ESP32S3_PROCPU if BOARD_TDONGLE_S3_ESP32S3_PROCPU + select SOC_ESP32S3_APPCPU if BOARD_TDONGLE_S3_ESP32S3_APPCPU diff --git a/boards/lilygo/tdongle_s3/board.cmake b/boards/lilygo/tdongle_s3/board.cmake new file mode 100644 index 000000000000..3bde85956087 --- /dev/null +++ b/boards/lilygo/tdongle_s3/board.cmake @@ -0,0 +1,10 @@ +# Copyright(c) 2025 Stefan Golinschi < stefan.golinschi @gmail.com> +# SPDX - License - Identifier : Apache - 2.0 + +if(NOT "${OPENOCD}" MATCHES "^${ESPRESSIF_TOOLCHAIN_PATH}/.*") + set(OPENOCD OPENOCD-NOTFOUND) +endif() +find_program(OPENOCD openocd PATHS ${ESPRESSIF_TOOLCHAIN_PATH}/openocd-esp32/bin NO_DEFAULT_PATH) + +include(${ZEPHYR_BASE}/boards/common/esp32.board.cmake) +include(${ZEPHYR_BASE}/boards/common/openocd.board.cmake) diff --git a/boards/lilygo/tdongle_s3/board.yml b/boards/lilygo/tdongle_s3/board.yml new file mode 100644 index 000000000000..778871178114 --- /dev/null +++ b/boards/lilygo/tdongle_s3/board.yml @@ -0,0 +1,6 @@ +board: + name: tdongle_s3 + full_name: Lilygo T-Dongle S3 + vendor: lilygo + socs: + - name: esp32s3 diff --git a/boards/lilygo/tdongle_s3/doc/img/tdongle_s3.webp b/boards/lilygo/tdongle_s3/doc/img/tdongle_s3.webp new file mode 100644 index 000000000000..b970f6b1b8d9 Binary files /dev/null and b/boards/lilygo/tdongle_s3/doc/img/tdongle_s3.webp differ diff --git a/boards/lilygo/tdongle_s3/doc/index.rst b/boards/lilygo/tdongle_s3/doc/index.rst new file mode 100644 index 000000000000..19964690d338 --- /dev/null +++ b/boards/lilygo/tdongle_s3/doc/index.rst @@ -0,0 +1,233 @@ +.. zephyr:board:: tdongle_s3 + +Overview +******** + +Lilygo T-Dongle S3 is an IoT mini development board based on the +Espressif ESP32-S3 WiFi/Bluetooth dual-mode chip. + +It features the following integrated components: + +- ESP32-S3 chip (240MHz dual core, Bluetooth 5, WiFi) +- On-board antenna and IPEX connector +- USB-A connector with integrated TF Card slot +- MX 1.25mm 2-pin battery connector +- APA102 RGB LED +- JST SH 1.0mm 4-pin UART connector +- Transparent plastic case + +Functional Description +********************** +This board is based on the ESP32-S3 with 16MB of flash, WiFi and BLE support. It +has an USB-A port for programming and debugging, integrated battery charging +and an on-board antenna. The fitted U.FL external antenna connector can be +enabled by moving a 0-ohm resistor. + +Connections and IOs +=================== + +The ``tdongle_s3`` board target supports the following hardware features: + ++------------+------------+-------------------------------------+ +| Interface | Controller | Driver/Component | ++============+============+=====================================+ +| UART | on-chip | serial port | ++------------+------------+-------------------------------------+ +| GPIO | on-chip | gpio | ++------------+------------+-------------------------------------+ +| PINMUX | on-chip | pinmux | ++------------+------------+-------------------------------------+ +| USB-JTAG | on-chip | hardware interface | ++------------+------------+-------------------------------------+ +| SPI Master | on-chip | spi, sdmmc | ++------------+------------+-------------------------------------+ +| TWAI/CAN | on-chip | can | ++------------+------------+-------------------------------------+ +| ADC | on-chip | adc | ++------------+------------+-------------------------------------+ +| Timers | on-chip | counter | ++------------+------------+-------------------------------------+ +| Watchdog | on-chip | watchdog | ++------------+------------+-------------------------------------+ +| TRNG | on-chip | entropy | ++------------+------------+-------------------------------------+ +| LEDC | on-chip | pwm | ++------------+------------+-------------------------------------+ +| MCPWM | on-chip | pwm | ++------------+------------+-------------------------------------+ +| PCNT | on-chip | qdec | ++------------+------------+-------------------------------------+ +| GDMA | on-chip | dma | ++------------+------------+-------------------------------------+ +| USB-CDC | on-chip | serial | ++------------+------------+-------------------------------------+ +| DISPLAY | on-chip | display | ++------------+------------+-------------------------------------+ + +Start Application Development +***************************** + +Before powering up your Lilygo T-Dongle T8-S3, please make sure that the board is in good +condition with no obvious signs of damage. + +System requirements +******************* + +Prerequisites +============= + +Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command +below to retrieve those files. + +.. code-block:: console + + west blobs fetch hal_espressif + +.. note:: + + It is recommended running the command above after :file:`west update`. + +Building & Flashing +******************* + +Simple boot +=========== + +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. + +MCUboot bootloader +================== + +User may choose to use MCUboot bootloader instead. In that case the bootloader +must be built (and flashed) at least once. + +There are two options to be used when building an application: + +1. Sysbuild +2. Manual build + +.. note:: + + User can select the MCUboot bootloader by adding the following line + to the board default configuration file. + + .. code-block:: cfg + + CONFIG_BOOTLOADER_MCUBOOT=y + +Sysbuild +======== + +The sysbuild makes possible to build and flash all necessary images needed to +bootstrap the board with the ESP32 SoC. + +To build the sample application using sysbuild use the command: + +.. zephyr-app-commands:: + :tool: west + :zephyr-app: samples/hello_world + :board: tdongle_s3/esp32s3/procpu + :goals: build + :west-args: --sysbuild + :compact: + +By default, the ESP32 sysbuild creates bootloader (MCUboot) and application +images. But it can be configured to create other kind of images. + +Build directory structure created by sysbuild is different from traditional +Zephyr build. Output is structured by the domain subdirectories: + +.. code-block:: + + build/ + ├── hello_world + │   └── zephyr + │   ├── zephyr.elf + │   └── zephyr.bin + ├── mcuboot + │ └── zephyr + │ ├── zephyr.elf + │ └── zephyr.bin + └── domains.yaml + +.. note:: + + With ``--sysbuild`` option the bootloader will be re-build and re-flash + every time the pristine build is used. + +For more information about the system build please read the :ref:`sysbuild` documentation. + +Manual build +============ + +During the development cycle, it is intended to build & flash as quickly possible. +For that reason, images can be built one at a time using traditional build. + +The instructions following are relevant for both manual build and sysbuild. +The only difference is the structure of the build directory. + +.. note:: + + Remember that bootloader (MCUboot) needs to be flash at least once. + +Build and flash applications as usual (see :ref:`build_an_application` and +:ref:`application_run` for more details). + +.. zephyr-app-commands:: + :zephyr-app: samples/hello_world + :board: tdongle_s3/esp32s3/procpu + :goals: build + +The usual ``flash`` target will work with the ``tdongle_s3`` board target +configuration. Here is an example for the :zephyr:code-sample:`hello_world` +application. + +.. zephyr-app-commands:: + :zephyr-app: samples/hello_world + :board: tdongle_s3/esp32s3/procpu + :goals: flash + +The default baud rate for the Lilygo T-Dongle S3 is set to 1500000bps. If experiencing issues when flashing, +try using different values by using ``--esp-baud-rate `` option during +``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). + +You can also open the serial monitor using the following command: + +.. code-block:: shell + + west espressif monitor + +After the board has automatically reset and booted, you should see the following +message in the monitor: + +.. code-block:: console + + ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** + Hello World! tdongle_s3 + +Code samples +============ + +The following code samples will run out of the box on the T-Dongle S3 board: + +* :zephyr:code-sample:`wifi-shell` +* :zephyr:code-sample:`hello-world` +* :zephyr:code-sample:`display` + + +References +********** + +.. target-notes:: + +.. _`Lilygo T-Dongle S3 schematic`: https://github.com/Xinyuan-LilyGO/T-Dongle-S3/blob/main/shcematic/T-Dongle-S3.pdf +.. _`Lilygo github repo`: https://github.com/Xinyuan-LilyGO/T-Dongle-S3.git +.. _`ESP32-S3 Datasheet`: https://github.com/Xinyuan-LilyGO/T-Dongle-S3/blob/main/doc/esp32-s3_datasheet_en.pdf +.. _`ESP32-S3 Technical Reference Manual`: https://github.com/Xinyuan-LilyGO/T-Dongle-S3/blob/main/doc/esp32-s3_technical_reference_manual_en.pdf +.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases +.. _`JTAG debugging for ESP32-S3`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/jtag-debugging/ diff --git a/boards/lilygo/tdongle_s3/support/openocd.cfg b/boards/lilygo/tdongle_s3/support/openocd.cfg new file mode 100644 index 000000000000..0b2c4909fe0e --- /dev/null +++ b/boards/lilygo/tdongle_s3/support/openocd.cfg @@ -0,0 +1,7 @@ +set ESP_RTOS none +set ESP32_ONLYCPU 1 + +source [find interface/esp_usb_jtag.cfg] + +source [find target/esp32s3.cfg] +adapter_khz 5000 diff --git a/boards/lilygo/tdongle_s3/tdongle_s3-pinctrl.dtsi b/boards/lilygo/tdongle_s3/tdongle_s3-pinctrl.dtsi new file mode 100644 index 000000000000..d345d79becc3 --- /dev/null +++ b/boards/lilygo/tdongle_s3/tdongle_s3-pinctrl.dtsi @@ -0,0 +1,51 @@ +/* + * Copyright 2025 Stefan Golinschi + * + * SPDX-License-Identifier: Apache-2.0 + */ + +#include +#include +#include + +&pinctrl { + uart0_default: uart0_default { + group1 { + pinmux = ; + output-high; + }; + group2 { + pinmux = ; + bias-pull-up; + }; + }; + + spim2_default: spim2_default { + group1 { + pinmux = , + , + ; + + }; + }; + + spim3_default: spim3_default { + group1 { + pinmux = , + ; + }; + }; + + sdhc0_default: sdhc0_default { + group1 { + pinmux = , + , + , + , + , + ; + bias-pull-up; + output-high; + }; + }; +}; diff --git a/boards/lilygo/tdongle_s3/tdongle_s3_appcpu.dts b/boards/lilygo/tdongle_s3/tdongle_s3_appcpu.dts new file mode 100644 index 000000000000..68c7c501421e --- /dev/null +++ b/boards/lilygo/tdongle_s3/tdongle_s3_appcpu.dts @@ -0,0 +1,31 @@ +/* + * Copyright 2025 Stefan Golinschi + * + * SPDX-License-Identifier: Apache-2.0 + */ + +/dts-v1/; + +#include +#include + +/ { + model = "TDONGLE S3 APPCPU"; + compatible = "espressif,esp32s3"; + + chosen { + zephyr,sram = &sram0; + zephyr,ipc_shm = &shm0; + zephyr,ipc = &ipm0; + zephyr,flash = &flash0; + zephyr,code-partition = &slot0_appcpu_partition; + }; +}; + +&trng0 { + status = "okay"; +}; + +&ipm0 { + status = "okay"; +}; diff --git a/boards/lilygo/tdongle_s3/tdongle_s3_appcpu_defconfig b/boards/lilygo/tdongle_s3/tdongle_s3_appcpu_defconfig new file mode 100644 index 000000000000..3354204ec78d --- /dev/null +++ b/boards/lilygo/tdongle_s3/tdongle_s3_appcpu_defconfig @@ -0,0 +1,4 @@ +# Copyright(c) 2025 Stefan Golinschi < stefan.golinschi @gmail.com> +# SPDX - License - Identifier : Apache - 2.0 + +CONFIG_CLOCK_CONTROL=y diff --git a/boards/lilygo/tdongle_s3/tdongle_s3_procpu.dts b/boards/lilygo/tdongle_s3/tdongle_s3_procpu.dts new file mode 100644 index 000000000000..9b17037ae439 --- /dev/null +++ b/boards/lilygo/tdongle_s3/tdongle_s3_procpu.dts @@ -0,0 +1,158 @@ +/* + * Copyright 2025 Stefan Golinschi + * + * SPDX-License-Identifier: Apache-2.0 + */ + +/dts-v1/; + +#include +#include "tdongle_s3-pinctrl.dtsi" +#include +#include +#include +#include + +/ { + model = "TDONGLE S3 PROCPU"; + compatible = "espressif,esp32s3"; + + aliases { + watchdog0 = &wdt0; + sdhc0 = &sdhc0; + uart-0 = &uart0; + sw0 = &button0; + led-strip = &apa102; + }; + + chosen { + zephyr,sram = &sram0; + /* console can be UART or USB CDC */ + /* zephyr,console = &uart0; */ + /* zephyr,shell-uart = &uart0; */ + zephyr,console = &usb_serial; + zephyr,shell-uart = &usb_serial; + zephyr,flash = &flash0; + zephyr,code-partition = &slot0_partition; + zephyr,bt-hci = &esp32_bt_hci; + zephyr,display = &st7735r; + zephyr,sdhc = &sdhc0; + }; + + buttons { + compatible = "gpio-keys"; + button0: button_0 { + gpios = <&gpio0 0 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>; + label = "BOOT Button"; + zephyr,code = ; + }; + status="okay"; + }; + + mipi_dbi { + compatible = "zephyr,mipi-dbi-spi"; + /* Enable D/C line for 4wire mode */ + dc-gpios = <&gpio0 2 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio0 1 GPIO_ACTIVE_LOW>; + spi-dev = <&spi2>; + #address-cells = <1>; + #size-cells = <0>; + write-only; + status = "okay"; + + st7735r: st7735r@0 { + compatible = "sitronix,st7735r"; + mipi-max-frequency = <20000000>; + mipi-mode = "MIPI_DBI_MODE_SPI_4WIRE"; + reg = <0>; + width = <160>; + height = <80>; + inversion-on; + rgb-is-inverted; + madctl = <0xBE>; + x-offset = <1>; + y-offset = <26>; + gamctrp1 = [02 1c 07 12 37 32 29 2d 29 25 2B 39 00 01 03 10]; + gamctrn1 = [03 1d 07 06 2E 2C 29 2D 2E 2E 37 3F 00 00 02 10]; + te-delay = <0x0A>; + vmctr1 = <0x0E>; + colmod = <0x05>; + caset = [00 02 00 81]; + raset = [00 01 00 A0]; + status = "okay"; + }; + }; +}; + +&uart0 { + current-speed = <115200>; + pinctrl-0 = <&uart0_default>; + pinctrl-names = "default"; + status = "okay"; +}; + +&spi2 { + #address-cells = <1>; + #size-cells = <0>; + cs-gpios = <&gpio0 4 GPIO_ACTIVE_LOW>; + pinctrl-0 = <&spim2_default>; + pinctrl-names = "default"; + clock-frequency = <20000000>; + status = "okay"; +}; + +&spi3 { + #address-cells = <1>; + #size-cells = <0>; + pinctrl-0 = <&spim3_default>; + pinctrl-names = "default"; + clock-frequency = <20000000>; + status = "okay"; + + apa102: apa102@0 { + compatible = "apa,apa102"; + reg = <0>; + spi-max-frequency = <24000000>; + chain-length = <1>; + color-mapping = ; + status = "okay"; + }; +}; + +&usb_serial { + status = "okay"; +}; + +&timer0 { + status = "okay"; +}; + +&wdt0 { + status = "okay"; +}; + +&trng0 { + status = "okay"; +}; + +&esp32_bt_hci { + status = "okay"; +}; + +&sdhc { + sdhc0: sdhc@0 { + pinctrl-0 = <&sdhc0_default>; + pinctrl-names = "default"; + power-delay-ms = <100>; + max-bus-freq = <52000000>; + bus-width = <4>; + status = "okay"; + mmc { + compatible = "zephyr,sdmmc-disk"; + disk-name = "SD"; + status = "okay"; + }; + }; +}; diff --git a/boards/lilygo/tdongle_s3/tdongle_s3_procpu.yaml b/boards/lilygo/tdongle_s3/tdongle_s3_procpu.yaml new file mode 100644 index 000000000000..5b01812a0bfd --- /dev/null +++ b/boards/lilygo/tdongle_s3/tdongle_s3_procpu.yaml @@ -0,0 +1,22 @@ +identifier: tdongle_s3/esp32s3/procpu +name: TDONGLE S3 PROCPU +type: mcu +arch: xtensa +toolchain: + - zephyr +supported: + - gpio + - uart + - i2c + - i2s + - spi + - can + - counter + - watchdog + - entropy + - pwm + - dma + - input + - video + - display +vendor: lilygo diff --git a/boards/lilygo/tdongle_s3/tdongle_s3_procpu_defconfig b/boards/lilygo/tdongle_s3/tdongle_s3_procpu_defconfig new file mode 100644 index 000000000000..b43e7013c5f3 --- /dev/null +++ b/boards/lilygo/tdongle_s3/tdongle_s3_procpu_defconfig @@ -0,0 +1,8 @@ +# Copyright(c) 2025 Stefan Golinschi < stefan.golinschi @gmail.com> +# SPDX - License - Identifier : Apache - 2.0 + +CONFIG_CONSOLE=y +CONFIG_SERIAL=y +CONFIG_UART_CONSOLE=y +CONFIG_GPIO=y +CONFIG_CLOCK_CONTROL=y diff --git a/boards/lilygo/tdongle_s3/ttgo_t8s3_appcpu.yaml b/boards/lilygo/tdongle_s3/ttgo_t8s3_appcpu.yaml new file mode 100644 index 000000000000..b9bea7145c3e --- /dev/null +++ b/boards/lilygo/tdongle_s3/ttgo_t8s3_appcpu.yaml @@ -0,0 +1,27 @@ +identifier: tdongle_s3/esp32s3/appcpu +name: LILYGO T-DONGLE S3 APPCPU +type: mcu +arch: xtensa +toolchain: + - zephyr +supported: + - uart +testing: + ignore_tags: + - net + - bluetooth + - flash + - cpp + - posix + - watchdog + - logging + - kernel + - pm + - gpio + - crypto + - eeprom + - heap + - cmsis_rtos + - jwt + - zdsp +vendor: lilygo