1.. zephyr:board:: walter
2
3Overview
4********
5
6Walter is a compact IoT development board that combines an Espressif ESP32-S3 SoC
7with a Sequans Monarch 2 GM02SP LTE-M/NB-IoT/GNSS modem.
8More information about Walter can be found on the `QuickSpot Website`_ and on the
9`QuickSpot GitHub page`_.
10
11Hardware
12********
13
14ESP32-S3-WROOM-1-N16R2 microcontroller:
15
16- Xtensa dual-core 32-bit LX7 CPU
17- 16 MiB quad SPI flash memory
18- 2 MiB quad SPI PSRAM
19- 150 Mbps 802.11 b/g/n Wi-Fi 4 with on-board PCB antenna
20- 2 Mbps Bluetooth 5 Low Energy with on-board PCB antenna
21
22Sequans Monarch 2 GM02SP modem:
23
24- Dual-mode LTE-M / NB-IoT (NB1, NB2)
25- 3GPP LTE release 14 (Upgradable up to release 17)
26- Ultra-low, deep-sleep mode in eDRX and PSM
27- Adaptive +23 dBm, +20 dBm and +14 dBm output power
28- Integrated LNA and SAW filter for GNSS reception
29- Assisted and non-assisted GNSS with GPS and Galileo constellations
30- Integrated SIM card
31- Nano-SIM card slot
32- u.FL RF connectors for GNSS and 5G antennas
33
34Inputs & outputs:
35
36- 24 GPIO pins for application use
37- UART, SPI, I²C, CAN, I²S, and SD available on any of the GPIO pins
38- ADC, DAC, and PWM integrated in ESP32-S3
39- 3.3 V software-controllable output
40- USB Type-C connector for flashing and debugging
41- 22 test points for production programming and testing
42- On-board reset button
43
44Power supply
45
46- 5.0 V via USB Type-C
47- 3.0 - 5.5 V via Vin pin
48- Not allowed to use both power inputs simultaneously
49- Designed for extremely low quiescent current
50
51Form factor
52
53- Easy to integrate via 2.54 mm headers
54- 55 mm x 24.8 mm board dimensions
55- Pin and footprint compatible with EOL Pycom GPy
56- Breadboard friendly
57
58Supported Features
59==================
60
61Current Zephyr's Walter board supports the following features:
62
63+------------+------------+-------------------------------------+
64| Interface  | Controller | Driver/Component                    |
65+============+============+=====================================+
66| UART       | on-chip    | serial port                         |
67+------------+------------+-------------------------------------+
68| GPIO       | on-chip    | gpio                                |
69+------------+------------+-------------------------------------+
70| PINMUX     | on-chip    | pinmux                              |
71+------------+------------+-------------------------------------+
72| USB-JTAG   | on-chip    | hardware interface                  |
73+------------+------------+-------------------------------------+
74| SPI Master | on-chip    | spi                                 |
75+------------+------------+-------------------------------------+
76| TWAI/CAN   | on-chip    | can                                 |
77+------------+------------+-------------------------------------+
78| ADC        | on-chip    | adc                                 |
79+------------+------------+-------------------------------------+
80| Timers     | on-chip    | counter                             |
81+------------+------------+-------------------------------------+
82| Watchdog   | on-chip    | watchdog                            |
83+------------+------------+-------------------------------------+
84| TRNG       | on-chip    | entropy                             |
85+------------+------------+-------------------------------------+
86| LEDC       | on-chip    | pwm                                 |
87+------------+------------+-------------------------------------+
88| MCPWM      | on-chip    | pwm                                 |
89+------------+------------+-------------------------------------+
90| PCNT       | on-chip    | qdec                                |
91+------------+------------+-------------------------------------+
92| GDMA       | on-chip    | dma                                 |
93+------------+------------+-------------------------------------+
94| USB-CDC    | on-chip    | serial                              |
95+------------+------------+-------------------------------------+
96| Wi-Fi      | on-chip    |                                     |
97+------------+------------+-------------------------------------+
98| Bluetooth  | on-chip    |                                     |
99+------------+------------+-------------------------------------+
100| Cellular   | on-board   | modem_cellular                      |
101+------------+------------+-------------------------------------+
102
103Prerequisites
104-------------
105
106Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
107below to retrieve those files.
108
109.. code-block:: console
110
111   west blobs fetch hal_espressif
112
113.. note::
114
115   It is recommended running the command above after :file:`west update`.
116
117Building & Flashing
118*******************
119
120Simple boot
121===========
122
123The board could be loaded using the single binary image, without 2nd stage bootloader.
124It is the default option when building the application without additional configuration.
125
126.. note::
127
128   Simple boot does not provide any security features nor OTA updates.
129
130MCUboot bootloader
131==================
132
133User may choose to use MCUboot bootloader instead. In that case the bootloader
134must be build (and flash) at least once.
135
136There are two options to be used when building an application:
137
1381. Sysbuild
1392. Manual build
140
141.. note::
142
143   User can select the MCUboot bootloader by adding the following line
144   to the board default configuration file.
145
146   .. code:: cfg
147
148      CONFIG_BOOTLOADER_MCUBOOT=y
149
150Sysbuild
151========
152
153The sysbuild makes possible to build and flash all necessary images needed to
154bootstrap the board with the ESP32-S3 SoC.
155
156To build the sample application using sysbuild use the command:
157
158.. zephyr-app-commands::
159   :tool: west
160   :app: samples/hello_world
161   :board: walter/esp32s3/procpu
162   :goals: build
163   :west-args: --sysbuild
164   :compact:
165
166By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
167images. But it can be configured to create other kind of images.
168
169Build directory structure created by sysbuild is different from traditional
170Zephyr build. Output is structured by the domain subdirectories:
171
172.. code-block::
173
174  build/
175  ├── hello_world
176  │   └── zephyr
177  │       ├── zephyr.elf
178  │       └── zephyr.bin
179  ├── mcuboot
180  │    └── zephyr
181  │       ├── zephyr.elf
182  │       └── zephyr.bin
183  └── domains.yaml
184
185.. note::
186
187   With ``--sysbuild`` option the bootloader will be re-build and re-flash
188   every time the pristine build is used.
189
190For more information about the system build please read the :ref:`sysbuild` documentation.
191
192Manual build
193============
194
195During the development cycle, it is intended to build & flash as quickly possible.
196For that reason, images can be build one at a time using traditional build.
197
198The instructions following are relevant for both manual build and sysbuild.
199The only difference is the structure of the build directory.
200
201.. note::
202
203   Remember that bootloader (MCUboot) needs to be flash at least once.
204
205Build and flash applications as usual (see :ref:`build_an_application` and
206:ref:`application_run` for more details).
207
208.. zephyr-app-commands::
209   :zephyr-app: samples/hello_world
210   :board: walter/esp32s3/procpu
211   :goals: build
212
213The usual ``flash`` target will work with the ``walter`` board
214configuration. Here is an example for the :zephyr:code-sample:`hello_world`
215application.
216
217.. zephyr-app-commands::
218   :zephyr-app: samples/hello_world
219   :board: walter/esp32s3/procpu
220   :goals: flash
221
222Open the serial monitor using the following command:
223
224.. code-block:: shell
225
226   west espressif monitor
227
228After the board has automatically reset and booted, you should see the following
229message in the monitor:
230
231.. code-block:: console
232
233   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
234   Hello World! walter/esp32s3/procpu
235
236Debugging
237*********
238
239ESP32-S3 support on OpenOCD is available at `OpenOCD ESP32`_.
240
241ESP32-S3 has a built-in JTAG circuitry and can be debugged without any additional chip. Only an USB cable connected to the D+/D- pins is necessary.
242
243Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32-S3`_.
244
245Here is an example for building the :zephyr:code-sample:`hello_world` application.
246
247.. zephyr-app-commands::
248   :zephyr-app: samples/hello_world
249   :board: walter/esp32s3/procpu
250   :goals: build flash
251
252You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application.
253
254.. zephyr-app-commands::
255   :zephyr-app: samples/hello_world
256   :board: walter/esp32s3/procpu
257   :goals: debug
258
259References
260**********
261
262.. target-notes::
263
264.. _`QuickSpot Website`: https://www.quickspot.io/
265.. _`QuickSpot GitHub page`: https://github.com/QuickSpot
266.. _`JTAG debugging for ESP32-S3`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/jtag-debugging/
267.. _`OpenOCD ESP32`: https://github.com/openocd-org/openocd
268