docs(esp32h21): Add documentation for ESP32-H21

This commit is contained in:
Jaroslav Safka
2025-09-01 08:56:06 +02:00
parent a1ca6c9c4a
commit cacc180f9e
9 changed files with 190 additions and 29 deletions

View File

@@ -10,7 +10,7 @@ This document provides essential information for coding agents working on the es
- `espsecure.py` - Security-related operations (signing, encryption)
- `esp_rfc2217_server.py` - RFC2217 serial-over-TCP server
**Project type:** Python 3.10+ package with console entry points, using setuptools build system and Click/rich_click for CLI interfaces. Supports ESP32, ESP32-S2, ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-H2, ESP32-P4, ESP8266, and other Espressif chips.
**Project type:** Python 3.10+ package with console entry points, using setuptools build system and Click/rich_click for CLI interfaces. Supports ESP32, ESP32-S2, ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-H2, ESP32-H21, ESP32-P4, ESP8266, and other Espressif chips.
**Repository size:** ~200 files, primarily Python code with some binary stub flasher files and YAML configuration files.

View File

@@ -545,7 +545,7 @@ build_docs:
script:
- pip install ".[docs]" --prefer-binary # esptool is needed for the automatic API documentation generation
- cd docs
- build-docs -l en -t {esp8266,esp32,esp32s2,esp32c3,esp32s3,esp32c2,esp32c6,esp32h2,esp32p4,esp32c5,esp32c61}
- build-docs -l en -t {esp8266,esp32,esp32s2,esp32c3,esp32s3,esp32c2,esp32c6,esp32h2,esp32p4,esp32c5,esp32c61,esp32h21}
.deploy_docs_template:
stage: deploy_docs

View File

@@ -3,20 +3,21 @@ var DOCUMENTATION_VERSIONS = {
supported_targets: [ "esp32" ]
},
VERSIONS: [
{ name: "latest", old: false, pre_release: false, supported_targets: [ "esp8266", "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32c2", "esp32c6", "esp32p4", "esp32h2", "esp32c5", "esp32c61" ] },
{ name: "release-v4", old: false, pre_release: false, supported_targets: [ "esp8266", "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32c2", "esp32c6", "esp32p4", "esp32h2", "esp32c5", "esp32c61" ] },
{ name: "latest", old: false, pre_release: false, supported_targets: [ "esp8266", "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32c2", "esp32c6", "esp32p4", "esp32h2", "esp32c5", "esp32c61", "esp32h21" ] },
{ name: "release-v4", old: false, pre_release: false, supported_targets: [ "esp8266", "esp32", "esp32s2", "esp32s3", "esp32c3", "esp32c2", "esp32c6", "esp32p4", "esp32h2", "esp32c5", "esp32c61", "esp32h21" ] },
],
IDF_TARGETS: [
{ text: "ESP8266", value: "esp8266" },
{ text: "ESP32", value: "esp32" },
{ text: "ESP32-C2", value: "esp32c2" },
{ text: "ESP32-C3", value: "esp32c3" },
{ text: "ESP32-C5", value: "esp32c5" },
{ text: "ESP32-C6", value: "esp32c6" },
{ text: "ESP32-C61", value: "esp32c61" },
{ text: "ESP32-H2", value: "esp32h2" },
{ text: "ESP32-H21", value: "esp32h21" },
{ text: "ESP32-P4", value: "esp32p4" },
{ text: "ESP32-S2", value: "esp32s2" },
{ text: "ESP32-S3", value: "esp32s3" },
{ text: "ESP32-C3", value: "esp32c3" },
{ text: "ESP32-C2", value: "esp32c2" },
{ text: "ESP32-C6", value: "esp32c6" },
{ text: "ESP32-H2", value: "esp32h2" },
{ text: "ESP32-P4", value: "esp32p4" },
{ text: "ESP32-C5", value: "esp32c5" },
{ text: "ESP32-C61", value: "esp32c61" },
{ text: "ESP8266", value: "esp8266" },
]
};

View File

@@ -13,6 +13,7 @@ idf_targets = [
"esp32p4",
"esp32c5",
"esp32c61",
"esp32h21",
]
# link roles config
@@ -53,6 +54,7 @@ conditional_include_dict = {
"esp32p4": ESP32_DOCS,
"esp32c5": ESP32_DOCS,
"esp32c61": ESP32_DOCS,
"esp32h21": ESP32_DOCS,
}
# Extra options required by sphinx_idf_theme

View File

