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`.
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:
@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.
- **esp-open-sdk** which includes the **Xtensa GCC** compiler toolchain, the hardware abstraction library **libhal** for Xtensa LX106, and the flash programmer tool <b>`esptool.py`</b>
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:
The ESP Flasher tool <b>`esptool.py`</b> is available at [GitHub](https://github.com/espressif/esptool). 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`:
A `riotdocker` fork that only installs the `RIOT-Xtensa-ESP8266-toolchain` is available at [GitHub](https://github.com/gschorcht/riotdocker-Xtensa-ESP.git). After cloning this git repository, you can use branch `esp8266_only` to generate a Docker image with a size of "only" 990 MByte:
A `riotdocker` version that contains the toolchains for all different RIOT platforms can be found at [GitHub](https://github.com/RIOT-OS/riotdocker). However, the Docker image generated from the this Docker file has a size of about 1.5 GByte.
@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.
Alternatively, an existing Docker image from Docker Hub can be used. You can either pull and start the [schorcht/riotbuild_esp8266](https://hub.docker.com/r/schorcht/riotbuild_esp8266) Docker image which only contains the `RIOT-Xtensa-ESP8266-toolchain` using
or the [riot/riotbuild](https://hub.docker.com/r/riot/riotbuild/) Docker image (size is about 1.5 GB) which contains the toolchains for all platforms using
### <a name="esp8266_flashing_using_docker"> Make Process with Docker Image </a> [[TOC](#esp8266_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:
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.
You can get a precompiled version of the whole toolchain from the GIT repository [RIOT-Xtensa-ESP8266-toolchain](https://github.com/gschorcht/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:<br> `cppcheck` `coccinelle` `curl` `doxygen` `git` `graphviz` `make` `pcregrep` `python` `python-serial` `python3` `python3-flake8` `unzip` `wget`
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.
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:
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.
### <a name="esp8266_installation_of_espressif_original_sdk"> Installation of Espressif original SDK (optional) </a> [[TOC](#esp8266_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](https://github.com/espressif/ESP8266_NONOS_SDK/releases/tag/v2.1.0). 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
ENABLE_GDB | 0, 1 | 0 | Enable compilation with debug information for debugging with QEMU (`QEMU=1`), see section [QEMU Mode and GDB](#esp8266_qemu_mode_and_gdb)
[esp_gdb](#esp8266_qemu_mode_and_gdb) | Enable the compilation with debug information, which is equivalent to using `ENABLE_GDB=1`.
[esp_now](#esp8266_esp_now_network_interface) | Enable the built-in WiFi module with the ESP-NOW protocol as `netdev` network device, implies the setting module `esp_sdk`.
[esp_sdk](#esp8266_sdk_task_handling) | Enable the SDK version, which is equivalent to using `USE_SDK=1`.
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:
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.
@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`.
## <a name="esp8266_erasing"> Erasing the Device </a> [[TOC](#esp8266_toc)]
The flash memory of ESP8266 can be erased completely with following command:
```
esptool.py erase_flash
```
@note 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:
- Flash and start a non-SDK image before the SDK version is flashed.
- Use the esptool.py file to update the default init data as following.
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.
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](#esp8266_application_specific_board_configuration)
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 `I2C_SPEED_FAST_PLUS`. The maximum number of buses that can be defined is 2, `I2C_DEV(0)` ... `I2C_DEV(1)`.
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 is defined as shown in the following table. Only the CS signal can be configured and overridden by [application-specific card configuration] (# esp8266_application_specific_board_configuration).
When SPI is enabled using module `periph_spi`, these GPIOs cannot be used for any other purpose. The given CS pin is used when `spi_acquire` is called with `cs=GPIO_UNDEF` parameter.
GPIOs 0, 2, 4, 5, 15, and 16 can be used as CS signal. In `dio` and `dout` flash modes (see section [Flash Modes](#esp8266_flash_modes)), GPIOs 9 and 10 can also be used as CS signal.
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.
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:
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`.
the application has to add the `esp_now` module in its makefile when needed.<br>
```
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](#esp8266_application_specific_board_configuration).
<center>
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.
ESP_WIFI_STACKSIZE | @ref THREAD_STACKSIZE_DEFAULT | Stack size used for the WiFi netdev driver thread.
The ESP8266 port of RIOT has been tested with several common external devices that can be connected to ESP8266 boards and are preconfigured accordingly.
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:
ESP8266 port of RIOT is preconfigured for RIOT applications that use the [SPI SD-Card driver](https://riot-os.org/api/group__drivers__sdcard__spi.html). To use SPI SD-Card driver, the `sdcard_spi` module has to be added to a makefile:
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.
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 <b>last</b> 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:
It is important to ensure that the application-specific board configuration `$APPDIR/board.h` is included first. Insert the following line as the <b>first</b> line to the application makefile `$APPDIR/Makefile`.
@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
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 <b>last</b> 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:
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 <b>first</b> 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:
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.
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
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:
