Skip to content

Getting started with the ESP8266

I’ve always loved to play with Arduino’s, but also thought it was underequiped. There must be at least something that connects it to a network and should have at least a radio on board. Because of that I got really excited about Jeenodes, which had a RF12B radio on board (really good for low-energy, battery operated stuff), and was a couple of factors smaller than an Arduino at the same time.

But that was back-then. Theres a new kid on the block that offers a very nice set of features, and doesn’t only just have a blip-radio built-in, but has a complete 802.1b/g/n Wifi stack, including a radio and antenna on board. Initially it was released as a component that could be used as a shield for an arduino, in which the arduino would provide computing and the esp8266 would provide wifi networking. The thing about the esp8266 is that it actually has a very powerful 32-bit CPU on board that can double as application processor. Unfortunately, when it was just release, it didn’t come with an SDK and it wasn’t possible to load your own firmware into the chip.

This has changed though, an SDK has been release and chip can now be reprogrammed. This is excellent, because it wouldn’t need an Arduino anymore and can run completely autonomously. Which is not a bad idea in the first place,  as the esp8266’s 32-bit MCU, has a lot of horsepower compared to your average Atmega.

Oh, and it’s tiny! It so tiny, I’d consider it cute! (check the size compared to a dollar coin in the picture on the right)

Now the thing is, this little board doesn’t have a USB port built in, and requires certain pins to be shorted to be programmed and doesn’t nicely fit in a breadboard. However, it does fit in one of these great development boards that you can find all over the internet. I bought mine from banggood for less than 9 euros, together with 3 esp8266 boards for 3 euros each to play with.

Development board esp8266

Getting it hooked up

The first thing I wanted to do was to hook it to my computer, to see if I could connect to it. It is supposed to be easy, because out of the box they speak some sort of AT language (just like modems in the days) if you connect through a serial connection. This means that you could just fire up a serial terminal and start speaking AT-commands to it. E.g. the board should respond to an AT command without any parameters with OK.

The tough part about the development board is that it came with absolutely no description or schematics, and it seems very hard to find on the internet as well. Fortunately one of my colleagues had some knowledge about this and told me how the dip switches should be set to get the esp8266 online (if you want to know, it’s set in the picture above). After setting the dip-switches, is was a matter of switching the devevelopment board on (black lever on the bottom-right) and it should start getting online.

The development board has a ch340g USB-to-serial chip. My PC automatically recognized it, but it may be because I’ve been playing with arduino’s and ftdi chips for quite sometime already and have installed some drivers in the process. So, it may need a certain driver to be installed, which may or may not come with Windows, all of this was thanks to Laptopsgeek that has so much information regarding tech, laptops and computers in general.

One my computer connected to the board, an additional serial port was installed (COM10), which I could connect to with putty. The baud rate to be use is 9600 baud. I read somewhere on the internet that it should be higher, but 9600 is really the default speed.

Install firmware toolchain

Once there’s a link between the computer and the esp8266, it should also be possible to write new firmware to it. This requires a specifc toolchain though.

Because I didn’t want to install this toolchain on my PC (which I try to keep relatively clean), I have setup a virtual machine for it using Virtualbox. The nice thing about Virtualbox is that is allows you to redirect USB equipment that’s connected to the host PC to the virtual machine. My virtual machine is a 64-bit installation of Ubuntu 14.04 (server) after a bare install, I followed the steps below to get the toolchain installed:

This process takes a while btw. Some steps take almost an hour to complete.

Build the first “sketch”

The first sketch everyone should start with, is to get one of the GPIOs to alternate between high and low. On my development board, this means that one of the leds would start to blink. Exactly this, is what one of the examples sketches does. Pulling it from github and compiling it is simple:

Two files were built: firmware/0x00000.bin and firmware/0x40000.bin.


Before you can upload anything, you need to have access to the serial port to do so. The serial port device (/dev/ttyUSB0) has the group of dialout. All you need to do grant yourself access to the serial port is to add yourself to the dialout group:

After getting access to the serial port, the sketch that has just been built can be uploaded to the esp8266 chip. To get the board in “upload mode”, the board should be booted while GPIO0 is grounded. On the development board this can be very easily achieved by keeping the GPIO0 pushbutton (top-leftmost button in picture above) pressed, while pressing the reset-button (bottom-left-most button the picture above). Shortly after the reset-button has been released, the GPIO0 button can also be released again. The sketch can then be uploaded using:

