1# Base MAC Address
2
3(See the README.md file in the upper level 'examples' directory for more information about examples.)
4
5Each network interface on the ESP32 (e.g., WiFi Station/AP, BT, Ethernet) must be assigned a unique Medium Access Control (MAC) address. Each interface's MAC address is [derived from a base MAC address](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/system.html#mac-address) that must be set before any network interface's initialization is called.
6
7This example demonstrates the following:
8
91. How to retrieve a base MAC address from non-volatile memory
102. How to set the base MAC address
113. How to obtain the derived MAC addresses of each network interface
12
13This example utilizes the [MAC Address API](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/system.html#mac-address).
14
15## How to use example
16
17### Hardware Required
18
19This example should be able to run on any commonly available ESP32 development board. However, if an external source of non-volatile memory is used to store the base MAC address (e.g. an I2C Serial EEPROM), the user should wire the connections to their chosen external storage as needed.
20
21### Configure the project
22
23```
24idf.py menuconfig
25```
26
27* To select the storage source of the base MAC address, go to `Example Configuration > Storage location of the base MAC address` where the following options are available:
28  * `eFuse BLK0` will cause this example to read the base MAC address from eFuse Block 0 and is selected by default. The `eFuse BLK0` MAC address is factory programmed into each ESP32.
29  * `eFuse BLK3` will cause this example to read the base MAC address from words 1 & 2 of eFuse Block 3. `eFuse BLK3` allows users to use a custom eFuse, but must be burned into the ESP32 using the [espefuse tool](https://github.com/espressif/esptool/wiki/espefuse). Attempting to read `eFuse BLK3` without burning the eFuse will result in an error.
30  * `Other external storage` will call a `external_storage_mac_get()` which will merely retrieve an arbitrary base MAC address that is set in software. Users should re-implement `external_storage_mac_get()` to access their chosen external storage (e.g. an I2C Serial EEPROM)
31
32* If `eFuse BLK3` is chosen, the `Behavior when retrieving BLK3 eFuse fails` option may also be selected. When retrieving the base MAC address from `eFuse BLK3` without burning eFuse Block 3, the example can either abort or default to retrieving from eFuse Block 0.
33
34### Build and Flash
35
36Build the project and flash it to the board, then run monitor tool to view serial output:
37
38```
39idf.py -p PORT flash monitor
40```
41
42(Replace PORT with the name of the serial port to use.)
43
44(To exit the serial monitor, type ``Ctrl-]``.)
45
46See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
47
48## Example Output
49
50Depending on the `Storage of the base MAC address` configuration option, the console should output one of the following logs to indicate the source of the base MAC address.
51
52```
53I (288) BASE_MAC: Base MAC Address read from EFUSE BLK0
54...
55I (288) BASE_MAC: Base MAC Address read from EFUSE BLK3
56...
57I (288) BASE_MAC: Base MAC Address read from external storage
58```
59
60The console will also output the retrieved 6 byte MAC address when it sets it as the system wide base MAC address.
61```
62I (298) BASE_MAC: Using "0xd8, 0xa0, 0x1d, 0x0, 0xb, 0x88" as base MAC address
63```
64
65The console will then output the derived MAC address of each network interface as such:
66```
67I (297) WIFI_STA MAC: 0x0, 0x11, 0x22, 0x33, 0x44, 0x55
68I (307) SoftAP MAC: 0x0, 0x11, 0x22, 0x33, 0x44, 0x56
69I (317) BT MAC: 0x0, 0x11, 0x22, 0x33, 0x44, 0x57
70I (317) Ethernet MAC: 0x0, 0x11, 0x22, 0x33, 0x44, 0x58
71```
72
73## Troubleshooting
74
75When attempting to retrieve the base MAC address from `eFuse BLK3` without first burning eFuse Block 3 will result in one of the following situations.
76
77If the example has been configured to abort when retrieving from `eFuse BLK3` fails.
78
79```
80E (288) system_api: Base MAC address from BLK3 of EFUSE version error, version = 0
81E (298) BASE_MAC: Failed to get base MAC address from EFUSE BLK3. (ESP_ERR_INVALID_VERSION)
82E (308) BASE_MAC: Aborting
83abort() was called at PC 0x400d237b on core 0
84```
85
86If not configured to abort, the example will default to `eFuse BLK0` and output the following instead.
87
88```
89E (288) system_api: Base MAC address from BLK3 of EFUSE version error, version = 0
90E (298) BASE_MAC: Failed to get base MAC address from EFUSE BLK3. (ESP_ERR_INVALID_VERSION)
91I (308) BASE_MAC: Defaulting to base MAC address in BLK0 of EFUSE
92I (308) BASE_MAC: Base MAC Address read from EFUSE BLK0
93```