ESP8266 / ESP8285

RIOT-OS port for Espressif's ESP8266 / ESP8285 MCUs. More...

Detailed Description

RIOT-OS port for Espressif's ESP8266 / ESP8285 MCUs.

RIOT-OS on ESP8266 and ESP8285 boards

Table of Contents

  1. Overview
  2. MCU ESP8266
  3. Toolchain
    1. RIOT Docker Toolchain (riotdocker)
    2. Precompiled Toolchain
    3. Manual Toolchain Installation
  4. Flashing the Device
    1. Toolchain Usage
    2. Compile Options
    3. Flash Modes
    4. Erasing the Device
  5. Peripherals
    1. GPIO pins
    2. ADC Channels
    3. SPI Interfaces
    4. I2C Interfaces
    5. PWM Channels
    6. Timers
    7. SPIFFS Device
    8. Other Peripherals
  6. Network Interfaces
    1. WiFi Network Interface
    2. ESP-NOW Network Interface
  7. Preconfigured Devices
    1. Network Devices
    2. SD-Card Device
  8. Application-Specific Configurations
    1. Application-Specific Board Configuration
    2. Application-Specific Driver Configuration
  9. SDK Task Handling
  10. QEMU Mode and GDB

Overview    [TOC]

There are two implementations that can be used:

The non-SDK version produces a much smaller code size than the SDK version and is more efficient in execution because it does not need to run additional SDK functions to keep the SDK system alive.

The non-SDK version is probably the best choice if you do not need the built-in WiFi module, for example, when you plan to connect an IEEE 802.15.4 radio module to the MCU for communication.

By default, the non-SDK version is compiled. To compile the SDK version, add USE_SDK=1 to the make command line, e.g.,

make flash BOARD=esp8266-esp-12x -C tests/shell USE_SDK=1 ...

For more information about the make command variables, see section Compile Options.

MCU ESP8266  [TOC]

ESP8266 is a low-cost, ultra-low-power, single-core SoCs with an integrated WiFi module from Espressif Systems. The processor core is based on the Tensilica Xtensa Diamond Standard 106Micro 32-bit Controller Processor Core, which Espressif calls L106. The key features of ESP8266 are:

Vendor Espressif
Cores 1 x Tensilica Xtensa LX106
FPU no
RAM 80 kByte user-data RAM
32 kByte instruction RAM
32 kByte instruction cache
16 kByte EST system-data RAM
Flash 512 kByte ... 16 MByte
Frequency 80 MHz or 160 MHz
Power Consumption 70 mA in normal operating mode
20 uA in deep sleep mode
Timers 1 x 32 bit
ADCs 1 x 10 bit (1 channel)
GPIOs 16
I2Cs 2 (software implementation)
SPIs 2
UARTs 1 (console) + 1 transmit-only
WiFi IEEE 802.11 b/g/n built in
Vcc 2.5 - 3.6 V
Datasheet Datasheet
Technical Reference Technical Reference

ESP8285 is simply an ESP8266 SoC with 1 MB built-in flash. Therefore, the documentation also applies to the SoC ESP8285, even if only the ESP8266 SoC is described below.

Toolchain  [TOC]

To compile RIOT for The ESP8266 SoC, the following software components are required:

You have the following options to install the Toolchain:

RIOT Docker Toolchain (riotdocker)  [TOC]

The easiest way to use the toolchain is Docker.

Preparing the Environment  [TOC]

Using RIOT Docker requires at least the following software:

For information about installing Docker on your host, refer to the appropriate manuals for your operating system. For example, the easiest way to install Docker on the Ubuntu/Debian system is:

sudo apt-get install

The ESP Flasher tool is available at GitHub. To install the tool, either Python 2.7 or Python 3.4 or later must be installed. The latest stable version of can be installed with pip:

pip install esptool depends on pySerial which can be installed either using pip

pip install pyserial

or the package manager of your OS, for example on Debian/Ubuntu systems:

apt-get install pyserial

For more information on, please refer the git repository

Please make sure that is in your PATH variable.

Generating a riotdocker Image  [TOC]

A riotdocker fork that only installs the RIOT-Xtensa-ESP8266-toolchain is available at GitHub. After cloning this git repository, you can use branch esp8266_only to generate a Docker image with a size of "only" 990 MByte:

