cpu/esp8266: doc restructured for esp_now_netdev
This commit is contained in:
Gunar Schorcht
Schorcht
parent
cd1bd3811c
commit
3d2df7114f
@ -8,22 +8,25 @@
|
||||
## <a name="esp8266_toc"> Table of Contents </a>
|
||||
|
||||
1. [Overview](#esp8266_overview)
|
||||
2. [MCU ESP8266](#esp8266_mcu_esp8266)
|
||||
3. [Toolchain](#esp8266_toolchain)
|
||||
2. [Short Configuration Reference](#esp8266_short_configuration_reference)
|
||||
3. [MCU ESP8266](#esp8266_mcu_esp8266)
|
||||
1. [Features of ESP8266](#esp8266_features)
|
||||
2. [Features Supported by RIOT-OS](#esp8266_supported_features)
|
||||
4. [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)
|
||||
5. [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)
|
||||
4. [Erasing the Device](#esp8266_erasing)
|
||||
5. [Peripherals](#esp8266_peripherals)
|
||||
6. [Peripherals](#esp8266_peripherals)
|
||||
1. [GPIO pins](#esp8266_gpio_pins)
|
||||
2. [ADC Channels](#esp8266_adc_channels)
|
||||
3. [SPI Interfaces](#esp8266_spi_interfaces)
|
||||
3. [PWM Channels](#esp8266_pwm_channels)
|
||||
4. [I2C Interfaces](#esp8266_i2c_interfaces)
|
||||
5. [PWM Channels](#esp8266_pwm_channels)
|
||||
5. [SPI Interfaces](#esp8266_spi_interfaces)
|
||||
6. [Timers](#esp8266_timers)
|
||||
7. [SPIFFS Device](#esp8266_spiffs_device)
|
||||
8. [Other Peripherals](#esp8266_other_peripherals)
|
||||
@ -39,6 +42,7 @@
|
||||
9. [SDK Task Handling](#esp8266_sdk_task_handling)
|
||||
10. [QEMU Mode and GDB](#esp8266_qemu_mode_and_gdb)
|
||||
|
||||
|
||||
# <a name="esp8266_overview"> Overview </a> [[TOC](#esp8266_toc)]
|
||||
|
||||
There are two implementations that can be used:
|
||||
@ -58,10 +62,44 @@ 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> [[TOC](#esp8266_toc)]
|
||||
# <a name="esp8266_short_configuration_reference"> Short Configuration Reference </a> [[TOC](#esp8266_toc)]
|
||||
|
||||
The following table gives a short reference of all board configuration parameters used by the ESP8266 port in alphabetical order.
|
||||
|
||||
<center>
|
||||
|
||||
Parameter | Short Description | Type*
|
||||
----------|----------------------------------------|------
|
||||
[I2C0_SPEED](#esp8266_i2c_interfaces)| Bus speed of I2C_DEV(0) | o
|
||||
[I2C0_SCL](#esp8266_i2c_interfaces) | GPIO used as SCL for I2C_DEV(0) | o
|
||||
[I2C0_SDA](#esp8266_i2c_interfaces) | GPIO used as SCL for I2C_DEV(0 | o
|
||||
[PWM0_GPIOS](#esp8266_pwm_channels) | GPIOs that can be used at channels of PWM_DEV(0) | o
|
||||
[SPI0_CS0](#esp8266_spi_interfaces) | GPIO used as default CS for SPI_DEV(0) | o
|
||||
|
||||
</center>
|
||||
|
||||
<b>Type:</b> m - mandatory, o - optional# <a name=esp8266_mcu_esp8266> MCU ESP8266 </a> [[TOC](#esp8266_toc)]
|
||||
|
||||
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```.
|
||||
|
||||
<center>
|
||||
|
||||
Module | Default | Short description
|
||||
----------|----------|-------------------
|
||||
[esp_gdb](#esp8266_qemu_mode_and_gdb) | not used | enable the compilation with debug information for debugging
|
||||
[esp_now](#esp8266_esp_now_network_interface) | not used | enable the ESP-NOW network device
|
||||
[esp_sdk](#esp8266_sdk_task_handling) | not used | Enable the SDK version, which is equivalent to using ```USE_SDK=1```
|
||||
[esp_spiffs](#esp8266_spiffs_device) | not used | Enable the SPIFFS drive in on-board flash memory
|
||||
[esp_sw_timer](#esp8266_timers) | not used | Enable software timer implementation, implies the module ```esp_sdk```
|
||||
|
||||
</center>
|
||||
|
||||
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:
|
||||
|
||||
## <a name=esp8266_features> Features of ESP8266 </a> [[TOC](#esp8266_toc)]
|
||||
|
||||
The key features of ESP8266 are:
|
||||
|
||||
<center>
|
||||
|
||||
MCU | ESP8266EX
|
||||
@ -88,6 +126,22 @@ Technical Reference | [Technical Reference](https://www.espressif.com/sites/defa
|
||||
|
||||
@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_supported_features"> Features Supported by RIOT-OS </a> [[TOC](#esp8266_toc)]
|
||||
|
||||
The RIOT-OS for ESP8266 SoCs supports the following features at the moment:
|
||||
|
||||
- I2C interfaces
|
||||
- SPI interfaces
|
||||
- UART interfaces
|
||||
- CPU ID access
|
||||
- ADC channel
|
||||
- PWM channels
|
||||
- SPI Flash Drive (MTD with SPIFFS and VFS)
|
||||
- Hardware number generator
|
||||
- Hardware timer devices
|
||||
- ESP-NOW netdev interface
|
||||
|
||||
|
||||
# <a name="esp8266_toolchain"> Toolchain</a> [[TOC](#esp8266_toc)]
|
||||
|
||||
To compile RIOT for The ESP8266 SoC, the following software components are required:
|
||||
@ -460,35 +514,33 @@ ESP8266 has **one dedicated ADC** pin with a resolution of 10 bits. This ADC pin
|
||||
|
||||
@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> [[TOC](#esp8266_toc)]
|
||||
## <a name="esp8266_pwm_channels"> PWM Channels </a> [[TOC](#esp8266_toc)]
|
||||
|
||||
ESP8266 provides two hardware SPI interfaces:
|
||||
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.
|
||||
|
||||
- _FSPI_ for flash memory access that is usually simply referred to as _SPI_
|
||||
- _HSPI_ for peripherals
|
||||
@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.
|
||||
|
||||
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)```.
|
||||
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.
|
||||
|
||||
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```.
|
||||
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.
|
||||
|
||||
<center>
|
||||
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)
|
||||
|
||||
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.
|
||||
```
|
||||
#define PWM0_CHANNEL_GPIOS { GPIO12, GPIO13, GPIO14, GPIO15 }
|
||||
```
|
||||
|
||||
## <a name="esp8266_i2c_interfaces"> I2C Interfaces </a> [[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)```.
|
||||
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)```.
|
||||
|
||||
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.
|
||||
The board-specific configuration of the I2C interface <b>```I2C_DEV(n)```</b> requires the definition of
|
||||
|
||||
- <b>```I2Cn_SPEED```</b>, the bus speed,
|
||||
- <b>```I2Cn_SCL```</b>, the GPIO used as SCL signal, and
|
||||
- <b>```I2Cn_SDA```</b>, the GPIO used as SDA signal,
|
||||
|
||||
where ```n``` can be 0 or 1. If they are not defined, the I2C interface ```I2C_DEV(n)``` is not used.
|
||||
|
||||
In the following example, only one I2C bus is defined:
|
||||
|
||||
@ -515,22 +567,37 @@ A configuration with two I2C buses would look like the following:
|
||||
|
||||
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> [[TOC](#esp8266_toc)]
|
||||
## <a name="esp8266_spi_interfaces"> SPI Interfaces </a> [[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.
|
||||
ESP8266 provides two hardware SPI interfaces:
|
||||
|
||||
@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.
|
||||
- _FSPI_ for flash memory access that is usually simply referred to as _SPI_
|
||||
- _HSPI_ for peripherals
|
||||
|
||||
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.
|
||||
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)```.
|
||||
|
||||
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.
|
||||
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).
|
||||
|
||||
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)
|
||||
<center>
|
||||
|
||||
Signal of _HSPI_ | Pin
|
||||
-----------------|-------
|
||||
MISO | GPIO12
|
||||
MOSI | GPIO13
|
||||
SCK | GPIO14
|
||||
CS | GPIO15
|
||||
|
||||
</center>
|
||||
|
||||
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.
|
||||
|
||||
To the default CS can be overridden as following:
|
||||
```
|
||||
#define PWM0_CHANNEL_GPIOS { GPIO12, GPIO13, GPIO14, GPIO15 }
|
||||
#define SPI0_CS0_GPIO GPIO15 /* HSPI/SPI_DEV(0) CS default pin */
|
||||
```
|
||||
|
||||
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_timers"> Timers </a> [[TOC](#esp8266_toc)]
|
||||
|
||||
There are two timer implementations:
|
||||
@ -557,6 +624,34 @@ 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_esp_now_network_interface"> ESP-NOW Network Interface </a> [[TOC](#esp8266_toc)]
|
||||
|
||||
With ESP-NOW, the ESP8266 provides a connectionless communication technology, featuring short packet transmission. It applies the IEEE802.11 Action Vendor frame technology, along with the IE function developed by Espressif, and CCMP encryption technology, realizing a secure, connectionless communication solution.
|
||||
|
||||
The RIOT port for ESP8266 implements in module ```esp_now``` a ```netdev``` driver which uses ESP-NOW to provide a link layer interface to a meshed network of ESP8266 nodes. In this network, each node can send short packets with up to 250 data bytes to all other nodes that are visible in its range.
|
||||
|
||||
@note Due to symbol conflicts in the ```esp_idf_wpa_supplicant_crypto``` module used by the ```esp_now``` with RIOT's ```crypto``` and ```hashes``` modules, ESP-NOW cannot be used for application that use these modules.
|
||||
|
||||
Therefore, the module ```esp_now``` is not enabled automatically if the ```netdev_default``` module is used. Instead, the application has to add the ```esp_now``` module in its makefile when needed.
|
||||
```
|
||||
USEMODULE += esp_now
|
||||
```
|
||||
|
||||
For ESP-NOW, ESP8266 nodes are used in WiFi SoftAP + Station mode to advertise their SSID and become visible to other ESP8266 nodes. The SSID of an ESP8266 node is the concatenation of the prefix ```RIOT_ESP_``` with the MAC address of its SoftAP WiFi interface. The driver periodically scans all visible ESP8266 nodes.
|
||||
|
||||
The following parameters are defined for ESP-NOW nodes. These parameters can be overriden by [application-specific board configurations](#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_PASSPHRASE | ThisistheRIOTporttoESP | Defines the passphrase (max. 64 chars) that is used for the SoftAP interface of an 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.
|
||||
|
||||
</center>
|
||||
|
||||
## <a name="esp8266_other_peripherals"> Other Peripherals </a> [[TOC](#esp8266_toc)]
|
||||
|
||||
The ESP8266 port of RIOT also supports
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user