This document walks through the steps to setup a development environment for ESP32 on MacOS. The steps follow closely the official ESP32 documentation with some clarifications in each steps.
- Install homebrew: Open a terminal and paste this line and hit Enter
/bin/bash -c "$(curl -fsSL https:/raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Homebrew is a package management for Mac and Linux which can help you install various software packages. You use Homebrew to install
ccache packages which ESP-IDF relies on. When installing homebrew, it will check if XCode Command Line Tools have been installed on your system. If not, it will download XCode Command Line Tools. The process might take a while and you might want to grab a cup of coffee.
- After homebrew has successfully installed, you install
brew install cmake ninja dfu-util ccache
- Make sure python3 is installed on your system by running
New versions of MacOS such as Big Sur or Monterey come with python3 preinstalled in the system. For previous versions of MacOS, you might need to install manually.
Download ESP-IDF from Github
First, create a directory to store ESP-IDF. We will create a new directory in the home folder by using
mkdir ~/esp cd ~/esp
To download ESP-IDF from Github, open a Terminal and type in
git clone -b v4.3.2 --recursive https://github.com/espressif/esp-idf.git
It takes a while to download esp-idf repository.
Setup ESP-IDF tools
After downloading ESP-IDF repository from Github, you need to run a script
install.sh inside the folder esp_idf. The scripts will install a number of tools that are necessary such as compiler, debugger, python packages for creating a virtual terminal environment, etc.
First, go to the clone esp_idf folder
Then run the
install.sh script and pass in
esp32 as argument. This will install tools for working with ESP32 in the default folder
By looking at the output on the terminal, we can see that the script install a couple of esp32 tools, for example
Installing tools: xtensa-esp32-elf, esp32ulp-elf, openocd-esp32
The script also install python environment and packages
Installing Python environment and packages Creating a new Python environment in /Users/epro/.espressif/python_env/idf4.3_py3.8_env Installing virtualenv
And the last message printed on the terminal is
All done! You can now run: . ./export.sh
This message reminds you the final step which is setup environment variables, because the installed tools have not been added to PATH yet. The script
export.sh does that.
We will create an alias for running
export.sh from terminal. For newer MacOS, the default shell is zsh. Therefore, we need to add a line in
~/.zprofile. If you are using VSCode and have added
code in the PATH, you can type
Then paste this line to that file and save it.
alias get_idf='. $HOME/esp/esp-idf/export.sh'
Then run this command to reload
Now if you run
get_idf from Terminal, you will see output like this
Setting IDF_PATH to '/Users/epro/esp/esp-idf' Detecting the Python interpreter Checking "python" ... Checking "python3" ... Python 3.8.9 "python3" has been detected Adding ESP-IDF tools to PATH...
Whenever you want to run esp32 commands, for example
idf.py build, remember to run
get_idf first to activate virtual environment. If you don’t, you will get error such as
command not found: idf.py.
Test the setup
Now all the necessary tools have been downloaded and configured, it’s time to test the setup. We will use an existing sample project
blinky in esp_idf and make sure that we can configure, compile, and flash the firmware onto a target ESP32 chip. To continue with this step, you will need an ESP32 development board. Here, we will use ESP-WROVER-KIT, however, any ESP32 development board is fine.
Connect hardware and determine serial port
First, make sure the following jumpers are set to correct position on the ESP-WROVER-KIT board:
- Select USB as power source (USB_5V) in Jumper JP7
- Enable UART communication using jumper JP2 (connect RXD and TXD0, TXD and RXD0). These jumpers connect the UART interface of ESP32 with the channel B of serial chip FT2232HL. This is necessary to upload code to ESP32.
Then connect your ESP-WROVER-KIT to Mac, make sure the power switch is turned to ON position. Open a terminal and type
You will see that the terminal display two channels of FT2232HL chip that presents on the board, for example
/dev/tty.usbserial-FD3400 (Channel A) /dev/tty.usbserial-FD3401 (Channel B)
Note the channel B port as we will need to use it in the next step when flashing program to ESP32.
Create a new project from sample projects
Now go to
~/esp/esp_idf/examples/get-started/ folder and create a duplicate of
blinky project and name it
blink_copy. Then move it to ~/esp Then open a terminal and go to
Next, configure the target for the project by running
get_idf idf.py set-target esp32
Remember that we need to run
get_idf once to set environment variables for esp_idf as described in previous steps.
Modify project configuration
To modify project configuration, we run
In this example, we want to modify the pin that toggle the Blue LED on the ESP-WROVER-KIT board which is GPIO4. Select
Example Configuration ---> in the Menu and set
4 for the option
Blink GPIO number. Then press
S to Save the configuration and
ESC to exit menu config.
To build the project, run
This command will start the build process and generate binary image for uploading to the ESP32.
Flashing the firmware
To flash the firmware to ESP32, you use this command
idf.py -p /dev/tty.usbserial-FD3401 flash
Note that we specify the port
/dev/tty.usbserial-FD3401 as the argument for
-p option. If everything is running correctly, you will see the Blue LED flash on and off every second.
To see log messages that are flushed through serial port, you use monitor utility. Run
idf.py -p /dev/tty.usbserial-FD3401 monitor
You should see log messages printed on terminal, like so
I (307) cpu_start: Starting scheduler on PRO CPU. I (0) cpu_start: Starting scheduler on APP CPU. I (318) gpio: GPIO| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 Turning off the LED Turning on the LED Turning off the LED Turning on the LED Turning off the LED Turning on the LED Turning off the LED
This is useful when you are developing applications and want to know where is the current progress of the code execution. To exit the monitor, press
Ctrl + ].
Phew! That was quite a bit of setting up. If you have followed along, congratulation on completing the first step to ESP32 development with ESP-IDF. This first step is essential to continue with learning to program ESP32.