1 /* 2 * SPDX-FileCopyrightText: 2021-2022 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 #ifndef MAC2STR 13 #define MAC2STR(a) (a)[0], (a)[1], (a)[2], (a)[3], (a)[4], (a)[5] 14 #define MACSTR "%02x:%02x:%02x:%02x:%02x:%02x" 15 #endif 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 typedef enum { 22 ESP_MAC_WIFI_STA, /**< MAC for WiFi Station (6 bytes) */ 23 ESP_MAC_WIFI_SOFTAP, /**< MAC for WiFi Soft-AP (6 bytes) */ 24 ESP_MAC_BT, /**< MAC for Bluetooth (6 bytes) */ 25 ESP_MAC_ETH, /**< MAC for Ethernet (6 bytes) */ 26 ESP_MAC_IEEE802154, /**< if CONFIG_SOC_IEEE802154_SUPPORTED=y, MAC for IEEE802154 (8 bytes) */ 27 ESP_MAC_BASE, /**< Base MAC for that used for other MAC types (6 bytes) */ 28 ESP_MAC_EFUSE_FACTORY, /**< MAC_FACTORY eFuse which was burned by Espressif in production (6 bytes) */ 29 ESP_MAC_EFUSE_CUSTOM, /**< MAC_CUSTOM eFuse which was can be burned by customer (6 bytes) */ 30 ESP_MAC_EFUSE_EXT, /**< if CONFIG_SOC_IEEE802154_SUPPORTED=y, MAC_EXT eFuse which is used as an extender for IEEE802154 MAC (2 bytes) */ 31 } esp_mac_type_t; 32 33 /** @cond */ 34 #define TWO_UNIVERSAL_MAC_ADDR 2 35 #define FOUR_UNIVERSAL_MAC_ADDR 4 36 #if CONFIG_IDF_TARGET_ESP32 37 #define UNIVERSAL_MAC_ADDR_NUM CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES 38 #elif CONFIG_IDF_TARGET_ESP32S2 39 #define UNIVERSAL_MAC_ADDR_NUM CONFIG_ESP32S2_UNIVERSAL_MAC_ADDRESSES 40 #elif CONFIG_IDF_TARGET_ESP32S3 41 #define UNIVERSAL_MAC_ADDR_NUM CONFIG_ESP32S3_UNIVERSAL_MAC_ADDRESSES 42 #elif CONFIG_IDF_TARGET_ESP32C3 43 #define UNIVERSAL_MAC_ADDR_NUM CONFIG_ESP32C3_UNIVERSAL_MAC_ADDRESSES 44 #elif CONFIG_IDF_TARGET_ESP32C2 45 #define UNIVERSAL_MAC_ADDR_NUM CONFIG_ESP32C2_UNIVERSAL_MAC_ADDRESSES 46 #elif CONFIG_IDF_TARGET_ESP32C6 47 #define UNIVERSAL_MAC_ADDR_NUM CONFIG_ESP32C6_UNIVERSAL_MAC_ADDRESSES 48 #endif 49 /** @endcond */ 50 51 52 /** 53 * @brief Set base MAC address with the MAC address which is stored in BLK3 of EFUSE or 54 * external storage e.g. flash and EEPROM. 55 * 56 * Base MAC address is used to generate the MAC addresses used by network interfaces. 57 * 58 * If using a custom base MAC address, call this API before initializing any network interfaces. 59 * Refer to the ESP-IDF Programming Guide for details about how the Base MAC is used. 60 * 61 * @note Base MAC must be a unicast MAC (least significant bit of first byte must be zero). 62 * 63 * @note If not using a valid OUI, set the "locally administered" bit 64 * (bit value 0x02 in the first byte) to avoid collisions. 65 * 66 * @param mac base MAC address, length: 6 bytes. 67 * length: 6 bytes for MAC-48 68 * 69 * @return ESP_OK on success 70 * ESP_ERR_INVALID_ARG If mac is NULL or is not a unicast MAC 71 */ 72 esp_err_t esp_base_mac_addr_set(const uint8_t *mac); 73 74 /** 75 * @brief Return base MAC address which is set using esp_base_mac_addr_set. 76 * 77 * @note If no custom Base MAC has been set, this returns the pre-programmed Espressif base MAC address. 78 * 79 * @param mac base MAC address, length: 6 bytes. 80 * length: 6 bytes for MAC-48 81 * 82 * @return ESP_OK on success 83 * ESP_ERR_INVALID_ARG mac is NULL 84 * ESP_ERR_INVALID_MAC base MAC address has not been set 85 */ 86 esp_err_t esp_base_mac_addr_get(uint8_t *mac); 87 88 /** 89 * @brief Return base MAC address which was previously written to BLK3 of EFUSE. 90 * 91 * Base MAC address is used to generate the MAC addresses used by the networking interfaces. 92 * This API returns the custom base MAC address which was previously written to EFUSE BLK3 in 93 * a specified format. 94 * 95 * Writing this EFUSE allows setting of a different (non-Espressif) base MAC address. It is also 96 * possible to store a custom base MAC address elsewhere, see esp_base_mac_addr_set() for details. 97 * 98 * @note This function is currently only supported on ESP32. 99 * 100 * @param mac base MAC address, length: 6 bytes/8 bytes. 101 * length: 6 bytes for MAC-48 102 * 8 bytes for EUI-64(used for IEEE 802.15.4, if CONFIG_SOC_IEEE802154_SUPPORTED=y) 103 * 104 * @return ESP_OK on success 105 * ESP_ERR_INVALID_ARG mac is NULL 106 * ESP_ERR_INVALID_MAC CUSTOM_MAC address has not been set, all zeros (for esp32-xx) 107 * ESP_ERR_INVALID_VERSION An invalid MAC version field was read from BLK3 of EFUSE (for esp32) 108 * ESP_ERR_INVALID_CRC An invalid MAC CRC was read from BLK3 of EFUSE (for esp32) 109 */ 110 esp_err_t esp_efuse_mac_get_custom(uint8_t *mac); 111 112 /** 113 * @brief Return base MAC address which is factory-programmed by Espressif in EFUSE. 114 * 115 * @param mac base MAC address, length: 6 bytes/8 bytes. 116 * length: 6 bytes for MAC-48 117 * 8 bytes for EUI-64(used for IEEE 802.15.4, if CONFIG_SOC_IEEE802154_SUPPORTED=y) 118 * 119 * @return ESP_OK on success 120 * ESP_ERR_INVALID_ARG mac is NULL 121 */ 122 esp_err_t esp_efuse_mac_get_default(uint8_t *mac); 123 124 /** 125 * @brief Read base MAC address and set MAC address of the interface. 126 * 127 * This function first get base MAC address using esp_base_mac_addr_get(). 128 * Then calculates the MAC address of the specific interface requested, 129 * refer to ESP-IDF Programming Guide for the algorithm. 130 * 131 * The MAC address set by the esp_iface_mac_addr_set() function will not depend on the base MAC address. 132 * 133 * @param mac base MAC address, length: 6 bytes/8 bytes. 134 * length: 6 bytes for MAC-48 135 * 8 bytes for EUI-64(used for IEEE 802.15.4, if CONFIG_SOC_IEEE802154_SUPPORTED=y) 136 * @param type Type of MAC address to return 137 * 138 * @return ESP_OK on success 139 */ 140 esp_err_t esp_read_mac(uint8_t *mac, esp_mac_type_t type); 141 142 /** 143 * @brief Derive local MAC address from universal MAC address. 144 * 145 * This function copies a universal MAC address and then sets the "locally 146 * administered" bit (bit 0x2) in the first octet, creating a locally 147 * administered MAC address. 148 * 149 * If the universal MAC address argument is already a locally administered MAC 150 * address, then the first octet is XORed with 0x4 in order to create a different 151 * locally administered MAC address. 152 * 153 * @param local_mac base MAC address, length: 6 bytes. 154 * length: 6 bytes for MAC-48 155 * @param universal_mac Source universal MAC address, length: 6 bytes. 156 * 157 * @return ESP_OK on success 158 */ 159 esp_err_t esp_derive_local_mac(uint8_t *local_mac, const uint8_t *universal_mac); 160 161 /** 162 * @brief Set custom MAC address of the interface. This function allows you to overwrite the MAC addresses 163 * of the interfaces set by the base MAC address. 164 * 165 * @param mac MAC address, length: 6 bytes/8 bytes. 166 * length: 6 bytes for MAC-48 167 * 8 bytes for EUI-64(used for ESP_MAC_IEEE802154 type, if CONFIG_SOC_IEEE802154_SUPPORTED=y) 168 * @param type Type of MAC address 169 * 170 * @return ESP_OK on success 171 */ 172 esp_err_t esp_iface_mac_addr_set(const uint8_t *mac, esp_mac_type_t type); 173 174 /** 175 * @brief Return the size of the MAC type in bytes. 176 * 177 * If CONFIG_SOC_IEEE802154_SUPPORTED is set then for these types: 178 * - ESP_MAC_IEEE802154 is 8 bytes. 179 * - ESP_MAC_BASE, ESP_MAC_EFUSE_FACTORY and ESP_MAC_EFUSE_CUSTOM the MAC size is 6 bytes. 180 * - ESP_MAC_EFUSE_EXT is 2 bytes. 181 * If CONFIG_SOC_IEEE802154_SUPPORTED is not set then for all types it returns 6 bytes. 182 * 183 * @param type Type of MAC address 184 * 185 * @return 0 MAC type not found (not supported) 186 * 6 bytes for MAC-48. 187 * 8 bytes for EUI-64. 188 */ 189 size_t esp_mac_addr_len_get(esp_mac_type_t type); 190 191 #ifdef __cplusplus 192 } 193 #endif 194
