cpu/esp32: add ESP32-H2 support #21522

gschorcht · 2025-06-02T16:00:47Z

Contribution description

This PR adds the support for the ESP32-H2 variant, a RISC-V based ESP32x SoC with IEEE802.15.4 and Bluetooth 5 (LE). It includes a board definition for the Espressif development board ESP32-H2-DevKitM-1.

Testing procedure

Basic tests for peripherals and ESP-specific modules have to work. Following peripherals and modules have been tested successfully:

Module	esp32h2
shell	OK
periph/adc	OK
periph/can	OK
periph/cpuid	OK
periph/dac	-
periph/flash	OK
periph/flashpage	OK
periph/gpio	OK
periph/gpio_ll	OK
periph/gpio_ll_irq	OK
periph/hwrng	OK
periph/i2c_sw	OK
periph/i2c_hw	OK
periph/pm	OK
periph/pwm	OK
periph/rtt_sys	OK
periph/rtt_hw	OK
periph/sdmmc	-
periph/spi	OK
periph/timer	OK
esp_hw_counter	-
esp_ble_nimble	follow-up PR
esp_ble_nimble + esp_wifi	-
esp_eth	-
esp_idf_gpio_hal	OK
esp_idf_usb	-
esp_idf_heap	OK
esp_ieee802154	follow-up PR
esp_now	-
esp_spi_ram	-
esp_wifi	-
esp_wifi_ap	-
esp_wifi_enterprise	-

[-] not supported by ESP32-H2

Issues/PRs references

riot-ci · 2025-06-02T16:03:47Z

Murdock results

✔️ PASSED

986cda8 examples/gnrc/mqtt/paho-mqtt: disable WiFi for ESP32-H2

Success	Failures	Total	Runtime
10504	0	10504	23m:04s

Artifacts

Documentation preview

tests/net/ieee802154_submac/main.c

benpicco

terrific news!

Just quickly skimmed the PR:

benpicco · 2025-06-02T16:27:14Z

cpu/esp32/esp-ieee802154/esp_ieee802154_hal.c

