ESP8266 SDK Tutorials

Getting up to speed with the ESP8266 SDK has never been easier!

Similar projects worth following
This is a series of tutorials for learning the SDK used to develop C applications for the ESP8266. The SDK is available both directly from Espressif, and also a (mostly) open-source version. We'll look at both but focus on the open source one. All code example should work perfectly with both.

Links to the other tutorials in this series:

ESP8266 SDK Tutorial
(You are here!)
Learn how to use the ESP8266 SDK. This is what the pros use!
ESP8266 Lua/NodeMCU Tutorial
A look at the NodeMCU Lua interpreter for the ESP8266.
Learn how to get to Blinky!
ESP8266 Arduino TutorialUse the Arduino IDE to simplify development and get up to speed very quickly!

The ESP8266 has been popular for quite a while now. The low cost of getting a module coupled with its power and reliability has made sales of the chip shoot through the roof. There's a lot of resources out there, but I wanted to combine all that information together into one place. So let's get started!

The ESP8266 was designed by a Chinese fabless semiconductor company called Espressif. Fabless means they just create the chip design, and they get another company to actually manufacture the silicon (Atmel was also a fabless semiconductor company). While having Wi-fi on-chip with a microcontroller was not a new idea, the concept having a simple serial link to control it out of the box was. Hobbyists all over the world started playing with the chip to see what it could do. Without having to program the ESP, complex IoT applications could be developed, using the ESP simply as an external Wi-fi chip. This is the easiest method for those who don't have interest in diving into the ESP itself. You can use AT commands over a serial link to control the chip. This is the only way to control the ESP modules which only have 8 pins. A full list of the AT command set can be found here. This is a perfectly acceptable solution for many hackers, and if that's all you need then great! I built a data-logging module which used the Sparkfun phant server as the backend using only AT commands. Getting it connected to my Wi-fi network and sending data was very easy.  

However, many of you are here because you want to dive deep down into the power at the heart of the ESP8266. You want to program the module using Arduino or the SDK. You are interested in playing with Lua and discovering how it can be used in an embedded system like this. I generally recommend that people new to the ESP8266 buy a pre-fabricated module from a company like SparkFun or Adafruit

The Adafruit Feather HUZZAH with ESP8266

