1.. zephyr:board:: ttgo_t7v1_5
2
3Overview
4********
5
6LILYGO® TTGO T7 Mini32 V1.5 ia an IoT mini development board
7based on the Espressif ESP32-WROVER-E module.
8
9It features the following integrated components:
10- ESP32 chip (240MHz dual core, 520KB SRAM, Wi-Fi, Bluetooth)
11- on board antenna
12- Micro-USB connector for power and communication
13- JST GH 2-pin battery connector
14- LED
15
16Functional Description
17**********************
18This board is based on the ESP32-WROVER-E module with 4MB of flash (there
19are models 16MB as well), WiFi and BLE support. It has a Micro-USB port for
20programming and debugging, integrated battery charging and an on-board antenna.
21
22Connections and IOs
23===================
24
25The ``ttgo_t7v1_5/esp32/procpu`` board target supports the following hardware features:
26
27+-----------+------------+------------------+
28| Interface | Controller | Driver/Component |
29+===========+============+==================+
30| CPU       | ESP32      | arch/xtensa      |
31+-----------+------------+------------------+
32| GPIO      | on-chip    | gpio_esp32       |
33+-----------+------------+------------------+
34| UART      | on-chip    | uart_esp32       |
35+-----------+------------+------------------+
36| I2C       | on-chip    | i2c_esp32        |
37+-----------+------------+------------------+
38| SPI       | on-chip    | spi_esp32_spim   |
39+-----------+------------+------------------+
40| LoRa      | SX1276     | lora_sx127x      |
41+-----------+------------+------------------+
42| WiFi      | on-chip    | wifi_esp32       |
43+-----------+------------+------------------+
44| BLE       | on-chip    | bluetooth_esp32  |
45+-----------+------------+------------------+
46| Flash     | on-chip    | flash_esp32      |
47+-----------+------------+------------------+
48
49System requirements
50*******************
51
52Prerequisites
53=============
54
55Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
56below to retrieve those files.
57
58.. code-block:: console
59
60   west blobs fetch hal_espressif
61
62.. note::
63
64   It is recommended running the command above after :file:`west update`.
65
66Building & Flashing
67*******************
68
69Simple boot
70===========
71
72The board could be loaded using the single binary image, without 2nd stage bootloader.
73It is the default option when building the application without additional configuration.
74
75.. note::
76
77   Simple boot does not provide any security features nor OTA updates.
78
79MCUboot bootloader
80==================
81
82User may choose to use MCUboot bootloader instead. In that case the bootloader
83must be build (and flash) at least once.
84
85There are two options to be used when building an application:
86
871. Sysbuild
882. Manual build
89
90.. note::
91
92   User can select the MCUboot bootloader by adding the following line
93   to the board default configuration file.
94
95   .. code:: cfg
96
97      CONFIG_BOOTLOADER_MCUBOOT=y
98
99Sysbuild
100========
101
102The sysbuild makes possible to build and flash all necessary images needed to
103bootstrap the board with the ESP32 SoC.
104
105To build the sample application using sysbuild use the command:
106
107.. zephyr-app-commands::
108   :tool: west
109   :app: samples/hello_world
110   :board: ttgo_t7v1_5/esp32/procpu
111   :goals: build
112   :west-args: --sysbuild
113   :compact:
114
115By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
116images. But it can be configured to create other kind of images.
117
118Build directory structure created by sysbuild is different from traditional
119Zephyr build. Output is structured by the domain subdirectories:
120
121.. code-block::
122
123  build/
124  ├── hello_world
125  │   └── zephyr
126  │       ├── zephyr.elf
127  │       └── zephyr.bin
128  ├── mcuboot
129  │    └── zephyr
130  │       ├── zephyr.elf
131  │       └── zephyr.bin
132  └── domains.yaml
133
134.. note::
135
136   With ``--sysbuild`` option the bootloader will be re-build and re-flash
137   every time the pristine build is used.
138
139For more information about the system build please read the :ref:`sysbuild` documentation.
140
141Manual build
142============
143
144During the development cycle, it is intended to build & flash as quickly possible.
145For that reason, images can be build one at a time using traditional build.
146
147The instructions following are relevant for both manual build and sysbuild.
148The only difference is the structure of the build directory.
149
150.. note::
151
152   Remember that bootloader (MCUboot) needs to be flash at least once.
153
154Build and flash applications as usual (see :ref:`build_an_application` and
155:ref:`application_run` for more details).
156
157.. zephyr-app-commands::
158   :zephyr-app: samples/hello_world
159   :board: ttgo_t7v1_5/esp32/procpu
160   :goals: build
161
162The usual ``flash`` target will work with the ``ttgo_t7v1_5`` board
163configuration. Here is an example for the :zephyr:code-sample:`hello_world`
164application.
165
166.. zephyr-app-commands::
167   :zephyr-app: samples/hello_world
168   :board: ttgo_t7v1_5/esp32/procpu
169   :goals: flash
170
171The default baud rate for the Lilygo TTGO T7 V1.5 is set to 1500000bps. If experiencing issues when flashing,
172try using different values by using ``--esp-baud-rate <BAUD>`` option during
173``west flash`` (e.g. ``west flash --esp-baud-rate 115200``).
174
175You can also open the serial monitor using the following command:
176
177.. code-block:: shell
178
179   west espressif monitor
180
181After the board has automatically reset and booted, you should see the following
182message in the monitor:
183
184.. code-block:: console
185
186   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
187   Hello World! ttgo_t7v1_5
188
189Sample applications
190===================
191
192The following samples will run out of the box on the TTGO T7 V1.5 board.
193
194To build the blinky sample:
195
196.. zephyr-app-commands::
197   :tool: west
198   :app: samples/basic/blinky
199   :board: ttgo_t7v1_5/esp32/procpu
200   :goals: build
201
202To build the bluetooth beacon sample:
203
204.. zephyr-app-commands::
205   :tool: west
206   :app: samples/bluetooth/beacon
207   :board: ttgo_t7v1_5/esp32/procpu
208   :goals: build
209
210
211Related Documents
212*****************
213.. _`Lilygo TTGO T7-V1.5 schematic`: https://github.com/LilyGO/TTGO-T7-Demo/blob/master/t7_v1.5.pdf
214.. _`Lilygo github repo`: https://github.com/LilyGO/TTGO-T7-Demo/tree/master
215.. _`Espressif ESP32-WROVER-E datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-wrover-e_esp32-wrover-ie_datasheet_en.pdf
216.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
217