ESP-IDF: Read and Set ESP32 MAC Address

This guide shows how to get the ESP32 board MAC Address using ESP-IDF. We’ll get the following MAC addresses: the base (factory default), Wi-Fi station, Wi-Fi SoftAP, and Bluetooth. We’ll also show how to change your board’s MAC Address.

What’s a MAC Address?

MAC Address stands for Media Access Control Address and it is a hardware unique identifier that identifies each device on a network. MAC Addresses are made up of six groups of two hexadecimal digits, separated by colons, for example: 30:AE:A4:07:0D:64.

MAC Addresses are assigned by manufacturers, but you can also give a custom MAC Address to your board. However, every time the board resets, it will return to its original MAC Address. So, you need to include the code to set a custom MAC Address in every code.

With ESP-IDF you have two main functions that are available in the esp_mac.h:

esp_read_mac() – reads the requested MAC address type, example: base/factory, WiFi STA, SoftAP or Bluetooth
esp_base_mac_addr_set() – sets a custom ESP32 MAC address

Prerequisites

Before following this guide, you need to install the ESP-IDF extension on VS Code IDE (Microsoft Visual Studio Code). Follow the next guide to install it, if you haven’t already:

Getting Started Guide: Programming ESP32 with ESP-IDF using VS Code

You will also need an ESP32 development board model of your choice.

Creating an ESP-IDF Template App Project for the ESP32

The ESP-IDF extension provides an easy way to create a project from scratch with all the required files and configurations generated automatically.

To create a new ESP-IDF project on VS Code, follow these steps:

Open the ESP-IDF Espressif extension and expand the “Advanced” menu
Click the “New Project Wizard” option
Choose the “Use ESP-IDF v6.X” to select the ESP-IDF framework version

VS Code Open ESP-IDF Extension New Project Wizard Select ESP-IDF Version

In the menu, select the “ESP-IDF Templates” sample project and press the “Create project using template sample project” button.

ESP-IDF ESP32 Create New Sample Project using IDF Template

A new window opens, you need to fill in these fields:

Project Name: type the desired project name;
Enter Project Directory: click the folder icon and select the target folder to save all your project files. You can use any directory. Note: do NOT use a Google Drive / One Drive / Dropbox folder, because it will write/create many files during the building process. If it’s on a cloud folder, this process might be extremely slow;
ESP-IDF Target: select the target device chip, I’m using an ESP32 with the esp32s3 chip;
ESP-IDF Board: for the esp32s3 chip, I also need to select the configuration: ESP32-S chip (via builtin USB-JTAG);
Serial Port: while having your ESP32 board connected to your computer, select the correct COM port number that refers to your ESP32;
Choose Template: click the blue button to create a new project using a template.

ESP-IDF ESP32 Create Open New Project Wizard Menu Select Directory Board Template

Opening the ESP-IDF Project on VS Code

After a few seconds, a notification will appear on a new window on VS Code. You can click “Open Project” to open the newly created ESP-IDF sample project template.

IMPORTANT: if you didn’t see the notification that allows you to automatically open the ESP-IDF project on VS Code, you can easily do it by following these instructions:

Go to File > Open Folder…

ESP-IDF ESP32 Open Project Folder VS Code File Menu

Browse on your computer for the esp-idf-project folder (your project folder name that you’ve previously defined) and “Select Folder“.

ESP-IDF ESP32 Open Project VS Code Select Folder

That’s it! Your new ESP-IDF project example has been successfully created and opened.

The scanner code is in the scan.c file. To open it, follow these instructions:

Open the project explorer by clicking the first icon on the left sidebar and select your project.
Expand the “main” folder.
Open the “scan.c” file.
Your main.c file should load

ESP-IDF ESP32 Wi-Fi Scanner Open scan.c file VS Code

Code – Get ESP32 MAC Address using ESP-IDF

To get your ESP32 board MAC Address, copy the the following code to your main.c file and upload it to your board.

/*  
  Rui Santos & Sara Santos - Random Nerd Tutorials
  https://RandomNerdTutorials.com/esp-idf-esp32-mac-address/
*/
#include <stdio.h>
#include "esp_mac.h"
#include "esp_log.h"

static const char *TAG = "MAC";

