Setting up build environment


All these examples assume linux host. Personnally I use very stripped down Debian (Jessie), but acknowledging most of the rest of world goes with (bloaded...) Ubuntus, these instructions should work just fine in there too. Ubuntu is practically a Debian testing/unstable, ie. equipped with newer software versions.

There might be already usable packages in distribution's package repositories. I think for example esptool is packaged. You can use them if they exists, but at least these tar.gz's below contain all necessary components.

Also, these tar.gz's dont make you install any rarely needed packages. Personnally I hate instructions where you are instructed to install this and that, cut-pasting stuff that you are bit worried of what it actually dows. These instuctions below are meant to be simple and readable so that you know what is done to your system and know how to get rid of all changes made.

Installing required packages, SDK and toolchain

Download prebuild binaries

Download SDK and toolchain packages from links below. These are compiled for use in 64bit systems.

To refer original sources :

SDK package is unmodified, except modification of getting rid of annoying compiler warning with fix explained at

Extract SDK, cross compiler and tools

Extract downloaded packages with commands below. Since all files in packages are prefixed with /usr/local, option -C / chdirs tar into root before extracting.

esp:~/Downloads$ sudo tar -C / -xzf esp-open-sdk-v1.5.4_160520.tar.gz
esp:~/Downloads$ sudo tar -C / -xzf esp-toolchain-20170304.tar.gz

After extraction there will be new filesystem items :


To get rid of actions above, just remove created directories and your system is back on state you started.

Late warning. Never!! untar with method above without either validating the package contents beforehand or fully trusting the source. You don't probably want your /etc/passwd or /sbin/init overwritten by "accident". Always check before package extraction, what really will get done.

Serial communications

Serial communication is needed for interacting and flashing the esp8266 chip. Below is explained required changes to system so that future development and flashing can be done without sudoing or running anything extra as root.

Serial communication program

The weirdness with esp8266 is that it strictly uses CRLF line terminations in serial communication in both directions. Common terminal emulators like putty or minicom does not work since they support only LF line-endings at least on not both directions. Of course you can emulate CR with Ctrl+M but it's far from perfect solution for long run.

Personal preference is cutecom which is packaged at least in Wheezy and successors. Most probably exists also on Ubuntus. There might be also more alternatives, but since cutecom did exactly what was needed, I didn't search for more.

Physical adapters & cables

As you must have already read from net, you cannot use direct serial RS-232 connection but you need something called USB to TTL level converter. Adjacent link points to cable I use, fully supported by Linux for very long time.

In case you compile you own very very stripped down kernels into your very very streamlined system like I do, required module for cable above is :

Device Drivers  --->
  [*] USB support  --->
    <M>   USB Serial Converter support  --->
      <M>   USB CP210x family of UART Bridge Controllers

...with USB id...

Bus 003 Device 005: ID 10c4:ea60 Cygnal Integrated Products, Inc. CP210x UART Bridge / myAVR mySmartUSB light

But since you are running distribution kernel, you don't need to worry about that above.

Serial device permissions

To operate serial device without root access, you need to grant yourself into system group that allows access to serial devices. On Debians and Ubuntus (probably almost everywhere) the required group is dialout.

Add youself to group by command : (or edit /etc/group with care..)

esp:~$ sudo adduser youraccount dialout

Remember that you need to logout and log back in to get chat new group membership active. After successful relogin you should have the dialout group active on your group memberships :

esp:~$ id -a

To exit group, reverse command is :

esp:~$ sudo deluser youraccount dialout

Required extra packages on host system requires python-serial. On Debian based system install it with :

pri:~$ sudo apt-get install python-serial

Again, to get rid of installation :

 pri:~$ sudo apt-get --purge remove python-serial
 pri:~$ sudo apt-get --purge autoremove

Validating installation

As a result of previous steps you should have :

Basic validation, apply yourself..

# TTL-USB-device is writable for dialout group
esp:~$ ls -l /dev/ttyUSB*
crw-rw---- 1 root dialout 188, 0 maali  4 14:11 /dev/ttyUSB0

# you belong to that dialout group
esp:~$ id -a
uid=1002(tempuser) gid=1002(tempuser) groups=1006(tempuser),4(adm),8(mail),20(dialout), (...snip...)

# shell-snippet updates the path (remember dot..)
esp:~$ . use-esp8266-build-system 
esp:~$ set | fgrep PATH

# cross-compiler works
esp:~$ xtensa-lx106-elf-gcc -v
Using built-in specs.
Target: xtensa-lx106-elf
Configured with: /home/tempuser/esp-open-sdk/crosstool-NG/. (...snip...)
Thread model: single
gcc version 4.8.5 (crosstool-NG crosstool-ng-1.22.0-55-gecfc19a)
# works
esp:~$ -h
usage: esptool [-h] [--port PORT] [--baud BAUD]

...(snip)... v1.2-dev - ESP8266 ROM Bootloader Utility

positional arguments:


optional arguments:
  -h, --help            show this help message and exit
  --port PORT, -p PORT  Serial port device
  --baud BAUD, -b BAUD  Serial port baud rate used when flashing/reading