ESP8266 Building Hello World Blink LED and Simple Web Server to drive the Relay and check Button status


ESP8266-EVB is small 57×50 mm board with Relay and Button which are connected to Internet via ESP8266 WIFI module.

ESP8266 has inside Xtensa106 processor and RF front end circuit, you do not need separate processor to drive the relay and read the button as ESP8266 can be programmed with custom code.

Here we will explain how to setup your tools and make your first project.

First you need to install your tools. It’s simple, just follow the instructions here:

There are just few small mistakes as some commands will require SUDO before them and some paths are not exactly same, but you have to follow the steps and once you get error to read and correct the problem.

Here is what we do on Ubuntu 14.04 LTE 64-bit:

sudo apt-get install git autoconf build-essential gperf bison flex texinfo libtool libncurses5-dev wget gawk libc6-dev-amd64 python-serial libexpat-dev
sudo mkdir /opt/Espressif
sudo chown $username /opt/Espressif/
sudo cd /opt/Espressif
sudo git clone -b lx106 git:// 
cd crosstool-NG
./bootstrap && ./configure --prefix=`pwd` && make && make install
./ct-ng xtensa-lx106-elf
./ct-ng build
cd /opt/Espressif
mkdir ESP8266_SDK
wget -O
wget -O
mv esp_iot_sdk_v0.9.3 ESP8266_SDK
mv License ESP8266_SDK/esp_iot_sdk_v0.9.3
cd /opt/Espressif/ESP8266_SDK/esp_iot_sdk_v0.9.3
sed -i -e 's/xt-ar/xtensa-lx106-elf-ar/' -e 's/xt-xcc/xtensa-lx106-elf-gcc/' -e 's/xt-objcopy/xtensa-lx106-elf-objcopy/' Makefile
mv examples/IoT_Demo .
cd /opt/Espressif/ESP8266_SDK/esp_iot_sdk_v0.9.3
wget -O lib/libc.a
wget -O lib/libhal.a
wget -O include.tgz
tar -xvzf include.tgz
cd /opt/Espressif
wget -O esptool_0.0.2-1_i386.deb
dpkg -i esptool_0.0.2-1_i386.deb
cd /opt/Espressif
git clone esptool-py
ln -s $PWD/esptool-py/ crosstool-NG/builds/xtensa-lx106-elf/bin/

For less experienced users, we are preparing VirtualBox disk image which to run on Virtual machine on any OS like Linux, MAC OS, Windows, and everything inside is pre-configured and ready to use, hopefully we will upload this image on ESP8266-EVB web page tomorrow as we didn’t manage to complete it today.

Once you have setup the Tools you can download our examples from GitHub:

cd /opt/Espressif
git clone
cd ESP8266-EVB-blinkLED

the project will be compiled and you will see something like this:

AR build/app_app.a
LD build/app.out
FW firmware/0x00000.bin
FW firmware/0x40000.bin

congratulations you made your first code!

now we hae to load it to ESP8266-EVB

you need: ESP8266-EVB, 5V adapter like SY0605E, USB-Serial-Cable-F
connect the USB-SERIAL-CABLE-F to ESP8266-EVB UEXT connector as follows:

  • blue wire to pin#2
  • green wire to pin#3
  • red wire to pin#4

plug the USB cable to your computer USB connector and check which serial port it connects by typing:


your computer should display something like:

Bus 004 Device 005: ID 067b:2303 Prolific Technology, Inc. PL2303 Serial Port

if you type:

ls /dev/tty*

you will see:

.... /dev/ttyUSB0 ....

If the USB device is with different name you have to update it in the makefile.

After the code is compiled with no errors you can write it to ESP8266 by following these steps:

  1.  first you have to press button and hold it and to apply power 5V, ESP8266 will enter bootloader mode
  2. type ‘sudo make flash’ and wait until code is loaded:
sudo make flash
/opt/Espressif/esptool-py/ --port /dev/ttyUSB0 write_flash 0x00000 firmware/0x00000.bin 0x40000 firmware/0x40000.bin
Erasing flash...
Writing at 0x00007300... (100 %)
Erasing flash...
Writing at 0x00061200... (100 %)

now Green LED must start blinking!

So far so good, you just made blinking LED on ESP8266, now let’s make something more complicated – to run Embedded web server on ESP8266, go to esphttpd project directory:

cd /opt/Espressif/ESP8266/esphttpd

then upload the code

sudo make flash

then upload web pages with:

sudo make htmlflash

Now ESP8266 firmware is uploaded and ESP8266 create Embedded server.

Scan for WIFI which name starts with ESP_XXXXXXX where XXXXXX is the ESP8266 MAC address and connect to this network then open browser at you will see this home page:


if you click on Relay button in the right side you will see new page:


On this page you can switch the on-board relay by clicking on ON and OFF button

If you click on the Button button in the right side you will see new page:


If you click on Start scan the web page will start to refresh each second and display the button status if you click on Stop scan the page will not refresh.

This is very basic demo code which can be used as template for your own projects!