void app_main(void)
{
    uint8_t mac[6];
    esp_err_t ret;

    // Base MAC Address (factory default)
    ret = esp_read_mac(mac, ESP_MAC_EFUSE_FACTORY);
    if (ret == ESP_OK) {
        ESP_LOGI(TAG, "Base MAC Address (Factory): %02X:%02X:%02X:%02X:%02X:%02X",
                 mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
    }

    // Wi-Fi Station MAC Address
    ret = esp_read_mac(mac, ESP_MAC_WIFI_STA);
    if (ret == ESP_OK) {
        ESP_LOGI(TAG, "Wi-Fi STA MAC Address: %02X:%02X:%02X:%02X:%02X:%02X",
                 mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
    }

    // Wi-Fi SoftAP MAC Address
    ret = esp_read_mac(mac, ESP_MAC_WIFI_SOFTAP);
    if (ret == ESP_OK) {
        ESP_LOGI(TAG, "Wi-Fi SoftAP MAC Address: %02X:%02X:%02X:%02X:%02X:%02X",
                 mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
    }

    // Bluetooth MAC Address
    ret = esp_read_mac(mac, ESP_MAC_BT);
    if (ret == ESP_OK) {
        ESP_LOGI(TAG, "Bluetooth MAC Address: %02X:%02X:%02X:%02X:%02X:%02X",
                 mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
    }
}

View raw code

How the Code Works

In this section, we’ll take a look at the code to see how it works.

Libraries

We start by including the required libraries:

stdio.h – the standard C library will be used for the printf function that prints the debugging information in the serial monitor;
esp_mac.h – provides functions to read, set and manage the ESP32 MAC addresses;
esp_log.h – offers a framework to format log messages in the serial monitor for debugging.

#include <stdio.h>
#include "esp_mac.h"
#include "esp_log.h"

Logging Tag

The “MAC” prefix will be used to log all the debugging messages.

static const char *TAG = "MAC";

Base MAC Address

The esp_read_mac() function is used to read the different MAC addresses on the ESP32 chip. You can specify which MAC address you want to read by passing the appropriate constant as the second parameter. For example, to get the base MAC address:

ret = esp_read_mac(mac, ESP_MAC_EFUSE_FACTORY);
if (ret == ESP_OK) {
    ESP_LOGI(TAG, "Base MAC Address (Factory): %02X:%02X:%02X:%02X:%02X:%02X",
                mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
}

Wi-Fi Station MAC Address

If you pass the parameter ESP_MAC_WIFI_STA, you’ll get the ESP32 Wi-Fi Station MAC address.

ret = esp_read_mac(mac, ESP_MAC_WIFI_STA);
if (ret == ESP_OK) {
    ESP_LOGI(TAG, "Wi-Fi STA MAC Address: %02X:%02X:%02X:%02X:%02X:%02X",
                mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
}

Wi-Fi SoftAP MAC Address

These next lines read the ESP32’s Wi-Fi SoftAP MAC address.

ret = esp_read_mac(mac, ESP_MAC_WIFI_SOFTAP);
if (ret == ESP_OK) {
    ESP_LOGI(TAG, "Wi-Fi SoftAP MAC Address: %02X:%02X:%02X:%02X:%02X:%02X",
                mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
}

Bluetooth MAC Address

Finally, this code returns the ESP32’s Bluetooth MAC address.

ret = esp_read_mac(mac, ESP_MAC_BT);
if (ret == ESP_OK) {
    ESP_LOGI(TAG, "Bluetooth MAC Address: %02X:%02X:%02X:%02X:%02X:%02X",
                mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
}

Build and Flash Code to the ESP32 Board

To build and flash ESP-IDF code to the ESP32, you always need to follow this procedure. You need to select the flash method (UART), the COM port number, the target device (ESP32), build the code, and finally, flash it to the board. All these commands are available in the bottom menu bar of VS Code.

Make sure all your options are correct (they may already be properly configured if you used the project wizard).

However, if your setup is not correct, follow the next instructions to ensure everything is set up correctly. First, click the “Star” icon and select the flash method as UART.

VS Code ESP-IDF Select Flash UART Option to Program Flash ESP32

While the ESP32 board is connected to your computer, click the COM Port (plug icon) and select the correct port number that refers to your ESP32.

VS Code ESP-IDF Programming ESP32 Board Select Correct COM Port Number

You also need to select the target device. Click on the chip icon at the bottom bar. In my case, I have an ESP32 with the esp32s3 chip.

VS Code Select the ESP32 S3 or Correct Target Device ESP-IDF

For this board, I also need to select the configuration: ESP32-S chip (via builtin USB-JTAG).

VS Code ESP-IDF Select the ESP32 S3 chip via built in USB JTAG Target Device

Finally, your command bar on the bottom of VS Code should have similar options selected.

Now, you can build the project by clicking the wrench icon (Build Project) as shown in the image below.

VS Code Build Project Example Code ESP32 ESP-IDF

The first time you build a project, it usually takes a bit more time. Once completed, it should print a similar message in the Terminal menu and show a “Build Successfully” message.

VS Code Build Example Project ESP32 ESP-IDF Success Message

This is the final step. You can now flash the ESP-IDF project to the ESP32 by clicking the “Flash Device” button (thunder icon).

VS Code Flash Hello World Code Project to ESP32 ESP-IDF

Depending on your board, you might need to hold down the on-board BOOT button on your ESP32 to put into flashing mode. Once the process is completed, it will pop-up a info message saying “Flash Done“.

VS Code Flash Hello World Project to ESP32 ESP-IDF Done Success Message

Demonstration – Get ESP32 MAC Address

If you followed all the steps, the example to get the MAC address should be running successfully on your board. Open your Terminal window and click the “Monitor Device” tool that is illustrated with a screen icon.

VS Code Open Terminal Window Monitor Device ESP32 ESP-IDF

You can press the ESP32’s onboard RESET button to restart the device, and the Terminal will print all the MAC addresses line by line.

MAC: Base MAC Address (Factory): 68:B6:B3:22:9E:60
MAC: Wi-Fi STA MAC Address: 68:B6:B3:22:9E:60
MAC: Wi-Fi SoftAP MAC Address: 68:B6:B3:22:9E:61
MAC: Bluetooth MAC Address: 68:B6:B3:22:9E:62

ESP-IDF ESP32 Get Current MAC Address base factory default Wi-Fi station SoftAP Bluetooth

That’s it! Now, you know how to get your ESP32 MAC Address.

Code – Set a Custom ESP32 MAC Address using ESP-IDF

In some applications, it might be useful to give your boards a custom MAC Address. However, as explained previously, this doesn’t overwrite the MAC Address set by the manufacturer. So, every time you reset the board, or upload a new code, it will get back to its default MAC Address. The following code sets a custom MAC Address for the ESP32 board.

/*  
  Rui Santos & Sara Santos - Random Nerd Tutorials
  https://RandomNerdTutorials.com/esp-idf-esp32-mac-address/
*/
#include <stdio.h>
#include "esp_mac.h"
#include "esp_log.h"
#include "nvs_flash.h"

static const char *TAG = "CUSTOM_MAC";

// REPLACE THE NEXT VARIABLE WITH YOUR CUSTOM MAC ADDRESS
uint8_t custom_mac[6] = {0x32, 0xA1, 0xB2, 0xC3, 0xD4, 0xE5}; 

void app_main(void)
{  
    // Set custom MAC Address
    esp_err_t err = esp_base_mac_addr_set(custom_mac);
    if (err == ESP_OK) {
        ESP_LOGI(TAG, "Custom MAC address set successfully!");
    } else {
        ESP_LOGE(TAG, "Failed to set custom MAC address: %s", esp_err_to_name(err));
    }

    uint8_t read_mac[6];
    // Read new custom Wi-Fi STA MAC Address
    err = esp_read_mac(read_mac, ESP_MAC_WIFI_STA);
    if (err == ESP_OK) {
        ESP_LOGI(TAG, "[NEW] Wi-Fi STA MAC Address: %02X:%02X:%02X:%02X:%02X:%02X",
                 read_mac[0], read_mac[1], read_mac[2],
                 read_mac[3], read_mac[4], read_mac[5]);
    }
}

View raw code

How the Code Works

You can set a custom MAC Address in the following line:

uint8_t custom_mac[6] = {0x32, 0xA1, 0xB2, 0xC3, 0xD4, 0xE5};

Attention: the bit 0 of the first byte of MAC address can not be 1. For example, the MAC address can set to be “1a:XX:XX:XX:XX:XX”, but can not be “15:XX:XX:XX:XX:XX”.

The function esp_base_mac_addr_set() sets the new ESP32 custom MAC address. You must call this function first before any network interface initialization, otherwise the MAC address will not change.

esp_err_t err = esp_base_mac_addr_set(custom_mac);
if (err == ESP_OK) {
    ESP_LOGI(TAG, "Custom MAC address set successfully!");
} else {
    ESP_LOGE(TAG, "Failed to set custom MAC address: %s", esp_err_to_name(err));
}

These next lines read the current ESP32 MAC address to check if it was changed successfully.

uint8_t read_mac[6];
err = esp_read_mac(read_mac, ESP_MAC_WIFI_STA);
if (err == ESP_OK) {
    ESP_LOGI(TAG, "[NEW] Wi-Fi STA MAC Address: %02X:%02X:%02X:%02X:%02X:%02X",
                read_mac[0], read_mac[1], read_mac[2],
                read_mac[3], read_mac[4], read_mac[5]);
}

Demonstration – Set ESP32 MAC Address

After uploading the code, open the Terminal window and restart the ESP32. After a few seconds, it will print the new ESP32 MAC address as illustrated below.

CUSTOM_MAC: Custom MAC address set successfully!
CUSTOM_MAC: [NEW] Wi-Fi STA MAC Address: 32:A1:B2:C3:D4:E5

Wrapping Up

In this quick guide, we’ve shown you how to get your ESP32 manufacturer MAC Address with ESP-IDF. You’ve also learned how to set a custom MAC Address for your boards.

You might find helpful reading other ESP-IDF guides:

Meanwhile, you can check our ESP32 resources to learn more about the ESP32 board (with Arduino IDE):

Thanks for reading.