This takes a lot of the difficulty out of spinning your own board. But if you want to spin your own board using, say, an ESP-12F module, here are a few tips (skip to the tutorial section if you bought a HUZZAH Feather or a SparkFun Thing, or similar):

  • Decide which module you want to use. The modules were originally designed by a company called AI Thinker, but now have been widely cloned. Some of these have on-board 3.3V regulators, others don't. Take some time to find a reliable source, and take a close look at the requirements for the board. The cheaper boards tend to require more external components, while the more expensive ones have them built-in, so it's up to you to decide what is more important.
  • If you are designing your own breakout board, make the pads on your PCB nice and big. This makes soldering the castellated pads much easier to do by hand. Or, if you are using 0.1" headers, which some of the modules support, make sure to think about the outline of the board. How high will it be above the PCB? Do I need to move capacitors/other tall components out of the way?
  • There are breakout boards that you can get from the usual suspects for incredibly low prices. These are great for development and testing.
  • ESP GPIO pins 6-11 cannot be used, as they are reserved for talking to the flash chip. Be mindful of this, as trying to control those pins will probably just crash the chip! In some modules, pins 9 and 11 are available because the module uses a DIO flash chip, instead of QIO (double data rate instead of quad...
Read more »


Lubuntu VM for ESP8266 development. Has the SDK, Arduino, and Lua tools installed and ready to use.

x-bittorrent - 38.24 kB - 08/03/2018 at 18:51


  • 1
    Installing the SDK on Linux

    Our first look will be at getting a Blinky app running using the esp-open-sdk. This is the result of an incredible amount of work by a bunch of very dedicated people who are trying to make the ESP8266 toolchain as open-source as possible. This toolchain is designed to work with Linux and Mac. Windows users will have to use a Linux VM, but I've provided a pre-configured one. Linux and Mac users can also use the VM if they want. I'm a lazy hacker sometimes too, though I strongly recommend setting it up locally where possible. It will likely be less prone to problems.

    ESP-12F on a breakout board

    Linux Instructions

    I run Ubuntu Budgie 18.04 on my daily driver development laptop. (Say that three times fast!) In order for this toolchain to compile, it requires a few dependencies to be installed. In my case, I already had all but two, but just to make sure, you may as well run the entire list:

    $ sudo apt-get install make unrar-free autoconf automake libtool libtool-bin gcc g++ gperf flex bison texinfo gawk ncurses-dev libexpat-dev python-dev python python-serial sed git unzip bash help2man wget bzip2

    If you are running a version of Ubuntu older than 16.04, remove "libtool-bin" from that if you get a package not found error. The above command should work on any recent version of Debian or Ubuntu, or distros which use those repositories (Mint, etc). If you are unable to find a package, use your package manager's search function to try and find the correct package. Use keywords; for example, on Fedora, if I got an error that it couldn't find libexpat-dev, I might issue

    $ sudo dnf search libexpat

    Take a good look at the results. Usually the correct package to install is obvious. Now it's a good idea to create a directory for your toolchain. I was trained to always create a directory in my home directory called workspace, and to do all my development work in there. You can also keep project-specific SDKs in there, which is what we will do. My ESP8266 projects ended up in:

    $ mkdir -vp ~/workspace/ESP8266/projects

    And we will clone the project into ~/workspace/ESP8266. This keeps the code and the projects segregated from each other.

    Ready to clone!

    Alright. Now we are ready to clone the project and build! This is actually the easy part. Move into the directory we created (something like ~/workspace/ESP8266) Just clone the project with:

    $ git clone --recursive

    Note the --recursive flag! The project will not build successfully if you leave this out. This is because this project contains pointers to other projects, which need to be recursively cloned.

    If we were to build right now, everything would work just fine. However, the default settings will create many libraries which are unnecessary and when we build our code later on, it won't fit into the RAM on the ESP8266. So we must apply a patch to slim down the libraries that are created.

    Move into the directory we just cloned, esp-open-sdk. Then we can get the patch with this simple command:

    $ wget -O strip.patch
    $ patch < strip.patch

    You will see a message showing you that the patch was successful. If you get errors saying it cannot find the files to patch, make sure you are in the esp-open-sdk directory.

    Now building it is as easy as running make. Do not use a -j option!

    $ make

    If you have any errors, make sure to read the error log carefully. It will usually give hints as to what to do. Skip ahead to step 4 after you get a clean build.

  • 2
    Install SDK on Mac

    Mac Instructions

    For Mac, the process is a bit more complex. I have never used a Mac, so I am just copying the build instructions provided by the project. If there are errors in this, let me know and I will correct them immediately: 

    $ brew tap homebrew/cask
    $ brew install binutils coreutils automake wget gawk libtool help2man gperf gnu-sed --with-default-names grep
    $ export PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"

    Apparently Mac file systems aren't case-sensitive (which seems absolutely crazy to me!), so you need to create a virtual, case-sensitive file system. To do so, enter these commands (maybe use a name like "ESP-dev-volume" or something similar instead of "case-sensitive"): 

    $ sudo hdiutil create ~/Documents/case-sensitive.dmg -volname "case-sensitive" -size 10g -fs "Case-sensitive HFS+"
    $ sudo hdiutil mount ~/Documents/case-sensitive.dmg
    $ cd /Volumes/case-sensitive

    So now we are in our new volume. It's time to clone the Git repository and build it! 

    $ git clone --recursive

    Don't forget the recursive flag! That ensures that the sub-projects are also cloned. Move into the new directory that was created when cloning:

    $ cd esp-open-sdk

    We're going to patch the Makefile and add a couple other files to make the compiled code smaller later on. We can get the patch and apply it with these two commands:

    $ wget -O strip.patch
    $ patch < strip.patch

    Once the patch has applied successfully, we can now build the toolchain. This might take a while, depending on your hardware. On my 2015 laptop, it takes about 20 minutes. Do not use a -j option!

    $ make

     Once this process is complete, the toolchain is built! Skip ahead to step 4 to do the post-build steps.

  • 3
    Installing SDK on Windows/VM

    Windows/VM Instructions:

    Espressif recommend using a VM with Linux to do ESP8266 development on Windows. I highly recommend creating a virtual machine from scratch, and following along with the tutorial for Linux. This way, you will learn a lot more, and you will understand what to do if things go wrong. To make this even easier for you, I have created a VM image of Lubuntu 18.04 pre-installed with all the tools you will need to develop applications for the ESP8266. You could use this image on Linux or Mac as well if you wanted to keep your development environment self-contained. Start by downloading VirtualBox. Pick the platform package that matches the host system, i.e., if you are on Windows, pick the Windows Platform Package. Also, download the VirtualBox Extension Pack. Go through the setup process for VirtualBox. Once that is complete, double-click on the Extension Pack file. This will open VirtualBox if it isn't already open and prompt you to install the extension. Go ahead and install it. Now we are ready to download and import our development image.

    I've gone with Lubuntu, because it is lightweight and easy to use. It should run as a VM on just about any modern hardware. The image is available as a torrent, which you can download here. Please reseed after downloading! Once the file has downloaded, you can open VirtualBox, go to File->Import Applicance... and then locate the .ova file. A new virtual machine should appear in the list after this is done! You might want to tweak a few settings depending on how much RAM your system has. If you need help on this topic, there are many excellent tutorials out there on how to use VirtualBox.

    A few quick notes: the password for the user esp is hackaday. You'll need this when running commands prefixed with sudo. I have created shortcuts to the terminal and to emacs on the desktop. The VM already has the toolchain installed, with the patches and changes made that we outline in the next sections. In the Settings page for the VM, you need to pass your USB device through to the VM. You do this by going to the USB page, and clicking the green plus sign at the right. Choose the device you want the VM to use, and then click OK. Restart the VM, and the device will show up inside the VM! Note that while the VM is capturing that device, the host system can no longer see it. The VM contains a udev rule for the Feather HUZZAH, all you need to do is edit the serial number to match yours. Read the next section on udev rules if you want to create one for your device!

View all 7 instructions

Enjoy this project?



Similar Projects

Does this project spark your interest?

Become a member to follow this project and never miss any updates