RIOT/cpu/esp8266/doc.txt

/**
@defgroup        cpu_esp8266 ESP8266 / ESP8285 MCU
@ingroup         cpu
@brief           RIOT-OS port for Espressif's ESP8266 / ESP8285 MCUs

\section esp8266_riot  RIOT-OS on ESP8266 and ESP8285 boards

## <a name="esp8266_toc"> Table of Contents </a>

1. [Overview](#esp8266_overview)
2. [MCU ESP8266](#esp8266_mcu_esp8266)
3. [Toolchain](#esp8266_toolchain)
    1. [RIOT Docker Toolchain (riotdocker)](#esp8266_riot_docker_toolchain)
    2. [Precompiled Toolchain](#esp8266_precompiled_toolchain)
    3. [Manual Toolchain Installation](#esp8266_manual_toolchain_installation)
4. [Flashing the Device](#esp8266_flashing_the_device)
    1. [Toolchain Usage](#esp8266_toolchain_usage)
    2. [Compile Options](#esp8266_compile_options)
    3. [Flash Modes](#esp8266_flash_modes)
5. [Peripherals](#esp8266_peripherals)
    1. [GPIO pins](#esp8266_gpio_pins)
    2. [ADC Channels](#esp8266_adc_channels)
    3. [SPI Interfaces](#esp8266_spi_interfaces)
    4. [I2C Interfaces](#esp8266_i2c_interfaces)
    5. [PWM Channels](#esp8266_pwm_channels)
    6. [Timers](#esp8266_timers)
    7. [SPIFFS Device](#esp8266_spiffs_device)
    8. [Other Peripherals](#esp8266_other_peripherals)
6. [Preconfigured Devices](#esp8266_preconfigured_devices)
    1. [Network Devices](#esp8266_network_devices)
    2. [SD-Card Device](#esp8266_sd_card_device)
7. [Application-Specific Configurations](#esp8266_application_specific_configurations)
    1. [Application-Specific Board Configuration](#esp8266_application_specific_board_configuration)
    2. [Application-Specific Driver Configuration](#esp8266_application_specific_driver_configuration)
8. [SDK Task Handling](#esp8266_sdk_task_handling)
9. [QEMU Mode and GDB](#esp8266_qemu_mode_and_gdb)

# <a name="esp8266_overview"> Overview </a> &nbsp;&nbsp; [[TOC](#esp8266_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](#esp8266_compile_options).

# <a name=esp8266_mcu_esp8266> MCU ESP8266 </a> &nbsp;[[TOC](#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:

<center>

MCU         | ESP8266EX
------------|----------------------------
Vendor      | Espressif
Cores       | 1 x Tensilica Xtensa LX106
FPU         | no
RAM         | 80 kByte user-data RAM <br> 32 kByte instruction RAM <br> 32 kByte instruction cache <br/> 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 <br> 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](https://www.espressif.com/sites/default/files/documentation/0a-esp8266ex_datasheet_en.pdf)
Technical Reference | [Technical Reference](https://www.espressif.com/sites/default/files/documentation/esp8266-technical_reference_en.pdf)

</center><br>

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

# <a name="esp8266_toolchain"> Toolchain</a> &nbsp;[[TOC](#esp8266_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 <b>```esptool.py```</b>
- **newlib-c** library for Xtensa (esp-open-rtos version)
- **SDK (optional)**, either as part of <b>```esp-open-sdk```</b> or the <b>```ESP8266_NONOS_SDK```</b>

You have the following options to install the Toolchain:

- <b>```riotdocker```</b> image and <b>```esptool.py```</b>, see section [RIOT Docker Toolchain (riotdocker)](#esp8266_riot_docker_toolchain)
- **precompiled toolchain** installation from GIT, see section [Precompiled Toolchain](#esp8266_toolchain_installation)
- **manual installation**, see section [Manual Toolchain Installation](#esp8266_manual_toolchain_installation)

## <a name="esp8266_riot_docker_toolchain"> RIOT Docker Toolchain (riotdocker) </a> &nbsp;[[TOC](#esp8266_toc)]

The easiest use the toolchain is Docker.

### <a name="esp8266_preparing_the_environment"> Preparing the Environment </a> &nbsp;[[TOC](#esp8266_toc)]

Using RIOT Docker requires at least the following software:

- <b>```Docker```</b> container virtualization software
- RIOT Docker (<b>```riotdocker```</b>) image
- flasher 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:
```
sudo apt-get install docker.io
```

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```:
```
pip install esptool
```

<b>```esptool.py```</b> 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](https://github.com/espressif/esptool)

Please make sure that ```esptool.py``` is in your ```PATH``` variable.

### <a name="esp8266_generating_docker_image"> Generating a riotdocker Image </a> &nbsp;[[TOC](#esp8266_toc)]

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:

```
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](https://github.com/RIOT-OS/riotdocker). 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](https://github.com/RIOT-OS/RIOT/wiki/Use-Docker-to-build-RIOT) on how to use the Docker image to compile RIOT OS.

### <a name="esp8266_using_existing_docker_image"> Using an Existing riotdocker Image </a> &nbsp;[[TOC](#esp8266_toc)]

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
```
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](https://hub.docker.com/r/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
```
### <a name="esp8266_flashing_using_docker"> Make Process with Docker Image </a> &nbsp;[[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:

```
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
```


## <a name="esp8266_precompiled_toolchain"> Precompiled Toolchain </a> &nbsp;[[TOC](#esp8266_toc)]

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```

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.

## <a name="esp8266_manual_toolchain_installation"> Manual Toolchain Installation </a> &nbsp;[[TOC](#esp8266_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```

### <a name="esp8266_installation_of_esp_open_sdk"> Installation of esp-open-sdk </a> &nbsp;[[TOC](#esp8266_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
```

### <a name="esp8266_installation_of_newlib-c"> Installation of newlib-c </a> &nbsp;[[TOC](#esp8266_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
```

### <a name="esp8266_installation_of_espressif_original_sdk"> Installation of Espressif original SDK (optional) </a> &nbsp;[[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
```

To use the installed SDK, set variable ```ESP8266_SDK_DIR``` accordingly.

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

# <a name="esp8266_flashing_the_device"> Flashing the Device </a> &nbsp;[[TOC](#esp8266_toc)]

## <a name="esp8266_toolchain_usage"> Toolchain Usage </a> &nbsp;[[TOC](#esp8266_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
```

## <a name="esp8266_compile_options"> Compile Options </a> &nbsp;[[TOC](#esp8266_toc)]

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

<center>

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](#esp8266_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](#esp8266_flash_modes)
NETDEV_DEFAULT | module name | mrf24j40 | Set the module that is used as default network device, see section [Network Devices](#esp8266_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](#esp8266_qemu_mode_and_gdb).
USE_SDK | 0, 1 | 0 | Compile the SDK version (```USE_SDK=1```), see section [SDK Task Handling](#esp8266_sdk_task_handling)

</center><br>

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

<center>

Module | Description
-------|------------
esp_spiffs | Enables the SPIFFS file system, see section [SPIFFS Device](#esp8266_spiffs_device)
esp_sw_timer | Enables software timer implementation, implies the setting ```USE_SDK=1```, see section [Timers](#esp8266_timers)

</center><br>

## <a name="esp8266_flash_modes"> Flash Modes </a> &nbsp;[[TOC](#esp8266_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](https://github.com/espressif/esptool/wiki/SPI-Flash-Modes).

@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_peripherals"> Peripherals </a> &nbsp;[[TOC](#esp8266_toc)]

## <a name="esp8266_gpio_pins"> GPIO pins </a> &nbsp;[[TOC](#esp8266_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.

<center>

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](#esp8266_flash_modes)
GPIO10 | Flash SPI in ```qout``` and ```qio``` mode, see section [Flash Modes](#esp8266_flash_modes)
GPIO11 | Flash SPI
GPIO12 | |
GPIO13 | |
GPIO14 | |
GPIO15 | usually pulled down
GPIO16 | RTC pin and wake up signal in deep sleep mode

</center>

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

<center>

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)

</center>

## <a name="esp8266_adc_channels"> ADC Channels </a> &nbsp;[[TOC](#esp8266_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.

## <a name="esp8266_spi_interfaces"> SPI Interfaces </a> &nbsp;[[TOC](#esp8266_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](#esp8266_application_specific_board_configuration) is the CS signal defined by ```SPI0_CS0_GPIO```.

<center>

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)

</center>

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](#esp8266_flash_modes)), GPIOs 9 and 10 can also be used as CS signal.

## <a name="esp8266_i2c_interfaces"> I2C Interfaces </a> &nbsp;[[TOC](#esp8266_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](#esp8266_application_specific_board_configuration).

## <a name="esp8266_pwm_channels"> PWM Channels </a> &nbsp;[[TOC](#esp8266_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](#esp8266_application_specific_board_configuration)

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

## <a name="esp8266_timers"> Timers </a> &nbsp;[[TOC](#esp8266_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```).

## <a name="esp8266_spiffs_device"> SPIFFS Device </a> &nbsp;[[TOC](#esp8266_toc)]

If SPIFFS module is enabled (```USE_SPIFFS=1```), 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```.

## <a name="esp8266_other_peripherals"> Other Peripherals </a> &nbsp;[[TOC](#esp8266_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.

# <a name="esp8266_preconfigured_devices"> Preconfigured Devices </a> &nbsp;[[TOC](#esp8266_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.

## <a name="esp8266_network_devices"> Network Devices </a> &nbsp;[[TOC](#esp8266_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](http://riot-os.org/api/group__drivers__mrf24j40.html) (driver for Microchip MRF24j40 based IEEE 802.15.4
- [enc28j60](http://riot-os.org/api/group__drivers__enc28j60.html) (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.

### <a name="esp8266_using_mrf24j40"> Using MRF24J40 (module ```mrf24j40```) </a> &nbsp;[[TOC](#esp8266_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:

<center>

Parameter              | Default      | Remarks
-----------------------|--------------|----------------------------
MRF24J40_PARAM_SPI     | SPI_DEV(0)   | fix, see section [SPI Interfaces](#esp8266_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

</center><br>

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](#esp8266_application_specific_board_configuration).

### <a name="esp8266_using_enc28j60"> Using ENC28J60 (module ```enc28j60```) </a> &nbsp;[[TOC](#esp8266_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:

<center>

Parameter            | Default      | Remarks
---------------------|--------------|----------------------------
ENC28J60_PARAM_SPI   | SPI_DEV(0)   | fix, see section [SPI Interfaces](#esp8266_spi_interfaces)
ENC28J60_PARAM_CS    | GPIO4        | can be overridden
ENC28J60_PARAM_INT   | GPIO9        | can be overridden
ENC28J60_PARAM_RESET | GPIO10       | can be overridden

</center>

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](#esp8266_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
```

## <a name="esp8266_sd_card_device"> SD-Card Device </a> &nbsp;[[TOC](#esp8266_toc)]

ESP8266 port of RIOT is preconfigured for RIOT applications that use the [SPI SD-Card driver](http://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:

```
USEMODULE += sdcard_spi
```

Module ```sdcard_spi``` uses the following interface parameters by default:

<center>

Parameter              | Default       | Remarks
-----------------------|---------------|----------------------------
SDCARD_SPI_PARAM_SPI   | SPI0_DEV      | fix, see section [SPI Interfaces](#esp8266_spi_interfaces)
SDCARD_SPI_PARAM_CS    | SPI0_CS0_GPIO | can be overridden

</center>

The GPIO used as CS signal can be overridden by an [application-specific board configuration](#esp8266_application_specific_board_configuration).

# <a name="esp8266_application_specific_configurations"> Application-Specific Configurations </a> &nbsp;[[TOC](#esp8266_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.

\anchor esp8266_app_spec_conf
## <a name="esp8266_application_specific_board_configuration"> Application-Specific Board Configuration </a> &nbsp;[[TOC](#esp8266_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)
```

## <a name="esp8266_application_specific_driver_configuration"> Application-Specific Driver Configuration </a> &nbsp;[[TOC](#esp8266_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)
```

# <a name="esp8266_sdk_task_handling"> SDK Task Handling </a> &nbsp;[[TOC](#esp8266_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.

# <a name="esp8266_qemu_mode_and_gdb"> QEMU Mode and GDB </a> &nbsp;[[TOC](#esp8266_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
```
*/