1.. zephyr:board:: we_orthosie1ev
2
3Overview
4********
5
6Orthosie-I-EV is an entry-level development board based on Orthosie-I,
7a module named for its small size. This board integrates complete Wi-Fi and Bluetooth® Low Energy functions.
8For more information, check `Orthosie-I Website`_.
9
10Hardware
11********
12
13ESP32-C3 is a single-core Wi-Fi and Bluetooth 5 (LE) microcontroller SoC,
14based on the open-source RISC-V architecture. It strikes the right balance of power,
15I/O capabilities and security, thus offering the optimal cost-effective
16solution for connected devices.
17The availability of Wi-Fi and Bluetooth 5 (LE) connectivity not only makes the device configuration easy,
18but it also facilitates a variety of use-cases based on dual connectivity.
19
20The features include the following:
21
22- 32-bit core RISC-V microcontroller with a maximum clock speed of 160 MHz
23- 400 KB of internal RAM
24- 802.11b/g/n/e/i
25- A Bluetooth LE subsystem that supports features of Bluetooth 5 and Bluetooth Mesh
26- Various peripherals:
27
28  - 12-bit ADC with up to 6 channels
29  - TWAI compatible with CAN bus 2.0
30  - Temperature sensor
31  - 3x SPI
32  - 1x I2S
33  - 1x I2C
34  - 2x UART
35  - LED PWM with up to 6 channels
36
37- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES)
38
39For more information, check the datasheet at `ESP32-C3 Datasheet`_ or the technical reference
40manual at `ESP32-C3 Technical Reference Manual`_.
41
42Supported Features
43==================
44
45Currently Zephyr's ``we_orthosie1ev`` board target supports the following features:
46
47+------------+------------+-------------------------------------+
48| Interface  | Controller | Driver/Component                    |
49+============+============+=====================================+
50| UART       | on-chip    | serial port                         |
51+------------+------------+-------------------------------------+
52| GPIO       | on-chip    | gpio                                |
53+------------+------------+-------------------------------------+
54| PINMUX     | on-chip    | pinmux                              |
55+------------+------------+-------------------------------------+
56| USB-JTAG   | on-chip    | hardware interface                  |
57+------------+------------+-------------------------------------+
58| SPI Master | on-chip    | spi                                 |
59+------------+------------+-------------------------------------+
60| Timers     | on-chip    | counter                             |
61+------------+------------+-------------------------------------+
62| Watchdog   | on-chip    | watchdog                            |
63+------------+------------+-------------------------------------+
64| TRNG       | on-chip    | entropy                             |
65+------------+------------+-------------------------------------+
66| LEDC       | on-chip    | pwm                                 |
67+------------+------------+-------------------------------------+
68| SPI DMA    | on-chip    | spi                                 |
69+------------+------------+-------------------------------------+
70| TWAI       | on-chip    | can                                 |
71+------------+------------+-------------------------------------+
72| USB-CDC    | on-chip    | serial                              |
73+------------+------------+-------------------------------------+
74| ADC        | on-chip    | adc                                 |
75+------------+------------+-------------------------------------+
76| Wi-Fi      | on-chip    |                                     |
77+------------+------------+-------------------------------------+
78| Bluetooth  | on-chip    |                                     |
79+------------+------------+-------------------------------------+
80
81System requirements
82*******************
83
84Prerequisites
85=============
86
87Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
88below to retrieve those files.
89
90.. code-block:: console
91
92   west blobs fetch hal_espressif
93
94.. note::
95
96   It is recommended running the command above after :file:`west update`.
97
98Building & Flashing
99*******************
100
101Simple boot
102===========
103
104The board could be loaded using the single binary image, without 2nd stage bootloader.
105It is the default option when building the application without additional configuration.
106
107.. note::
108
109   Simple boot does not provide any security features nor OTA updates.
110
111MCUboot bootloader
112==================
113
114User may choose to use MCUboot bootloader instead. In that case the bootloader
115must be built (and flashed) at least once.
116
117There are two options to be used when building an application:
118
1191. Sysbuild
1202. Manual build
121
122.. note::
123
124   User can select the MCUboot bootloader by adding the following line
125   to the board default configuration file.
126
127   .. code:: cfg
128
129      CONFIG_BOOTLOADER_MCUBOOT=y
130
131Sysbuild
132========
133
134The sysbuild makes possible to build and flash all necessary images needed to
135bootstrap the board with the ESP32 SoC.
136
137To build the sample application using sysbuild use the command:
138
139.. zephyr-app-commands::
140   :tool: west
141   :zephyr-app: samples/hello_world
142   :board: orthosie1ev
143   :goals: build
144   :west-args: --sysbuild
145   :compact:
146
147By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
148images. But it can be configured to create other kind of images.
149
150Build directory structure created by sysbuild is different from traditional
151Zephyr build. Output is structured by the domain subdirectories:
152
153.. code-block::
154
155  build/
156  ├── hello_world
157  │   └── zephyr
158  │       ├── zephyr.elf
159  │       └── zephyr.bin
160  ├── mcuboot
161  │    └── zephyr
162  │       ├── zephyr.elf
163  │       └── zephyr.bin
164  └── domains.yaml
165
166.. note::
167
168   With ``--sysbuild`` option the bootloader will be re-build and re-flash
169   every time the pristine build is used.
170
171For more information about the system build please read the :ref:`sysbuild` documentation.
172
173Manual build
174============
175
176During the development cycle, it is intended to build & flash as quickly possible.
177For that reason, images can be built one at a time using traditional build.
178
179The instructions following are relevant for both manual build and sysbuild.
180The only difference is the structure of the build directory.
181
182.. note::
183
184   Remember that bootloader (MCUboot) needs to be flash at least once.
185
186Build and flash applications as usual (see :ref:`build_an_application` and
187:ref:`application_run` for more details).
188
189.. zephyr-app-commands::
190   :zephyr-app: samples/hello_world
191   :board: orthosie1ev
192   :goals: build
193
194The usual ``flash`` target will work with the ``orthosie1ev`` board
195configuration. Here is an example for the :zephyr:code-sample:`hello_world`
196application.
197
198.. zephyr-app-commands::
199   :zephyr-app: samples/hello_world
200   :board: orthosie1ev
201   :goals: flash
202
203Open the serial monitor using the following command:
204
205.. code-block:: shell
206
207   west espressif monitor
208
209After the board has automatically reset and booted, you should see the following
210message in the monitor:
211
212.. code-block:: console
213
214   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
215   Hello World! orthosie1ev
216
217Debugging
218*********
219
220As with much custom hardware, the ESP32-C3 modules require patches to
221OpenOCD that are not upstreamed yet. Espressif maintains their own fork of
222the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_.
223
224The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
225``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
226parameter when building.
227
228Here is an example for building the :zephyr:code-sample:`hello_world` application.
229
230.. zephyr-app-commands::
231   :zephyr-app: samples/hello_world
232   :board: orthosie1ev
233   :goals: build flash
234   :gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
235
236You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application.
237
238.. zephyr-app-commands::
239   :zephyr-app: samples/hello_world
240   :board: orthosie1ev
241   :goals: debug
242
243References
244**********
245
246.. target-notes::
247
248.. _`Orthosie-I Website`: https://www.we-online.com/en/components/products/ORTHOSIE-I
249.. _`ESP32-C3 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf
250.. _`ESP32-C3 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf
251.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
252