ESP8266 Wifi module on Linux

July 22, 2016

ESP8266 basics

I have had a bunch of Espressif ESP8266 modules since last year, getting started with them seemed very difficult. Yesterday I looked at them again and got somewhere with them.

There are many pages already with pieces of information about ESP8266, and some great guys have been all over it reversing the bootloader a while ago. However it took me a while to get enough info for using my modules on Linux, and to understand what the modules are and aren't inside.

So this page will try to document the basics in one place for people wanting to use the modules on Linux.


The firmware is not all open but is actively developed. Since old versions of it ship on the module, the first job is set yourself up to be able to reflash it.

Required module connections

Baud rate nonsense

From boot, in the ROM bootloader and the second stage bootloader, the chip's baud rate on serial is a completely nonstandard 74880bps. Most normal serial ports can't do that, however serial - USB adapters usually have a very flexible baud rate generator and can handle it. Even so, most serial terminal applications cannot express such random baud rates, eg. minicom can't do it. gtkterm did it once (?) and never again, it stuck at 9600 even while displaying 74880 in the UI.

pyserial package has a python terminal emulator that can do it, if your USB adapter can do it. /dev/ttyUSB0 -b 74880

If you're debugging what is going wrong from boot, you need the funny baud rate. But modern firmwares that run after the second stage bootloader change the baud rate to 115200, so if you avoid problems in early boot using the info following, you can stick at 115200 and just see some junk coming at module reset.

What it's actually saying (at 74880bps) during a normal boot looks like this

ets Jan  8 2013,rst cause:2, boot mode:(3,6)

load 0x40100000, len 2408, room 16
tail 8
chksum 0xe5
load 0x3ffe8000, len 776, room 0
tail 8
chksum 0x84
load 0x3ffe8310, len 632, room 0
tail 8
chksum 0xd8
csum 0xd8

2nd boot version : 1.6
 SPI Speed      : 40MHz
 SPI Mode       : DIO
 SPI Flash Size & Map: 8Mbit(512KB+512KB)
jump to run user1 @ 1000

rf cal sector: 251
rf[112] : 00
rf[113] : 00
rf[114] : 01

SDK ver: 2.0.0(656edbf) compiled @ Jul 19 2016 17:58:40
phy ver: 1055, pp ver: 10.2

At the end it switches to 115200 and says


and will accept AT commands. Note some terminal emulators don't send suitable things for CRLF, in that case try Ctrl-J to end the line.

From a terminal emulator in 115200bps mode only, the end result is a spew of junk and then the word "ready".

In text from the ROM bootloader boot mode:(3,6), the 3 indicates GPIO0 is pulled high for normal boot. If you hold GPIO0 to 0V, this changes to boot mode:(1,6) and the ROM bootloader enters the path for flashing the SPI instead of normal boot.

Areas in the SPI flash

Then there are two areas that go at the "end" of the SPI flash, the addresses shown are for the 8Mbit SPI flash on my module, for 16MBit, they are +0x100000

Using Linux commandline tools to flash the module

There is a python flasher here that works well.

You can install it using pip as mentioned in its readme, but since pyserial is packaged in Fedora I installed that dependency from the package.

I got the current-at-the-time-of-writing binary "NONOS" SDK image from here unpacked it and navigated to ./bin/at/512+512/

You must exit your terminal emulator while doing this or it will compete for reading the serial data wants to read. --port /dev/ttyUSB0 --baud 115200 write_flash --verify -fs 8m \
 0x00000 ../../boot_v1.6.bin \
 0x01000 \
 0x81000 \
 0xfc000 ../../esp_init_data_default.bin \
 0xfe000 ../../blank.bin

At the end, it should says

-- verify OK (digest matched)

Afterwards stop forcing GPIO0 to 0V and either cycle the power or take RST to 0V briefly to come up in the application firmware at 115200 (after the inevitable junk from the ROM + second stage bootloader at 74880 baud first), and say "ready".

AT commands to connect to AP







The AT based fw is the default but it turns out it's not at all the best way to use the chip, for that you need to build an application firmware from scratch. You must build the toolchain and the actual application, but that is surprisingly simple it turns out since all the main grunt work has been done.

Homebrew firmware - Toolchain

Clone this

and follow the build instructions. For Fedora, as mentioned in the following packages will be needed.

sudo dnf install make unrar autoconf automake libtool gcc gcc-c++ gperf \
   flex bison texinfo gawk ncurses-devel expat-devel python sed \
   help2man python-devel pyserial

I chose the "include the SDK" build option and after some minutes it completed the build OK on Fedora24.

Set PATH to point to wherever you cloned the Toolchain

export PATH=/projects/esp-open-sdk/xtensa-lx106-elf/bin/:$PATH

That's it to get started with the toolchain.

Homebrew Firmware - application

I was really surprised that there is already a FOSS (MIT licensed) application in < 400KB with basically all the features needed (in a bare way, but still, this is an amazing boon). The author seems to have put together things from other projects, but it seems all FOSS.

Clone this

Edit line 8 of ./Makefile to point to your toolchain bin dir from earlier.

XTENSA_TOOLS_ROOT ?= /projects/esp-open-sdk/xtensa-lx106-elf/bin/

After that just make. He built without errors here.

Using the esptool from earlier, we can blow everything in one step --port /dev/ttyUSB0 --baud 115200 write_flash --verify -fs 8m \
0x00000 bin/0x00000.bin \
0x10000 bin/0x10000.bin \
0xfe000 bin/blank.bin \
0xfc000 bin/esp_init_data_default.bin

The core application is taken from some smart relay project. It runs the ESP8266 in both AP and station modes, and allows you to select and authenticate to another AP. It also has some kind of websocket serving support, but something about it is broken since it logs

http_ws_cgi_execute c =0x3ffea500
websocket frame size 520
    Invalid frame type 07
    received invalid frame

Opcode 7 is reserved in RFC6455... anyway that's a great start, I thought doing stuff like making the station connection and keeping it nailed up would have to be done by hand. I guess the next step is study the pile of code.

Special constraints

ESP8266 has one big advantage on the constraint front, a relatively huge SPI NOR flash used to store code and data. Even on my old modules from 2015 that is 1MiByte, and on recent modules it's 4MiBytes.

Allowing that half of it will need reserving for processing updates, 2MiBytes is still a lot of space for this kind of device. The whole image for example from the esp-ginx image is only 350KiB.

However there are problems. Of the main two issues, one can be imagined, there is only 80KiB of SRAM on the whole device. Typically there is around 30KiB of heap left after init.

The much less expected problem is that the ROM copies the first 0x9000 (36KiB) of flash to SRAM and jumps into it, for unknown reasons it seems the global .rodata section is required to be in there (!)

Any code that operates the SPI flash has to be in there as well, because it can't mess with it while executing from it.


Edit: the bad opcode thing is a bug, the websocket "cgi" code receives a first packet which is actually the GET / HTTP headers, 0x47 for G of GET is parsed in ws protocol to get opcode 7. However the code (illegally) ignores it and continues on. With small packet sizes (32 bytes) the lwip stack falls over with OOM, like this It seems related to how many connections are coming at lwip, which is a bit worrying for robustness (the http / websocket parser stuff also looks a bit shaky).

I threw out their http arrangements and replaced it with lws, which I will discuss in another post.