After the upload had completed, it started toggling GPIO2 and the led connected to GPIO2 started to blink:

After successfully loading my first sketch, I am now ready to take over the world 🙂

Schematics of the development board here

Published inTechnoblog


  1. JLA JLA

    Hi Jan,

    Many thanks, but I got problem with the step make :

    cd /opt/Espressif
    git clone
    cd source-code-examples/blinky

    I got this error with the “make” command :
    [email protected]:/opt/Espressif/source-code-examples/blinky$ make
    CC user/user_main.c
    In file included from user/user_main.c:2:0:
    /opt/Espressif/ESP8266_SDK/include/osapi.h:8:20: fatal error: string.h: No such file or directory
    compilation terminated.
    make: *** [build/user/user_main.o] Erreur 1

    Can you help me ?
    Thanks in advance.

    Jean Louis (from France)

    • Hi Jean Louis,

      Can you check if your ran through the part “Installing Xtensa libraries and headers”. That would install the strings.h file as well.
      Good luck!


  2. Kevin Route Kevin Route

    I was glad to find this page and followed it to also “start with ESP”(-12 in my case). I succeeded, just one caveat:
    # Installing Xtensa libraries and headers
    doesn’t it, I had to fallback to esp8266-wiki/wiki/Toolchain page and do the missing stuff.

    One question, do you have some documentation/description of your development board ?; it’s seems kind of generic (i.e. not just for ESP-…) and might be useful for all kind of micro-controller related experimenting/prototyping.

    Best regards.

    • Hi Kevin,

      Too bad that it didn’t work for you. Just to be sure I’ve replayed the entire thing on a fresh virtual machine. I did make a few changes, I seemed to have missed a couple of sudo statement. Other than that, it worked perfectly fine for me.

      Anyhow, I do have a little bit of documentation on the developmentboard and it’s indeed for more board than only my version of the ESP8266. In fact, because the ESP-01 only has GPIO0 and GPIO4 exposed, you won’t be able to use many of the features of the board. You’ll need e.g. a GPIO14 to get the relay to switch. Besides the ESP8266, you’ll be able to plug an NRF24L01 into it as well. It’s quite a nice board. Happy with it 🙂

      If you’re interested, you can have a look at the schematics that I happened to find on I’ve added it to bottom of the blog.


  3. gowtham gowtham

    sir i have a problem could u help me as soon possible
    problem :
    the architecture of ESP8266 and its SDK. Write a program to blink an LED using the inbuilt GPIO’s. Also make a repeater out of it using Arduino Platform

    • I would love to help Gowtham, but your question is not really clear to me. Please do not that my experiments were about autonomous ESP8266 modules and custom firmware, and not working in conjunction with an Arduino board.

  4. Vijayalakshmi Vijayalakshmi

    I have spent about 10 days googleing but have found no result.

    here is the thing:
    [INFO ] Extracting and patching toolchain components
    [ERROR] The ‘mpc-1.0.2’ sources were partially extracted.
    [ERROR] Please remove first:
    [ERROR] – the source dir for ‘mpc-1.0.2’, in ‘/home/esp8266/esp-open-sdk/crosstool-NG/.build/src’
    [ERROR] – the file ‘/home/esp8266/esp-open-sdk/crosstool-NG/.build/src/.mpc-1.0.2.extracting’
    [ERROR] I’ll stop now to avoid any carnage…
    [ERROR] >>
    [ERROR] >> Build failed in step ‘Extracting and patching toolchain components’
    [ERROR] >> called in step ‘(top-level)’
    [ERROR] >>
    [ERROR] >> Error happened in: CT_Abort[scripts/[email protected]]
    [ERROR] >> called from: CT_Extract[scripts/[email protected]]
    [ERROR] >> called from: do_mpc_extract[scripts/build/companion_libs/[email protected]]
    [ERROR] >> called from: do_companion_libs_extract[scripts/build/[email protected]]
    [ERROR] >> called from: main[scripts/[email protected]]
    [ERROR] >>
    [ERROR] >> For more info on this error, look at the file: ‘build.log’
    [ERROR] >> There is a list of known issues, some with workarounds, in:
    [ERROR] >> ‘share/doc/crosstool-ng/ct-ng.1.20.0/B – Known issues.txt’
    [ERROR] (elapsed: 0:01.70)
    [00:02] / make[2]: *** [build] Error 1
    make[2]: Leaving directory /home/esp8266/esp-open-sdk/crosstool-NG'
    make[1]: *** [_toolchain] Error 2
    make[1]: Leaving directory
    make: *** [/home/esp8266/esp-open-sdk/xtensa-lx106-elf/bin/xtensa-lx106-elf-gcc] Error 2

    • It sounds like you have received/downloaded corrupt files. I think it would be best to remove the directories created during that step, redownload and try again…

  5. Shahriar Shahriar

    Hello ,
    i tried many ways to work with esp8266 and only way i could from LuaLoader , i want to run some IoT project with it , but the big problem is with arduino 1.6 for any kind of upload got some error after googling alot and checked many ways finally find your site ,. and want to try your way . im runing windows 7 and already downloaded and installed Python 2.7 and pySerial , and tried
    cd /opt/Espressif
    then press enter key and got this error
    Traceback :
    file “”, line 1, in
    NameError: name ‘cd’ is not define

    can you tell me where i have to enter code . also where i have to run
    #Install needed dependencies

    on python but got this error

    • Hi Shahriar, The instructions above are for Linux, not for Windows. I’m currently running Linux in a VirtualBox session on Windows sometimes, which may have confused you.
      Sorry about that.

      • Shahriar Shahriar

        Hi , i got it downloaded virtualbox and started already , tnx for your reply and your wonderful website

  6. hamad hamad

    very nice toutrial i really get well with it
    but i can not run make for blinky it give me errors
    LD build/app.out
    /opt/Espressif/ESP8266_SDK/lib/libmain.a(app_main.o): In function user_uart_wait_tx_fifo_empty':
    (.irom0.text+0x340): undefined reference to
    /opt/Espressif/ESP8266_SDK/lib/libmain.a(app_main.o): In function user_uart_wait_tx_fifo_empty':
    (.irom0.text+0x458): undefined reference to
    collect2: error: ld returned 1 exit status
    make: *** [build/app.out] Error 1
    i want to solve this issue
    thank you

    • The newer versions (> 1.1.0) of the SDK require a function “user_rf_pre_init” to be defined. Just adding the line below to the bottom of your user/user_main.c should do the trick:

      void user_rf_pre_init(void) { return; }

  7. Jose Josemar Jose Josemar

    Hello John Pellinkhof, I’m in trouble, I’m following the suggested steps, however I have this message it after running the ./bootstrap line && ./configure –prefix = pwd && make && make install:
    For auto-completion, do not forget to install ‘ct-ng.comp’ into
    your bash completion directory (Usually /etc/bash_completion.d)
    I tried to change Linux distribution, but to no avail.
    I am currently with Lubuntu 10.15 64bit, you could help me?

  8. Mack Mack

    My development board keeping making buzzing sound when I turn it on. I have tried setting up DIP switches as per image. I can see the driver loaded and see USB connected to Mac as well Windows but I cant open COM port form Windows or I can not communicate with /dev/ttyUSB0 on either Linux 9irtual install) or Mac native.

    Any chance my development board is bad 🙁

    • Hey Mack. It definitely is not supposed to buzz. If you can get a connection on USB, this means that your FTDI on the dev board is working. From there it will try to connect to the board and chip, and that doesn’t seem to work, which is why you can’t establish a serial connection. You could try to connect the ESP directly with an FTDI if you have one, to see if the ESP is working, or swap it with another ESP perhaps?

  9. Hi:

    There are some difference here. When I build it, it generates just firmware/0x00000.bin and firmware/0x10000.bin instead of firmware/0x00000.bin and firmware/0x40000.bin.

    Do you know why?

    Thank you very much. Great tutorial!!

  10. Arif Arif

    Hello Jan,

    I just purchased the same dev board of esp8266 but unable use it due to lack of any manual..
    If you dont mine can you pls inform me its swithc positions?
    It is only buzzing when I plug into usb port.
    If you have more things usefull for such board pls send me e mail…
    Thank you,

    • Jan Jan

      Hey Arif, the pictures are took are of a high enough resolution to see the switch positions I think. Have a look and see if you can make sense out of them?

  11. Personally, I do it through the USB port included on the development board. I think most 8266 boards probably come with a built-in USB to serial converter these days. Great article! Keep up the good work.

  12. Hi,
    Photo quality really good which camera you have used

  13. My development board keeping making buzzing sound when I turn it on. I have tried setting up DIP switches as per image. Need your help

Leave a Reply

Your email address will not be published. Required fields are marked *

two × 3 =