docs(esp_hw_support): fix IEEE 802.15.4 spelling and EUI-64 byte-range notation

Correct "802.154" to "802.15.4" and change the EUI-64 derivation notation from base_mac[0:3]/base_mac[3:6] to the inclusive base_mac[0:2]/base_mac[3:5] in the esp32h2/esp32h21/esp32h4 Kconfig.mac help text and the EN/zh_CN misc_system_api docs. Co-authored-by: Cursor <cursoragent@cursor.com> (cherry picked from commit 811c64c17c)
2026-09-22 13:01:16 +03:00 · 2026-07-06 20:14:53 +08:00
parent b5cd9ce7fa
commit 7ca1369ffc
5 changed files with 26 additions and 23 deletions
--- a/components/esp_hw_support/port/esp32h2/Kconfig.mac
+++ b/components/esp_hw_support/port/esp32h2/Kconfig.mac
@@ -7,12 +7,13 @@ choice ESP32H2_UNIVERSAL_MAC_ADDRESSES
        single base MAC address.

        ESP32-H2 provides a single universally administered MAC address in eFuse
-        (MAC_FACTORY, 6 bytes) plus the MAC_EXT field used to build the IEEE 802.154
+        (MAC_FACTORY, 6 bytes) plus the MAC_EXT field used to build the IEEE 802.15.4
        EUI-64. Only one universal MAC address is consumed:
-          - IEEE 802.154 EUI-64 is derived from the base MAC and MAC_EXT
-            (base_mac[0:3] || MAC_EXT || base_mac[3:6], MAC_EXT defaults to ff:fe);
-          - Bluetooth reuses the base MAC as-is. The BT offset is not applied because
-            ESP32-H2 has no Wi-Fi, so no second universal MAC slot is required.
+
+        - IEEE 802.15.4 EUI-64 is derived from the base MAC and MAC_EXT
+          (base_mac[0:2] || MAC_EXT || base_mac[3:5], MAC_EXT defaults to ff:fe).
+        - Bluetooth reuses the base MAC as-is. The BT offset is not applied because
+          ESP32-H2 has no Wi-Fi, so no second universal MAC slot is required.

    config ESP32H2_UNIVERSAL_MAC_ADDRESSES_ONE
        bool "One"
--- a/components/esp_hw_support/port/esp32h21/Kconfig.mac
+++ b/components/esp_hw_support/port/esp32h21/Kconfig.mac
@@ -7,12 +7,13 @@ choice ESP32H21_UNIVERSAL_MAC_ADDRESSES
        single base MAC address.

        ESP32-H21 provides a single universally administered MAC address in eFuse
-        (MAC_FACTORY, 6 bytes) plus the MAC_EXT field used to build the IEEE 802.154
+        (MAC_FACTORY, 6 bytes) plus the MAC_EXT field used to build the IEEE 802.15.4
        EUI-64. Only one universal MAC address is consumed:
-          - IEEE 802.154 EUI-64 is derived from the base MAC and MAC_EXT
-            (base_mac[0:3] || MAC_EXT || base_mac[3:6], MAC_EXT defaults to ff:fe);
-          - Bluetooth reuses the base MAC as-is. The BT offset is not applied because
-            ESP32-H21 has no Wi-Fi, so no second universal MAC slot is required.
+
+        - IEEE 802.15.4 EUI-64 is derived from the base MAC and MAC_EXT
+          (base_mac[0:2] || MAC_EXT || base_mac[3:5], MAC_EXT defaults to ff:fe).
+        - Bluetooth reuses the base MAC as-is. The BT offset is not applied because
+          ESP32-H21 has no Wi-Fi, so no second universal MAC slot is required.

    config ESP32H21_UNIVERSAL_MAC_ADDRESSES_ONE
        bool "One"
--- a/components/esp_hw_support/port/esp32h4/Kconfig.mac
+++ b/components/esp_hw_support/port/esp32h4/Kconfig.mac
@@ -7,12 +7,13 @@ choice ESP32H4_UNIVERSAL_MAC_ADDRESSES
        single base MAC address.

        ESP32-H4 provides a single universally administered MAC address in eFuse
-        (MAC_FACTORY, 6 bytes) plus the MAC_EXT field used to build the IEEE 802.154
+        (MAC_FACTORY, 6 bytes) plus the MAC_EXT field used to build the IEEE 802.15.4
        EUI-64. Only one universal MAC address is consumed:
-          - IEEE 802.154 EUI-64 is derived from the base MAC and MAC_EXT
-            (base_mac[0:3] || MAC_EXT || base_mac[3:6], MAC_EXT defaults to ff:fe);
-          - Bluetooth reuses the base MAC as-is. The BT offset is not applied because
-            ESP32-H4 has no Wi-Fi, so no second universal MAC slot is required.
+
+        - IEEE 802.15.4 EUI-64 is derived from the base MAC and MAC_EXT
+          (base_mac[0:2] || MAC_EXT || base_mac[3:5], MAC_EXT defaults to ff:fe).
+        - Bluetooth reuses the base MAC as-is. The BT offset is not applied because
+          ESP32-H4 has no Wi-Fi, so no second universal MAC slot is required.

    config ESP32H4_UNIVERSAL_MAC_ADDRESSES_ONE
        bool "One"
--- a/docs/en/api-reference/system/misc_system_api.rst
+++ b/docs/en/api-reference/system/misc_system_api.rst
@@ -104,7 +104,7 @@ In ESP-IDF, the MAC addresses for the various network interfaces are calculated

    .. note::