+    unsigned len = 0;
+    for (; psdu; psdu = psdu->iol_next) {
+        if (psdu->iol_len) {
+            memcpy(&_tx_frame[len + 1], psdu->iol_base, psdu->iol_len);


Why len + 1?

Because the IEEE802.15.4 driver of the ESP-IDF expects that byte 0 in the TX frame array is the length of the frame to be sent.

benpicco · 2025-06-02T16:30:41Z

cpu/esp32/esp-ieee802154/esp_ieee802154_hal.c

+    esp_ieee802154_set_rx_when_idle(true);
+    esp_ieee802154_receive();
+    esp_ieee802154_set_cca_mode(ESP_IEEE802154_CCA_MODE_ED);
+    esp_ieee802154_set_ack_timeout(3456);    /* should be a multiple of 16 */


Not IEEE802154_ACK_TIMEOUT_SYMS * IEEE802154_SYMBOL_TIME_US (864 µs)?

I am not familiar enough with IEEE 802.15.4 to know what the correct timeout value is. In ESP-IDF, esp_ieee802154_set_ack_timeout is documented as follows:

* @param[in] timeout The time to wait for the ack frame, in us. * It Should be a multiple of 16. The default value is 1728 us (108 * 16).

If I remember correctly, it didn't work with this default value, so I just tried it with the double which works.

benpicco · 2025-06-02T16:32:39Z

cpu/esp32/include/periph_cpu.h

+#if defined(CPU_FAM_ESP32H2) && defined(CONFIG_IEEE802154_ENABLED)
+/* ESP32H2 has IEEE802.15.4 radio which has an EUI64 address. Function
+ * esp_efuse_mac_get_default will return this 8 byte address if
+ * CONFIG_IEEE802154_ENABLED */


Does it still have a separate CPU ID though?

ESPs don't have a CPU ID. Therefore, the MAC address burned in eFuse is usually used as CPU ID. For ESP32-H2, the function used to get the MAC address returns the 8 byte EUI64.

benpicco · 2025-06-02T16:37:24Z

cpu/esp_common/Makefile.features

+
+ifneq (esp32h2,$(CPU_FAM))
+  # All ESP* MCUs have a peripheral network interface
+  FEATURES_PROVIDED += netif


What about the 802.15.4 radio?

It comes now as follow-up PR 😉

crasbe

I don't have the hardware (yet) to test it, but so far these are mostly styling related comments.

However in general I think it would've been good if this PR had been three PRs. One for the board, one for NimBLE and one for the 802.15.4 changes. This is quite a hefty chunk 😅

boards/common/esp32h2/doc.md

boards/esp32h2-devkit/doc.md

boards/esp32h2-devkit/include/arduino_iomap.h

cpu/esp32/syscalls.c

crasbe · 2025-06-12T13:21:21Z

pkg/nimble/contrib/include/nimble_riot.h

+/**
+ * @brief   Indicates whether Setup NimBLE's controller has been initialized
+ *
+ * nimble_port_initialized` is false by default and is set to true as soon as


Suggested change

* nimble_port_initialized` is false by default and is set to true as soon as

* `nimble_port_initialized` is false by default and is set to true as soon as

Not part of the PR any longer.

crasbe · 2025-06-12T13:21:35Z

pkg/nimble/contrib/include/nimble_riot.h

+ * @brief   Indicates whether Setup NimBLE's controller has been initialized
+ *
+ * nimble_port_initialized` is false by default and is set to true as soon as
+ * `nimble_port_init` has been called by nimble_riot_init, i.e. that the NimBLE


Suggested change

* `nimble_port_init` has been called by nimble_riot_init, i.e. that the NimBLE

* `nimble_port_init` has been called by nimble_riot_init(), i.e. that the NimBLE

crasbe · 2025-06-12T13:22:45Z

pkg/nimble/contrib/include/nimble_riot.h

+ * of the low-level BLE controller driver starts sending events to the host
+ * before the NimBLE stack has been initialized by the lower-prioritized
+ * host thread. */
+extern bool nimble_port_initialized;


This change might fix the crashes I saw in #21206.

crasbe · 2025-06-12T13:23:31Z

sys/net/gnrc/netif/init_devs/auto_init_esp_ieee802154.c

+#ifndef ESP_IEEE802154_MAC_STACKSIZE
+#define ESP_IEEE802154_MAC_STACKSIZE       (IEEE802154_STACKSIZE_DEFAULT)
+#endif
+
+#ifndef ESP_IEEE802154_MAC_PRIO
+#define ESP_IEEE802154_MAC_PRIO            (GNRC_NETIF_PRIO)
+#endif


Suggested change

#ifndef ESP_IEEE802154_MAC_STACKSIZE

#define ESP_IEEE802154_MAC_STACKSIZE (IEEE802154_STACKSIZE_DEFAULT)

#endif

#ifndef ESP_IEEE802154_MAC_PRIO

#define ESP_IEEE802154_MAC_PRIO (GNRC_NETIF_PRIO)

#endif

#ifndef ESP_IEEE802154_MAC_STACKSIZE

# define ESP_IEEE802154_MAC_STACKSIZE (IEEE802154_STACKSIZE_DEFAULT)

#endif

#ifndef ESP_IEEE802154_MAC_PRIO

# define ESP_IEEE802154_MAC_PRIO (GNRC_NETIF_PRIO)

#endif

gschorcht · 2025-06-12T14:23:06Z

@benpicco @crasbe Many thanks for your first look to this PR. I will take fix it next days.

Yes, the PR is pretty big 😎 But do you really think it makes sense to split it into three PRs. Without having IEEE802.15.4 radio or BLE, the ESP32-H2 has no network interface. Unlike the other ESP32x variants, the ESP32-H2 has no WiFi interface.

For me it would not be a problem to split it as you suggested, as I have sorted the commits exactly in the order you suggested anyway, because I implemented them in that order.

crasbe · 2025-06-12T14:39:15Z

Not sure if it makes sense to split it now, but it would've been better if it had been split to begin with.

There are already many things to test without network interfaces on a new board and with the other two changes, the PR should be tested with other hardware too (not that I would have the required hardware though...).

gschorcht · 2025-06-24T07:36:12Z

After removing the esp_wifi module as netdev_default for ESP32-H2, the compilation in CI for ESP32-H2 works also without having any network interface.

gschorcht · 2025-07-03T14:17:01Z

@crasbe @benpicco Do you see a real chance to get the PR merged before release 2025-07? I'm not sure whether the soft freeze or the hard freeze would be the deadline for this PR because I'm not sure whether its impact is high enough for the soft freeze.

The Zephyr project already supports the EPS32-C6, but not the ESP32-H2. Both are the first ESP32 SoCs to support IEEE 802.15.4. I have RIOT-OS already working ESP32-C6 but it is implemented on top of this PR.

crasbe

IMO this is good for merging. I wanted to get an H2 board for testing it myself, but so far I haven't issued the Reichelt order yet :/
However I do trust your testing, so this should not postpone this.

gschorcht · 2025-07-04T08:39:13Z

IMO this is good for merging.

@crasbe Thanks for reviewing and approving. So, may I squash?

crasbe · 2025-07-04T09:57:21Z

Yes, please squash. I was waiting if @benpicco has something else to note, but if not, you can hit merge at your own discretion.

gschorcht · 2025-07-10T12:36:21Z

@crasbe @benpicco Many thanks for reviewing and merging.

gschorcht requested review from kaspar030, leandrolanzieri, jia200x, MrKevinWeiss, aabadie, MichelRottleuthner, miri64 and PeterKietzmann as code owners June 2, 2025 16:00

gschorcht added Type: new feature The issue requests / The PR implemements a new feature for RIOT CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR labels Jun 2, 2025

benpicco reviewed Jun 2, 2025

View reviewed changes

tests/net/ieee802154_submac/main.c Outdated Show resolved Hide resolved

benpicco reviewed Jun 2, 2025

View reviewed changes

crasbe reviewed Jun 12, 2025

View reviewed changes

gschorcht removed the CI: full build disable CI build filter label Jun 24, 2025

github-actions bot added Area: CI Area: Continuous Integration of RIOT components Area: examples Area: Example Applications labels Jun 24, 2025

crasbe approved these changes Jul 3, 2025

View reviewed changes

gschorcht added 11 commits July 4, 2025 13:51

boards/common: add common board definitions for ESP32-H2

4326d1b

boards: add ESP32-H2-DekitM-1 board definition

90b863c

cpu/esp32/bootloader: add ESP32-H2 support

686d234

pkg/esp32_sdk: add patches for ESP32-H2 support

aa45bfc

cpu/esp_common: changes for ESP32-H2 support

31bc2e2

cpu/esp32/vendor/ld: add linker scripts for ESP32-H2

dc7856f

cpu/esp32/esp-idf: add ESP32-H2 support

8dc879b

cpu/esp32: add ESP32-H2 support

3019928

cpu/esp32/periph: add ESP32-H2 support

06f0c2c

cpu/esp32: add ESP32-H2 doc

dcce366

examples/gnrc/mqtt/paho-mqtt: disable WiFi for ESP32-H2

986cda8

gschorcht force-pushed the cpu/esp32/add_esp32h2 branch 2 times, most recently from 4e9d5c3 to 986cda8 Compare July 4, 2025 12:00

github-actions bot removed the Area: CI Area: Continuous Integration of RIOT components label Jul 4, 2025

benpicco added this pull request to the merge queue Jul 8, 2025

github-merge-queue bot removed this pull request from the merge queue due to no response for status checks Jul 8, 2025

gschorcht added this pull request to the merge queue Jul 8, 2025

Merged via the queue into RIOT-OS:master with commit 02c0f48 Jul 9, 2025
25 checks passed

gschorcht deleted the cpu/esp32/add_esp32h2 branch July 10, 2025 12:36

Teufelchen1 added this to the Release 2025.07 milestone Jul 14, 2025

	* nimble_port_initialized` is false by default and is set to true as soon as
	* `nimble_port_initialized` is false by default and is set to true as soon as

	* `nimble_port_init` has been called by nimble_riot_init, i.e. that the NimBLE
	* `nimble_port_init` has been called by nimble_riot_init(), i.e. that the NimBLE

cpu/esp32: add ESP32-H2 support #21522

cpu/esp32: add ESP32-H2 support #21522

Uh oh!

Conversation

gschorcht commented Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Contribution description

Testing procedure

Issues/PRs references

Uh oh!

riot-ci commented Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Murdock results

Artifacts

Uh oh!

Uh oh!

benpicco left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

crasbe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gschorcht commented Jun 12, 2025

Uh oh!

crasbe commented Jun 12, 2025

Uh oh!

gschorcht commented Jun 24, 2025

Uh oh!

gschorcht commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

crasbe left a comment

Choose a reason for hiding this comment

Uh oh!

gschorcht commented Jul 4, 2025

Uh oh!

crasbe commented Jul 4, 2025

Uh oh!

Uh oh!

Uh oh!

gschorcht commented Jul 10, 2025

Uh oh!

Uh oh!

gschorcht commented Jun 2, 2025 •

edited

Loading

riot-ci commented Jun 2, 2025 •

edited

Loading

gschorcht commented Jul 3, 2025 •

edited

Loading