git clone
cd riotdocker-Xtensa-ESP
git checkout esp8266_only
docker build -t riotbuild .

A riotdocker version that contains the toolchains for all different RIOT platforms can be found at GitHub. However, the Docker image generated from the this Docker file has a size of about 1.5 GByte.

Once a Docker image has been created, it can be started with the following commands while in the RIOT root directory:

cd /path/to/RIOT
docker run -i -t --privileged -v /dev:/dev -u $UID -v $(pwd):/data/riotbuild riotbuild
RIOT's root directory /path/to/RIOT becomes visible as the home directory of the riotbuild user in the Docker image. That is, the output of compilations performed in RIOT Docker is also accessible on the host system.

Please refer the RIOT wiki on how to use the Docker image to compile RIOT OS.

Using an Existing riotdocker Image  [TOC]

Alternatively, an existing Docker image from Docker Hub can be used. You can either pull and start the schorcht/riotbuild_esp8266 Docker image which only contains the RIOT-Xtensa-ESP8266-toolchain using

cd /path/to/RIOT
docker run -i -t --privileged -v /dev:/dev -u $UID -v $(pwd):/data/riotbuild schorcht/riotbuild_esp8266

or the riot/riotbuild Docker image (size is about 1.5 GB) which contains the toolchains for all platforms using

cd /path/to/RIOT
docker run -i -t --privileged -v /dev:/dev -u $UID -v $(pwd):/data/riotbuild riot/riotbuild

Make Process with Docker Image  [TOC]

Using Docker, the make process consists of the following two steps:

  1. making the RIOT binary within a RIOT Docker image
  2. flashing the RIOT binary using a flasher program on the host system

Once the RIOT Docker image has been started from RIOT's root directory, a RIOT application can be compiled inside the Docker using the make command as usual, for example:

make BOARD=esp8266-esp-12x -C tests/shell ...

This will generate a RIOT binary in ELF format.

You can't use the flash target inside the Docker image.

The RIOT binary has to be flash outside docker on the host system. Since the Docker image was stared while in RIOT's root directory, the output of the compilations is also accessible on the host system. On the host system, the flash-only target can then be used to flash the binary.

make flash-only BOARD=esp8266-esp-12x -C tests/shell

Precompiled Toolchain  [TOC]

You can get a precompiled version of the whole toolchain from the GIT repository RIOT-Xtensa-ESP8266-toolchain. This repository contains the precompiled toolchain including all libraries that are necessary to compile RIOT-OS for ESP8266.

To use the precompiled toolchain the following packages (Debian/Ubuntu) have to be installed:
cppcheck coccinelle curl doxygen git graphviz make pcregrep python python-serial python3 python3-flake8 unzip wget

To install the toolchain use the following commands:

cd /opt
sudo git clone esp

After the installation, all components of the toolchain are installed in directory /opt/esp. Of course, you can use any other location for the installation.

To use the toolchain, you have to add the path of the binaries to your PATH variable according to your toolchain location

export PATH=$PATH:/path/to/toolchain/esp-open-sdk/xtensa-lx106-elf/bin

where /path/to/toolchain/ is the directory you selected for the installation of the toolchain. For the default installation in /opt/esp this would be:

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

Furthermore, you have to set variables ESP8266_SDK_DIR and ESP8266_NEWLIB_DIR according to the location of the toolchain.

export ESP8266_SDK_DIR=/path/to/toolchain/esp-open-sdk/sdk
export ESP8266_NEWLIB_DIR=/path/to/toolchain/newlib-xtensa

If you have used /opt/esp as installation directory, it is not necessary to set these variables since makefiles use them as default directories.

Manual Toolchain Installation  [TOC]

The most difficult way to install the toolchain is the manual installation of required components as described below.

Manual toolchain installation requires that the following packages (Debian/Ubuntu) are installed: autoconf automake bash bison build-essential bzip2 coccinelle cppcheck curl doxygen g++ gperf gawk gcc git graphviz help2man flex libexpat-dev libtool libtool-bin make ncurses-dev pcregrep python python-dev python-serial python3 python3-flake8 sed texinfo unrar-free unzip wget

