1.. zephyr:board:: heltec_wifi_lora32_v2
2
3Overview
4********
5
6Heltec WiFi LoRa 32 is a classic IoT dev-board designed & produced by Heltec Automation(TM), it's a highly
7integrated product based on ESP32 + SX127x, it has Wi-Fi, BLE, LoRa functions, also Li-Po battery management
8system, 0.96" OLED are also included. [1]_
9
10The features include the following:
11
12- Microprocessor: ESP32 (dual-core 32-bit MCU + ULP core)
13- LoRa node chip SX1276/SX1278
14- Micro USB interface with a complete voltage regulator, ESD protection, short circuit protection,
15  RF shielding, and other protection measures
16- Onboard SH1.25-2 battery interface, integrated lithium battery management system
17- Integrated WiFi, LoRa, Bluetooth three network connections, onboard Wi-Fi, Bluetooth dedicated 2.4GHz
18  metal 3D antenna, reserved IPEX (U.FL) interface for LoRa use
19- Onboard 0.96-inch 128*64 dot matrix OLED display
20- Integrated CP2102 USB to serial port chip
21
22System requirements
23*******************
24
25Prerequisites
26=============
27
28Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
29below to retrieve those files.
30
31.. code-block:: console
32
33   west blobs fetch hal_espressif
34
35.. note::
36
37   It is recommended running the command above after :file:`west update`.
38
39Building & Flashing
40*******************
41
42Simple boot
43===========
44
45The board could be loaded using the single binary image, without 2nd stage bootloader.
46It is the default option when building the application without additional configuration.
47
48.. note::
49
50   Simple boot does not provide any security features nor OTA updates.
51
52MCUboot bootloader
53==================
54
55User may choose to use MCUboot bootloader instead. In that case the bootloader
56must be built (and flashed) at least once.
57
58There are two options to be used when building an application:
59
601. Sysbuild
612. Manual build
62
63.. note::
64
65   User can select the MCUboot bootloader by adding the following line
66   to the board default configuration file.
67
68   .. code:: cfg
69
70      CONFIG_BOOTLOADER_MCUBOOT=y
71
72Sysbuild
73========
74
75The sysbuild makes possible to build and flash all necessary images needed to
76bootstrap the board with the ESP32 SoC.
77
78To build the sample application using sysbuild use the command:
79
80.. zephyr-app-commands::
81   :tool: west
82   :zephyr-app: samples/hello_world
83   :board: heltec_wifi_lora32_v2
84   :goals: build
85   :west-args: --sysbuild
86   :compact:
87
88By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
89images. But it can be configured to create other kind of images.
90
91Build directory structure created by sysbuild is different from traditional
92Zephyr build. Output is structured by the domain subdirectories:
93
94.. code-block::
95
96  build/
97  ├── hello_world
98  │   └── zephyr
99  │       ├── zephyr.elf
100  │       └── zephyr.bin
101  ├── mcuboot
102  │    └── zephyr
103  │       ├── zephyr.elf
104  │       └── zephyr.bin
105  └── domains.yaml
106
107.. note::
108
109   With ``--sysbuild`` option the bootloader will be re-build and re-flash
110   every time the pristine build is used.
111
112For more information about the system build please read the :ref:`sysbuild` documentation.
113
114Manual build
115============
116
117During the development cycle, it is intended to build & flash as quickly possible.
118For that reason, images can be built one at a time using traditional build.
119
120The instructions following are relevant for both manual build and sysbuild.
121The only difference is the structure of the build directory.
122
123.. note::
124
125   Remember that bootloader (MCUboot) needs to be flash at least once.
126
127Build and flash applications as usual (see :ref:`build_an_application` and
128:ref:`application_run` for more details).
129
130.. zephyr-app-commands::
131   :zephyr-app: samples/hello_world
132   :board: heltec_wifi_lora32_v2/esp32/procpu
133   :goals: build
134
135The usual ``flash`` target will work with the ``heltec_wifi_lora32_v2`` board
136configuration. Here is an example for the :zephyr:code-sample:`hello_world`
137application.
138
139.. zephyr-app-commands::
140   :zephyr-app: samples/hello_world
141   :board: heltec_wifi_lora32_v2/esp32/procpu
142   :goals: flash
143
144Open the serial monitor using the following command:
145
146.. code-block:: shell
147
148   west espressif monitor
149
150After the board has automatically reset and booted, you should see the following
151message in the monitor:
152
153.. code-block:: console
154
155   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
156   Hello World! heltec_wifi_lora32_v2
157
158Debugging
159*********
160
161As with much custom hardware, the ESP32 modules require patches to
162OpenOCD that are not upstreamed yet. Espressif maintains their own fork of
163the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_.
164
165The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
166``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
167parameter when building.
168
169Here is an example for building the :zephyr:code-sample:`hello_world` application.
170
171.. zephyr-app-commands::
172   :zephyr-app: samples/hello_world
173   :board: heltec_wifi_lora32_v2/esp32/procpu
174   :goals: build flash
175   :gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
176
177You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application.
178
179.. zephyr-app-commands::
180   :zephyr-app: samples/hello_world
181   :board: heltec_wifi_lora32_v2/esp32/procpu
182   :goals: debug
183
184Utilizing Hardware Features
185***************************
186
187Onboard OLED display
188====================
189
190The onboard OLED display is of type ``ssd1306``, has 128*64 pixels and is
191connected via I2C. It can therefore be used by enabling the
192:ref:`ssd1306_128_shield` as shown in the following for the :zephyr:code-sample:`lvgl` sample:
193
194.. zephyr-app-commands::
195   :zephyr-app: samples/subsys/display/lvgl
196   :board: heltec_wifi_lora32_v2/esp32/procpu
197   :shield: ssd1306_128x64
198   :goals: flash
199
200References
201**********
202
203- `Heltec WiFi LoRa (v2) Pinout Diagram <https://resource.heltec.cn/download/WiFi_LoRa_32/WIFI_LoRa_32_V2.pdf>`_
204- `Heltec WiFi LoRa (v2) Schematic Diagrams <https://resource.heltec.cn/download/WiFi_LoRa_32/V2>`_
205- `ESP32 Toolchain <https://docs.espressif.com/projects/esp-idf/en/v4.2/esp32/api-guides/tools/idf-tools.html#xtensa-esp32-elf>`_
206- `esptool documentation <https://github.com/espressif/esptool/blob/master/README.md>`_
207- `OpenOCD ESP32 <https://github.com/espressif/openocd-esp32/releases>`_
208
209.. [1] https://heltec.org/project/wifi-lora-32/
210