From c7434cc9d96afc43f10b77b688301c0316b0a2fa Mon Sep 17 00:00:00 2001 From: Jack Date: Mon, 6 Jul 2026 15:20:44 +0800 Subject: [PATCH 1/4] fix(esp32s31): default UNIVERSAL_MAC_ADDRESSES to Two ESP32-S31 only provides two universally administered MAC addresses in eFuse. The previous default of "Four" led to WiFi softap and Ethernet consuming global MAC slots (base+1/+3) that do not exist on this chip and could collide with the Bluetooth MAC. Switch the default to "Two" so Softap and Ethernet fall back to locally administered MACs derived from the WiFi station and Bluetooth MACs. The "Four" option is retained for customers who override the base MAC with a custom range in which four universally administered MAC addresses are allocated per device; the help text now documents this constraint. Co-authored-by: Cursor (cherry picked from commit f18f3814ccefc6ba9d24f113c86bd531a88d443a) --- components/esp_hw_support/port/esp32s31/Kconfig.mac | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/components/esp_hw_support/port/esp32s31/Kconfig.mac b/components/esp_hw_support/port/esp32s31/Kconfig.mac index 4bf383285fd..7162d3d9a7f 100644 --- a/components/esp_hw_support/port/esp32s31/Kconfig.mac +++ b/components/esp_hw_support/port/esp32s31/Kconfig.mac @@ -1,6 +1,6 @@ choice ESP32S31_UNIVERSAL_MAC_ADDRESSES bool "Number of universally administered (by IEEE) MAC address" - default ESP32S31_UNIVERSAL_MAC_ADDRESSES_FOUR + default ESP32S31_UNIVERSAL_MAC_ADDRESSES_TWO help Configure the number of universally administered (by IEEE) MAC addresses. During initialization, MAC addresses for each network interface are generated or derived from a @@ -13,9 +13,9 @@ choice ESP32S31_UNIVERSAL_MAC_ADDRESSES and 1 (respectively) to the base MAC address. The remaining two interfaces (WiFi softap and Ethernet) receive local MAC addresses. These are derived from the universal WiFi station and Bluetooth MAC addresses, respectively. - When using the default (Espressif-assigned) base MAC address, either setting can be used. When using - a custom universal MAC address range, the correct setting will depend on the allocation of MAC - addresses in this range (either 2 or 4 per device.) + ESP32-S31 only provides two universally administered MAC addresses in eFuse, so "Two" is the + recommended and default setting. "Four" is only intended for use with a custom base MAC range + where four universally administered MAC addresses are allocated per device. config ESP32S31_UNIVERSAL_MAC_ADDRESSES_TWO bool "Two" From 57184eb356a4c319e3bce2c6ea013890cbe3796e Mon Sep 17 00:00:00 2001 From: Jack Date: Mon, 6 Jul 2026 18:08:27 +0800 Subject: [PATCH 2/4] fix(esp_hw_support): use one universal MAC address for esp32h2/esp32h21/esp32h4 ESP32-H2/H21/H4 only provide a single universally administered MAC address in eFuse (MAC_FACTORY), so switch their UNIVERSAL_MAC_ADDRESSES Kconfig from "Two" to "One" to match the hardware allocation. This is a functional no-op for MAC generation: the BT offset is only applied when SOC_WIFI_SUPPORTED, and these chips have no Wi-Fi, so Bluetooth already reuses the base MAC as-is; the IEEE 802.154 EUI-64 is derived from the base MAC and MAC_EXT regardless. The only change is the (otherwise unused) ESP_MAC_UNIVERSAL_MAC_ADDRESSES int value going from 2 to 1. Co-authored-by: Cursor (cherry picked from commit 431983a0916423042e4d9c19669e3ddc19fb913f) --- components/esp_hw_support/port/esp32h2/Kconfig.mac | 10 +++++----- components/esp_hw_support/port/esp32h21/Kconfig.mac | 10 +++++----- components/esp_hw_support/port/esp32h4/Kconfig.mac | 10 +++++----- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/components/esp_hw_support/port/esp32h2/Kconfig.mac b/components/esp_hw_support/port/esp32h2/Kconfig.mac index 48c69f0fa08..cc4cd68ae9c 100644 --- a/components/esp_hw_support/port/esp32h2/Kconfig.mac +++ b/components/esp_hw_support/port/esp32h2/Kconfig.mac @@ -1,18 +1,18 @@ choice ESP32H2_UNIVERSAL_MAC_ADDRESSES bool "Number of universally administered (by IEEE) MAC address" - default ESP32H2_UNIVERSAL_MAC_ADDRESSES_TWO + default ESP32H2_UNIVERSAL_MAC_ADDRESSES_ONE help Configure the number of universally administered (by IEEE) MAC addresses. During initialization, MAC addresses for each network interface are generated or derived from a single base MAC address. - config ESP32H2_UNIVERSAL_MAC_ADDRESSES_TWO - bool "Two" - select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_TWO + config ESP32H2_UNIVERSAL_MAC_ADDRESSES_ONE + bool "One" + select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_ONE select ESP_MAC_ADDR_UNIVERSE_IEEE802154 select ESP_MAC_ADDR_UNIVERSE_BT endchoice config ESP32H2_UNIVERSAL_MAC_ADDRESSES int - default 2 if ESP32H2_UNIVERSAL_MAC_ADDRESSES_TWO + default 1 if ESP32H2_UNIVERSAL_MAC_ADDRESSES_ONE diff --git a/components/esp_hw_support/port/esp32h21/Kconfig.mac b/components/esp_hw_support/port/esp32h21/Kconfig.mac index 40fd8709b0a..a1a0795cc1e 100644 --- a/components/esp_hw_support/port/esp32h21/Kconfig.mac +++ b/components/esp_hw_support/port/esp32h21/Kconfig.mac @@ -1,18 +1,18 @@ choice ESP32H21_UNIVERSAL_MAC_ADDRESSES bool "Number of universally administered (by IEEE) MAC address" - default ESP32H21_UNIVERSAL_MAC_ADDRESSES_TWO + default ESP32H21_UNIVERSAL_MAC_ADDRESSES_ONE help Configure the number of universally administered (by IEEE) MAC addresses. During initialization, MAC addresses for each network interface are generated or derived from a single base MAC address. - config ESP32H21_UNIVERSAL_MAC_ADDRESSES_TWO - bool "Two" - select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_TWO + config ESP32H21_UNIVERSAL_MAC_ADDRESSES_ONE + bool "One" + select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_ONE select ESP_MAC_ADDR_UNIVERSE_IEEE802154 select ESP_MAC_ADDR_UNIVERSE_BT endchoice config ESP32H21_UNIVERSAL_MAC_ADDRESSES int - default 2 if ESP32H21_UNIVERSAL_MAC_ADDRESSES_TWO + default 1 if ESP32H21_UNIVERSAL_MAC_ADDRESSES_ONE diff --git a/components/esp_hw_support/port/esp32h4/Kconfig.mac b/components/esp_hw_support/port/esp32h4/Kconfig.mac index 699af307712..24371cb6303 100644 --- a/components/esp_hw_support/port/esp32h4/Kconfig.mac +++ b/components/esp_hw_support/port/esp32h4/Kconfig.mac @@ -1,18 +1,18 @@ choice ESP32H4_UNIVERSAL_MAC_ADDRESSES bool "Number of universally administered (by IEEE) MAC address" - default ESP32H4_UNIVERSAL_MAC_ADDRESSES_TWO + default ESP32H4_UNIVERSAL_MAC_ADDRESSES_ONE help Configure the number of universally administered (by IEEE) MAC addresses. During initialization, MAC addresses for each network interface are generated or derived from a single base MAC address. - config ESP32H4_UNIVERSAL_MAC_ADDRESSES_TWO - bool "Two" - select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_TWO + config ESP32H4_UNIVERSAL_MAC_ADDRESSES_ONE + bool "One" + select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_ONE select ESP_MAC_ADDR_UNIVERSE_IEEE802154 select ESP_MAC_ADDR_UNIVERSE_BT endchoice config ESP32H4_UNIVERSAL_MAC_ADDRESSES int - default 2 if ESP32H4_UNIVERSAL_MAC_ADDRESSES_TWO + default 1 if ESP32H4_UNIVERSAL_MAC_ADDRESSES_ONE From b5cd9ce7faac882a2465090fe4f63a8c31b5a81a Mon Sep 17 00:00:00 2001 From: Jack Date: Mon, 6 Jul 2026 18:06:24 +0800 Subject: [PATCH 3/4] docs(esp_hw_support): document one-universal-MAC scheme and esp32s31 Four-option constraint Add help text to the esp32h2/esp32h21/esp32h4 Kconfig.mac explaining that these chips only consume one universally administered MAC address: the IEEE 802.154 EUI-64 is derived from the base MAC and MAC_EXT, and Bluetooth reuses the base MAC as-is (no BT offset, since there is no Wi-Fi). Add a matching 1-MAC derivation table and note to misc_system_api.rst (EN and zh_CN) under a new `.. only:: esp32h2 or esp32h21 or esp32h4` block, and exclude these targets from the generic 4/2 table. Add an esp32s31-only note stating that the "Four" option may only be used with a customer-provided custom base MAC range, since ESP32-S31 only provides two universally administered MAC addresses in eFuse. Co-authored-by: Cursor (cherry picked from commit e3bc260178417ce6ec1f70d35e89628caf44563e) --- .../esp_hw_support/port/esp32h2/Kconfig.mac | 8 ++++ .../esp_hw_support/port/esp32h21/Kconfig.mac | 8 ++++ .../esp_hw_support/port/esp32h4/Kconfig.mac | 8 ++++ .../api-reference/system/misc_system_api.rst | 45 ++++++++++++++++++- .../api-reference/system/misc_system_api.rst | 45 ++++++++++++++++++- 5 files changed, 112 insertions(+), 2 deletions(-) diff --git a/components/esp_hw_support/port/esp32h2/Kconfig.mac b/components/esp_hw_support/port/esp32h2/Kconfig.mac index cc4cd68ae9c..a3829ec3bb8 100644 --- a/components/esp_hw_support/port/esp32h2/Kconfig.mac +++ b/components/esp_hw_support/port/esp32h2/Kconfig.mac @@ -6,6 +6,14 @@ choice ESP32H2_UNIVERSAL_MAC_ADDRESSES During initialization, MAC addresses for each network interface are generated or derived from a 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 + 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. + config ESP32H2_UNIVERSAL_MAC_ADDRESSES_ONE bool "One" select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_ONE diff --git a/components/esp_hw_support/port/esp32h21/Kconfig.mac b/components/esp_hw_support/port/esp32h21/Kconfig.mac index a1a0795cc1e..33d385be1b8 100644 --- a/components/esp_hw_support/port/esp32h21/Kconfig.mac +++ b/components/esp_hw_support/port/esp32h21/Kconfig.mac @@ -6,6 +6,14 @@ choice ESP32H21_UNIVERSAL_MAC_ADDRESSES During initialization, MAC addresses for each network interface are generated or derived from a 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 + 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. + config ESP32H21_UNIVERSAL_MAC_ADDRESSES_ONE bool "One" select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_ONE diff --git a/components/esp_hw_support/port/esp32h4/Kconfig.mac b/components/esp_hw_support/port/esp32h4/Kconfig.mac index 24371cb6303..713782a94ca 100644 --- a/components/esp_hw_support/port/esp32h4/Kconfig.mac +++ b/components/esp_hw_support/port/esp32h4/Kconfig.mac @@ -6,6 +6,14 @@ choice ESP32H4_UNIVERSAL_MAC_ADDRESSES During initialization, MAC addresses for each network interface are generated or derived from a 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 + 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. + config ESP32H4_UNIVERSAL_MAC_ADDRESSES_ONE bool "One" select ESP_MAC_UNIVERSAL_MAC_ADDRESSES_ONE diff --git a/docs/en/api-reference/system/misc_system_api.rst b/docs/en/api-reference/system/misc_system_api.rst index 5f709db72f6..10dca299ce9 100644 --- a/docs/en/api-reference/system/misc_system_api.rst +++ b/docs/en/api-reference/system/misc_system_api.rst @@ -54,7 +54,7 @@ In ESP-IDF, the MAC addresses for the various network interfaces are calculated On ESP32-P4, :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` is fixed to one universally administered MAC address. -.. only:: (not esp32s2) and (not esp32p4) +.. only:: (not esp32s2) and (not esp32p4) and (not esp32h2) and (not esp32h21) and (not esp32h4) and (not esp32s31) .. list-table:: :widths: 20 40 40 @@ -80,6 +80,49 @@ In ESP-IDF, the MAC addresses for the various network interfaces are calculated The :ref:`configuration ` configures the number of universally administered MAC addresses that are provided by Espressif. +.. only:: esp32s31 + + .. list-table:: + :widths: 20 40 40 + :header-rows: 1 + + * - Interface + - MAC Address (2 universally administered, default) + - MAC Address (4 universally administered) + * - Wi-Fi Station + - base_mac + - base_mac + * - Wi-Fi SoftAP + - :ref:`Local MAC ` (derived from Wi-Fi Station MAC) + - base_mac, +1 to the last octet + * - Bluetooth + - base_mac, +1 to the last octet + - base_mac, +2 to the last octet + * - Ethernet + - :ref:`Local MAC ` (derived from Bluetooth MAC) + - base_mac, +3 to the last octet + + .. 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 `), 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 + + .. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - 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) + * - 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. + .. only:: esp32s2 .. list-table:: diff --git a/docs/zh_CN/api-reference/system/misc_system_api.rst b/docs/zh_CN/api-reference/system/misc_system_api.rst index d0b8bda17ec..9d27429cc18 100644 --- a/docs/zh_CN/api-reference/system/misc_system_api.rst +++ b/docs/zh_CN/api-reference/system/misc_system_api.rst @@ -54,7 +54,7 @@ MAC 地址 在 ESP32-P4 上，:ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` 固定为单个通用管理型 MAC 地址。 -.. only:: (not esp32s2) and (not esp32p4) +.. only:: (not esp32s2) and (not esp32p4) and (not esp32h2) and (not esp32h21) and (not esp32h4) and (not esp32s31) .. list-table:: :widths: 20 40 40 @@ -80,6 +80,49 @@ MAC 地址 :ref:`配置选项 ` 配置了乐鑫提供的全局 MAC 地址的数量。 +.. only:: esp32s31 + + .. list-table:: + :widths: 20 40 40 + :header-rows: 1 + + * - 接口 + - MAC 地址（默认 2 个全局地址） + - MAC 地址（4 个全局地址） + * - Wi-Fi Station + - base_mac + - base_mac + * - Wi-Fi SoftAP + - :ref:`本地 MAC ` （由 Wi-Fi Station MAC 生成） + - base_mac 最后一组字节后加 1 + * - 蓝牙 + - base_mac 最后一组字节后加 1 + - base_mac 最后一组字节后加 2 + * - 以太网 + - :ref:`本地 MAC ` （由蓝牙 MAC 生成） + - base_mac 最后一组字节后加 3 + + .. note:: + + ESP32-S31 在 eFuse 中仅提供两个全局管理型 MAC 地址，因此 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_UNIVERSAL_MAC_ADDRESSES` 默认为两个。其中的“四个”选项仅在使用客户自定义基准 MAC 范围时可用（参见 :ref:`自定义基准 MAC `），且该范围内每个设备需分配 4 个全局管理型 MAC 地址。若在使用乐鑫 eFuse 默认基准 MAC 时选择“四个”，SoftAP 和以太网会占用 base+1/+3 的全局 MAC 槽位，而这些槽位在本芯片上并未分配，可能与蓝牙 MAC 发生冲突。 + +.. only:: esp32h2 or esp32h21 or esp32h4 + + .. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - 接口 + - 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） + * - 蓝牙 + - 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 槽位。 + .. only:: esp32s2 .. list-table:: From 7ca1369ffcfa424e864f811b7a5ba64fe2543d60 Mon Sep 17 00:00:00 2001 From: Jack Date: Mon, 6 Jul 2026 20:14:53 +0800 Subject: [PATCH 4/4] 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 (cherry picked from commit 811c64c17c14f7e395f90f7cc89f47073a713161) --- components/esp_hw_support/port/esp32h2/Kconfig.mac | 11 ++++++----- components/esp_hw_support/port/esp32h21/Kconfig.mac | 11 ++++++----- components/esp_hw_support/port/esp32h4/Kconfig.mac | 11 ++++++----- docs/en/api-reference/system/misc_system_api.rst | 8 ++++---- docs/zh_CN/api-reference/system/misc_system_api.rst | 8 ++++---- 5 files changed, 26 insertions(+), 23 deletions(-) diff --git a/components/esp_hw_support/port/esp32h2/Kconfig.mac b/components/esp_hw_support/port/esp32h2/Kconfig.mac index a3829ec3bb8..77977a5ed3b 100644 --- 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" diff --git a/components/esp_hw_support/port/esp32h21/Kconfig.mac b/components/esp_hw_support/port/esp32h21/Kconfig.mac index 33d385be1b8..a8ad015469a 100644 --- 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" diff --git a/components/esp_hw_support/port/esp32h4/Kconfig.mac b/components/esp_hw_support/port/esp32h4/Kconfig.mac index 713782a94ca..8d189478734 100644 --- 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" diff --git a/docs/en/api-reference/system/misc_system_api.rst b/docs/en/api-reference/system/misc_system_api.rst index 10dca299ce9..b599559ebef 100644 --- 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 `), 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 `), 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 diff --git a/docs/zh_CN/api-reference/system/misc_system_api.rst b/docs/zh_CN/api-reference/system/misc_system_api.rst index 9d27429cc18..9e96ec3c298 100644 --- 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 `），且该范围内每个设备需分配 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 `），且该范围内每个设备需分配 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