-        ESP32-S31 only provides two universally administered MAC addresses in eFuse, so :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` defaults to two. The "Four" option may only be used when a customer-provided custom base MAC range is used (see :ref:`Custom Base MAC <MAC-Address-Allocation>`), where four universally administered MAC addresses are allocated per device. Using "Four" with the default Espressif eFuse base MAC leads to SoftAP and Ethernet consuming global MAC slots (base+1/+3) that are not allocated on this chip and may collide with the Bluetooth MAC.
+        {IDF_TARGET_NAME} only provides two universally administered MAC addresses in eFuse, so :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` defaults to two. The "Four" option may only be used when a customer-provided custom base MAC range is used (see :ref:`Custom Base MAC <MAC-Address-Allocation>`), where four universally administered MAC addresses are allocated per device. Using "Four" with the default Espressif eFuse base MAC leads to SoftAP and Ethernet consuming global MAC slots (base+1/+3) that are not allocated on this chip and may collide with the Bluetooth MAC.

 .. only:: esp32h2 or esp32h21 or esp32h4

@@ -114,14 +114,14 @@ In ESP-IDF, the MAC addresses for the various network interfaces are calculated

        * - Interface
          - MAC Address (1 universally administered, default)
-        * - IEEE 802.154
-          - EUI-64 derived from base_mac and MAC_EXT (base_mac[0:3] ‖ MAC_EXT ‖ base_mac[3:6], MAC_EXT defaults to ff:fe)
+        * - IEEE 802.15.4
+          - EUI-64 derived from base_mac and MAC_EXT (base_mac[0:2] ‖ MAC_EXT ‖ base_mac[3:5], MAC_EXT defaults to ff:fe)
        * - Bluetooth
          - base_mac

    .. note::

-        {IDF_TARGET_NAME} provides a single universally administered MAC address in eFuse (MAC_FACTORY) plus the MAC_EXT field used to build the IEEE 802.154 EUI-64. :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` is fixed to one. Bluetooth reuses the base MAC as-is — the BT offset is not applied because {IDF_TARGET_NAME} has no Wi-Fi, so no second universal MAC slot is required.
+        {IDF_TARGET_NAME} provides a single universally administered MAC address in eFuse (MAC_FACTORY) plus the MAC_EXT field used to build the IEEE 802.15.4 EUI-64. :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` is fixed to one. Bluetooth reuses the base MAC as-is — the BT offset is not applied because {IDF_TARGET_NAME} has no Wi-Fi, so no second universal MAC slot is required.

 .. only:: esp32s2

--- a/docs/zh_CN/api-reference/system/misc_system_api.rst
+++ b/docs/zh_CN/api-reference/system/misc_system_api.rst
@@ -104,7 +104,7 @@ MAC 地址

    .. note::

-        ESP32-S31 在 eFuse 中仅提供两个全局管理型 MAC 地址，因此 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` 默认为两个。其中的“四个”选项仅在使用客户自定义基准 MAC 范围时可用（参见 :ref:`自定义基准 MAC <MAC-Address-Allocation>`），且该范围内每个设备需分配 4 个全局管理型 MAC 地址。若在使用乐鑫 eFuse 默认基准 MAC 时选择“四个”，SoftAP 和以太网会占用 base+1/+3 的全局 MAC 槽位，而这些槽位在本芯片上并未分配，可能与蓝牙 MAC 发生冲突。
+        {IDF_TARGET_NAME} 在 eFuse 中仅提供两个全局管理型 MAC 地址，因此 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` 默认为两个。其中的“四个”选项仅在使用客户自定义基准 MAC 范围时可用（参见 :ref:`自定义基准 MAC <MAC-Address-Allocation>`），且该范围内每个设备需分配 4 个全局管理型 MAC 地址。若在使用乐鑫 eFuse 默认基准 MAC 时选择“四个”，SoftAP 和以太网会占用 base+1/+3 的全局 MAC 槽位，而这些槽位在本芯片上并未分配，可能与蓝牙 MAC 发生冲突。

 .. only:: esp32h2 or esp32h21 or esp32h4

@@ -114,14 +114,14 @@ MAC 地址

        * - 接口
          - MAC 地址（1 个默认的通用管理地址）
-        * - IEEE 802.154
-          - 由 base_mac 和 MAC_EXT 派生的 EUI-64（base_mac[0:3] ‖ MAC_EXT ‖ base_mac[3:6]，MAC_EXT 默认为 ff:fe）
+        * - IEEE 802.15.4
+          - 由 base_mac 和 MAC_EXT 派生的 EUI-64（base_mac[0:2] ‖ MAC_EXT ‖ base_mac[3:5]，MAC_EXT 默认为 ff:fe）
        * - 蓝牙
          - base_mac

    .. note::

-        {IDF_TARGET_NAME} 在 eFuse 中仅提供一个全局管理型 MAC 地址（MAC_FACTORY），以及用于构造 IEEE 802.154 EUI-64 的 MAC_EXT 字段。:ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` 固定为 1。蓝牙直接复用基准 MAC —— 由于 {IDF_TARGET_NAME} 没有 Wi-Fi，BT 偏移不会生效，因此不需要第二个全局 MAC 槽位。
+        {IDF_TARGET_NAME} 在 eFuse 中仅提供一个全局管理型 MAC 地址（MAC_FACTORY），以及用于构造 IEEE 802.15.4 EUI-64 的 MAC_EXT 字段。:ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` 固定为 1。蓝牙直接复用基准 MAC —— 由于 {IDF_TARGET_NAME} 没有 Wi-Fi，BT 偏移不会生效，因此不需要第二个全局 MAC 槽位。

 .. only:: esp32s2