1.. zephyr:board:: esp32c3_042_oled
2
3Overview
4********
5
6ESP32C3 0.42 OLED is a mini development board based on the `Espressif ESP32-C3`_
7RISC-V WiFi/Bluetooth dual-mode chip.
8
9For more details see the `01space ESP32C3 0.42 OLED`_ Github repo.
10
11Hardware
12********
13
14This board is based on the ESP32-C3-FH4 with WiFi and BLE support.
15It features:
16
17* RISC-V SoC @ 160MHz with 4MB flash and 400kB RAM
18* WS2812B RGB serial LED
19* 0.42-inch OLED over I2C
20* Qwiic I2C connector
21* One pushbutton
22* Onboard ceramic chip antenna
23* On-chip USB-UART converter
24
25.. note::
26
27   The RGB led is not supported on this Zephyr board yet.
28
29.. note::
30
31   The ESP32-C3 does not have native USB, it has an on-chip USB-serial converter
32   instead.
33
34Supported Features
35==================
36
37The 01space ESP32C3 0.42 OLED board configuration supports the following hardware features:
38
39+-----------+------------+------------------+
40| Interface | Controller | Driver/Component |
41+===========+============+==================+
42| PMP       | on-chip    | arch/riscv       |
43+-----------+------------+------------------+
44| INTMTRX   | on-chip    | intc_esp32c3     |
45+-----------+------------+------------------+
46| PINMUX    | on-chip    | pinctrl_esp32    |
47+-----------+------------+------------------+
48| USB UART  | on-chip    | serial_esp32_usb |
49+-----------+------------+------------------+
50| GPIO      | on-chip    | gpio_esp32       |
51+-----------+------------+------------------+
52| UART      | on-chip    | uart_esp32       |
53+-----------+------------+------------------+
54| I2C       | on-chip    | i2c_esp32        |
55+-----------+------------+------------------+
56| SPI       | on-chip    | spi_esp32_spim   |
57+-----------+------------+------------------+
58| RADIO     | on-chip    | Bluetooth        |
59+-----------+------------+------------------+
60| DISPLAY   | off-chip   | display          |
61+-----------+------------+------------------+
62
63Connections and IOs
64===================
65
66See the following image:
67
68.. figure:: img/esp32c3_042_oled_pinout.webp
69   :align: center
70   :alt: 01space ESP32C3 0.42 OLED Pinout
71
72   01space ESP32C3 0.42 OLED Pinout
73
74It also features a 0.42 inch OLED display, driven by a SSD1306-compatible chip.
75It is connected over I2C: SDA on GPIO5, SCL on GPIO6.
76
77Prerequisites
78=============
79
80Espressif HAL requires WiFi and Bluetooth binary blobs. Run the command below to
81retrieve those files.
82
83.. code-block:: console
84
85   west blobs fetch hal_espressif
86
87.. note::
88
89   It is recommended running the command above after :file:`west update`.
90
91Programming and Debugging
92*************************
93
94Standalone application
95======================
96
97The board can be loaded using a single binary image, without 2nd stage bootloader.
98It is the default option when building the application without additional configuration.
99
100.. note::
101
102   This mode does not provide any security features nor OTA updates.
103
104Use the following command to build a sample hello_world application:
105
106.. zephyr-app-commands::
107   :zephyr-app: samples/hello_world
108   :board: esp32c3_042_oled
109   :goals: build
110
111Sysbuild
112========
113
114:ref:`sysbuild` makes it possible to build and flash all necessary images needed to
115bootstrap the board.
116
117By default, the ESP32 sysbuild configuration creates bootloader (MCUboot) and
118application images.
119
120To build the sample application using sysbuild, use this command:
121
122.. zephyr-app-commands::
123   :tool: west
124   :zephyr-app: samples/hello_world
125   :board: esp32c3_042_oled
126   :goals: build
127   :west-args: --sysbuild
128   :compact:
129
130Flashing
131========
132
133For the :code:`Hello, world!` application, follow the instructions below.
134Assuming the board is connected to ``/dev/ttyACM0`` on Linux.
135
136.. zephyr-app-commands::
137   :zephyr-app: samples/hello_world
138   :board: esp32c3_042_oled
139   :goals: flash
140   :flash-args: --esp-device /dev/ttyACM0
141
142Since the Zephyr console is by default on the ``usb_serial`` device, we use
143the espressif monitor utility to connect to the console.
144
145.. code-block:: console
146
147   $ west espressif monitor -p /dev/ttyACM0
148
149After the board has automatically reset and booted, you should see the following
150message in the monitor:
151
152.. code-block:: console
153
154   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
155   Hello World! esp32c3_042_oled
156
157References
158**********
159
160.. target-notes::
161
162.. _`Espressif ESP32-C3`: https://www.espressif.com/en/products/socs/esp32-c3
163.. _`01space ESP32C3 0.42 OLED`: https://github.com/01Space/ESP32-C3-0.42LCD
164