Installation of esp-open-sdk  [TOC]

esp-open-sdk is directly installed inside its source directory. Therefore, change directly to the target directory of the toolchain to build it.

cd /path/to/esp
git clone --recursive
cd esp-open-sdk

If you plan to use the SDK version of the RIOT port and to use the SDK as part of esp-open-sdk, simply build its standalone version.


If you only plan to use the non-SDK version of the RIOT port or if you want to use one of Espressif's original SDKs, it is enough to build the toolchain.

make toolchain esptool libhal STANDALONE=n

Once compilation has been finished, the toolchain is available in $PWD/xtensa-lx106-elf/bin. To use it, set the PATH variable accordingly.

export PATH=$ESP_OPEN_SDK_DIR/xtensa-lx106-elf/bin:$PATH

If you have compiled the standalone version of esp-open-sdk and you plan to use this SDK version, set additionally the ESP8266_SDK_DIR variable.

export ESP8266_SDK_DIR=$ESP_OPEN_SDK_DIR/sdk

Installation of newlib-c  [TOC]

First, set the target directory for the installation.

export ESP8266_NEWLIB_DIR=/path/to/esp/newlib-xtensa

Please take care, to use the newlib-c version that was modified for esp-open-rtos since it includes stdatomic.h.

cd /my/source/dir
git clone

Once you have cloned the GIT repository, build and install it with following commands.

cd newlib
./configure --prefix=$ESP8266_NEWLIB_DIR --with-newlib --enable-multilib --disable-newlib-io-c99-formats --enable-newlib-supplied-syscalls --enable-target-optspace --program-transform-name="s&^&xtensa-lx106-elf-&" --disable-option-checking --with-target-subdir=xtensa-lx106-elf --target=xtensa-lx106-elf --enable-newlib-nano-formatted-io --enable-newlib-reent-small
make install

Installation of Espressif original SDK (optional)  [TOC]

If you plan to use the SDK version of the RIOT port and if you want to use one of Espressif's original SDKs, you have to install it.

First, download the ESP8266_NONOS_SDK version 2.1.0 from the Espressif web site. Probably other version might also work. However, RIOT port is tested with version 2.1.0.

Once you have downloaded it, you can install it with following commands.

cd /path/to/esp
tar xvfz /downloads/ESP8266_NONOS_SDK-2.1.0.tar.gz

To use the installed SDK, set variable ESP8266_SDK_DIR accordingly.

export ESP8266_SDK_DIR=/path/to/esp/ESP8266_NONOS_SDK-2.1.0

Flashing the Device  [TOC]

Toolchain Usage  [TOC]

Once you have installed all required components, you should have the following directories.

/path/to/esp/ESP8266_NONOS_SDK-2.1.0 (optional)

To use the toolchain and optionally the SDK, please check that your environment variables are set correctly to

export PATH=/path/to/esp/esp-open-sdk/xtensa-lx106-elf/bin:$PATH
export ESP8266_NEWLIB_DIR=/path/to/esp/newlib-xtensa


export ESP8266_SDK_DIR=/path/to/esp/esp-open-sdk/sdk


export ESP8266_SDK_DIR=/path/to/esp/ESP8266_NONOS_SDK-2.1.0

Compile Options  [TOC]

The compilation process can be controlled by a number of variables for the make command:

