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. Short Configuration Reference
3. MCU ESP8266
4. Toolchain
   1. RIOT Docker Toolchain (riotdocker)
   2. Manual Toolchain Installation
5. Flashing the Device
   1. Toolchain Usage
   2. Compile Options
   3. Flash Modes
   4. Erasing the Device
6. Peripherals
   1. GPIO pins
   2. ADC Channels
   3. SPI Interfaces
   4. I2C Interfaces
   5. PWM Channels
   6. Timers
   7. SPIFFS Device
   8. Other Peripherals
7. Network Interfaces
   1. WiFi Network Interface
   2. WiFi SoftAP Network Interface
   3. ESP-NOW Network Interface
8. Preconfigured Devices
   1. Network Devices
   2. SD-Card Device
9. Application-Specific Configurations
   1. Application-Specific Board Configuration
   2. Application-Specific Driver Configuration
10. SDK Specific Information
    1. Tasks
    2. Heap
11. Debugging
    1. QEMU Mode and GDB
    2. Module esp_gdbstub

Overview

The RIOT port for Xtensa-ESP is a bare metal implementation of RIOT-OS for ESP8266 / ESP8285 SOCs which supports most features of RIOT-OS. The peripheral SPI and I2C interfaces allow to connect all external hardware modules supported by RIOT-OS, such as sensors and actuators. SPI interface can also be used to connect external IEEE802.15.4 modules to integrate ESP8266 boards into a GNRC network.

The RIOT-OS port for ESP8266 supports ESP8266 as well as ESP8285 MCUs and requires the ESP8266 RTOS SDK v3.x. To build a RIOT application, simply use the make command and specify an existing ESP8266 board, for example:

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

For more information about the make command variables and specific compile options, see section Compile Options.

Although the port does not use the official ESP8266 RTOS SDK directly, it must be installed for compilation. The reason is that the port uses most of the ESP8266 SOC definitions provided by SDK header files. In addition, it needs the hardware abstraction library (libhal), and ESP8266 WiFi stack binary libraries which are part of the SDK.

Back to table of contents

MCU ESP8266

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:

Back to table of contents

Short Configuration Reference

The following table gives a short reference of all board configuration parameters used by the ESP8266 port in alphabetical order.

Parameter	Short Description	Type[1]
I2C0_SPEED	Bus speed of I2C_DEV(0)	o
I2C0_SCL	GPIO used as SCL for I2C_DEV(0)	o
I2C0_SDA	GPIO used as SCL for I2C_DEV(0)	o
I2C1_SPEED	Bus speed of I2C_DEV(1)	o
I2C1_SCL	GPIO used as SCL for I2C_DEV(1)	o
I2C1_SDA	GPIO used as SCL for I2C_DEV(1)	o
PWM0_GPIOS	GPIOs that can be used as PWM_DEV(0) channels	o
SPI0_CS0	GPIO used as default CS for SPI_DEV(0)	o

1. Type: m - mandatory, o - optional

The following table gives a short reference in alphabetical order of modules that can be enabled/disabled by board configurations and/or application's makefile using USEMODULE and DISABLE_MODULE.

Module	Default	Short description
esp_gdb	not used	enable the compilation with debug information for debugging
esp_gdbstub	not used	enable the compilation of the gdbstub interface
esp_idf_heap	not used	use SDK heap implementation
esp_now	not used	enable the ESP-NOW network device
esp_qemu	not used	generate image for QEMU and GDB debugging
esp_spiffs	not used	enable SPIFFS for on-board flash memory
esp_wifi	not used	enable the Wifi network device
esp_wifi_ap	not used	enable the Wifi SoftAP network device

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.

Back to table of contents

Toolchain

The following software components are required for compilation:

• Xtensa GCC compiler suite for ESP8266
• Modified ESP8266 RTOS SDK which includes all SOC definitions and some binary libraries
• Modified version of ESP flash programmer tool **esptool.py**

There are two options to install the toolchain:

• using RIOT Docker (riotdocker), see section RIOT Docker Toolchain (riotdocker)
• manual installation, see section Manual Toolchain Installation

In both cases, the ESP flash programmer tool esptool.py is required, see section Installation of `esptool.py`.

Back to table of contents

RIOT Docker Toolchain (riotdocker)

The easiest way to install the toolchain is to use RIOT Docker riotdocker. The compilation process using RIOT Docker consists of two steps

1. making the RIOT application in RIOT Docker with command make BOARD=...
2. flashing the RIOT application on the host computer with command make flash-only BOARD=...

where step 2 requires that the ESP flash programmer tool esptool.py is installed. Both steps can also be performed with a single command on the host system using the BUILD_IN_DOCKER variable:

BUILD_IN_DOCKER=1 make BOARD=... flash

Back to table of contents

Preparing the Environment

Using RIOT Docker requires at least the following software components:

• Docker container virtualization software
• RIOT Docker image (**riotdocker**)
• ESP flash programmer tool **esptool.py**

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

sudo apt-get install docker.io

For information on how to install esptool.py, see section Installation of esptool.py.

Back to table of contents

Using an Existing RIOT Docker Image

The easiest way to use RIOT Docker is to use an existing riotdocker image. You can either pull and start the schorcht/riotbuild_esp8266_rtos Docker image which only contains the toolchain for ESP8266 RTOS SDK using

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

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 -u $UID -v $(pwd):/data/riotbuild riot/riotbuild

Back to table of contents

Generating a riotdocker Image

Alternatively, you can generate the riotdocker image by yourself. A riotdocker fork that only installs the toolchain for ESP8266 RTOS SDK is available at GitHub. After cloning this repository, checkout branch esp8266_only_rtos_sdk to generate a Docker image with a size of "only" 890 MByte:

cd $HOME/esp
git clone https://github.com/gschorcht/riotdocker-Xtensa-ESP.git
cd riotdocker-Xtensa-ESP
git checkout esp8266_only_rtos_sdk
docker build -t riotbuild .

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

Once the 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 -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. That is, the output of compilations in RIOT Docker are also accessible on the host system.

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

Back to table of contents

Make Process with RIOT Docker

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

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

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

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

This will generate a RIOT binary in ELF format.

Note

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

The RIOT binary has to be flash outside RIOT Docker on the host system. Since the RIOT Docker image was started 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/sys/shell/

Note

Both steps can also be performed with a single command on the host system using the BUILD_IN_DOCKER variable:

`BUILD_IN_DOCKER=1 make BOARD=... flash

Back to table of contents

Manual Toolchain Installation

A more difficult way to install the toolchain is the manual installation of all required components as described below.

Note

To install the toolchain manually, a 64-bit Linux system is required. Furthermore, the following packages (Debian/Ubuntu) have to be installed:
build-essential, cppcheck, coccinelle, curl, doxygen, git, graphviz, make, pcregrep, python, python-serial, python3, python3-flake8, unzip, wget

Back to table of contents

Installation of Xtensa GCC compiler suite

The Xtensa GCC compiler for ESP8266 configured for use with RIOT-OS can be downloaded and installed as precompiled binary archive from GitHub:

mkdir -p $HOME/esp
cd $HOME/esp
git clone https://github.com/gschorcht/xtensa-esp8266-elf

Once the compiler is installed, you have to expand your PATH variable by the directory with Xtensa GCC binaries:

export PATH=$HOME/esp/xtensa-esp8266-elf/bin:$PATH

Back to table of contents

ESP8266 RTOS SDK

RIOT-OS uses the ESP8266 RTOS SDK as part of the build. This is downloaded as a package at build-time and there is no need to install it separately.

Back to table of contents

Installation of esptool.py (ESP flash programmer tool)

The RIOT port does not work with the esptool.py ESP flasher program available on GitHub or as package for your OS. Instead, a modified version from the ESP8266 RTOS SDK is required.

To avoid the installation of the complete ESP8266 RTOS SDK, for example because RIOT Docker riotdocker is used for compilation, esptool.py has been extracted from the ESP8266 RTOS SDK and placed in RIOT's directory dist/tools/esptool. For convenience, the build system uses always the version from this directory.

Therefore, it is not necessary to install esptool.py explicitly. However esptool.py depends on pySerial which can be installed either using pip

sudo pip install pyserial

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

apt install python-pyserial

For more information on esptool.py, please refer the git repository.

Back to table of contents

Flashing the Device

Toolchain Usage

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

/path/to/esp/xtensa-esp8266-elf
/path/to/esp/ESP8266_RTOS_SDK

To use the toolchain, please ensure that your environment variables are set correctly to

export PATH=/path/to/esp/xtensa-esp8266-elf/bin:$PATH

Back to table of contents

Compile Options

The compilation process can be controlled by following make variables:

Option	Values	Default	Description
FLASH_MODE	dout, dio, qout, qio	dout	Set the flash mode, please take care with your module, see section Flash Modes
PORT	/dev/<port>	/dev/USB0	Set the USB port for flashing the firmware

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

Module	Description
esp_gdb	Enable the compilation with debug information
esp_gdbstub	Enable the compilation of the gdbstub interface for debugging with GDB
esp_idf_heap	Enable SDK heap implementation which provides remaining IRAM as additional heap region
esp_now	Enable the built-in WiFi module with the ESP-NOW protocol as netdev network device
esp_qemu	Enable the compilation of an QEMU image for debugging with GDB
esp_spiffs	Enable the SPIFFS drive in on-board flash memory
esp_sw_timer	Enable software timer implementation
esp_wifi	Enable the built-in WiFi module in infrastructure mode as netdev network device
esp_wifi_ap	Enable the built-in WiFi SoftAP 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=...

Back to table of contents

Flash Modes

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.

Back to table of contents

Erasing the Device

The flash memory of ESP8266 can be erased completely with following command:

esptool.py erase_flash

Back to table of contents

Peripherals

GPIO pins

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)

Back to table of contents

ADC Channels

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.

Back to table of contents

SPI Interfaces

ESP8266 has two SPI controllers:

• CSPI for caching and accessing the flash memory
  
• HSPI for peripherals

Thus, HSPI is the only SPI interface that is available for peripherals. It is exposed as RIOT's SPI_DEV(0). The pin configuration of the HSPI interface is fixed as shown in following table.

Signal	Pin
#SPI0_MISO	GPIO12
#SPI0_MOSI	GPIO13
#SPI0_SCK	GPIO14
#SPI0_CS0	GPIOn with n = 0, 2, 4, 5, 15, 16 (additionally 9, 10 in DOUT flash mode)

The only pin definition that can be overridden by an application-specific board configuration is the CS signal defined by #SPI0_CS0.

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.

Back to table of contents

I2C Interfaces

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) and #I2C_DEV(1).

GPIO pins (#I2C0_SCL, #I2C0_SDA and/or I2C1_SCL, I2C1_SDA) have to be defined in the board-specific peripheral configuration in $BOARD/periph_conf.h. Furthermore, the default I2C bus speed (I2C0_SPEED and/or I2C1_SPEED) that is used for I2C bus(ses) has to be defined. The number of configured buses #I2C_NUMOF is then determined automatically from these definitions.

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

#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 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.

Back to table of contents

PWM Channels

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.

The GPIOs that can be used as channels of the PWM device #PWM_DEV(0) are defined by #PWM0_GPIOS. By default, all GPIOs that are not used as I2C, SPI, or UART signals are defined as PWM channels in board definition. As long as these channels are not initialized with function #pwm_init, they can be used as normal GPIOs for other purposes. Even if they are already initialized, but have a duty cycle value of 0 can be used as output GPIOs for other purposes. GPIOs in #PWM0_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 #PWM0_GPIOS in an application-specific board configuration

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

Back to table of contents

Timers

There are two timer implementations:

• hardware timer implementation with 1 timer device and only 1 channel (default)
• software timer implementation with 1 timer device and 10 channels

By default, the hardware timer implementation is used.

Software timers use SDK's timers to implement the timer device and the 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.

Back to table of contents

SPIFFS Device

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.

Back to table of contents

Other Peripherals

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.

Back to table of contents

Network Interfaces

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

• ESP WiFi, usual AP-based wireless LAN (not yet supported)
• ESP-NOW, a WiFi based AP-less and connectionless peer to peer communication protocol

Back to table of contents

WiFi Network Interface

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

Note

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
WIFI_SSID	"RIOT_AP"	SSID of the AP to be used.
WIFI_PASS	-	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 \
CFLAGS='-DWIFI_SSID=\"MySSID\" -DWIFI_PASS=\"MyPassphrase\"' \
make -C examples/gnrc_networking BOARD=...

Note

• Module esp_wifi is not enabled automatically when module netdev_default is used.
• Leave WIFI_PASS undefined to connect to an open WiFi access point.
• 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. In this case the ESP-NOW interface must use the same channel as the AP of the infrastructure WiFi network. All ESP-NOW nodes must therefore be compiled with the channel of the AP asvalue for the parameter 'ESP_NOW_CHANNEL'.

Back to table of contents

WiFi SoftAP Network Interface

The RIOT port for the ESP8266 supports a netdev interface for the ESP32 WiFi SoftAP mode. Module esp_wifi_ap has to be enabled to use it.

The following parameters can be configured:

Parameter	Default	Description
WIFI_SSID	"RIOT_AP"	Static SSID definition for the SoftAP
WIFI_PASS	none	The password for the WiFi SoftAP network interface.[1]
ESP_WIFI_SSID_DYNAMIC	0	Defines whether dynamic SSID is used for the SoftAP [2].
ESP_WIFI_SSID_HIDDEN	0	Defines whether the SoftAP SSID should be hidden.
ESP_WIFI_MAX_CONN	4	The maximum number of connections for the SoftAP.
ESP_WIFI_BEACON_INTERVAL	100	The beacon interval time in milliseconds for the SoftAP.
ESP_WIFI_STACKSIZE	THREAD_STACKSIZE_DEFAULT	Stack size used for the WiFi netdev driver thread.

[1] If no password is provided, the interface will be "open", otherwise it uses WPA2-PSK authentication mode.
[2] If ESP_WIFI_SSID_DYNAMIC is set to 1, a dynamic SSID is generated for the SoftAP by extending the defined SSID (WIFI_SSID) with the MAC address of the SoftAP interface used, e.g.: RIOT_AP_aabbccddeeff

These configuration parameter definitions, as well as enabling the esp_wifi_ap module, can be done either in the makefile of the project or at make command line, for example:

USEMODULE=esp_wifi_ap \
CFLAGS='-DWIFI_SSID=\"MySSID\" -DWIFI_PASS=\"MyPassphrase\" -DESP_WIFI_MAX_CONN=1' \
make -C examples/gnrc_networking BOARD=...

Note

• The esp_wifi_ap module is not used by default when netdev_default is used.
• Supports open and WPA2-PSK authentication modes.
• The ESP-NOW network interface and the WiFi SoftAP network interface can not be used simultaneously.

Warning

The SoftAP may or may not be at all reliable sometimes, this is a known problem with the Wi-Fi network interface, even on the official ESP-IDF. The problem is that the AP doesn't cache multicast data for connected stations, and if stations connected to the AP are power save enabled, they may experience multicast packet loss. This affects RIOT, because NDP relies on multicast packets to work correctly. Refer to the SDK documentation from Espressif on AP Sleep for more information.

Back to table of contents

ESP-NOW Network Interface

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.

Note

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 overridden by application-specific board configurations.

Parameter	Default	Description
ESP_NOW_SCAN_PERIOD_MS	10000UL	Defines the period in ms 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.

Note

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. In this case the ESP-NOW interface must use the same channel as the AP of the infrastructure WiFi network. All ESP-NOW nodes must therefore be compiled with the channel of the AP asvalue for the parameter 'ESP_NOW_CHANNEL'.

Back to table of contents

Preconfigured Devices

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

Back to table of contents

Network Devices

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:

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

Back to table of contents

Using MRF24J40 (module mrf24j40)

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_SPI_CLK	#SPI_CLK_1MHZ	fixed
#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.

Back to table of contents

Using ENC28J60 (module enc28j60)

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 overriddn
#ENC28J60_PARAM_RESET	GPIO10	can be overridden

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

Back to table of contents

SD-Card Device

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	#SPI_DEV(0)	fix, see section SPI Interfaces
#SDCARD_SPI_PARAM_CS	#SPI0_CS0	can be overridden

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

Back to table of contents

Application-Specific Configurations

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.

Back to table of contents

Application-Specific Board Configuration

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
#define PWM0_GPIOS { GPIO12, GPIO13, GPIO14, GPIO15 }
#endif
 
#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.

INCLUDES += -I$(APPDIR)

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
...
#endif
 
#ifdef BOARD_ESP8266_ESP-12X
...
#endif

Back to table of contents

Application-Specific Driver Configuration

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

INCLUDES += -I$(APPDIR)

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
...
#endif
 
#ifdef BOARD_ESP8266_ESP-12X
...
#endif

Back to table of contents

SDK Specific Information

SDK Tasks

ESP8266 RTOS SDK libraries create a number of high-priority threads, see the listing below, which handle high priority interrupts from SoC and WiFi hardware. These threads are also created, if the WiFi hardware is not used.

pid | name                 | state    Q | pri | stack  ( used) | base addr  | current
  - | isr_stack            | -        - |   - |   2048 (  832) | 0x3ffe8420 | 0x3ffe8c20
  1 | ppT                  | bl rx    _ |   2 |   3632 ( 1296) | 0x3fff5df0 | 0x3fff6ac0
  2 | pmT                  | bl rx    _ |   4 |   1072 (  320) | 0x3fff6c70 | 0x3fff6f70
  3 | rtT                  | bl rx    _ |   3 |   2096 ( 1376) | 0x3fff70b0 | 0x3fff77b0
  4 | esp_events           | bl rx    _ |   5 |   2096 (  864) | 0x3fff7f20 | 0x3fff8600

Back to table of contents

SDK Heap Implementation

Using module esp_idf_heap enables the compilation of SDK heap handling instead of memory management provided by newlibc.

Normally, the remaining ESP8266 DRAM, which is not used by static variables, is provided as heap memory. The SDK heap implementation also provides the unused ESP8266 IRAM (Command RAM) as the additional heap memory region.

Note

The heap in IRAM allows only 32-bit-aligned word access.

The following example shows the heap when the esp_idf_heap is used:

Heap region 0 @40107690: 18800 (used 8, free 18792) [bytes]
Heap region 1 @3fff1760: 59552 (used 8520, free 51032) [bytes]

In this example, heap region 0 at address 0x401xxxxx is located in IRAM and heap region 1 at address 0x3fffxxxx in DRAM. While memory management functions of newlibc use always heap region 1 in DRAM, functions of binary SDK libraries like the WiFi stack can also also heap region 0 for 32-bit aligned data.

Back to table of contents

Debugging

There are two options to debug your RIOT application for ESP8266 either

• using QEMU and module esp_gdb, see QEMU Mode andB or
• using module esp_gdbstub, see Module esp_gdbstub.

QEMU Mode and GDB

Compilation for <tt>QEMU</tt>

When QEMU mode is enabled by using the esp_qemu module, make flash does not try to download the image of your RIOT application to the target hardware. Instead, a binary image $ELFFILE.bin as well as the 1 MByte flash image esp8266flash.bin is created in the application build directory $(BINDIR). This flash image can be used together with QEMU and GDB to debug the application.

For debugging purposes, the application should be compiled with debugging information. This can either be done by using the esp_gdb module, for example:

USEMODULE=esp_gdb make flash BOARD=esp8266-esp-12x -C tests/sys/shell/

Back to table of contents

Installation of <tt>QEMU</tt>

To use QEMU, you have to install QEMU for Xtensa with ESP8266 machine implementation first 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

Back to table of contents

Start Debugging with <tt>QEMU</tt>

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 in first terminal with

term1> $QEMU/bin/qemu-system-xtensa -M esp8266 -nographic -serial stdio -monitor none -s -S \
                                    -kernel /path/to/build/dir/esp8266flash.bin

where /path/to/build/dir is the path to the application build directory $(BINDIR) where $ELFFILE.bin is generated by the make command, for example $(RIOTBASE)/tests/sys/shell//bin/esp8266-esp-12x. After that you can start GDB in second terminal window using command:

term2> xtensa-esp8266-elf-gdb /path/to/build/dir/image.elf

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

(gdb) target remote :1234

Note

QEMU does not support the emulation of hardware interrupts or special hardware modules like the WiFi module. Applications that rely on interrupts or the WiFi interface can only be debugged with restrictions with QEMU and GDB.

Back to table of contents

Module esp_gdbstub

Compilation with <tt>esp_gdbstub</tt>

Using the esp_gdbstub module enables the compilation of the gdbstub interface for ESP8266. This interface implements the target side of the GDB Remote Protocol. The initial gdbstub implementation for ESP8266 was provided by Espressif. However, for using it with RIOT it had to be changed a lot.

Note

Enabling the gdbstub interface automatically enables the compilation with debug information (module esp_gdb) gdbstub.

Back to table of contents

Start Debugging with <tt>esp_gdbstub</tt>

To start debugging, the application has to be compiled using module esp_gdbstub, for example:

USEMODULE=esp_gdbstub make flash BOARD=esp8266-esp-12x -C tests/sys/shell/

Once, the application is flashed to ESP82666, debugging can be started as following.

1. Start in first terminal window a terminal program which connects to the port of the ESP8266 module as console window:

   term1> python -m serial.tools.miniterm <port> 115200

   where <port> is the serial interface to which the ESP8266 module is connected, e.g., /dev/ttyUSB0.
2. Start GDB with the application in a second terminal window:

   term2> xtensa-esp8266-elf-gdb /path/to/the/build/dir/image.elf

   where /path/to/build/dir is the path to the application build directory $(BINDIR) where $ELFFILE.bin is generated by the make command, for example $(RIOTBASE)/tests/sys/shell//bin/esp8266-esp-12x.
3. Connect from GDB to the ESP8266 module with command:

   (gdb) target remote <port>

   where <port> is the serial interface to which the ESP8266 module is connected, e.g., /dev/ttyUSB0.

By default, gdbstub stops the execution automatically using function gdbstub_do_break after the board initialization and before the kernel is initialized.

(gdb) tar rem /dev/ttyUSB0
Remote debugging using /dev/ttyUSB0
gdbstub_do_break_breakpoint_addr () at cpu/esp8266/vendor/esp-gdbstub/gdbstub-entry.S:400
400     break 0,0
(gdb) bt
#0  gdbstub_do_break_breakpoint_addr () at cpu/esp8266/vendor/esp-gdbstub/gdbstub-entry.S:400
#1  0x40100f89 in gdbstub_init () at cpu/esp8266/vendor/esp-gdbstub/gdbstub.c:985

At this time, you can set breakpoints, execute the application stepwise or just continue the execution using the continue command. Please note the limitations below. Once you have started the execution in GDB, you can use Ctrl-C in GDB or the console window to break it anytime.

If your application uses console inputs (stdio), such as the tests/sys/shell/ application, you can type characters in the console window that gdbstub will forward to the application. However, the echo of these inputs occur in GDB.

Note

Since the terminal program and GDB are using the same serial port, typed characters can be lost sporadically.

When you reset the ESP8266 module, you will observe a message such as the following after boot messages in the console window.

$T05#b9

This is simply the first GDB Remote Protocol packet that is generated as a result of the automatic break during the initialization when the GDB is not yet connected to the ESP8266 module.

Back to table of contents

Limitations of <tt>esp_gdbstub</tt>

Due to hardware limitations of the Xtensa architecture, esp_gdbstub debugging has the following limitations:

• Software breakpoints (command br) only work for code in IRAM with addresses 0x4010xxxx, see below.
• Code in IROM (flash) with addresses 0x402xxxxx require a hardware breakpoint (command hbr), see below.
• There is only one hardware breakpoint (command hbr).
• There is only one hardware watchpoint (command watch).
• Stepwise execution on source code level is only possible in IRAM with addresses 0x4010xxxx, see below.

If you want to use multiple software breakpoints or execute stepwise on source code level, you have to ensure that the function you want to debug is located in RAM. For that purpose, add the IRAM attribute to that function, for example:

#include "esp/common_macros.h"
...
void IRAM my_func(void)
{
    ...
}

Then you should be able to set a breakpoint to this function using command bp and to execute it stepwise after break.

Another option is to use gdbstub_do_break() wherever you want to break the execution. If you know where you want to break before downloading the program to the target, you can use gdbstub_do_break() as much as you want.

Back to table of contents

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

Files
file	gpio_arch.h
	Architecture specific GPIO functions for ESP8266.
file	irq_arch.h
	Implementation of the kernels irq interface.
file	periph_cpu.h
	CPU specific definitions and functions for peripheral handling.
file	sdk_conf.h
	SDK configuration compatible to the ESP-IDF.
file	syscalls.h
	Implementation of required system calls.