1.. zephyr:board:: ttgo_t8s3
2
3Overview
4********
5
6Lilygo TTGO T8-S3 is an IoT mini development board based on the
7Espressif ESP32-S3 WiFi/Bluetooth dual-mode chip.
8
9It features the following integrated components:
10
11- ESP32-S3 chip (240MHz dual core, Bluetooth LE, Wi-Fi)
12- on board antenna and IPEX connector
13- USB-C connector for power and communication
14- MX 1.25mm 2-pin battery connector
15- JST SH 1.0mm 4-pin UART connector
16- SD card slot
17
18Functional Description
19**********************
20This board is based on the ESP32-S3 with 16MB of flash, WiFi and BLE support. It
21has an USB-C port for programming and debugging, integrated battery charging
22and an on-board antenna. The fitted U.FL external antenna connector can be
23enabled by moving a 0-ohm resistor.
24
25Connections and IOs
26===================
27
28The ``ttgo_t8s3`` board target supports the following hardware features:
29
30+------------+------------+-------------------------------------+
31| Interface  | Controller | Driver/Component                    |
32+============+============+=====================================+
33| UART       | on-chip    | serial port                         |
34+------------+------------+-------------------------------------+
35| GPIO       | on-chip    | gpio                                |
36+------------+------------+-------------------------------------+
37| PINMUX     | on-chip    | pinmux                              |
38+------------+------------+-------------------------------------+
39| USB-JTAG   | on-chip    | hardware interface                  |
40+------------+------------+-------------------------------------+
41| SPI Master | on-chip    | spi, sdmmc                          |
42+------------+------------+-------------------------------------+
43| TWAI/CAN   | on-chip    | can                                 |
44+------------+------------+-------------------------------------+
45| ADC        | on-chip    | adc                                 |
46+------------+------------+-------------------------------------+
47| Timers     | on-chip    | counter                             |
48+------------+------------+-------------------------------------+
49| Watchdog   | on-chip    | watchdog                            |
50+------------+------------+-------------------------------------+
51| TRNG       | on-chip    | entropy                             |
52+------------+------------+-------------------------------------+
53| LEDC       | on-chip    | pwm                                 |
54+------------+------------+-------------------------------------+
55| MCPWM      | on-chip    | pwm                                 |
56+------------+------------+-------------------------------------+
57| PCNT       | on-chip    | qdec                                |
58+------------+------------+-------------------------------------+
59| GDMA       | on-chip    | dma                                 |
60+------------+------------+-------------------------------------+
61| USB-CDC    | on-chip    | serial                              |
62+------------+------------+-------------------------------------+
63
64Start Application Development
65*****************************
66
67Before powering up your Lilygo TTGO T8-S3, please make sure that the board is in good
68condition with no obvious signs of damage.
69
70System requirements
71*******************
72
73Prerequisites
74=============
75
76Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
77below to retrieve those files.
78
79.. code-block:: console
80
81   west blobs fetch hal_espressif
82
83.. note::
84
85   It is recommended running the command above after :file:`west update`.
86
87Building & Flashing
88*******************
89
90Simple boot
91===========
92
93The board could be loaded using the single binary image, without 2nd stage bootloader.
94It is the default option when building the application without additional configuration.
95
96.. note::
97
98   Simple boot does not provide any security features nor OTA updates.
99
100MCUboot bootloader
101==================
102
103User may choose to use MCUboot bootloader instead. In that case the bootloader
104must be built (and flashed) at least once.
105
106There are two options to be used when building an application:
107
1081. Sysbuild
1092. Manual build
110
111.. note::
112
113   User can select the MCUboot bootloader by adding the following line
114   to the board default configuration file.
115
116   .. code-block:: cfg
117
118      CONFIG_BOOTLOADER_MCUBOOT=y
119
120Sysbuild
121========
122
123The sysbuild makes possible to build and flash all necessary images needed to
124bootstrap the board with the ESP32 SoC.
125
126To build the sample application using sysbuild use the command:
127
128.. zephyr-app-commands::
129   :tool: west
130   :zephyr-app: samples/hello_world
131   :board: ttgo_t8s3/esp32s3/procpu
132   :goals: build
133   :west-args: --sysbuild
134   :compact:
135
136By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
137images. But it can be configured to create other kind of images.
138
139Build directory structure created by sysbuild is different from traditional
140Zephyr build. Output is structured by the domain subdirectories:
141
142.. code-block::
143
144  build/
145  ├── hello_world
146  │   └── zephyr
147  │       ├── zephyr.elf
148  │       └── zephyr.bin
149  ├── mcuboot
150  │    └── zephyr
151  │       ├── zephyr.elf
152  │       └── zephyr.bin
153  └── domains.yaml
154
155.. note::
156
157   With ``--sysbuild`` option the bootloader will be re-build and re-flash
158   every time the pristine build is used.
159
160For more information about the system build please read the :ref:`sysbuild` documentation.
161
162Manual build
163============
164
165During the development cycle, it is intended to build & flash as quickly possible.
166For that reason, images can be built one at a time using traditional build.
167
168The instructions following are relevant for both manual build and sysbuild.
169The only difference is the structure of the build directory.
170
171.. note::
172
173   Remember that bootloader (MCUboot) needs to be flash at least once.
174
175Build and flash applications as usual (see :ref:`build_an_application` and
176:ref:`application_run` for more details).
177
178.. zephyr-app-commands::
179   :zephyr-app: samples/hello_world
180   :board: ttgo_t8s3/esp32s3/procpu
181   :goals: build
182
183The usual ``flash`` target will work with the ``ttgo_t8s3`` board target
184configuration. Here is an example for the :zephyr:code-sample:`hello_world`
185application.
186
187.. zephyr-app-commands::
188   :zephyr-app: samples/hello_world
189   :board: ttgo_t8s3/esp32s3/procpu
190   :goals: flash
191
192The default baud rate for the Lilygo TTGO T8-S3 is set to 1500000bps. If experiencing issues when flashing,
193try using different values by using ``--esp-baud-rate <BAUD>`` option during
194``west flash`` (e.g. ``west flash --esp-baud-rate 115200``).
195
196You can also open the serial monitor using the following command:
197
198.. code-block:: shell
199
200   west espressif monitor
201
202After the board has automatically reset and booted, you should see the following
203message in the monitor:
204
205.. code-block:: console
206
207   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
208   Hello World! ttgo_t8s3
209
210Code samples
211============
212
213The following code samples will run out of the box on the TTGO T8-S3 board:
214
215* :zephyr:code-sample:`wifi-shell`
216* :zephyr:code-sample:`fs`
217
218
219References
220**********
221
222.. target-notes::
223
224.. _`Lilygo TTGO T8-S3 schematic`: https://github.com/Xinyuan-LilyGO/T8-S3/blob/main/schematic/T8_S3_V1.0.pdf
225.. _`Lilygo github repo`: https://github.com/Xinyuan-LilyGo
226.. _`ESP32-S3 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-s3-mini-1_mini-1u_datasheet_en.pdf
227.. _`ESP32-S3 Technical Reference Manual`: https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_en.pdf
228.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
229.. _`JTAG debugging for ESP32-S3`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/jtag-debugging/
230