Option Values Default Description
ENABLE_GDB 0, 1 0 Enable compilation with debug information for debugging with QEMU (QEMU=1), see section QEMU Mode and GDB
FLASH_MODE dout, dio, qout, qio dout Set the flash mode, please take care with your module, see section Flash Modes
PORT /dev/ttyUSBx /dev/* Set the USB port for flashing the firmware
QEMU 0, 1 0 Generate an image for QEMU, see section QEMU Mode and GDB.
USE_SDK 0, 1 0 Compile the SDK version (USE_SDK=1), see section SDK Task Handling

Optional features of ESP8266 can be enabled by USEMODULE definitions in the makefile of the application. These are:

Module Description
esp_gdb Enable the compilation with debug information, which is equivalent to using ENABLE_GDB=1
esp_now Enable the built-in WiFi module with the ESP-NOW protocol as netdev network device
esp_sdk Enable the SDK version, which is equivalent to using USE_SDK=1
esp_spiffs Enable the SPIFFS drive in on-board flash memory
esp_sw_timer Enable software timer implementation, implies the setting USE_SDK=1 (module esp_sdk)
esp_wifi Use the built-in WiFi module as netdev network device

For example, to activate the SPIFFS drive in on-board flash memory, the makefile of application has simply to add the esp_spiffs module to USEMODULE make variable:

USEMODULE += esp_spiffs

Modules can also be activated temporarily at the command line when calling the make command:

USEMODULE="esp_spiffs" make BOARD=...

Flash Modes  [TOC]

The FLASH_MODE make command variable determines the mode that is used for flash access in normal operation.

The flash mode determines whether 2 data lines (dio and dout) or 4 data lines (qio and qout) for addressing and data access. For each data line, one GPIO is required. Therefore, using qio or qout increases the performance of SPI Flash data transfers, but uses two additional GPIOs (GPIO9 and GPIO10). That is, in this flash modes these GPIOs are not available for other purposes. If you can live with lower flash data transfer rates, you should always use dio or dout to keep GPIO9 and GPIO10 free for other purposes.

For more information about these flash modes, refer the documentation of

While ESP8266 modules can be flashed with qio, qout, dio and dout, ESP8285 modules have to be always flashed in dout mode. The default flash mode is dout.

Erasing the Device  [TOC]

The flash memory of ESP8266 can be erased completely with following command: erase_flash
After deleting the flash, the default init data must be rewritten. In a non-SDK version, this will happen automatically when RIOT is started for the first time after flashing the image. In the SDK version, this must be done explicitly. There are two possible approaches to rewriting standard initialization data: write_flash <address> $RIOTBASE/cpu/esp8266/bin/esp_init_data_default.bin

where address depends on ESP8266 chip version.

Chip version address Module examples
512 kByte 0x07c000 ESP-01, ESP-03, ESP-07, etc.
1 MByte 0x0fc000 ESP8285-based modules like Wemos D1 mini lite, PSF-A85, some ESP-01, ESP-03 etc.
2 MByte 0x1fc000
4 MByte 0x3fc000 ESP-12E, NodeMCU devkit 1.0, WeMos D1 mini
8 MByte 0x7fc000
16 MByte 0xffc000 WeMos D1 mini pro (USE 0x07c000!)

Peripherals  [TOC]

GPIO pins  [TOC]

ESP8266 has 17 GPIO pins, which are all digital pins. Some of them can not be used at all or have bootstrapping capabilities and are therefore not available on all boards.

Pin Remarks
GPIO0 usually pulled up
GPIO2 usually pulled up
GPIO9 Flash SPI in qout and qio mode, see section Flash Modes
GPIO10 Flash SPI in qout and qio mode, see section Flash Modes
GPIO11 Flash SPI
GPIO15 usually pulled down
GPIO16 RTC pin and wake up signal in deep sleep mode

GPIO0, GPIO2, and GPIO15 are bootstrapping pins which are used to boot ESP8266 in different modes:

1 X X boot in SDIO mode to start OCD
0 0 1 boot in UART mode for flashing the firmware
0 1 1 boot in FLASH mode to boot the firmware from flash (default mode)

ADC Channels  [TOC]

ESP8266 has one dedicated ADC pin with a resolution of 10 bits. This ADC pin can measure voltages in the range of 0 V ... 1.1 V.

Some boards have voltage dividers to scale this range to a maximum of 3.3 V. For more information, see the hardware manual for the board.

SPI Interfaces  [TOC]

ESP8266 provides two hardware SPI interfaces:

Even though FSPI (or simply SPI) is a normal SPI interface, it is not possible to use it for peripherals. HSPI is therefore the only usable SPI interface available for peripherals as RIOT's SPI_DEV(0).

The pin configuration of the HSPI interface SPI_DEV(0) is fixed. The only pin definition that can be overridden by an application-specific board configuration is the CS signal defined by SPI0_CS0_GPIO.

Signal of HSPI Pin
CS GPIOn with n = 0, 2, 4, 5, 15, 16 (additionally 9, 10 in dout and dio flash mode)

When the SPI is enabled using module periph_spi, these GPIOs cannot be used for any other purpose. GPIOs 0, 2, 4, 5, 15, and 16 can be used as CS signal. In dio and dout flash modes (see section Flash Modes), GPIOs 9 and 10 can also be used as CS signal.

I2C Interfaces  [TOC]

Since the ESP8266 does not or only partially support the I2C in hardware, I2C interfaces are realized as bit-banging protocol in software. The maximum usable bus speed is therefore I2C_SPEED_FAST_PLUS. The maximum number of buses that can be defined is 2, I2C_DEV(0) ... I2C_DEV(1).

Number of I2C buses (I2C_NUMOF) and used GPIO pins (I2Cx_SCL and I2Cx_SDA where x stands for the bus device x) have to be defined in the board-specific peripheral configuration in $BOARD/periph_conf.h. Furthermore, the default I2C bus speed (I2Cx_SPEED) that is used for bus x has to be defined.

In the following example, only one I2C bus is defined:

#define I2C_NUMOF (1)
#define I2C0_SDA GPIO4
#define I2C0_SCL GPIO5

A configuration with two I2C buses would look like the following:

#define I2C_NUMOF (2)
#define I2C0_SDA GPIO4
#define I2C0_SCL GPIO5
#define I2C1_SDA GPIO2
#define I2C1_SCL GPIO14

All these configurations can be overridden by an application-specific board configuration.

PWM Channels  [TOC]

The hardware implementation of ESP8266 PWM supports only frequencies as power of two. Therefore, a software implementation of one PWM device (PWM_DEV(0)) with up to 8 PWM channels (PWM_CHANNEL_NUM_MAX) is used.

The minimum PWM period that can be realized with this software implementation is 10 us or 100.000 PWM clock cycles per second. Therefore, the product of frequency and resolution should not be greater than 100.000. Otherwise the frequency is scaled down automatically.

GPIOs that can be used as channels of the PWM device PWM_DEV(0) are defined by PWM0_CHANNEL_GPIOS. By default, GPIOs 2, 4 and 5 are defined as PWM channels. As long as these channels are not started with function pwm_set, they can be used as normal GPIOs for other purposes.

GPIOs in PWM0_CHANNEL_GPIOS with a duty cycle value of 0 can be used as normal GPIOs for other purposes. GPIOs in PWM0_CHANNEL_GPIOS that are used for other purposes, e.g., I2C or SPI, are no longer available as PWM channels.

To define other GPIOs as PWM channels, just overwrite the definition of PWM_CHANNEL_GPIOS in an application-specific board configuration


Timers  [TOC]

There are two timer implementations:

By default, the hardware timer implementation is used.

When the SDK version of the RIOT port (USE_SDK=1) is used, the software timer implementation is activated by using module esp_sw_timer.

The software timer uses SDK's software timers to implement the timer channels. Although these SDK timers usually have a precision of a few microseconds, they can deviate up to 500 microseconds. So if you need a timer with high accuracy, you'll need to use the hardware timer with only one timer channel.

When module esp_sw_timer is used, the SDK version is automatically compiled (USE_SDK=1).

SPIFFS Device  [TOC]

If SPIFFS module is enabled (USEMODULE += esp_spiffs), the implemented MTD system drive mtd0 for the on-board SPI flash memory is used together with modules spiffs and vfs to realize a persistent file system.

For this purpose, the flash memory is formatted as SPIFFS starting at the address 0x80000 (512 kByte) on first boot. All sectors up to the last 5 sectors of the flash memory are then used for the file system. With a fixed sector size of 4096 bytes, the top address of the SPIFF is flash_size - 5 * 4096, e.g., 0xfb000 for a flash memory of 1 MByte. The size of the SPIFF then results from:

flash_size - 5 * 4096 - 512 kByte

Please refer file $RIOTBASE/tests/unittests/test-spiffs/tests-spiffs.c for more information on how to use SPIFFS and VFS together with a MTD device mtd0 alias MTD_0.

Other Peripherals  [TOC]

The ESP8266 port of RIOT also supports

RTC is not yet implemented.

Network Interfaces  [TOC]

ESP8266 provides different built-in possibilities to realize network devices:

WiFi Network Interface  [TOC]

The RIOT port for ESP8266 implements in module esp_wifi a netdev driver for the built-in WiFi interface.

Due to symbol conflicts with the crypto and hash modules of RIOT in vendor library, which is required by module esp_wifi, esp_wifi cannot be used for applications that use these modules. Therefore, module esp_wifi is not automatically enabled when module netdev_default is used. Instead, if necessary, the application has to add the module esp_wifi in the Makefile.
USEMODULE += esp_wifi

Furthermore, the following configuration parameters have to be defined:

Parameter Default Description
ESP_WIFI_SSID "RIOT_AP" SSID of the AP to be used.
ESP_WIFI_PASS "ThisistheRIOTporttoESP" Passphrase used for the AP as clear text (max. 64 chars).
ESP_WIFI_STACKSIZE THREAD_STACKSIZE_DEFAULT Stack size used for the WiFi netdev driver thread.

These configuration parameter definitions, as well as enabling the esp_wifi module, can be done either in the makefile of the project or at make command line, e.g.:

USEMODULE=esp_wifi \
make -C examples/gnrc_networking BOARD=...
The Wifi network interface (module esp_wifi) and the ESP-NOW network interface (module esp_now) can be used simultaneously, for example, to realize a border router for a mesh network which uses ESP-NOW.

ESP-NOW Network Interface  [TOC]

With ESP-NOW, the ESP8266 provides a connectionless communication technology, featuring short packet transmission. It applies the IEEE802.11 Action Vendor frame technology, along with the IE function developed by Espressif, and CCMP encryption technology, realizing a secure, connectionless communication solution.

The RIOT port for ESP8266 implements in module esp_now a netdev driver which uses ESP-NOW to provide a link layer interface to a meshed network of ESP8266 nodes. In this network, each node can send short packets with up to 250 data bytes to all other nodes that are visible in its range.

Due to symbol conflicts in vendor library used by the esp_now with RIOT's crypto and hashes modules, ESP-NOW cannot be used for application that use these modules. Therefore, the module esp_now is not enabled automatically if the netdev_default module is used. Instead, the application has to add the esp_now module in its makefile when needed.
USEMODULE += esp_now

For ESP-NOW, ESP8266 nodes are used in WiFi SoftAP + Station mode to advertise their SSID and become visible to other ESP8266 nodes. The SSID of an ESP8266 node is the concatenation of the prefix RIOT_ESP_ with the MAC address of its SoftAP WiFi interface. The driver periodically scans all visible ESP8266 nodes.

The following parameters are defined for ESP-NOW nodes. These parameters can be overriden by application-specific board configurations.

Parameter Default Description
ESP_NOW_SCAN_PERIOD 10000000UL Defines the period in us at which an node scans for other nodes in its range. The default period is 10 s.
ESP_NOW_SOFT_AP_PASS "ThisistheRIOTporttoESP" Defines the passphrase as clear text (max. 64 chars) that is used for the SoftAP interface of ESP-NOW nodes. It has to be same for all nodes in one network.
ESP_NOW_CHANNEL 6 Defines the channel that is used as the broadcast medium by all nodes together.
ESP_NOW_KEY NULL Defines a key that is used for encrypted communication between nodes. If it is NULL, encryption is disabled. The key has to be of type uint8_t[16] and has to be exactly 16 bytes long.
The ESP-NOW network interface (module esp_now) and the Wifi network interface (module esp_wifi) can be used simultaneously, for example, to realize a border router for a mesh network which uses ESP-NOW.

Preconfigured Devices  [TOC]

The ESP8266 port of RIOT has been tested with several common external devices that can be connected to ESP8266 boards and are preconfigured accordingly.

Network Devices  [TOC]

RIOT provides a number of driver modules for different types of network devices, e.g., IEEE 802.15.4 radio modules and Ethernet modules. The RIOT port for ESP8266 has been tested with the following network devices:

Using MRF24J40 (module mrf24j40)  [TOC]

To use MRF24J40 based IEEE 802.15.4 modules as network device, the mrf24j40 driver module has to be added to the makefile of the application:

USEMODULE += mrf24j40

The mrf24j40 driver module uses the following preconfigured interface parameters for ESP8266 boards:

Parameter Default Remarks
MRF24J40_PARAM_SPI SPI_DEV(0) fixed, see section SPI Interfaces
MRF24J40_PARAM_CS GPIO16 can be overridden
MRF24J40_PARAM_INT GPIO0 can be overridden
MRF24J40_PARAM_RESET GPIO2 can be overridden

The GPIOs in this configuration can be overridden by application-specific board configurations.

Using ENC28J60 (module enc28j60)  [TOC]

To use ENC28J60 Ethernet modules as network device, the enc28j60 driver module has to be added to the makefile of the application:

USEMODULE += enc28j60

The enc28j60 driver module uses the following preconfigured interface parameters for ESP8266 boards:

Parameter Default Remarks
ENC28J60_PARAM_SPI SPI_DEV(0) fixed, see section SPI Interfaces
ENC28J60_PARAM_CS GPIO4 can be overridden
ENC28J60_PARAM_INT GPIO9 can be overridden
ENC28J60_PARAM_RESET GPIO10 can be overridden

The GPIOs in this configuration can be overridden by application-specific board configurations.

SD-Card Device  [TOC]

ESP8266 port of RIOT is preconfigured for RIOT applications that use the SPI SD-Card driver. To use SPI SD-Card driver, the sdcard_spi module has to be added to a makefile:

USEMODULE += sdcard_spi

The sdcard_spi driver module uses the following preconfigured interface parameters for ESP8266 boards:

Parameter Default Remarks
SDCARD_SPI_PARAM_SPI SPI0_DEV fix, see section SPI Interfaces
SDCARD_SPI_PARAM_CS SPI0_CS0_GPIO can be overridden

The GPIO used as CS signal can be overridden by application-specific board configurations.

Application-Specific Configurations  [TOC]

The board-specific configuration files board.h and periph_conf.h as well as the driver parameter configuration files <driver>_params.h define the default configurations for peripherals and device driver modules. These are, for example, the GPIOs used, bus interfaces used or available bus speeds. Because there are many possible configurations and many different application requirements, these default configurations are usually only a compromise between different requirements.

Therefore, it is often necessary to change some of these default configurations for individual applications. For example, while many PWM channels are needed in one application, another application does not need PWM channels, but many ADC channels.

Application-Specific Board Configuration  [TOC]

To override default board configurations, simply create an application-specific board configuration file $APPDIR/board.h in the source directory $APPDIR of the application and add the definitions to be overridden. To force the preprocessor to include board's original board.h after that, add the include_next preprocessor directive as the last line.

For example to override the default definition of the GPIOs that are used as PWM channels, the application-specific board configuration file $APPDIR/board.h could look like the following:

#ifdef CPU_ESP8266
#include_next "board.h"

It is important to ensure that the application-specific board configuration $APPDIR/board.h is included first. Insert the following line as the first line to the application makefile $APPDIR/Makefile.

To make such application-specific board configurations dependent on the ESP8266 MCU or a particular ESP8266 board, you should always enclose these definitions in the following constructs
#ifdef CPU_ESP8266
#ifdef BOARD_ESP8266_ESP-12X

Application-Specific Driver Configuration  [TOC]

Using the approach for overriding board configurations, the parameters of drivers that are typically defined in drivers/<device>/include/<device>_params.h can be overridden. For that purpose just create an application-specific driver parameter file $APPDIR/<device>_params.h in the source directory $APPDIR of the application and add the definitions to be overridden. To force the preprocessor to include driver's original <device>_params.h after that, add the include_next preprocessor directive as the last line.

For example, to override a GPIO used for LIS3DH sensor, the application-specific driver parameter file $APPDIR/<device>_params.h could look like the following:

#ifdef CPU_ESP8266
#define LIS3DH_PARAM_INT2 (GPIO_PIN(0, 4))
#include_next "lis3dh_params.h"

It is important to ensure that the application-specific driver parameter file $APPDIR/<device>_params.h is included first. Insert the following line as the first line to the application makefile $APPDIR/Makefile.


Pleae note:** To make such application-specific board configurations dependent on the ESP8266 MCU or a particular ESP8266 board, you should always enclose these definitions in the following constructs:

#ifdef CPU_ESP8266
#ifdef BOARD_ESP8266_ESP-12X

SDK Task Handling  [TOC]

With make command variable USE_SDK=1, the Espressif SDK is used. This is necessary, for example, if you want to use the built-in WLAN module. The SDK is also used automatically when software timers are used by activating the esp_sw_timer module.

Internally, the SDK uses its own priority-based multitasking sytsem, the ETS, to handle hardware components such as the WiFi interface, or to implement event-driven functions such as software timers. ETS periodically executes all ETS tasks with pending events in an infinite loop with the ROM function ets_run.

ETS doesn't process interrupts directly in interrupt service routines. Instead, they use the ets_post ROM function to send an event to one of the ETS tasks, which then processes the interrupts asynchronously. Context switches are not possible in interrupt service routines.

To use SDK functions and keep the system alive, ETS tasks with pending events have to be handled. For that purpose

The ets_task_func RIOT thread is waiting for a thread flag, which is set by the ets_post function at the end of an ETS interrupt service routine. The flag indicates that there are ETS tasks with pending events that need to be executed. The ets_task_func RIOT thread then calls the ets_run function, which performs all ETS tasks with pending events exactly once.

Thus, when a hardware component used by the SDK triggers an interrupt, e.g. the WiFi interface, the interrupt sevice routine posts an event to the ETS task by calling the ets_post function. The overwritten version of this function sets the thread flag of the ets_task_func thread. The thread then calls function ets_run to process pending events.

Since the non-SDK version of RIOT is much smaller and faster than the SDK version, you should always compile your application without the SDK (USE_SDK=0, the default) if you don't need the built-in WiFi module.

QEMU Mode and GDB  [TOC]

When QEMU mode is enabled (QEMU=1), instead of loading the image to the target hardware, a binary image $ELFFILE.bin is created in the target directory. This binary image file can be used together with QEMU to debug the code in GDB.

The binary image can be compiled with debugging information (ENABLE_GDB=1 or module esp_gdb) or optimized without debugging information (ENABLE_GDB=0). The latter one is the default. The version with debugging information can be debugged in source code while the optimized version can only be debugged in assembler mode.

To use QEMU, you have to install QEMU for Xtensa with ESP8266 machine implementation as following.

cd /my/source/dir
git clone
cd qemu-xtensa/
git checkout xtensa-esp8266
export QEMU=/path/to/esp/qemu
./configure --prefix=$QEMU --target-list=xtensa-softmmu --disable-werror
make install

Once the compilation has been finished, QEMU for Xtensa with ESP8266 machine implementation should be available in /path/to/esp/qemu/bin and you can start it with

$QEMU/bin/qemu-system-xtensa -M esp8266 -nographic -serial stdio -monitor none -s -S -kernel /path/to/the/target/image.elf.bin

where /path/to/the/target/image.elf.bin is the path to the binary image as generated by the make command as $ELFFILE.bin. After that you can start GDB in another terminal window using command:


If you have compiled your binary image with debugging information, you can load the ELF file in gdb with:

(gdb) file /path/to/the/target/image.elf

To start debugging, you have to connect to QEMU with command:

(gdb) target remote :1234


 ESP8266 SDK interface
 Function declarations and mappings for compatibility with ESP8266 SDK.
 ESP8266 WiFi netdev interface
 Network device driver for the ESP8266 WiFi interface.
 ESP8266 compile configurations
 Compile-time configuration macros for ESP8266 modules.


file  cpu/esp8266/include/common.h
 Common helper macros.
file  esp8266/include/cpu.h
 CPU common functions.
file  esp8266/include/exceptions.h
 ESP8266 exception handling.
file  gpio_common.h
 Low-level GPIO driver implementation for ESP8266.
file  esp8266/include/irq_arch.h
 Implementation of the kernels irq interface.
file  esp8266/include/periph_cpu.h
 CPU specific definitions and functions for peripheral handling.
file  esp8266/include/syscalls.h
 Implementation of required system calls.
file  esp8266/include/thread_arch.h
 Implementation of the kernel's architecture dependent thread interface.
file  esp8266/include/tools.h
 Implementation of some tools.
file  user_config.h
 Default configurations required by the SDK.
file  esp8266/include/xtensa_conf.h
 Xtensa ASM code specific configuration options.