@@ -1,6 +1,6 @@
{IDF_TARGET_STRAP_BOOT_GPIO:default="GPIO9", esp8266="GPIO0", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32p4="GPIO35", esp32c5="GPIO28"}
{IDF_TARGET_STRAP_BOOT_GPIO:default="GPIO9", esp8266="GPIO0", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32p4="GPIO35", esp32c5="GPIO28", esp32h21="GPIO14"}
{IDF_TARGET_STRAP_BOOT_2_GPIO:default="GPIO8", esp32="GPIO2", esp32s2="GPIO46", esp32s3="GPIO46", esp32p4="GPIO36", esp32c5="GPIO27"}
{IDF_TARGET_STRAP_BOOT_2_GPIO:default="GPIO8", esp32="GPIO2", esp32s2="GPIO46", esp32s3="GPIO46", esp32p4="GPIO36", esp32c5="GPIO27", esp32h21="GPIO13"}
{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000", esp32p4="0x2000", esp32c5="0x2000"}
@@ -87,7 +87,7 @@ This guide explains how to select the boot mode correctly and describes the boot
{IDF_TARGET_STRAP_BOOT_2_GPIO} must also be either left unconnected/floating, or driven Low, in order to enter the serial bootloader.
.. only:: esp32c3 or esp32c2 or esp32h2 or esp32c6 or esp32p4 or esp32c5 or esp32c61
.. only:: esp32c3 or esp32c2 or esp32h2 or esp32c6 or esp32p4 or esp32c5 or esp32c61 or esp32h21
{IDF_TARGET_STRAP_BOOT_2_GPIO} must also be driven High, in order to enter the serial bootloader reliably. The strapping combination of {IDF_TARGET_STRAP_BOOT_2_GPIO} = 0 and {IDF_TARGET_STRAP_BOOT_GPIO} = 0 is invalid and will trigger unexpected behavior.

View File

@@ -1,10 +1,10 @@
{IDF_TARGET_FLASH_FREQ_F:default="80", esp32c2="60", esp32h2="48"}
{IDF_TARGET_FLASH_FREQ_F:default="80", esp32c2="60", esp32h2="48", esp32h21="48"}
{IDF_TARGET_FLASH_FREQ_0:default="40", esp32c2="30", esp32h2="24"}
{IDF_TARGET_FLASH_FREQ_0:default="40", esp32c2="30", esp32h2="24", esp32h21="24"}
{IDF_TARGET_FLASH_FREQ_1:default="26", esp32c2="20", esp32h2="16"}
{IDF_TARGET_FLASH_FREQ_1:default="26", esp32c2="20", esp32h2="16", esp32h21="16"}
{IDF_TARGET_FLASH_FREQ_2:default="20", esp32c2="15", esp32h2="12"}
{IDF_TARGET_FLASH_FREQ_2:default="20", esp32c2="15", esp32h2="12", esp32h21="12"}
{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000", esp32p4="0x2000", esp32c5="0x2000"}
@@ -103,7 +103,7 @@ The image header is 8 bytes long:
Flash frequency with value ``0`` can mean either 80MHz or 40MHz based on MSPI clock source mode.
.. only:: esp32c5 or esp32c61
.. only:: esp32c5 or esp32c61 or esp32h21
+--------+------------------------------------------------------------------------------------------------+
| Byte | Description |
@@ -121,7 +121,7 @@ The image header is 8 bytes long:
| 4-7 | Entry point address |
+--------+------------------------------------------------------------------------------------------------+
.. only:: not (esp8266 or esp32c6 or esp32s3 or esp32s2 or esp32p4 or esp32c5 or esp32c61)
.. only:: not (esp8266 or esp32c6 or esp32s3 or esp32s2 or esp32p4 or esp32c5 or esp32c61 or esp32h21)
+--------+------------------------------------------------------------------------------------------------+
| Byte | Description |

View File

@@ -0,0 +1,158 @@
.. code-block:: none
> espefuse -p PORT summary
Connecting....
Detecting chip type... ESP32-H21
=== Run "summary" command ===
EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value)
----------------------------------------------------------------------------------------
Config fuses:
WR_DIS (BLOCK0) Disable programming of individual eFuses = 0 R/W (0x00000000)
RD_DIS (BLOCK0) Disable reading from BlOCK4-10 = 0 R/W (0b0000000)
DIS_ICACHE (BLOCK0) Represents whether icache is disabled or enabled.\ = False R/W (0b0)
\ 1: disabled\\ 0: enabled\\
DIS_DIRECT_BOOT (BLOCK0) Represents whether direct boot mode is disabled or = False R/W (0b0)
enabled.\\ 1: disabled\\ 0: enabled\\
UART_PRINT_CONTROL (BLOCK0) Set the default UARTboot message output mode = Enable R/W (0b00)
HYS_EN_PAD (BLOCK0) Represents whether the hysteresis function of corr = False R/W (0b0)
esponding PAD is enabled.\\ 1: enabled\\ 0:disable
d\\
ECC_FORCE_CONST_TIME (BLOCK0) Represents whether to force ecc to use const-time = False R/W (0b0)
calculation mode. \\ 1: Enable. \\ 0: Disable
PSRAM_CAP (BLOCK1) PSRAM capacity = 0 R/W (0b000)
PSRAM_VENDOR (BLOCK1) PSRAM vendor = 0 R/W (0b00)
TEMP (BLOCK1) Temperature = 0 R/W (0b00)
BLOCK_USR_DATA (BLOCK3) User data
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W
BLOCK_SYS_DATA2 (BLOCK10) System data part 2 (reserved)
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W
Flash fuses:
FLASH_TPUW (BLOCK0) Represents the flash waiting time after power-up; = 0 R/W (0x0)
in unit of ms. When the value less than 15; the wa
iting time is the programmed value. Otherwise; the wai
ting time is 2 times the programmed value
FORCE_SEND_RESUME (BLOCK0) Represents whether ROM code is forced to send a re = False R/W (0b0)
sume command during SPI boot
FLASH_CAP (BLOCK1) Flash capacity = 0 R/W (0b000)
FLASH_VENDOR (BLOCK1) Flash vendor = 0 R/W (0b000)
Identity fuses:
WAFER_VERSION_MINOR (BLOCK1) Minor chip version = 0 R/W (0x0)
WAFER_VERSION_MAJOR (BLOCK1) Major chip version = 0 R/W (0b00)
DISABLE_WAFER_VERSION_MAJOR (BLOCK1) Disables check of wafer version major = False R/W (0b0)
DISABLE_BLK_VERSION_MAJOR (BLOCK1) Disables check of blk version major = False R/W (0b0)
BLK_VERSION_MINOR (BLOCK1) BLK_VERSION_MINOR of BLOCK2 = 0 R/W (0b000)
BLK_VERSION_MAJOR (BLOCK1) BLK_VERSION_MAJOR of BLOCK2 = 0 R/W (0b00)
PKG_VERSION (BLOCK1) Package version = 0 R/W (0b000)
OPTIONAL_UNIQUE_ID (BLOCK2) Optional unique 128-bit ID
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W
Jtag fuses:
JTAG_SEL_ENABLE (BLOCK0) Represents whether the selection between usb_to_jt = False R/W (0b0)
ag and pad_to_jtag through strapping gpio15 when b
oth EFUSE_DIS_PAD_JTAG and EFUSE_DIS_USB_JTAG are
equal to 0 is enabled or disabled.\\ 1: enabled\\
0: disabled\\
DIS_PAD_JTAG (BLOCK0) Represents whether JTAG is disabled in the hard wa = False R/W (0b0)
y(permanently).\\ 1: disabled\\ 0: enabled\\
Mac fuses:
MAC (BLOCK1) MAC address
= 60:55:f9:f9:54:1c (OK) R/W
MAC_EXT (BLOCK1) Represents the extended bits of MAC address = ff:fe (OK) R/W
CUSTOM_MAC (BLOCK3) Custom MAC
= 00:00:00:00:00:00 (OK) R/W
MAC_EUI64 (BLOCK1) calc MAC_EUI64 = MAC[0]:MAC[1]:MAC[2]:MAC_EXT[0]:M
= 60:55:f9:ff:fe:f9:54:1c (OK) R/W
AC_EXT[1]:MAC[3]:MAC[4]:MAC[5]
Security fuses:
DIS_FORCE_DOWNLOAD (BLOCK0) Represents whether the function that forces chip i = False R/W (0b0)
nto download mode is disabled or enabled.\\ 1: dis
abled\\ 0: enabled\\
SPI_DOWNLOAD_MSPI_DIS (BLOCK0) Represents whether SPI0 controller during boot_mod = False R/W (0b0)
e_download is disabled or enabled.\\ 1: disabled\\
0: enabled\\
DIS_DOWNLOAD_MANUAL_ENCRYPT (BLOCK0) Represents whether flash encrypt function is disab = False R/W (0b0)
led or enabled(except in SPI boot mode).\\ 1: disa
bled\\ 0: enabled\\
SPI_BOOT_CRYPT_CNT (BLOCK0) Enables flash encryption when 1 or 3 bits are set = Disable R/W (0b000)
and disables otherwise
SECURE_BOOT_KEY_REVOKE0 (BLOCK0) Revoke 1st secure boot key = False R/W (0b0)
SECURE_BOOT_KEY_REVOKE1 (BLOCK0) Revoke 2nd secure boot key = False R/W (0b0)
SECURE_BOOT_KEY_REVOKE2 (BLOCK0) Revoke 3rd secure boot key = False R/W (0b0)
KEY_PURPOSE_0 (BLOCK0) Represents the purpose of Key0 = USER R/W (0x0)
KEY_PURPOSE_1 (BLOCK0) Represents the purpose of Key1 = USER R/W (0x0)
KEY_PURPOSE_2 (BLOCK0) Represents the purpose of Key2 = USER R/W (0x0)
KEY_PURPOSE_3 (BLOCK0) Represents the purpose of Key3 = USER R/W (0x0)
KEY_PURPOSE_4 (BLOCK0) Represents the purpose of Key4 = USER R/W (0x0)
KEY_PURPOSE_5 (BLOCK0) Represents the purpose of Key5 = USER R/W (0x0)
SEC_DPA_LEVEL (BLOCK0) Represents the spa secure level by configuring the = 0 R/W (0b00)
clock random divide mode
SECURE_BOOT_EN (BLOCK0) Represents whether secure boot is enabled or disab = False R/W (0b0)
led.\\ 1: enabled\\ 0: disabled\\
SECURE_BOOT_AGGRESSIVE_REVOKE (BLOCK0) Represents whether revoking aggressive secure boot = False R/W (0b0)
is enabled or disabled.\\ 1: enabled.\\ 0: disabl
ed\\
DIS_DOWNLOAD_MODE (BLOCK0) Represents whether Download mode is disabled or en = False R/W (0b0)
abled.\\ 1: disabled\\ 0: enabled\\
ENABLE_SECURITY_DOWNLOAD (BLOCK0) Represents whether security download is enabled or = False R/W (0b0)
disabled.\\ 1: enabled\\ 0: disabled\\
SECURE_VERSION (BLOCK0) Represents the version used by ESP-IDF anti-rollba = 0 R/W (0x0000)
ck feature
SECURE_BOOT_DISABLE_FAST_WAKE (BLOCK0) Represents whether FAST_VERIFY_ON_WAKE is disable = False R/W (0b0)
or enable when Secure Boot is enable
XTS_DPA_PSEUDO_LEVEL (BLOCK0) Represents the anti-dpa attack pseudo function lev = 0 R/W (0b00)
el.\\ 3:High\\ 2: Moderate\\ 1: Low\\ 0: Decided b
y register configuration\\
BLOCK_KEY0 (BLOCK4)
Purpose: USER
Key0 or user data
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W
BLOCK_KEY1 (BLOCK5)
Purpose: USER
Key1 or user data
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W
BLOCK_KEY2 (BLOCK6)
Purpose: USER
Key2 or user data
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W
BLOCK_KEY3 (BLOCK7)
Purpose: USER
Key3 or user data
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W
BLOCK_KEY4 (BLOCK8)
Purpose: USER
Key4 or user data
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W
BLOCK_KEY5 (BLOCK9)
Purpose: USER
Key5 or user data
= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W
Usb fuses:
DIS_USB_JTAG (BLOCK0) Represents whether the function of usb switch to j = False R/W (0b0)
tag is disabled or enabled.\\ 1: disabled\\ 0: ena
bled\\
USB_EXCHG_PINS (BLOCK0) Represents whether the D+ and D- pins is exchanged = False R/W (0b0)
.\\ 1: exchanged\\ 0: not exchanged\\
DIS_USB_SERIAL_JTAG_ROM_PRINT (BLOCK0) Represents whether print from USB-Serial-JTAG is d = False R/W (0b0)
isabled or enabled.\\ 1. Disable\\ 0: Enable\\
DIS_USB_SERIAL_JTAG_DOWNLOAD_MODE (BLOCK0) Represents whether the USB-Serial-JTAG download fu = False R/W (0b0)
nction is disabled or enabled.\\ 1: Disable\\ 0: E
nable\\
Vdd fuses:
VDD_SPI_AS_GPIO (BLOCK0) Represents whether vdd spi pin is functioned as gp = False R/W (0b0)
io.\\ 1: functioned\\ 0: not functioned\\
Wdt fuses:
WDT_DELAY_SEL (BLOCK0) Represents the threshold level of the RTC watchdog = 0 R/W (0b00)
STG0 timeout.\\ 0: Original threshold configurati
on value of STG0 *2 \\1: Original threshold config
uration value of STG0 *4 \\2: Original threshold c
onfiguration value of STG0 *8 \\3: Original thresh
old configuration value of STG0 *16 \\

View File

@@ -22,7 +22,7 @@ The ``--before`` argument allows you to specify whether the chip needs resetting
* ``--before default-reset`` is the default, which uses DTR & RTS serial control lines (see :ref:`entering-the-bootloader`) to try to reset the chip into bootloader mode.
* ``--before no-reset`` will skip DTR/RTS control signal assignments and just start sending a serial synchronisation command to the chip. This is useful if your chip doesn't have DTR/RTS, or for some serial interfaces (like Arduino board onboard serial) which behave differently when DTR/RTS are toggled.
* ``--before no-reset-no-sync`` will skip DTR/RTS control signal assignments and skip also the serial synchronization command. This is useful if your chip is already running the :ref:`stub bootloader <stub>` and you want to avoid resetting the chip and uploading the stub again.
:esp32c3 or esp32s3 or esp32c6 or esp32h2 or esp32p4 or esp32c5 or esp32c61: * ``--before usb-reset`` will use custom reset sequence for USB-JTAG-Serial (used for example for ESP chips connected through the USB-JTAG-Serial peripheral). Usually, this option doesn't have to be used directly. Esptool should be able to detect connection through USB-JTAG-Serial.
:esp32c3 or esp32s3 or esp32c6 or esp32h2 or esp32p4 or esp32c5 or esp32c61 or esp32h21: * ``--before usb-reset`` will use custom reset sequence for USB-JTAG-Serial (used for example for ESP chips connected through the USB-JTAG-Serial peripheral). Usually, this option doesn't have to be used directly. Esptool should be able to detect connection through USB-JTAG-Serial.
Reset After Operation: ``--after``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

View File

@@ -1,10 +1,10 @@
{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000", esp32p4="0x2000", esp32c5="0x2000"}
{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000", esp32p4="0x2000", esp32c5="0x2000", esp32h2="0x0", esp32h21="0x0"}
{IDF_TARGET_FLASH_FREQ_F:default="80", esp32c2="60", esp32h2="48"}
{IDF_TARGET_FLASH_FREQ_F:default="80", esp32c2="60", esp32h2="48", esp32h21="48"}
{IDF_TARGET_FLASH_FREQ_0:default="40", esp32c2="30", esp32h2="24"}
{IDF_TARGET_FLASH_FREQ_0:default="40", esp32c2="30", esp32h2="24", esp32h21="24"}
{IDF_TARGET_FLASH_FREQ:default="``40m``, ``26m``, ``20m``, ``80m``", esp32c2="``30m``, ``20m``, ``15m``, ``60m``", esp32h2="``24m``, ``16m``, ``12m``, ``48m``", esp32c6="``40m``, ``20m``, ``80m``, esp32c5="``40m``, ``20m``, ``80m``, esp32c61="``40m``, ``20m``, ``80m``"}
{IDF_TARGET_FLASH_FREQ:default="``40m``, ``26m``, ``20m``, ``80m``", esp32c2="``30m``, ``20m``, ``15m``, ``60m``", esp32h2="``24m``, ``16m``, ``12m``, ``48m``", esp32c6="``40m``, ``20m``, ``80m``, esp32c5="``40m``, ``20m``, ``80m``, esp32c61="``40m``, ``20m``, ``80m``", esp32h21="``24m``, ``16m``, ``12m``, ``48m``"}
.. _flash-modes:
@@ -56,7 +56,7 @@ Size of the SPI flash, given in megabytes.
Valid values are: ``keep``, ``detect``, ``256KB``, ``512KB``, ``1MB``, ``2MB``, ``4MB``, ``2MB-c1``, ``4MB-c1``, ``8MB``, ``16MB``
.. only:: esp32 or esp32c3 or esp32c6 or esp32c2 or esp32h2 or esp32c5 or esp32c61
.. only:: esp32 or esp32c3 or esp32c6 or esp32c2 or esp32h2 or esp32c5 or esp32c61 or esp32h21
Valid values are: ``keep``, ``detect``, ``1MB``, ``2MB``, ``4MB``, ``8MB``, ``16MB``