33 Comments (+add yours?)

  1. Walter Schreppers
    Jan 30, 2015 @ 04:33:25

    missing heatshrink_decoder.c implementation in the git repo. Won’t build…
    sink, poll, finish etc are missing and give linking errors…


  2. LinAdmin
    Jan 30, 2015 @ 12:33:51

    From the technical viewpoint it is a really fascinating gadget.

    But for my everyday life I still have to find an application. And imho it is somehow disturbing that the dumb power supply costs almost as much as the hightec part.


  3. zoobab
    Jan 31, 2015 @ 13:56:51

    Dockerfile? There are several already:

    You can also mount the /dev/ttyUSB0 inside the container so that can reflash the device.

    Someone made also a PPA for the toolchain, that might speedup the process a bit:


  4. Andras
    Feb 01, 2015 @ 12:48:10

    Linux? Upps… I was thinking. But I have luck, since i have here 2 raspberry pi boards. Some notes about the process for setting up the toolchain:
    – since there is no board, i was able to complete the installation till compiling the example project
    – i did not installed the toolchain in opt, but in home/pi. So at some points the sudo is not required. While there was one point where it was necessary to create the link.
    – the esptool packet is for i386 and not for raspy. But the original source code can be build very easy
    – Installing the compiler took nearly half a day on the pi. After 3 hours i just left the PI alone for the night to work.

    Conclusion, the toolchain can be installed for raspi.
    Next step is to check if i can load the sw into the board with a raspi.


  5. Wim Roose
    Feb 02, 2015 @ 16:14:04

    To use it as a client (connecting to WiFi), git clone the original esphttpd example, uncomment os_timer_arm(&reassTimer, 1000, 0); in cgiwifi.c. If esp still in SoftAP mode just hold pushbutton for 6-7 seconds, then you’ll be able to scan wifi networks & connect to one (herefore I had to uncomment os_timer_arm)




  6. Aldo
    Feb 05, 2015 @ 00:26:36

    Sorry but what about the VM you promised on Jan 29? I can’t find it on olimex webpage… nor in the wiki. Where can I find it?


  7. mipl
    Feb 05, 2015 @ 01:06:38

    Would like to know, what is the progress with RT5350F board. Olimex anouced somewhere in the autumn last year and since then silience. Would this board be with base board, smiliar to the esp8266 base board, in the first description it was mentioned so.


  8. carlos
    Feb 09, 2015 @ 19:10:36

    Is it possible to debug esp8266 using jtag? and What Jtag tool from olimex can be used to debug jtag esp8266?



  9. juke
    Feb 10, 2015 @ 14:51:14

    need same thing with a dimmer


  10. Trackback: .NET i jiné ... : Odkazy z prohlížeče – 13.2.2015
  11. yoannq
    Feb 15, 2015 @ 22:33:03

    very nice tuto , just 2 comments :
    – you can add that you need to be root (sudo) to install package using dkpg
    – i need to add write permission to crosstool-NG/ directory to create the link


  12. yoannq
    Feb 15, 2015 @ 22:36:11

    Reblogged this on Yoann's Blog and commented:
    Very nice tuto provided by olimex , can be use in parallel with the folowing one


  13. Manos
    Feb 17, 2015 @ 12:28:29

    Hi Olimex and thank you for the good work!

    I have successfully uploaded the ” blinking LED” example and now I’m trying to upload to the “Embedded web server” example but I’m facing the following problem:

    STEP 1
    $ make
    CC user/button.c
    CC user/cgii2c.c
    CC user/espfs.c
    CC user/heatshrink_decoder.c
    CC user/httpd.c
    CC user/httpdespfs.c
    CC user/io.c
    CC user/relay.c
    CC user/stdout.c
    CC user/user_main.c
    AR build/httpd_app.a
    LD build/httpd.out
    FW firmware/0x00000.bin
    FW firmware/0x40000.bin

    STEP 2
    Action: Entering ESP to bootloader mode

    STEP 3
    $ sudo make flash
    FW firmware/0x00000.bin
    /opt/Espressif/esptool-py/ –port /dev/ttyUSB0 write_flash 0x00000 firmware/0x00000.bin 0x40000 firmware/0x40000.bin
    Erasing flash…
    Writing at 0x00008000… (100 %)
    Erasing flash…
    Writing at 0x00063000… (100 %)


    STEP 4
    $ sudo make htmlflash
    if [ $(stat -c ‘%s’ webpages.espfs) -gt $(( 0x2E000 )) ]; then echo “webpages.espfs too big!”; false; fi
    /opt/Espressif/esptool-py/ –port /dev/ttyUSB0 write_flash 0x12000 webpages.espfs
    Traceback (most recent call last):
    File “/opt/Espressif/esptool-py/”, line 471, in
    File “/opt/Espressif/esptool-py/”, line 149, in connect
    raise Exception(‘Failed to connect’)
    Exception: Failed to connect
    make: [htmlflash] Error 1 (ignored)

    Although, I can connect to the new ESP_xxxx network as you can see below:

    $ ifconfig -a wlan0 | grep inet
    inet addr: Bcast: Mask:

    $ arp -a
    ? ( at 1a:fe:34:9c:62:8d [ether] on wlan0

    Obviously, I cannot get the page.

    $ wget
    –2015-02-17 11:18:07–
    Connecting to… connected.
    HTTP request sent, awaiting response… 302 Found
    Location: /index.html [following]
    –2015-02-17 11:18:07–
    Connecting to… connected.
    HTTP request sent, awaiting response… 404 Not Found
    2015-02-17 11:18:07 ERROR 404: Not Found.

    So, could you figure out what is going wrong on STEP 4? Also note that if the board enters to boot mode before issuing the STEP 4 command then the http server is not running at all.

    Thank you,


  14. Manos
    Feb 17, 2015 @ 13:46:10

    Let me add some more information about the issue I described at my previous post.

    By following the instructions listed into the file:

    make flash
    To upload demo webpages go again into bootloader mode and run:

    make htmlflash

    I’m getting the following behavior:

    STEP 2
    Action: Entering ESP to bootloader mode

    STEP 3
    $ sudo make flash
    /opt/Espressif/esptool-py/ –port /dev/ttyUSB0 write_flash 0x00000 firmware/0x00000.bin 0x40000 firmware/0x40000.bin
    Erasing flash…
    Writing at 0x00008000… (100 %)
    Erasing flash…
    Writing at 0x00063000… (100 %)


    STEP 4
    Action: Re-entering ESP to bootloader mode

    STEP 5
    $ sudo make htmlflash
    if [ $(stat -c ‘%s’ webpages.espfs) -gt $(( 0x2E000 )) ]; then echo “webpages.espfs too big!”; false; fi
    /opt/Espressif/esptool-py/ –port /dev/ttyUSB0 write_flash 0x12000 webpages.espfs
    Erasing flash…


    At this point seems that the the html code is not uploaded to the ESP board (since no writing message is appeared). Do I miss something?


  15. gbraultGilbert Brault
    Feb 20, 2015 @ 02:16:46


    • gbrault
      Feb 20, 2015 @ 20:41:05

      I did it today and it works… Got some difficulties:
      1- needed to compile esptoll for amd64 (I have a debian 64)
      2- changed some path in the make file…
      3- pyserial to be installed
      4- not quite undertsood how to use the bootloader button yet: after unpluging the powersupply (of the ESP8266) and holding the bootloader button down while plugging the power, and after sudo make flash it worked. I hold down the button till the thing got finished.
      The green led is blinking….

      Any possibility to use gdb server to step through the code?


  16. gbrault
    Feb 20, 2015 @ 22:20:26

    small issue to solve with esphttpd: needs to update git submodule
    enter esphttpd directory then
    git submodule init
    git submodule update


  17. gbrault
    Feb 21, 2015 @ 12:12:09

    For the esphttpd code, best is to use (with pfalcon toolchain & SDK)
    follow direction there
    after changing the paths in the Makefile
    – make
    then make mkespfsimage/mkespfsimage (to build the ‘zip’ tool)
    – make webpages.espfs to build the htmlflash image

    It works great!!!

    Thanks a lot olimex guys!

    Very funny to have this so small die make so big screens…


    • Remi
      Mar 03, 2015 @ 05:12:02

      When I tried the code you listed I get: “Please put the ESP in bootloader mode…

      I know it is in bootloader mode as I can upload other programs. Despite trying various power on combinations after about 3s the upload script just ends.

      sudo make flash
      Info: esptool v0.0.2 – (c) 2014 Ch. Klippel
      Info: This program is licensed under the GPL v2
      Info: See the file LICENSE for details

      Please put the ESP in bootloader mode…
      Info: esptool v0.0.2 – (c) 2014 Ch. Klippel
      Info: This program is licensed under the GPL v2
      Info: See the file LICENSE for details


  18. Ale
    Mar 10, 2015 @ 00:25:08

    Hi, when i try to build the second one sample, the “web server”, on the “make” an error shows up : heatshrink_decoder.h: No such file or directory

    So, i solved it with the following string, on terminal digit :

    git submodule update –init

    Then, play “make” and all should work 🙂


  19. Peter Retief
    Mar 12, 2015 @ 20:50:36

    Everything worked as you described except the LED flashed once then stopped? I guess it must have something to do with the timer but have no idea how to debug it, Any ideas or help


  20. peterretief
    Mar 12, 2015 @ 22:31:47

    Reblogged this on My Blog and commented:
    Works really well, wish I had found this first


  21. Bart Bories
    Apr 06, 2015 @ 21:30:20

    Can you use this board to plug in another MOD-WIFI-ESP8266-DEV module to program it?

    It’s related to my post on the forum:


  22. sven
    Apr 26, 2015 @ 18:55:06

    Please rebuild at first your webside under Ubuntu and Firefox only the half side of the pages can be seen.


  23. Roberto Faría Aguilar
    Jul 12, 2015 @ 13:10:13

    Hi where can I download the image of Vbox.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: