RIOT/cpu/esp8266

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
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. Preconfigured Devices
   1. Network Devices
   2. SD-Card Device
7. Application-Specific Configurations
   1. Application-Specific Board Configuration
   2. Application-Specific Driver Configuration
8. SDK Task Handling
9. QEMU Mode and GDB

Overview    [TOC]

There are two implementations that can be used:

• the SDK version which is realized on top of an SDK (esp-open-sdk or ESP8266_NONOS_SDK) and
• the non-SDK version which is realized without the SDK.

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:

MCU	ESP8266EX
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

@note 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:

• esp-open-sdk which includes the Xtensa GCC compiler toolchain, the hardware abstraction library libhal for Xtensa LX106, and the flash programmer tool esptool.py
• newlib-c library for Xtensa (esp-open-rtos version)
• SDK (optional), either as part of esp-open-sdk or the ESP8266_NONOS_SDK

You have the following options to install the Toolchain:

• riotdocker image and esptool.py, see section RIOT Docker Toolchain (riotdocker)
• precompiled toolchain installation from GIT, see section Precompiled Toolchain
• manual installation, see section Manual Toolchain Installation

RIOT Docker Toolchain (riotdocker)  [TOC]

The easiest use the toolchain is Docker.

Preparing the Environment  [TOC]

Using RIOT Docker requires at least the following software:

• Docker container virtualization software
• RIOT Docker (riotdocker) image
• flasher tool esptool.py

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 docker.io

The ESP Flasher tool esptool.py 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 esptool.py can be installed with pip:

pip install esptool

esptool.py 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 esptool.py, please refer the git repository

Please make sure that esptool.py 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 https://github.com/gschorcht/riotdocker-Xtensa-ESP.git
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

@note 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.

@note 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.

@note 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 https://github.com/gschorcht/RIOT-Xtensa-ESP8266-toolchain.git 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.

@note 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 https://github.com/pfalcon/esp-open-sdk.git
cd esp-open-sdk
export ESP_OPEN_SDK_DIR=$PWD

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.

make STANDALONE=y

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 https://github.com/ourairquality/newlib.git

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
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/esp-open-sdk
/path/to/esp/newlib-xtensa
/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

and

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

or

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
NETDEV_DEFAULT	module name	mrf24j40	Set the module that is used as default network device, see section Network Devices
PORT	/dev/ttyUSBx	/dev/ttyUSB0	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_spiffs	Enables the SPIFFS file system, see section SPIFFS Device
esp_sw_timer	Enables software timer implementation, implies the setting USE_SDK=1, see section Timers

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 esptool.py.

@note 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.

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
GPIO1	UART TxD
GPIO2	usually pulled up
GPIO3	UART RxD
GPIO4
GPIO5
GPIO6	Flash SPI
GPIO7	Flash SPI
GPIO8	Flash SPI
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
GPIO12
GPIO13
GPIO14
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:

GPIO0	GPIO2	GPIO15 (MTDO)	Mode
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.

@note 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:

• FSPI for flash memory access that is usually simply referred to as SPI
• HSPI for peripherals

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
MISO	GPIO12
MOSI	GPIO13
SCK	GPIO14
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_SPEED     I2C_SPEED_FAST
#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_SPEED     I2C_SPEED_FAST
#define I2C0_SDA       GPIO4
#define I2C0_SCL       GPIO5

#define I2C1_SPEED     I2C_SPEED_NORMAL
#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.

@note 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

#define PWM0_CHANNEL_GPIOS { GPIO12, GPIO13, GPIO14, GPIO15 }

Timers  [TOC]

There are two timer implementations:

• hardware timer implementation with 1 timer device and only 1 channel, the default
• software timer implementation with 1 timer device and only 10 channels

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.

@note 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 device 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

• one hardware number generator with 32 bit,
• one UART interface (GPIO1 and GPIO3),
• a CPU-ID function, and
• power management functions.

RTC is not yet implemented.

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 ESP8266 port has been tested with the following network devices and is preconfigured to create RIOT network applications with these devices:

• mrf24j40 (driver for Microchip MRF24j40 based IEEE 802.15.4
• enc28j60 (driver for Microchip ENC28J60 based Ethernet modules)

If the RIOT network application uses a default network device (module netdev_default), the NETDEV_DEFAULT make command variable can be used to define the device that will be used as the default network device. The value of this variable must match the name of the driver module for this network device. If NETDEV_DEFAULT is not defined, the mrf24j40 module is used as default network device.

Using MRF24J40 (module mrf24j40)  [TOC]

To use MRF24J40 based IEEE 802.15.4 modules as network device, module mrf24j40 has to be added to a makefile:

USEMODULE += mrf24j40

@note If module netdev_default is used (which is usually the case in all networking applications), module mrf24j40 is added automatically.

Module mrf24j40 uses the following interface parameters by default:

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

Used GPIOs can be overridden by corresponding make command variables, e.g,:

make flash BOARD=esp8266-esp-12x -C examples/gnrc_networking MRF24J40_PARAM_CS=GPIO15

or by an application-specific board configuration.

Using ENC28J60 (module enc28j60)  [TOC]

To use ENC28J60 Ethernet modules as network device, module enc28j60 has to be added to your makefile:

USEMODULE += enc28j60

Module enc28j60 uses the following interface parameters by default:

Parameter	Default	Remarks
ENC28J60_PARAM_SPI	SPI_DEV(0)	fix, 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

Used GPIOs can be overridden by corresponding make command variables, e.g.:

make flash BOARD=esp8266-esp-12x -C examples/gnrc_networking ENC28J60_PARAM_CS=GPIO15

or by an application-specific board configuration.

To use module enc28j60 as default network device, the NETDEV_DEFAULT make command variable has to set, for example:

make flash BOARD=esp8266-esp-12x -C examples/gnrc_networking NETDEV_DEFAULT=enc28j60

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

Module sdcard_spi uses the following interface parameters by default:

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 an application-specific board configuration.

Application-Specific Configurations  [TOC]

Configuration used for peripheral devices and for device driver modules, such as GPIO pins, bus interfaces or bus speeds are typically defined in the board-specific configurations board.h and periph_conf.h or in the driver parameter configuration < driver>_params.h. Most of these definitions are enclosed by

#ifndef ANY_PARAMETER
...
#endif

constructs, so it is possible to override them by defining them in front of these constructs.

Application-Specific Board Configuration  [TOC]

To override standard board configurations, simply create an application-specific board configuration file $APPDIR/board.h in the source directory of the application $APPDIR 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
#define PWM0_CHANNEL_GPIOS { GPIO12, GPIO13, GPIO14, GPIO15 }
#endif

#include_next "board.h"

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

#ifdef CPU_ESP8266
...
#endif

#ifdef BOARD_ESP8266_ESP_12X
...
#endif

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.

INCLUDES += -I$(APPDIR)

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 also 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))
#endif

#include_next "lis3dh_params.h"

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

#ifdef CPU_ESP8266
...
#endif

#ifdef BOARD_ESP8266_ESP_12X
...
#endif

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.

INCLUDES += -I$(APPDIR)

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 internally uses its own tasks (SDK tasks) and its own scheduling mechanism to realize event-driven SDK functions such as WiFi functions and software timers, and to keep the system alive. For this purpose, the SDK regularly executes SDK tasks with pending events in an endless loop using the ROM function ets_run.

Interrupt service routines do not process interrupts directly but use the ets_post ROM function to send an event to one of these SDK tasks, which then processes the interrupts asynchronously. A context switch is not possible in the interrupt service routines.

In the RIOT port, the task management of the SDK is replaced by the task management of the RIOT. To handle SDK tasks with pending events so that the SDK functions work and the system keeps alive, the ROM functions ets_run and ets_post are overwritten. The ets_run function performs all SDK tasks with pending events exactly once. It is executed at the end of the ets_post function and thus usually at the end of an SDK interrupt service routine or before the system goes into the lowest power mode.

@note 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 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 https://github.com/gschorcht/qemu-xtensa
cd qemu-xtensa/
git checkout xtensa-esp8266
export QEMU=/path/to/esp/qemu
./configure --prefix=$QEMU --target-list=xtensa-softmmu --disable-werror
make
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:

xtensa-lx106-elf-gdb

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