1.. zephyr:board:: odroid_go
2
3Overview
4********
5
6ODROID-GO Game Kit is a "Do it yourself" ("DIY") portable game console by
7HardKernel. It features a custom ESP32-WROVER with 16 MB flash and it operates
8from 80 MHz - 240 MHz [1]_.
9
10The features include the following:
11
12- Dual core Xtensa microprocessor (LX6), running at 80 -  240MHz
13- 4 MB of PSRAM
14- 802.11b/g/n/e/i
15- Bluetooth v4.2 BR/EDR and BLE
16- 2.4 inch 320x240 TFT LCD
17- Speaker
18- Micro SD card slot
19- Micro USB port (battery charging and USB_UART data communication
20- Input Buttons (Menu, Volume, Select, Start, A, B, Direction Pad)
21- Expansion port (I2C, GPIO, SPI)
22- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES)
23
24External Connector
25==================
26
27+-------+------------------+-------------------------+
28| PIN # | Signal Name      | ESP32-WROVER Functions  |
29+=======+==================+=========================+
30| 1     | GND              | GND                     |
31+-------+------------------+-------------------------+
32| 2     | VSPI.SCK (IO18)  | GPIO18, VSPICLK         |
33+-------+------------------+-------------------------+
34| 3     | IO12             | GPIO12                  |
35+-------+------------------+-------------------------+
36| 4     | IO15             | GPIO15, ADC2_CH3        |
37+-------+------------------+-------------------------+
38| 5     | IO4              | GPIO4, ADC2_CH0         |
39+-------+------------------+-------------------------+
40| 6     | P3V3             | 3.3 V                   |
41+-------+------------------+-------------------------+
42| 7     | VSPI.MISO (IO19) | GPIO19, VSPIQ           |
43+-------+------------------+-------------------------+
44| 8     | VSPI.MOSI (IO23) | GPIO23, VSPID           |
45+-------+------------------+-------------------------+
46| 9     | N.C              | N/A                     |
47+-------+------------------+-------------------------+
48| 10    | VBUS             | USB VBUS (5V)           |
49+-------+------------------+-------------------------+
50
51Supported Features
52==================
53
54The Zephyr odroid_go board configuration supports the following hardware
55features:
56
57+------------+------------+-------------------------------------+
58| Interface  | Controller | Driver/Component                    |
59+============+============+=====================================+
60| UART       | on-chip    | serial port                         |
61+------------+------------+-------------------------------------+
62| GPIO       | on-chip    | gpio                                |
63+------------+------------+-------------------------------------+
64| PINMUX     | on-chip    | pinmux                              |
65+------------+------------+-------------------------------------+
66| I2C        | on-chip    | i2c                                 |
67+------------+------------+-------------------------------------+
68| SPI        | on-chip    | spi                                 |
69+------------+------------+-------------------------------------+
70
71
72System requirements
73*******************
74
75Prerequisites
76=============
77
78Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
79below to retrieve those files.
80
81.. code-block:: console
82
83   west blobs fetch hal_espressif
84
85.. note::
86
87   It is recommended running the command above after :file:`west update`.
88
89Building & Flashing
90*******************
91
92Simple boot
93===========
94
95The board could be loaded using the single binary image, without 2nd stage bootloader.
96It is the default option when building the application without additional configuration.
97
98.. note::
99
100   Simple boot does not provide any security features nor OTA updates.
101
102MCUboot bootloader
103==================
104
105User may choose to use MCUboot bootloader instead. In that case the bootloader
106must be built (and flashed) at least once.
107
108There are two options to be used when building an application:
109
1101. Sysbuild
1112. Manual build
112
113.. note::
114
115   User can select the MCUboot bootloader by adding the following line
116   to the board default configuration file.
117
118   .. code:: cfg
119
120      CONFIG_BOOTLOADER_MCUBOOT=y
121
122Sysbuild
123========
124
125The sysbuild makes possible to build and flash all necessary images needed to
126bootstrap the board with the ESP32 SoC.
127
128To build the sample application using sysbuild use the command:
129
130.. zephyr-app-commands::
131   :tool: west
132   :zephyr-app: samples/hello_world
133   :board: odroid_go
134   :goals: build
135   :west-args: --sysbuild
136   :compact:
137
138By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
139images. But it can be configured to create other kind of images.
140
141Build directory structure created by sysbuild is different from traditional
142Zephyr build. Output is structured by the domain subdirectories:
143
144.. code-block::
145
146  build/
147  ├── hello_world
148  │   └── zephyr
149  │       ├── zephyr.elf
150  │       └── zephyr.bin
151  ├── mcuboot
152  │    └── zephyr
153  │       ├── zephyr.elf
154  │       └── zephyr.bin
155  └── domains.yaml
156
157.. note::
158
159   With ``--sysbuild`` option the bootloader will be re-build and re-flash
160   every time the pristine build is used.
161
162For more information about the system build please read the :ref:`sysbuild` documentation.
163
164Manual build
165============
166
167During the development cycle, it is intended to build & flash as quickly possible.
168For that reason, images can be built one at a time using traditional build.
169
170The instructions following are relevant for both manual build and sysbuild.
171The only difference is the structure of the build directory.
172
173.. note::
174
175   Remember that bootloader (MCUboot) needs to be flash at least once.
176
177Build and flash applications as usual (see :ref:`build_an_application` and
178:ref:`application_run` for more details).
179
180.. zephyr-app-commands::
181   :zephyr-app: samples/hello_world
182   :board: odroid_go/esp32/procpu
183   :goals: build
184
185The usual ``flash`` target will work with the ``odroid_go`` board
186configuration. Here is an example for the :zephyr:code-sample:`hello_world`
187application.
188
189.. zephyr-app-commands::
190   :zephyr-app: samples/hello_world
191   :board: odroid_go/esp32/procpu
192   :goals: flash
193
194Open the serial monitor using the following command:
195
196.. code-block:: shell
197
198   west espressif monitor
199
200After the board has automatically reset and booted, you should see the following
201message in the monitor:
202
203.. code-block:: console
204
205   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
206   Hello World! odroid_go
207
208Debugging
209*********
210
211As with much custom hardware, the ESP32 modules require patches to
212OpenOCD that are not upstreamed yet. Espressif maintains their own fork of
213the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_.
214
215The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
216``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
217parameter when building.
218
219Here is an example for building the :zephyr:code-sample:`hello_world` application.
220
221.. zephyr-app-commands::
222   :zephyr-app: samples/hello_world
223   :board: odroid_go/esp32/procpu
224   :goals: build flash
225   :gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
226
227You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application.
228
229.. zephyr-app-commands::
230   :zephyr-app: samples/hello_world
231   :board: odroid_go/esp32/procpu
232   :goals: debug
233
234References
235**********
236
237.. target-notes::
238
239.. [1] https://wiki.odroid.com/odroid_go/odroid_go
240.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
241