1 /* 2 * SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 9 #include "esp_err.h" 10 #include "sdkconfig.h" 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 typedef enum { 17 ESP_MAC_WIFI_STA, 18 ESP_MAC_WIFI_SOFTAP, 19 ESP_MAC_BT, 20 ESP_MAC_ETH, 21 ESP_MAC_IEEE802154, 22 } esp_mac_type_t; 23 24 /** @cond */ 25 #define TWO_UNIVERSAL_MAC_ADDR 2 26 #define FOUR_UNIVERSAL_MAC_ADDR 4 27 #if CONFIG_IDF_TARGET_ESP32 28 #define UNIVERSAL_MAC_ADDR_NUM CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES 29 #elif CONFIG_IDF_TARGET_ESP32S2 30 #define UNIVERSAL_MAC_ADDR_NUM CONFIG_ESP32S2_UNIVERSAL_MAC_ADDRESSES 31 #elif CONFIG_IDF_TARGET_ESP32S3 32 #define UNIVERSAL_MAC_ADDR_NUM CONFIG_ESP32S3_UNIVERSAL_MAC_ADDRESSES 33 #elif CONFIG_IDF_TARGET_ESP32C3 34 #define UNIVERSAL_MAC_ADDR_NUM CONFIG_ESP32C3_UNIVERSAL_MAC_ADDRESSES 35 #elif CONFIG_IDF_TARGET_ESP32H2 36 #define UNIVERSAL_MAC_ADDR_NUM CONFIG_ESP32H2_UNIVERSAL_MAC_ADDRESSES 37 #endif 38 /** @endcond */ 39 40 41 /** 42 * @brief Set base MAC address with the MAC address which is stored in BLK3 of EFUSE or 43 * external storage e.g. flash and EEPROM. 44 * 45 * Base MAC address is used to generate the MAC addresses used by network interfaces. 46 * 47 * If using a custom base MAC address, call this API before initializing any network interfaces. 48 * Refer to the ESP-IDF Programming Guide for details about how the Base MAC is used. 49 * 50 * @note Base MAC must be a unicast MAC (least significant bit of first byte must be zero). 51 * 52 * @note If not using a valid OUI, set the "locally administered" bit 53 * (bit value 0x02 in the first byte) to avoid collisions. 54 * 55 * @param mac base MAC address, length: 6 bytes/8 bytes. 56 * length: 6 bytes for MAC-48 57 * 8 bytes for EUI-64(used for IEEE 802.15.4) 58 * 59 * @return ESP_OK on success 60 * ESP_ERR_INVALID_ARG If mac is NULL or is not a unicast MAC 61 */ 62 esp_err_t esp_base_mac_addr_set(const uint8_t *mac); 63 64 /** 65 * @brief Return base MAC address which is set using esp_base_mac_addr_set. 66 * 67 * @note If no custom Base MAC has been set, this returns the pre-programmed Espressif base MAC address. 68 * 69 * @param mac base MAC address, length: 6 bytes/8 bytes. 70 * length: 6 bytes for MAC-48 71 * 8 bytes for EUI-64(used for IEEE 802.15.4) 72 * 73 * @return ESP_OK on success 74 * ESP_ERR_INVALID_ARG mac is NULL 75 * ESP_ERR_INVALID_MAC base MAC address has not been set 76 */ 77 esp_err_t esp_base_mac_addr_get(uint8_t *mac); 78 79 /** 80 * @brief Return base MAC address which was previously written to BLK3 of EFUSE. 81 * 82 * Base MAC address is used to generate the MAC addresses used by the networking interfaces. 83 * This API returns the custom base MAC address which was previously written to EFUSE BLK3 in 84 * a specified format. 85 * 86 * Writing this EFUSE allows setting of a different (non-Espressif) base MAC address. It is also 87 * possible to store a custom base MAC address elsewhere, see esp_base_mac_addr_set() for details. 88 * 89 * @note This function is currently only supported on ESP32. 90 * 91 * @param mac base MAC address, length: 6 bytes/8 bytes. 92 * length: 6 bytes for MAC-48 93 * 8 bytes for EUI-64(used for IEEE 802.15.4) 94 * 95 * @return ESP_OK on success 96 * ESP_ERR_INVALID_ARG mac is NULL 97 * ESP_ERR_INVALID_MAC CUSTOM_MAC address has not been set, all zeros (for esp32-xx) 98 * ESP_ERR_INVALID_VERSION An invalid MAC version field was read from BLK3 of EFUSE (for esp32) 99 * ESP_ERR_INVALID_CRC An invalid MAC CRC was read from BLK3 of EFUSE (for esp32) 100 */ 101 esp_err_t esp_efuse_mac_get_custom(uint8_t *mac); 102 103 /** 104 * @brief Return base MAC address which is factory-programmed by Espressif in EFUSE. 105 * 106 * @param mac base MAC address, length: 6 bytes/8 bytes. 107 * length: 6 bytes for MAC-48 108 * 8 bytes for EUI-64(used for IEEE 802.15.4) 109 * 110 * @return ESP_OK on success 111 * ESP_ERR_INVALID_ARG mac is NULL 112 */ 113 esp_err_t esp_efuse_mac_get_default(uint8_t *mac); 114 115 /** 116 * @brief Read base MAC address and set MAC address of the interface. 117 * 118 * This function first get base MAC address using esp_base_mac_addr_get(). 119 * Then calculates the MAC address of the specific interface requested, 120 * refer to ESP-IDF Programming Guide for the algorithm. 121 * 122 * @param mac base MAC address, length: 6 bytes/8 bytes. 123 * length: 6 bytes for MAC-48 124 * 8 bytes for EUI-64(used for IEEE 802.15.4) 125 * @param type Type of MAC address to return 126 * 127 * @return ESP_OK on success 128 */ 129 esp_err_t esp_read_mac(uint8_t *mac, esp_mac_type_t type); 130 131 /** 132 * @brief Derive local MAC address from universal MAC address. 133 * 134 * This function copies a universal MAC address and then sets the "locally 135 * administered" bit (bit 0x2) in the first octet, creating a locally 136 * administered MAC address. 137 * 138 * If the universal MAC address argument is already a locally administered MAC 139 * address, then the first octet is XORed with 0x4 in order to create a different 140 * locally administered MAC address. 141 * 142 * @param mac base MAC address, length: 6 bytes/8 bytes. 143 * length: 6 bytes for MAC-48 144 * 8 bytes for EUI-64(used for IEEE 802.15.4) 145 * @param universal_mac Source universal MAC address, length: 6 bytes. 146 * 147 * @return ESP_OK on success 148 */ 149 esp_err_t esp_derive_local_mac(uint8_t *local_mac, const uint8_t *universal_mac); 150 151 #ifdef __cplusplus 152 } 153 #endif 154
