Getting started with the ESP32 on OSX

A few days ago, I received from AliExpress the amazing ESP32 chip. This microcontroller is a low-cost (i bough it for just $5 USD on a ready-to-use development kit, you can find the URL of the product at the end of the article), low-powered IoT solution with amazing specs:

  • Built-in WiFi support
  • Built-in Bluetooth and BLE support
  • Xtensa® single-/dual-core 32-bit LX6 microprocessor
  • 520KB SRAM!
  • A lot of peripherals interfaces (34xGPIO, 4xSPI, 2xI2C, 3xUART, 2xI2S, etc.)
  • Cryptographic hardware acceleration (AES, SHA-2, etc.)

With those specs, for that price, the ESP32 has no competition overall. So, for all your IoT projects, the ESP32 seems like a really solid product to use.

On this post, I'm going to show how to use the ESP32 on an OSX based computer using all the official tools and docs. To follow this tutorial you are going to need:

  • An ESP32 DevKitC compatible board
  • A USB to micro USB cable
  • An OSX computer
  • (Optional) A LED with a 320[Ohm] resistance

Getting the ESP32 DevKit

The ESP32 is a very affordable microcontroller and as today you can find a lot of kits available on Chinese stores. I got mine from a store on the AliExpress website:

ESP32 DevKit from AliExpress

The kit arrived in just 1-2 weeks without any problems. It has a lot of pins to test and the micro USB interface to program the micro works seamlessly.

Installing the toolchain to program the ESP32

To start programming our ESP32, we need to install the toolchain on our operating system. You can find the official documentation HERE, but you can follow the steps below to get the same results.

Getting pip

The toolchain of the ESP32 has some python dependencies. To install those dependencies, you can use pip. If you don't have pip on your system, you can install it with the next command:

Getting the toolchain

Now we are ready to download the toolchain:

The above steps will download the toolchain and decompress it on the esp folder on your home directory. You will have a folder called xtensa-esp32-elf inside the ~/esp/ folder with the toolchain. To be able to use the toolchain on your command line, you will need to add the toolchain folder to your $PATH variable. So, add the next line to your ~/.profile file (I'm using zsh so I added the line below to my ~/.zshrc):

Now, reload your terminal and type:

You should see something like:

which indicates the toolchain has been installed correctly. Now, let's get the libraries to work with the ESP32.

Getting API libraries

To be able to program the ESP32, you will need the libraries to interact with the interfaces and functionalities of the chip. To this, we use the ESP-IDF or Espressif IoT Development Framework. The installation follows as (you will need the "git" command before executing the next lines):

This will install the IDF on the folder ~/esp/esp-idf, you also need to create a variable on your environment called IDF_PATH (on your ~/.profile file):

Now restart your terminal and check your IDF_PATH variable:

Installing Python requirements

Remember the pip command we installed at the beginning of the tutorial? Now is time to use it!

The above command should install all python requirements to make the toolchain and IDF to work.

Connecting the ESP32 to our computer

To be able to program the ESP32, we need to connect the chip to our computer and the computer needs to recognize the chip as a serial port. For this, you need to install the corresponding drivers on your mac. In short, we need an USB to UART driver. You can get the corresponding driver from the next site:

Or more directly, the driver for OSX, from here:

Install the driver and restart your computer. Now, if you connect your ESP32 kit to your computer (using the USB interface), your computer should recognize the chip:

and you should see something like:

Now, we are good to go!

Testing our installation

Finally, we reached the end of the installation process. Now, to test it, we are going to create a simple "hello world" program. Luckily for us, the toolchain provide us a set of examples to test our chip, including a "hello world". So, copy the hello world example to your ~/esp folder (you can choose whatever folder you want, but to keep things organized is better to use your base esp folder):

Now, we need to configure the project (to tell the toolchain which serial port use when programming the ESP32):

You should see something like this:

Select the "Serial flasher config" option and be sure the correct serial port is selected:

Then, press <Exit> and <Exit> again. Now, compile and flash the project:

You should see something like:

Congratulations! you have flashed your first program to your ESP32. The ESP32 toolchain has a nice tool to monitor what's going on in the chip (really useful to debug your programs):

and the output of our program:

In the end, you can see the "Hello world!" message and the countdown to restart the chip. That is what our "hello world" program does:

It just print "Hello word!" followed by some system information and then the countdown. Finally, it does a system restart using the "esp_restart()" function.


With the simple steps described above, you can start programming the ESP32 using your OSX based computer. The ESP32 give us a lot of posibilities to experiment with IoT in a very cost-effective way. In the next posts, I will be exploring some of the API's the IDF gives us to create more useful programs. Stay tuned!

Diego Acuña

Diego Acuña

I'm a Software Engineering and Web Developer from Chile. My main interests are web technologies, software development methodologies and data mining (mainly on financial area). If you want to get in touch with me, use the contact page from the top menu.