arduino/esp8266
1
0
Fork 0
mirror of https://github.com/esp8266/Arduino.git synced 2025-04-19 23:22:16 +03:00
Code

docs: convert to .rst and add readthedocs

Browse Source
This commit is contained in:
Ivan Grokhotkov 2017-02-19 16:55:37 +08:00 committed by Ivan Grokhotkov
parent 5c7247b0f4
commit 283eb97cd3
81 changed files with 7191 additions and 6324 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
.travis.yml
View File

@ -3,23 +3,25 @@ language: bash
os: os:
- linux - linux
addons: dist: trusty
apt:
sources: install:
- ubuntu-toolchain-r-test - pip install --user -r doc/requirements.txt
packages:
- g++-4.8
script: script:
- set -e - set -e
- export CXX="g++-4.8" CC="gcc-4.8" GCOV="gcov-4.8" - echo -e "travis_fold:start:docs"
- pushd $TRAVIS_BUILD_DIR/doc
- SPHINXOPTS="-W" make html
- popd
- echo -e "travis_fold:end:docs"
- echo -e "travis_fold:start:host_tests" - echo -e "travis_fold:start:host_tests"
- pushd $TRAVIS_BUILD_DIR/tests/host - pushd $TRAVIS_BUILD_DIR/tests/host
- make - make
- make clean-objects - make clean-objects
- popd
- echo -e "travis_fold:end:host_tests" - echo -e "travis_fold:end:host_tests"
- echo -e "travis_fold:start:sketch_test_env_prepare" - echo -e "travis_fold:start:sketch_test_env_prepare"
- popd
- wget -O arduino.tar.xz https://www.arduino.cc/download.php?f=/arduino-nightly-linux64.tar.xz - wget -O arduino.tar.xz https://www.arduino.cc/download.php?f=/arduino-nightly-linux64.tar.xz
- tar xf arduino.tar.xz - tar xf arduino.tar.xz
- mv arduino-nightly $HOME/arduino_ide - mv arduino-nightly $HOME/arduino_ide
@ -42,10 +44,6 @@ script:
- cat size.log - cat size.log
- echo -e "travis_fold:end:size_report" - echo -e "travis_fold:end:size_report"
after_success:
- pushd $TRAVIS_BUILD_DIR/tests/host
- bash <(curl -s https://codecov.io/bash) -X gcov
notifications: notifications:
email: email:
on_success: change on_success: change

1
doc/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
_build

20
doc/Makefile Normal file
View File

@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = ESP8266ArduinoCore
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

102
doc/Troubleshooting/debugging.md
View File

@ -1,102 +0,0 @@
---
title: Debugging
---
## Table of Contents
* [Introduction](#introduction)
* [Requirements](#requirements)
* [Usage](#Usage)
* [Informations](#Informations)
* [For Developers](#for-developers)
## Introduction
Since 2.1.0-rc1 the core includes a Debugging feature that is controllable over the IDE menu.
The new menu points manage the real-time Debug messages.
### Requirements
For usage of the debugging a Serial connection is required (Serial or Serial1).
The Serial Interface need to be initialized in the ```setup()```.
Set the Serial baud rate as high as possible for your Hardware setup.
Minimum sketch to use debugging:
```cpp
void setup() {
Serial.begin(115200);
}
void loop() {
}
```
### Usage
1. Select the Serial interface for the Debugging messages:
![Debug-Port](debug_port.png)
2. Select which type / level you want debug messages for:
![Debug-Level](debug_level.png)
3. Check if the Serial interface is initialized in ```setup()``` (see [Requirements](#requirements))
4. Flash sketch
5. Check the Serial Output
## Informations
It work with every sketch that enables the Serial interface that is selected as debug port.
The Serial interface can still be used normal in the Sketch.
The debug output is additional and will not disable any interface from usage in the sketch.
### For Developers
For the debug handling uses defines.
The defined are set by command line.
#### Debug Port
The port has the define ```DEBUG_ESP_PORT``` possible value:
- Disabled: define not existing
- Serial: Serial
- Serial1: Serial1
#### Debug Level
All defines for the different levels starts with ```DEBUG_ESP_```
a full list can be found here in the [boards.txt](https://github.com/esp8266/Arduino/blob/master/boards.txt#L180)
#### Example for own debug messages
The debug messages will be only shown when the Debug Port in the IDE menu is set.
```cpp
#ifdef DEBUG_ESP_PORT
#define DEBUG_MSG(...) DEBUG_ESP_PORT.printf( __VA_ARGS__ )
#else
#define DEBUG_MSG(...)
#endif
void setup() {
Serial.begin(115200);
delay(3000);
DEBUG_MSG("bootup...\n");
}
void loop() {
DEBUG_MSG("loop %d\n", millis());
delay(1000);
}
```

107
doc/Troubleshooting/debugging.rst Normal file
View File

@ -0,0 +1,107 @@
Debugging
=========
Introduction
------------
Since 2.1.0-rc1 the core includes a Debugging feature that is
controllable over the IDE menu.
The new menu points manage the real-time Debug messages.
Requirements
~~~~~~~~~~~~
For usage of the debugging a Serial connection is required (Serial or
Serial1).
The Serial Interface need to be initialized in the ``setup()``.
Set the Serial baud rate as high as possible for your Hardware setup.
Minimum sketch to use debugging:
.. code:: cpp
void setup() {
Serial.begin(115200);
}
void loop() {
}
Usage
~~~~~
1. Select the Serial interface for the Debugging messages: |Debug-Port|
2. Select which type / level you want debug messages for: |Debug-Level|
3. Check if the Serial interface is initialized in ``setup()`` (see
`Requirements <#requirements>`__)
4. Flash sketch
5. Check the Serial Output
Informations
------------
It work with every sketch that enables the Serial interface that is
selected as debug port.
The Serial interface can still be used normal in the Sketch.
The debug output is additional and will not disable any interface from
usage in the sketch.
For Developers
~~~~~~~~~~~~~~
For the debug handling uses defines.
The defined are set by command line.
Debug Port
^^^^^^^^^^
The port has the define ``DEBUG_ESP_PORT`` possible value: - Disabled:
define not existing - Serial: Serial - Serial1: Serial1
Debug Level
^^^^^^^^^^^
All defines for the different levels starts with ``DEBUG_ESP_``
a full list can be found here in the
`boards.txt <https://github.com/esp8266/Arduino/blob/master/boards.txt#L180>`__
Example for own debug messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The debug messages will be only shown when the Debug Port in the IDE
menu is set.
.. code:: cpp
#ifdef DEBUG_ESP_PORT
#define DEBUG_MSG(...) DEBUG_ESP_PORT.printf( __VA_ARGS__ )
#else
#define DEBUG_MSG(...)
#endif
void setup() {
Serial.begin(115200);
delay(3000);
DEBUG_MSG("bootup...\n");
}
void loop() {
DEBUG_MSG("loop %d\n", millis());
delay(1000);
}
.. |Debug-Port| image:: debug_port.png
.. |Debug-Level| image:: debug_level.png

66
doc/Troubleshooting/stack_dump.md
View File

@ -1,66 +0,0 @@
---
title: Debugging
---
## Table of Contents
* [Introduction](#introduction)
* [Decode](#Decode)
## Introduction
If the ESP crash the Exception Cause will be shown and the current stack will be dumped.
example:
```
Exception (0): epc1=0x402103f4 epc2=0x00000000 epc3=0x00000000 excvaddr=0x00000000 depc=0x00000000
ctx: sys
sp: 3ffffc10 end: 3fffffb0 offset: 01a0
>>>stack>>>
3ffffdb0: 40223e00 3fff6f50 00000010 60000600
3ffffdc0: 00000001 4021f774 3fffc250 4000050c
3ffffdd0: 400043d5 00000030 00000016 ffffffff
3ffffde0: 400044ab 3fffc718 3ffffed0 08000000
3ffffdf0: 60000200 08000000 00000003 00000000
3ffffe00: 0000ffff 00000001 04000002 003fd000
3ffffe10: 3fff7188 000003fd 3fff2564 00000030
3ffffe20: 40101709 00000008 00000008 00000020
3ffffe30: c1948db3 394c5e70 7f2060f2 c6ba0c87
3ffffe40: 3fff7058 00000001 40238d41 3fff6ff0
3ffffe50: 3fff6f50 00000010 60000600 00000020
3ffffe60: 402301a8 3fff7098 3fff7014 40238c77
3ffffe70: 4022fb6c 40230ebe 3fff1a5b 3fff6f00
3ffffe80: 3ffffec8 00000010 40231061 3fff0f90
3ffffe90: 3fff6848 3ffed0c0 60000600 3fff6ae0
3ffffea0: 3fff0f90 3fff0f90 3fff6848 3fff6d40
3ffffeb0: 3fff28e8 40101233 d634fe1a fffeffff
3ffffec0: 00000001 00000000 4022d5d6 3fff6848
3ffffed0: 00000002 4000410f 3fff2394 3fff6848
3ffffee0: 3fffc718 40004a3c 000003fd 3fff7188
3ffffef0: 3fffc718 40101510 00000378 3fff1a5b
3fffff00: 000003fd 4021d2e7 00000378 000003ff
3fffff10: 00001000 4021d37d 3fff2564 000003ff
3fffff20: 000003fd 60000600 003fd000 3fff2564
3fffff30: ffffff00 55aa55aa 00000312 0000001c
3fffff40: 0000001c 0000008a 0000006d 000003ff
3fffff50: 4021d224 3ffecf90 00000000 3ffed0c0
3fffff60: 00000001 4021c2e9 00000003 3fff1238
3fffff70: 4021c071 3ffecf84 3ffecf30 0026a2b0
3fffff80: 4021c0b6 3fffdab0 00000000 3fffdcb0
3fffff90: 3ffecf40 3fffdab0 00000000 3fffdcc0
3fffffa0: 40000f49 40000f49 3fffdab0 40000f49
<<<stack<<<
```
the first number after ```Exception``` gives the cause of the reset.
a full ist of all causes can be found [here](../exception_causes.md)
the hex after are the stack dump.
### Decode
it's possible to decode the Stack to readable information.
more info see [Esp Exception Decoder](https://github.com/me-no-dev/EspExceptionDecoder) tool
![ESP Exception Decoder](ESP_Exception_Decoderp.png)

65
doc/Troubleshooting/stack_dump.rst Normal file
View File

@ -0,0 +1,65 @@
Stack Dumps
===========
Introduction
------------
If the ESP crash the Exception Cause will be shown and the current stack will be dumped.
Example:
::
Exception (0): epc1=0x402103f4 epc2=0x00000000 epc3=0x00000000 excvaddr=0x00000000 depc=0x00000000
ctx: sys
sp: 3ffffc10 end: 3fffffb0 offset: 01a0
>>>stack>>>
3ffffdb0: 40223e00 3fff6f50 00000010 60000600
3ffffdc0: 00000001 4021f774 3fffc250 4000050c
3ffffdd0: 400043d5 00000030 00000016 ffffffff
3ffffde0: 400044ab 3fffc718 3ffffed0 08000000
3ffffdf0: 60000200 08000000 00000003 00000000
3ffffe00: 0000ffff 00000001 04000002 003fd000
3ffffe10: 3fff7188 000003fd 3fff2564 00000030
3ffffe20: 40101709 00000008 00000008 00000020
3ffffe30: c1948db3 394c5e70 7f2060f2 c6ba0c87
3ffffe40: 3fff7058 00000001 40238d41 3fff6ff0
3ffffe50: 3fff6f50 00000010 60000600 00000020
3ffffe60: 402301a8 3fff7098 3fff7014 40238c77
3ffffe70: 4022fb6c 40230ebe 3fff1a5b 3fff6f00
3ffffe80: 3ffffec8 00000010 40231061 3fff0f90
3ffffe90: 3fff6848 3ffed0c0 60000600 3fff6ae0
3ffffea0: 3fff0f90 3fff0f90 3fff6848 3fff6d40
3ffffeb0: 3fff28e8 40101233 d634fe1a fffeffff
3ffffec0: 00000001 00000000 4022d5d6 3fff6848
3ffffed0: 00000002 4000410f 3fff2394 3fff6848
3ffffee0: 3fffc718 40004a3c 000003fd 3fff7188
3ffffef0: 3fffc718 40101510 00000378 3fff1a5b
3fffff00: 000003fd 4021d2e7 00000378 000003ff
3fffff10: 00001000 4021d37d 3fff2564 000003ff
3fffff20: 000003fd 60000600 003fd000 3fff2564
3fffff30: ffffff00 55aa55aa 00000312 0000001c
3fffff40: 0000001c 0000008a 0000006d 000003ff
3fffff50: 4021d224 3ffecf90 00000000 3ffed0c0
3fffff60: 00000001 4021c2e9 00000003 3fff1238
3fffff70: 4021c071 3ffecf84 3ffecf30 0026a2b0
3fffff80: 4021c0b6 3fffdab0 00000000 3fffdcb0
3fffff90: 3ffecf40 3fffdab0 00000000 3fffdcc0
3fffffa0: 40000f49 40000f49 3fffdab0 40000f49
<<<stack<<<
The first number after ``Exception`` gives the cause of the reset. a
full ist of all causes can be found :doc:`here <../exception_causes>`
the hex after are the stack dump.
Decode
~~~~~~
It's possible to decode the Stack to readable information. For more info see the `Esp Exception Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ tool.
.. figure:: ESP_Exception_Decoderp.png
:alt: ESP Exception Decoder
ESP Exception Decoder

0
doc/_static/.keep vendored Normal file
View File

319
doc/boards.md
View File

@ -1,319 +0,0 @@
---
title: Supported Hardware
---
## Table of contents
* [Adafruit HUZZAH ESP8266 (ESP\-12)](#adafruit-huzzah-esp8266-esp-12)
* [ESPresso Lite 1\.0](#espresso-lite-10)
* [ESPresso Lite 2\.0](#espresso-lite-20)
* [NodeMCU 0\.9 <a name="user\-content\-nodemcu\-0\-9"></a>](#nodemcu-09-)
* [Pin mapping](#pin-mapping)
* [NodeMCU 1\.0](#nodemcu-10)
* [Olimex MOD\-WIFI\-ESP8266\-DEV](#olimex-mod-wifi-esp8266-dev)
* [Olimex MOD\-WIFI\-ESP8266](#olimex-mod-wifi-esp8266)
* [Olimex ESP8266\-EVB](#olimex-esp8266-evb)
* [Phoenix 1\.0](#phoenix-10)
* [Phoenix 2\.0](#phoenix-20)
* [SparkFun ESP8266 Thing](#sparkfun-esp8266-thing)
* [SweetPea ESP\-210](#sweetpea-esp-210)
* [ESPino](#espino)
* [WifInfo](#WifInfo)
* [Generic ESP8266 modules](#generic-esp8266-modules)
* [Generic ESP8285 modules](#generic-esp8285-modules)
* [Serial Adapter](#serial-adapter)
* [Minimal Hardware Setup for Bootloading and Usage](#minimal-hardware-setup-for-bootloading-and-usage)
* [ESP to Serial](#esp-to-serial)
* [Minimal Hardware Setup for Bootloading only](#minimal-hardware-setup-for-bootloading-only)
* [Minimal Hardware Setup for Running only](#minimal-hardware-setup-for-running-only)
* [Minimal](#minimal)
* [Improved Stability](#improved-stability)
* [Boot Messages and Modes](#boot-messages-and-modes)
* [rst cause](#rst-cause)
* [boot mode](#boot-mode)
* [WeMos D1](#wemos-d1)
* [WeMos D1 mini](#wemos-d1-mini)
* [ESPino by ThaiEasyElec](#espinotee)
* [gen4-IoD Range by 4D Systems](#gen4iod)
## Adafruit HUZZAH ESP8266 (ESP-12)
*TODO: add notes*
## ESPresso Lite 1.0
ESPresso Lite 1.0 (beta version) is an Arduino-compatible Wi-Fi development board powered by Espressif System's own ESP8266 WROOM-02 module. It has breadboard-friendly breakout pins with in-built LED, two reset/flash buttons and a user programmable button . The operating voltage is 3.3VDC, regulated with 800mA maximum current. Special distinctive features include on-board I2C pads that allow direct connection to OLED LCD and sensor boards.
## ESPresso Lite 2.0
ESPresso Lite 2.0 is an Arduino-compatible Wi-Fi development board based on an earlier V1 (beta version). Re-designed together with Cytron Technologies, the newly-revised ESPresso Lite V2.0 features the auto-load/auto-program function, eliminating the previous need to reset the board manually before flashing a new program. It also feature two user programmable side buttons and a reset button. The special distinctive features of on-board pads for I2C sensor and actuator is retained.
## Phoenix 1.0
Product page: http://www.espert.co
## Phoenix 2.0
Product page: http://www.espert.co
## NodeMCU 0.9
### Pin mapping
Pin numbers written on the board itself do not correspond to ESP8266 GPIO pin numbers. Constants are defined to make using this board easier:
```C++
static const uint8_t D0 = 16;
static const uint8_t D1 = 5;
static const uint8_t D2 = 4;
static const uint8_t D3 = 0;
static const uint8_t D4 = 2;
static const uint8_t D5 = 14;
static const uint8_t D6 = 12;
static const uint8_t D7 = 13;
static const uint8_t D8 = 15;
static const uint8_t D9 = 3;
static const uint8_t D10 = 1;
```
If you want to use NodeMCU pin 5, use D5 for pin number, and it will be translated to 'real' GPIO pin 14.
## NodeMCU 1.0
This module is sold under many names for around $6.50 on AliExpress and it's one of the cheapest, fully integrated ESP8266 solutions.
It's an open hardware design with an ESP-12E core and 4 MB of SPI flash.
Acording to the manufacturer, "with a micro USB cable, you can connect NodeMCU devkit to your laptop and flash it without any trouble". This is more or less true: the board comes with a CP2102 onboard USB to serial adapter which just works, well, the majority of the time. Sometimes flashing fails and you have to reset the board by holding down FLASH + RST, then releasing FLASH, then releasing RST. This forces the CP2102 device to power cycle and to be re-numbered by Linux.
The board also features a NCP1117 voltage regulator, a blue LED on GPIO16 and a 220k/100k Ohm voltage divider on the ADC input pin.
Full pinout and PDF schematics can be found [here](https://github.com/nodemcu/nodemcu-devkit-v1.0)
## Olimex MOD-WIFI-ESP8266-DEV
This board comes with 2 MB of SPI flash and optional accessories (e.g. evaluation board ESP8266-EVB or BAT-BOX for batteries).
The basic module has three solder jumpers that allow you to switch the operating mode between SDIO, UART and FLASH.
The board is shipped for FLASH operation mode, with jumpers TD0JP=0, IO0JP=1, IO2JP=1.
Since jumper IO0JP is tied to GPIO0, which is PIN 21, you'll have to ground it before programming with a USB to serial adapter and reset the board by power cycling it.
UART pins for programming and serial I/O are GPIO1 (TXD, pin 3) and GPIO3 (RXD, pin 4).
You can find the board schematics [here](https://github.com/OLIMEX/ESP8266/blob/master/HARDWARE/MOD-WIFI-ESP8266-DEV/MOD-WIFI-ESP8266-DEV_schematic.pdf)
## Olimex MOD-WIFI-ESP8266
This is a stripped down version of the above. Behaves identically in terms of jumpers but has less pins readily available for I/O. Still 2 MB of SPI flash.
## Olimex ESP8266-EVB
It's a Olimex MOD-WIFI-ESP8266-DEV module installed on the headers of a development board which features some breakout connectors, a button (GPIO0) and a relay (GPIO5).
Programming is pretty straightforward: the board is supported in the Arduino IDE after [installing it via the Board Manager](https://github.com/esp8266/Arduino#installing-with-boards-manager). To download a program you just have to connect GND/RX/TX from a serial/USB adapter to the UEXT connector and press the only button before applying power to enter UART mode.
Don't connect 5V from the serial/USB adapter to the board or you won't be able to power cycle it for UART mode.
You can find the board schematics [here](https://github.com/OLIMEX/ESP8266/blob/master/HARDWARE/ESP8266-EVB/ESP8266-EVB_Rev_A.pdf).
[This guide](https://www.olimex.com/Products/IoT/ESP8266-EVB/resources/ESP8266-EVB-how-to-use-Arduino.pdf) is also useful for the first setup, since it contains the UEXT connector pinout.
Board variants include:
* ESP8266-EVB-BAT: comes with built-in LiPo charger and step-up converter
* ESP8266-EVB-BAT-BOX: as above, but enclosd in a plastic box (non-weatherproof)
## SparkFun ESP8266 Thing ###
Product page: https://www.sparkfun.com/products/13231
*TODO: add notes*
## SweetPea ESP-210
*TODO: add notes*
## ESPino
ESPino integrates the ESP-12 module with a 3.3v regulator, CP2104 USB-Serial bridge and a micro USB connector for easy programming. It is designed for fitting in a breadboard and has an RGB Led and two buttons for easy prototyping.
For more information about the hardware, pinout diagram and programming procedures, please see the [datasheet](https://github.com/makerlabmx/ESPino-tools/raw/master/Docs/ESPino-Datasheet-EN.pdf).
Product page: http://www.espino.io/en
## WifInfo
WifInfo integrates the ESP-12 or ESP-07+Ext antenna module with a 3.3v regulator and the hardware to be able to measure French telemetry issue from ERDF powering meter serial output. It has a USB connector for powering, an RGB WS2812 Led, 4 pins I2C connector to fit OLED or sensor, and two buttons + FTDI connector and auto reset feature.
For more information, please see WifInfo related [blog](http://hallard.me/category/wifinfo/) entries, [github](https://github.com/hallard/WifInfo) and [community](https://community.hallard.me/category/16/wifinfo) forum.
## Generic ESP8266 modules
These modules come in different form factors and pinouts. See the page at ESP8266 community wiki for more info:
[ESP8266 Module Family](http://www.esp8266.com/wiki/doku.php?id=esp8266-module-family).
Usually these modules have no bootstapping resistors on board, insufficient decoupling capacitors, no voltage regulator, no reset circuit, and no USB-serial adapter. This makes using them somewhat tricky, compared to development boards which add these features.
In order to use these modules, make sure to observe the following:
- **Provide sufficient power to the module.** For stable use of the ESP8266 a power supply with 3.3V and >= 250mA is required. Using the power available from USB to Serial adapter is not recommended, these adapters typically do not supply enough current to run ESP8266 reliably in every situation. An external supply or regulator along with filtering capacitors is preferred.
- **Connect bootstapping resistors** to GPIO0, GPIO2, GPIO15 according to the schematics below.
- **Put ESP8266 into bootloader mode** before uploading code.
## Serial Adapter
There are many different USB to Serial adapters / boards.
To be able to put ESP8266 into bootloader mode using serial handshaking lines, you need the adapter which breaks out RTS and DTR outputs. CTS and DSR are not useful for upload (they are inputs). Make sure the adapter can work with 3.3V IO voltage: it should have a jumper or a switch to select between 5V and 3.3V, or be marked as 3.3V only.
Adapters based around the following ICs should work:
- FT232RL
- CP2102
- CH340G
PL2303-based adapters are known not to work on Mac OS X. See https://github.com/igrr/esptool-ck/issues/9 for more info.
## Minimal Hardware Setup for Bootloading and Usage
| PIN | Resistor | Serial Adapter |
| ------------- | -------- | -------------- |
| VCC | | VCC (3.3V) |
| GND | | GND |
| TX or GPIO2* | | RX |
| RX | | TX |
| GPIO0 | PullUp | DTR |
| Reset* | PullUp | RTS |
| GPIO15* | PullDown | |
| CH_PD | PullUp | |
* Note
- GPIO15 is also named MTDO
- Reset is also named RSBT or REST (adding PullUp improves the stability of the module)
- GPIO2 is alternative TX for the boot loader mode
- **Directly connecting a pin to VCC or GND is not a substitute for a PullUp or PullDown resistor, doing this can break upload management and the serial console, instability has also been noted in some cases.**
## ESP to Serial
![ESP to Serial](ESP_to_serial.png)
### Minimal Hardware Setup for Bootloading only ##
ESPxx Hardware
| PIN | Resistor | Serial Adapter |
| ------------- | -------- | --------------- |
| VCC | | VCC (3.3V) |
| GND | | GND |
| TX or GPIO2 | | RX |
| RX | | TX |
| GPIO0 | | GND |
| Reset | | RTS* |
| GPIO15 | PullDown | |
| CH_PD | PullUp | |
* Note
- if no RTS is used a manual power toggle is needed
### Minimal Hardware Setup for Running only ##
ESPxx Hardware
| PIN | Resistor | Power supply |
| ------------- | -------- | --------------- |
| VCC | | VCC (3.3V) |
| GND | | GND |
| GPIO0 | PullUp | |
| GPIO15 | PullDown | |
| CH_PD | PullUp | |
## Minimal
![ESP min](ESP_min.png)
## Improved Stability
![ESP improved stability](ESP_improved_stability.png)
## Boot Messages and Modes
The ESP module checks at every boot the Pins 0, 2 and 15.
based on them its boots in different modes:
| GPIO15 | GPIO0 | GPIO2 | Mode |
| ------ | ----- | ----- | -------------------------------- |
| 0V | 0V | 3.3V | Uart Bootloader |
| 0V | 3.3V | 3.3V | Boot sketch (SPI flash) |
| 3.3V | x | x | SDIO mode (not used for Arduino) |
at startup the ESP prints out the current boot mode example:
```
rst cause:2, boot mode:(3,6)
```
note:
- GPIO2 is used as TX output and the internal Pullup is enabled on boot.
### rst cause
| Number | Description |
| ------ | ---------------------- |
| 0 | unknown |
| 1 | normal boot |
| 2 | reset pin |
| 3 | software reset |
| 4 | watchdog reset |
### boot mode
the first value respects the pin setup of the Pins 0, 2 and 15.
| Number | GPIO15 | GPIO0 | GPIO2 | Mode |
| ------ | ------ | ----- | ----- | ---------- |
| 0 | 0V | 0V | 0V | Not valid |
| 1 | 0V | 0V | 3.3V | Uart |
| 2 | 0V | 3.3V | 0V | Not valid |
| 3 | 0V | 3.3V | 3.3V | Flash |
| 4 | 3.3V | 0V | 0V | SDIO |
| 5 | 3.3V | 0V | 3.3V | SDIO |
| 6 | 3.3V | 3.3V | 0V | SDIO |
| 7 | 3.3V | 3.3V | 3.3V | SDIO |
note:
- number = ((GPIO15 << 2) | (GPIO0 << 1) | GPIO2);
## Generic ESP8285 modules
ESP8285 ([datasheet](http://espressif.com/sites/default/files/documentation/0a-esp8285_datasheet_en_v1.0_20160422.pdf)) is a multi-chip package which contains ESP8266 and 1MB flash.
All points related to bootstrapping resistors and recommended circuits listed above apply to ESP8285 as well.
Note that since ESP8285 has SPI flash memory internally connected in DOUT mode, pins 9 and 10 may be used as GPIO / I2C / PWM pins.
## WeMos D1
Product page: http://wemos.cc
## WeMos D1 mini
Product page: http://wemos.cc
## ESPino (WROOM-02 Module) by ThaiEasyElec
ESPino by ThaiEasyElec using WROOM-02 module from Espressif Systems with 4 MB Flash.
We will update an English description soon.
- Product page: http://thaieasyelec.com/products/wireless-modules/wifi-modules/espino-wifi-development-board-detail.html
- Schematics: www.thaieasyelec.com/downloads/ETEE052/ETEE052_ESPino_Schematic.pdf
- Dimensions: http://thaieasyelec.com/downloads/ETEE052/ETEE052_ESPino_Dimension.pdf
- Pinouts: http://thaieasyelec.com/downloads/ETEE052/ETEE052_ESPino_User_Manual_TH_v1_0_20160204.pdf (Please see pg. 8)
## gen4-IoD Range by 4D Systems
gen4-IoD Range of ESP8266 powered Display Modules by 4D Systems.
2.4", 2.8" and 3.2" TFT LCD with uSD card socket and Resistive Touch. Chip Antenna + uFL Connector.
Datasheet and associated downloads can be found on the 4D Systems product page.
The gen4-IoD range can be programmed using the Arduino IDE and also the 4D Systems Workshop4 IDE, which incorporates many additional graphics benefits. GFX4d library is available, along with a number of demo applications.
- Product page: http://www.4dsystems.com.au/product/gen4-IoD

376
doc/boards.rst Normal file
View File

@ -0,0 +1,376 @@
Boards
======
Adafruit HUZZAH ESP8266 (ESP-12)
--------------------------------
*TODO: add notes*
ESPresso Lite 1.0
-----------------
ESPresso Lite 1.0 (beta version) is an Arduino-compatible Wi-Fi development board powered by Espressif System's own ESP8266 WROOM-02 module. It has breadboard-friendly breakout pins with in-built LED, two reset/flash buttons and a user programmable button . The operating voltage is 3.3VDC, regulated with 800mA maximum current. Special distinctive features include on-board I2C pads that allow direct connection to OLED LCD and sensor boards.
ESPresso Lite 2.0
-----------------
ESPresso Lite 2.0 is an Arduino-compatible Wi-Fi development board based on an earlier V1 (beta version). Re-designed together with Cytron Technologies, the newly-revised ESPresso Lite V2.0 features the auto-load/auto-program function, eliminating the previous need to reset the board manually before flashing a new program. It also feature two user programmable side buttons and a reset button. The special distinctive features of on-board pads for I2C sensor and actuator is retained.
Phoenix 1.0
-----------
Product page: http://www.espert.co
Phoenix 2.0
-----------
Product page: http://www.espert.co
NodeMCU 0.9
-----------
Pin mapping
~~~~~~~~~~~
Pin numbers written on the board itself do not correspond to ESP8266 GPIO pin numbers. Constants are defined to make using this board easier:
.. code:: c++
static const uint8_t D0 = 16;
static const uint8_t D1 = 5;
static const uint8_t D2 = 4;
static const uint8_t D3 = 0;
static const uint8_t D4 = 2;
static const uint8_t D5 = 14;
static const uint8_t D6 = 12;
static const uint8_t D7 = 13;
static const uint8_t D8 = 15;
static const uint8_t D9 = 3;
static const uint8_t D10 = 1;
If you want to use NodeMCU pin 5, use D5 for pin number, and it will be translated to 'real' GPIO pin 14.
NodeMCU 1.0
-----------
This module is sold under many names for around $6.50 on AliExpress and it's one of the cheapest, fully integrated ESP8266 solutions.
It's an open hardware design with an ESP-12E core and 4 MB of SPI flash.
Acording to the manufacturer, "with a micro USB cable, you can connect NodeMCU devkit to your laptop and flash it without any trouble". This is more or less true: the board comes with a CP2102 onboard USB to serial adapter which just works, well, the majority of the time. Sometimes flashing fails and you have to reset the board by holding down FLASH +
RST, then releasing FLASH, then releasing RST. This forces the CP2102 device to power cycle and to be re-numbered by Linux.
The board also features a NCP1117 voltage regulator, a blue LED on GPIO16 and a 220k/100k Ohm voltage divider on the ADC input pin.
Full pinout and PDF schematics can be found `here <https://github.com/nodemcu/nodemcu-devkit-v1.0>`__
Olimex MOD-WIFI-ESP8266-DEV
---------------------------
This board comes with 2 MB of SPI flash and optional accessories (e.g. evaluation board ESP8266-EVB or BAT-BOX for batteries).
The basic module has three solder jumpers that allow you to switch the operating mode between SDIO, UART and FLASH.
The board is shipped for FLASH operation mode, with jumpers TD0JP=0, IO0JP=1, IO2JP=1.
Since jumper IO0JP is tied to GPIO0, which is PIN 21, you'll have to ground it before programming with a USB to serial adapter and reset the board by power cycling it.
UART pins for programming and serial I/O are GPIO1 (TXD, pin 3) and GPIO3 (RXD, pin 4).
You can find the board schematics `here <https://github.com/OLIMEX/ESP8266/blob/master/HARDWARE/MOD-WIFI-ESP8266-DEV/MOD-WIFI-ESP8266-DEV_schematic.pdf>`__
Olimex MOD-WIFI-ESP8266
-----------------------
This is a stripped down version of the above. Behaves identically in terms of jumpers but has less pins readily available for I/O. Still 2 MB of SPI flash.
Olimex ESP8266-EVB
------------------
It's an Olimex MOD-WIFI-ESP8266-DEV module installed on the headers of a development board which features some breakout connectors, a button (GPIO0) and a relay (GPIO5).
To download a program you have to connect GND/RX/TX from a serial/USB adapter to the UEXT connector and press the only button before applying power to enter UART mode.
Don't connect 5V from the serial/USB adapter to the board or you won't be able to power cycle it for UART mode.
You can find the board schematics `here <https://github.com/OLIMEX/ESP8266/blob/master/HARDWARE/ESP8266-EVB/ESP8266-EVB_Rev_A.pdf>`__.
`This guide <https://www.olimex.com/Products/IoT/ESP8266-EVB/resources/ESP8266-EVB-how-to-use-Arduino.pdf>`__ is also useful for the first setup, since it contains the UEXT connector pinout.
Board variants include:
* ESP8266-EVB-BAT: comes with built-in LiPo charger and step-up converter
* ESP8266-EVB-BAT-BOX: as above, but enclosd in a plastic box (non-weatherproof)
SparkFun ESP8266 Thing
----------------------
Product page: https://www.sparkfun.com/products/13231
*TODO: add notes*
SweetPea ESP-210
----------------
*TODO: add notes*
ESPino
------
ESPino integrates the ESP-12 module with a 3.3v regulator, CP2104 USB-Serial bridge and a micro USB connector for easy programming. It is designed for fitting in a breadboard and has an RGB Led and two buttons for easy prototyping.
For more information about the hardware, pinout diagram and programming procedures, please see the `datasheet <https://github.com/makerlabmx/ESPino-tools/raw/master/Docs/ESPino-Datasheet-EN.pdf>`__.
Product page: http://www.espino.io/en
WifInfo
-------
WifInfo integrates the ESP-12 or ESP-07+Ext antenna module with a 3.3v regulator and the hardware to be able to measure French telemetry issue from ERDF powering meter serial output. It has a USB connector for powering, an RGB WS2812 Led, 4 pins I2C connector to fit OLED or sensor, and two buttons + FTDI connector and auto reset feature.
For more information, please see WifInfo related `blog <http://hallard.me/category/wifinfo/>`__ entries, `github <https://github.com/hallard/WifInfo>`__ and `community <https://community.hallard.me/category/16/wifinfo>`__ forum.
Generic ESP8266 modules
-----------------------
These modules come in different form factors and pinouts. See the page at ESP8266 community wiki for more info: `ESP8266 Module Family <http://www.esp8266.com/wiki/doku.php?id=esp8266-module-family>`__.
Usually these modules have no bootstapping resistors on board, insufficient decoupling capacitors, no voltage regulator, no reset circuit, and no USB-serial adapter. This makes using them somewhat tricky, compared to development boards which add these features.
In order to use these modules, make sure to observe the following:
- **Provide sufficient power to the module.** For stable use of the ESP8266 a power supply with 3.3V and >= 250mA is required. Using the power available from USB to Serial adapter is not recommended, these adapters typically do not supply enough current to run ESP8266 reliably in every situation. An external supply or regulator alongwith filtering capacitors is preferred.
- **Connect bootstapping resistors** to GPIO0, GPIO2, GPIO15 according to the schematics below.
- **Put ESP8266 into bootloader mode** before uploading code.
Serial Adapter
--------------
There are many different USB to Serial adapters / boards. To be able to put ESP8266 into bootloader mode using serial handshaking lines, you need the adapter which breaks out RTS and DTR outputs. CTS and DSR are not useful for upload (they are inputs). Make sure the adapter can work with 3.3V IO voltage: it should have a jumper or a switch to select between 5V and 3.3V, or be marked as 3.3V only.
Adapters based around the following ICs should work:
- FT232RL
- CP2102
- CH340G
PL2303-based adapters are known not to work on Mac OS X. See https://github.com/igrr/esptool-ck/issues/9 for more info.
Minimal Hardware Setup for Bootloading and Usage
------------------------------------------------
+-----------------+------------+------------------+
| PIN | Resistor | Serial Adapter |
+=================+============+==================+
| VCC | | VCC (3.3V) |
+-----------------+------------+------------------+
| GND | | GND |
+-----------------+------------+------------------+
| TX or GPIO2\* | | RX |
+-----------------+------------+------------------+
| RX | | TX |
+-----------------+------------+------------------+
| GPIO0 | PullUp | DTR |
+-----------------+------------+------------------+
| Reset\* | PullUp | RTS |
+-----------------+------------+------------------+
| GPIO15\* | PullDown | |
+-----------------+------------+------------------+
| CH\_PD | PullUp | |
+-----------------+------------+------------------+
- Note
- GPIO15 is also named MTDO
- Reset is also named RSBT or REST (adding PullUp improves the
stability of the module)
- GPIO2 is alternative TX for the boot loader mode
- **Directly connecting a pin to VCC or GND is not a substitute for a
PullUp or PullDown resistor, doing this can break upload management
and the serial console, instability has also been noted in some
cases.**
ESP to Serial
-------------
.. figure:: ESP_to_serial.png
:alt: ESP to Serial
ESP to Serial
Minimal Hardware Setup for Bootloading only
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ESPxx Hardware
+---------------+------------+------------------+
| PIN | Resistor | Serial Adapter |
+===============+============+==================+
| VCC | | VCC (3.3V) |
+---------------+------------+------------------+
| GND | | GND |
+---------------+------------+------------------+
| TX or GPIO2 | | RX |
+---------------+------------+------------------+
| RX | | TX |
+---------------+------------+------------------+
| GPIO0 | | GND |
+---------------+------------+------------------+
| Reset | | RTS\* |
+---------------+------------+------------------+
| GPIO15 | PullDown | |
+---------------+------------+------------------+
| CH\_PD | PullUp | |
+---------------+------------+------------------+
- Note
- if no RTS is used a manual power toggle is needed
Minimal Hardware Setup for Running only
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ESPxx Hardware
+----------+------------+----------------+
| PIN | Resistor | Power supply |
+==========+============+================+
| VCC | | VCC (3.3V) |
+----------+------------+----------------+
| GND | | GND |
+----------+------------+----------------+
| GPIO0 | PullUp | |
+----------+------------+----------------+
| GPIO15 | PullDown | |
+----------+------------+----------------+
| CH\_PD | PullUp | |
+----------+------------+----------------+
Minimal
-------
.. figure:: ESP_min.png
:alt: ESP min
ESP min
Improved Stability
------------------
.. figure:: ESP_improved_stability.png
:alt: ESP improved stability
ESP improved stability
Boot Messages and Modes
-----------------------
The ESP module checks at every boot the Pins 0, 2 and 15. based on them its boots in different modes:
+----------+---------+---------+------------------------------------+
| GPIO15 | GPIO0 | GPIO2 | Mode |
+==========+=========+=========+====================================+
| 0V | 0V | 3.3V | Uart Bootloader |
+----------+---------+---------+------------------------------------+
| 0V | 3.3V | 3.3V | Boot sketch (SPI flash) |
+----------+---------+---------+------------------------------------+
| 3.3V | x | x | SDIO mode (not used for Arduino) |
+----------+---------+---------+------------------------------------+
at startup the ESP prints out the current boot mode example:
::
rst cause:2, boot mode:(3,6)
note: - GPIO2 is used as TX output and the internal Pullup is enabled on boot.
rst cause
~~~~~~~~~
+----------+------------------+
| Number | Description |
+==========+==================+
| 0 | unknown |
+----------+------------------+
| 1 | normal boot |
+----------+------------------+
| 2 | reset pin |
+----------+------------------+
| 3 | software reset |
+----------+------------------+
| 4 | watchdog reset |
+----------+------------------+
boot mode
~~~~~~~~~
the first value respects the pin setup of the Pins 0, 2 and 15.
+----------+----------+---------+---------+-------------+
| Number | GPIO15 | GPIO0 | GPIO2 | Mode |
+==========+==========+=========+=========+=============+
| 0 | 0V | 0V | 0V | Not valid |
+----------+----------+---------+---------+-------------+
| 1 | 0V | 0V | 3.3V | Uart |
+----------+----------+---------+---------+-------------+
| 2 | 0V | 3.3V | 0V | Not valid |
+----------+----------+---------+---------+-------------+
| 3 | 0V | 3.3V | 3.3V | Flash |
+----------+----------+---------+---------+-------------+
| 4 | 3.3V | 0V | 0V | SDIO |
+----------+----------+---------+---------+-------------+
| 5 | 3.3V | 0V | 3.3V | SDIO |
+----------+----------+---------+---------+-------------+
| 6 | 3.3V | 3.3V | 0V | SDIO |
+----------+----------+---------+---------+-------------+
| 7 | 3.3V | 3.3V | 3.3V | SDIO |
+----------+----------+---------+---------+-------------+
note: - number = ((GPIO15 << 2) \| (GPIO0 << 1) \| GPIO2);
Generic ESP8285 modules
-----------------------
ESP8285 (`datasheet <http://www.espressif.com/sites/default/files/0a-esp8285_datasheet_en_v1.0_20160422.pdf>`__) is a multi-chip package which contains ESP8266 and 1MB flash. All points related to bootstrapping resistors and recommended circuits listed above apply to ESP8285 as well.
Note that since ESP8285 has SPI flash memory internally connected in DOUT mode, pins 9 and 10 may be used as GPIO / I2C / PWM pins.
WeMos D1
--------
Product page: https://www.wemos.cc/
WeMos D1 mini
-------------
Product page: https://www.wemos.cc/
ESPino (WROOM-02 Module) by ThaiEasyElec
----------------------------------------
ESPino by ThaiEasyElec using WROOM-02 module from Espressif Systems with 4 MB Flash.
We will update an English description soon. - Product page:
http://thaieasyelec.com/products/wireless-modules/wifi-modules/espino-wifi-development-board-detail.html
- Schematics:
www.thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_Schematic.pdf -
Dimensions:
http://thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_Dimension.pdf
- Pinouts:
http://thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_User\_Manual\_TH\_v1\_0\_20160204.pdf (Please see pg. 8)
gen4-IoD Range by 4D Systems
----------------------------
gen4-IoD Range of ESP8266 powered Display Modules by 4D Systems.
2.4", 2.8" and 3.2" TFT LCD with uSD card socket and Resistive Touch. Chip Antenna + uFL Connector.
Datasheet and associated downloads can be found on the 4D Systems product page.
The gen4-IoD range can be programmed using the Arduino IDE and also the 4D Systems Workshop4 IDE, which incorporates many additional graphics benefits. GFX4d library is available, along with a number of demo applications.
- Product page: http://www.4dsystems.com.au/product/gen4-IoD

364
doc/changes.md
View File

@ -1,364 +0,0 @@
---
title: Change Log
---
## 2.3.0
June 23, 2016
Package link: `http://arduino.esp8266.com/versions/2.3.0/package_esp8266com_index.json`.
### Core
- Fix NMI interrupt handler alignment
- Update SDK to 1.5.3
- umm_malloc: print block start address before heap corruption callback is triggered
- If GDBStub library is used, break into gdb on assert and panic
- Add option to keep FS classes in namespace (#2030)
- Add SPIFFS::end (#1657)
- Add ArduinoOTA::getHostname() interface
- Add __throw_out_of_range
- Add support for RTC user memory in ESP-specific APIs. (#1836)
- Expose RTC_USER_MEM in esp8266_peri.h
- Remove DISABLED macro (#2072)
- Execute global constructors in correct order (#2074)
- Real board name available in Sketch/MDNS/OTA (#2054)
- Add DOUT/QOUT flash modes
- Add ESP8285 entry in boards menu
- Move timer detachInterrupt functions into IRAM (#2083)
- Make Updater be able to run inside async callbacks (#2096)
- Add new boards Phoenix 1.0 & Phoenix 2.0 (#2088)
- Store git version of the core in the compiled binary (#2099)
- Rebuild libstdc++ with mlongcalls and link against it (#1983)
- Add mechanism for posting functions to the main loop (#2082)
- MD5Builder::addStream: fixed falsy calculated hash for len > filelength (#2126)
- Fix SPIFFS.openDir("") (#2143)
- Bring back old semantics to random and randomSeed, add secureRandom (#1710) (#2142)
- Add missing pgm_read_ptr{_near/_far} macros (#2160)
- Add macro for maximum open SPIFFS files, settings it to 1 saves about 1k heap. (#2167)
- Fix UART pins setting (#2098)
- Fix ESP.getSketchSize, add ESP.getSketchMD5 (#2158)
- Add Serial.baudRate() to get current baud rate (#2079)
### Libraries
- SNI support in WiFiClientSecure (#1285)
- Update axTLS to 139914f
- HTTPClient: return error when HTTPClient::begin is called with HTTPS URL without certificate fingerprint (#1941)
- HTTPClient: fix default port not being set
- HTTPClient: fix handling of chunked transfer encoding (#1975)
- ESP8266SSDP: switch SSDP send arguments around
- ESP8266WiFi: fix UdpContext::peek to return int (#1946)
- ESP8266WiFi: fix WiFiSleepType_t values to match SDK ones
- LwIP: use gcc-built LwIP by default (#1926)
- LwIP: fix crash in igmp_start_timer (#1826)
- HTTPClient: include non-standard ports in Host: header
- ESP8266WiFi: Prevent WiFi config corruption (#1997 #1856 #1699 #1675)
- GDBStub: fix section attribute for core gdbstub functions
- Wire: I2C bus reset with info to user
- ESP8266HTTPClient: allow HTTP header value without LWS
- ESP8266mDNS: Fix mDNS doesn't accept queryService responses from avahi-daemon (#2015)
- Add MFRC522 to supported libraries (#2044)
- Update axTLS to ab516f7 (1.5.3+)
- Mention ESP8266Ping library
- ESP8266HTTPClient: fix duplicate Content-Length headers (#1902)
- ESP8266HTTPUpdateServer: make HTTP Update Server more secure (#2104)
- ESP8266WiFi: add virtual destructor to WiFiServer class (#2116)
- ESP8266WiFi: fix error when calling `WiFiServer::close` more than once
- ESP8266WiFi: WiFi event handling refactoring (#2119)
- ESP8266mDNS: restart listening when WiFi STA is connected/disconnected (#1828)
- ESP8266WiFi: allow DHCP client to be re-enabled using WiFi.config(0U, 0U, 0U) (#1896)
- ESP8266WiFi: enable SO_REUSE in LwIP and WiFiServer (#1431)
- ESP8266WebServer: make ESP8266WebServer::urlDecode public (#1419)
- LwIP: sntp_localtime: return -1 in tm_isdst field (#2010)
- ESP8266WiFi: fix for crash in WiFiClientSecure when WiFi is disconnected (#2139)
- SD: Prevent WDT resets in SD library (#1815)
- ESP8266WiFi: Fix issue when WiFi.begin(ssid, pass) is called right after WiFi.mode(WIFI_OFF)
### Tools
- Python 3 compatibility for get.py
- Device side test library and test runner
- Fix ARM toolchain files permissions (#2004)
- Update esptool to 0.4.9
## 2.2.0
April 18, 2016
Package link: `http://arduino.esp8266.com/versions/2.2.0/package_esp8266com_index.json`.
### Core
- Leverage realloc() in String::changeBuffer()
- Clean up core files
- Add host side tests
- Fix possible null pointer in umm_malloc
- Remove "Upload Using" option from Tools menu
- Move attachInterrupt and detachInterrupt into IRAM (#1734)
- Implement strstr_P
- Allow indefinite duration for tone()
- Fix crashes when using tone()
- Fix RF_MODE and ADC_MODE
- Move micros, delayMicroseconds, millis to IRAM (#1326)
- Fix pulseIn (#1072, #1149)
- Accept both named constant and ADC channel number in analogRead (#1766)
- Enable heap poisoning only when debug options are enabled (#1800)
- Bootloader: don't touch RTC memory if it doesn't contain a valid command (#619)
- Update SDK to 1.5.2 (#1653)
- Clean up variants, fix digitalPinHasPWM definition (#1831)
- Don't set RF mode on boot unless it was overridden
- Change build.board property for boards which renumber pins like NodeMCU (#1878)
- Fix Exception 2 when using printf or vprintf
### Libraries
- Update axTLS to 5b4be7d
- WiFiClientSecure: implement connection timeout, fix connected method behavior
- WiFiClient: fix write behavior when connection is closed by remote side
- ESP8266HTTPServer: add font MIME types, fix #1601
- ESP8266mDNS: add client support
- Update SPIFFS to 82aeac6
- Servo: move some functions into IRAM (#1742)
- Update SoftwareSerial to version 3.1.0
- ESP8266SSDP: change templates to include deviceType
- ESP8266WebServer: handle more file types
- SPI: add CPOL setting
- ESP8266WebServer: Fix buffer overflow in ESP8266WebServer::authenticate (#1790)
- ESP8266WiFi: fix undefined behavior in WiFiServer::setNoDelay (#1695)
- Servo: use peripheral clock frequency when calculating FRC1 tick count (#1789)
- ESP8266WiFi: avoid multiple instances of INADDR_NONE
- Add LwIP binary built with gcc
- ESP8266WiFi: Allow PSK instead of passphrase in WiFiSTA::begin
- SPI: Fix SPI.transfer16() using wrong endianness
- HTTPClient: decouple transport layer handling + save some RAM
- ESP8266httpUpdate: decouple HTTPS overloads + save some RAM
- Update and move lwIP headers, add options to use different lwIP build
- ESP8266WebServer: wait for data to arrive
- ESP8266WebServer: save RAM by moving response strings to flash (#1732)
- SPI: Speed up SPI.writePattern()
### Tools
- Add ARM tools (#269)
---
## 2.1.0
February 27, 2016
Package link: `http://arduino.esp8266.com/versions/2.1.0/package_esp8266com_index.json`.
### Core
- Add function to know last reset reason.
- Allow control of enabling debug and debug level from IDE
- Add espduino board
- Rework StreamString::write to use String internal buffer directly (#1289)
- Add function to measure stack high water mark
- Fix RAM corruption caused by our hook of register_chipv6_phy(init_data*).
- Optimize PWM interrupt handler for better precision
- Add warning levels configurable through Preferences
- SPIFFS: check if path length is valid (#1089)
- Set CPU frequency before running setup
- Add core_esp8266_features.h to be able to detect the features and libraries included in the ESP core
- Add ESPino to supported boards
- Fix pwm first step getting skipped
- Update SDK to 1.5.1_16_01_08
- Bufferless and interruptless HardwareSerial
- HardwareSerial: allow mapping of UART0 TX to GPIO2
- Add 128K SPIFFS for 512KB modules
- Reduce stack usage by Print::printf
- Fix a crash in String::changeBuffer()
- Implement static initialization guards (#500)
- Implementation of Tone API using timer1
- Use umm_malloc for heap management
- Configurable I2C clock stretching limit
- Add a new board entry for the SparkFun Thing Dev
### Libraries
- ESP8266HTTPClient: add CHUNKED encoding support (#1324)
- Fixed crash bug with mDNS where a string buffer could be used uninitialized
- Add WiFi TX power control
- Add WiFi sleep management
- Allow to hook into WiFi events from sketch
- Allow setting TCP timeout
- Add setSleepMode + getSleepMode and setPhyMode + getPhyMode to WiFi
- Update GDBStub library with the source of esp-gdbstub
- Servo: fix detach and attach
- ESP8266mDNS: refactoring, add TXT support
- Add HTTP Basic Auth to WebServer and libb64 (base64) to core
- Fix link-time dependency of ESP8266WebServer on SPIFFS (#862)
- Allow setting client side TLS key and certificate
- Replace chain of UDP pbufs with a single pbuf before sending (#1009)
- Unique Built-In libraries library.properties name
- Improvements for MD5Builder with Stream
- ESP8266SSDP: fixing TTL to 2 per spec
- ESP8266WebServer: a content length of zero should also be sent
- Use SoftwareSerial version 2.2
- EEPROM: optimised `_dirty` flag
- ESP8266mDNS: advertise all hosted services
- Remove bundled OneWire - ESP8266 support has been merged in the official OneWire sources
- WiFiClientSecure: don't panic if memory allocation fails
- Verify domain name in WiFiClientSecure::verify
- Speed up WiFi.hostByName when the hostname is actually an IP
- Fix WiFi scan issue (#1355)
- Workaround for LwIP not handling ERR_ABRT
- Servo value read and write fixes
### Tools
- espota.py: add support for manually selecting ip and port for host side
- Update esptool to 0.4.8
- Make espota compatible with python 3.5
---
## 2.0.0
November 30, 2015
Package link: `http://arduino.esp8266.com/versions/2.0.0/package_esp8266com_index.json`.
### Core
- Add file system APIs and documentation
- Add ConfigFile example
- Allow user to run code in user_rf_pre_init
- Add strtoul and strtol, fix strtod
- Update documentation for NodeMCU and Olimex boards
- Disable interrupts inside ESP.getVcc (#567)
- Erase RTC RAM only if RF mode looks invalid (#619)
- Get pin levels at time of interrupt, rather than the time of calling the handler.
- Move interrupt handlers to ram.
- Improve debug output on critical errors
- Add ArduinoOTA library and docs
- Add WeMos D1 & D1 mini boards
- Add documentation about boot messages and mode meaning
- Disable sleep mode before doing OTA (#1005)
- Add the ability to be called back when the device is about to reset
- Add "Reset Method" menu
- Add MD5 to core
- I2C: generate STOP in case of NACK (fix #698, #254)
- Add libc time functions
- Fix linker script for 512k(no SPIFFS) variant (#966)
- I2S optimizations
- Support Sketch > Export compiled binary
- Update SPIFFS wrapper for 0.3.3
- Fix placement of code into RAM, enable gc-sections
- Make soft wdt reset more obvious
- Force disable IOSWAP for UART0 in HardwareSerial initialization (#744)
- Add IPAddress::toString()
### Libraries
- ESP8266WebServer: support for sending of PROGMEM strings
- ESP8266WebServer: support for serving files from file system
- ESP8266WiFi: fix mode selection (#529)
- ESP8266mDNS: allow to work on SoftAP interface
- EEPROM: round requested size to 4 bytes (#659)
- Add ESP8266AVRISP library
- Add ESP8266HTTPUpdate library
- Add HTTPClient library
- Add WiFiClientSecure
- ESP8266WiFi library: add persistent option, fix #1054
- Make RequestHandler handle uploads
- Add Digest Authentication to OTA and espota.py
- Don't close UDP pcbs when WiFi connection drops (#969)
- Add espsoftwareserial library
- Add HTTP Updater library
- Add Ethernet library for W5100
- Add SPIFFS WebServer Example
- add dnsIP() to ESP8266WiFi class
- OTA support encapsulated to ArduinoOTA class
- Add gdb stub library
- Extracted the WebUpdate example into a library.
- Fix to Servo allowing write() to be called before attach()
- ESP8266WiFi: add function `begin` without any parameters and add `psk` function to return current PSK form sdk config
- Fix a crash due to abort() called from TCP error callback (#428)
- Adding support for OPTIONS requests to ESP8266WebServer
- Add HTTPS request sample (#43)
- Fix _useClientMode & _useApMode in SDK auto connect mode (#754)
- Add ESP8266WebServer::sendContent_P with 'size_t size' argument for binary content
- Fix bug in WiFiClient::write_P when content was binary
- Add WiFiClient::write_P to be used with PROGMEM
### Tools
- Update SDK to 1.3.0_15_08_10_p1
- Update esptool to 0.4.6
- Bump toolchain version to force libm update on Windows
- ESP8266FS tool update
---
## 1.6.5-947-g39819f0
July 23, 2015
Package link: `http://arduino.esp8266.com/versions/1.6.5-947-g39819f0/package_esp8266com_index.json`.
### Core
- I2C library updated to better handle repeated start for certain devices,
improved waveforms, higher frequencies for 160MHz core clock, fix case where
using different pins would not work with libs calling begin internally.
- Add Adafruit HUZZAH board
- Add SparkFun Thing board
- Add SweetPea ESP-210 board
- Add eboot bootloader
- Timer0 support
- Add PWM range and frequency control
- Add ESP.eraseConfig method
- Fix pin change interrupt handling (#322)
- Add SLC and I2S register definitions
- Fix math functions calling themselves recursively (#233, #354)
- Print stack on exception and soft WDT reset
- Add Updater class
- Remove implementations of WDT-related functions
- Provide selection between A0 and VCC (#443, #338)
### Libraries
- ESP8266WebServer: add gzip streaming, fix sendContent behaviour,
add setContentSize method.
- ESP8266WiFi: add BSSID, channel, isHidden methods, fix AP/STA mode
selection (#28).
- Better handling of WiFi disconnect (#231)
- Add API to set the beginning of local ports range for WiFiClient.
- Add RSSI function
- Add function to get the MAC / BSSID as String
- Servo library support
- Add ESP8266WiFiMesh library
- Add ESP8266SSDP library
- Add DNS-SD support to ESP8266mDNS library
### Tools
- Update SDK to v1.2.0_15_07_03
- Better sketch size reporting (#314)
- Update esptool to 0.4.5
---
## 1.6.4-673-g8cd3697
May 22, 2015
Package link: `http://arduino.esp8266.com/versions/1.6.4-673-g8cd3697/package_esp8266com_index.json`.
### Tools
- Add 32-bit Linux toolchain.
- Rebuild toolchain and esptool with support for OS X down to 10.6.
### Libraries
- Better connection handling in ESP8266WebServer.
The server now sends Content-Length and Connection: close headers,
then waits for the client to disconnect. By not closing the connection
actively, server avoids TIME_WAIT TCP state, and TCP stack is able to
release the memory immediately, without waiting for 2xMSL period.
If the client doesn't disconnect in 2000ms, the server closes the connection
actively.
- Add Hash library, which has a function to calculate SHA1 hash.
- SD, Adafruit_ILI9341, and OneWire libraries are now bundled.
- Fix incorrect sector calculation in EEPROM library.
---
## 1.6.4-628-g545ffde
May 19, 2015
- Initial release of Boards Manager package for ESP8266 platform.

293
doc/changes.rst Normal file
View File

@ -0,0 +1,293 @@
Changelog
=========
2.3.0
-----
June 23, 2016
Package link:
``http://arduino.esp8266.com/versions/2.3.0/package_esp8266com_index.json``.
Core
~~~~
- Fix NMI interrupt handler alignment
- Update SDK to 1.5.3
- umm\_malloc: print block start address before heap corruption
callback is triggered
- If GDBStub library is used, break into gdb on assert and panic
- Add option to keep FS classes in namespace (#2030)
- Add SPIFFS::end (#1657)
- Add ArduinoOTA::getHostname() interface
- Add \_\_throw\_out\_of\_range
- Add support for RTC user memory in ESP-specific APIs. (#1836)
- Expose RTC\_USER\_MEM in esp8266\_peri.h
- Remove DISABLED macro (#2072)
- Execute global constructors in correct order (#2074)
- Real board name available in Sketch/MDNS/OTA (#2054)
- Add DOUT/QOUT flash modes
- Add ESP8285 entry in boards menu
- Move timer detachInterrupt functions into IRAM (#2083)
- Make Updater be able to run inside async callbacks (#2096)
- Add new boards Phoenix 1.0 & Phoenix 2.0 (#2088)
- Store git version of the core in the compiled binary (#2099)
- Rebuild libstdc++ with mlongcalls and link against it (#1983)
- Add mechanism for posting functions to the main loop (#2082)
- MD5Builder::addStream: fixed falsy calculated hash for len >
filelength (#2126)
- Fix SPIFFS.openDir("") (#2143)
- Bring back old semantics to random and randomSeed, add secureRandom
(#1710) (#2142)
- Add missing pgm\_read\_ptr{\_near/\_far} macros (#2160)
- Add macro for maximum open SPIFFS files, settings it to 1 saves about
1k heap. (#2167)
- Fix UART pins setting (#2098)
- Fix ESP.getSketchSize, add ESP.getSketchMD5 (#2158)
- Add Serial.baudRate() to get current baud rate (#2079)
Libraries
~~~~~~~~~
- SNI support in WiFiClientSecure (#1285)
- Update axTLS to 139914f
- HTTPClient: return error when HTTPClient::begin is called with HTTPS
URL without certificate fingerprint (#1941)
- HTTPClient: fix default port not being set
- HTTPClient: fix handling of chunked transfer encoding (#1975)
- ESP8266SSDP: switch SSDP send arguments around
- ESP8266WiFi: fix UdpContext::peek to return int (#1946)
- ESP8266WiFi: fix WiFiSleepType\_t values to match SDK ones
- LwIP: use gcc-built LwIP by default (#1926)
- LwIP: fix crash in igmp\_start\_timer (#1826)
- HTTPClient: include non-standard ports in Host: header
- ESP8266WiFi: Prevent WiFi config corruption (#1997 #1856 #1699 #1675)
- GDBStub: fix section attribute for core gdbstub functions
- Wire: I2C bus reset with info to user
- ESP8266HTTPClient: allow HTTP header value without LWS
- ESP8266mDNS: Fix mDNS doesn't accept queryService responses from
avahi-daemon (#2015)
- Add MFRC522 to supported libraries (#2044)
- Update axTLS to ab516f7 (1.5.3+)
- Mention ESP8266Ping library
- ESP8266HTTPClient: fix duplicate Content-Length headers (#1902)
- ESP8266HTTPUpdateServer: make HTTP Update Server more secure (#2104)
- ESP8266WiFi: add virtual destructor to WiFiServer class (#2116)
- ESP8266WiFi: fix error when calling ``WiFiServer::close`` more than
once
- ESP8266WiFi: WiFi event handling refactoring (#2119)
- ESP8266mDNS: restart listening when WiFi STA is
connected/disconnected (#1828)
- ESP8266WiFi: allow DHCP client to be re-enabled using WiFi.config(0U,
0U, 0U) (#1896)
- ESP8266WiFi: enable SO\_REUSE in LwIP and WiFiServer (#1431)
- ESP8266WebServer: make ESP8266WebServer::urlDecode public (#1419)
- LwIP: sntp\_localtime: return -1 in tm\_isdst field (#2010)
- ESP8266WiFi: fix for crash in WiFiClientSecure when WiFi is
disconnected (#2139)
- SD: Prevent WDT resets in SD library (#1815)
- ESP8266WiFi: Fix issue when WiFi.begin(ssid, pass) is called right
after WiFi.mode(WIFI\_OFF)
Tools
~~~~~
- Python 3 compatibility for get.py
- Device side test library and test runner
- Fix ARM toolchain files permissions (#2004)
- Update esptool to 0.4.9
2.2.0
-----
April 18, 2016
Package link:
``http://arduino.esp8266.com/versions/2.2.0/package_esp8266com_index.json``.
Core
~~~~
- Leverage realloc() in String::changeBuffer()
- Clean up core files
- Add host side tests
- Fix possible null pointer in umm\_malloc
- Remove "Upload Using" option from Tools menu
- Move attachInterrupt and detachInterrupt into IRAM (#1734)
- Implement strstr\_P
- Allow indefinite duration for tone()
- Fix crashes when using tone()
- Fix RF\_MODE and ADC\_MODE
- Move micros, delayMicroseconds, millis to IRAM (#1326)
- Fix pulseIn (#1072, #1149)
- Accept both named constant and ADC channel number in analogRead
(#1766)
- Enable heap poisoning only when debug options are enabled (#1800)
- Bootloader: don't touch RTC memory if it doesn't contain a valid
command (#619)
- Update SDK to 1.5.2 (#1653)
- Clean up variants, fix digitalPinHasPWM definition (#1831)
- Don't set RF mode on boot unless it was overridden
- Change build.board property for boards which renumber pins like
NodeMCU (#1878)
- Fix Exception 2 when using printf or vprintf
Libraries
~~~~~~~~~
- Update axTLS to 5b4be7d
- WiFiClientSecure: implement connection timeout, fix connected method
behavior
- WiFiClient: fix write behavior when connection is closed by remote
side
- ESP8266HTTPServer: add font MIME types, fix #1601
- ESP8266mDNS: add client support
- Update SPIFFS to 82aeac6
- Servo: move some functions into IRAM (#1742)
- Update SoftwareSerial to version 3.1.0
- ESP8266SSDP: change templates to include deviceType
- ESP8266WebServer: handle more file types
- SPI: add CPOL setting
- ESP8266WebServer: Fix buffer overflow in
ESP8266WebServer::authenticate (#1790)
- ESP8266WiFi: fix undefined behavior in WiFiServer::setNoDelay (#1695)
- Servo: use peripheral clock frequency when calculating FRC1 tick
count (#1789)
- ESP8266WiFi: avoid multiple instances of INADDR\_NONE
- Add LwIP binary built with gcc
- ESP8266WiFi: Allow PSK instead of passphrase in WiFiSTA::begin
- SPI: Fix SPI.transfer16() using wrong endianness
- HTTPClient: decouple transport layer handling + save some RAM
- ESP8266httpUpdate: decouple HTTPS overloads + save some RAM
- Update and move lwIP headers, add options to use different lwIP build
- ESP8266WebServer: wait for data to arrive
- ESP8266WebServer: save RAM by moving response strings to flash
(#1732)
- SPI: Speed up SPI.writePattern()
Tools
~~~~~
- Add ARM tools (#269)
2.0.0
-----
November 30, 2015
Package link:
``http://arduino.esp8266.com/versions/2.0.0/package_esp8266com_index.json``.
Core
~~~~
- Add file system APIs and documentation
- Add ConfigFile example
- Allow user to run code in user\_rf\_pre\_init
- Add strtoul and strtol, fix strtod
- Update documentation for NodeMCU and Olimex boards
- Disable interrupts inside ESP.getVcc (#567)
- Erase RTC RAM only if RF mode looks invalid (#619)
- Get pin levels at time of interrupt, rather than the time of calling
the handler.
- Move interrupt handlers to ram.
- Improve debug output on critical errors
- Add ArduinoOTA library and docs
- Add WeMos D1 & D1 mini boards
- Add documentation about boot messages and mode meaning
- Disable sleep mode before doing OTA (#1005)
- Add the ability to be called back when the device is about to reset
- Add "Reset Method" menu
- Add MD5 to core
- I2C: generate STOP in case of NACK (fix #698, #254)
- Add libc time functions
- Fix linker script for 512k(no SPIFFS) variant (#966)
- I2S optimizations
- Support Sketch > Export compiled binary
- Update SPIFFS wrapper for 0.3.3
- Fix placement of code into RAM, enable gc-sections
- Make soft wdt reset more obvious
- Force disable IOSWAP for UART0 in HardwareSerial initialization
(#744)
- Add IPAddress::toString()
Libraries
~~~~~~~~~
- ESP8266WebServer: support for sending of PROGMEM strings
- ESP8266WebServer: support for serving files from file system
- ESP8266WiFi: fix mode selection (#529)
- ESP8266mDNS: allow to work on SoftAP interface
- EEPROM: round requested size to 4 bytes (#659)
- Add ESP8266AVRISP library
- Add ESP8266HTTPUpdate library
- Add HTTPClient library
- Add WiFiClientSecure
- ESP8266WiFi library: add persistent option, fix #1054
- Make RequestHandler handle uploads
- Add Digest Authentication to OTA and espota.py
- Don't close UDP pcbs when WiFi connection drops (#969)
- Add espsoftwareserial library
- Add HTTP Updater library
- Add Ethernet library for W5100
- Add SPIFFS WebServer Example
- add dnsIP() to ESP8266WiFi class
- OTA support encapsulated to ArduinoOTA class
- Add gdb stub library
- Extracted the WebUpdate example into a library.
- Fix to Servo allowing write() to be called before attach()
- ESP8266WiFi: add function ``begin`` without any parameters and add
``psk`` function to return current PSK form sdk config
- Fix a crash due to abort() called from TCP error callback (#428)
- Adding support for OPTIONS requests to ESP8266WebServer
- Add HTTPS request sample (#43)
- Fix \_useClientMode & \_useApMode in SDK auto connect mode (#754)
- Add ESP8266WebServer::sendContent\_P with 'size\_t size' argument for
binary content
- Fix bug in WiFiClient::write\_P when content was binary
- Add WiFiClient::write\_P to be used with PROGMEM
Tools
~~~~~
- Update SDK to 1.3.0\_15\_08\_10\_p1
- Update esptool to 0.4.6
- Bump toolchain version to force libm update on Windows
- ESP8266FS tool update
1.6.4-673-g8cd3697
------------------
May 22, 2015
Package link:
``http://arduino.esp8266.com/versions/1.6.4-673-g8cd3697/package_esp8266com_index.json``.
Tools
~~~~~
- Add 32-bit Linux toolchain.
- Rebuild toolchain and esptool with support for OS X down to 10.6.
Libraries
~~~~~~~~~
- Better connection handling in ESP8266WebServer. The server now sends
Content-Length and Connection: close headers, then waits for the
client to disconnect. By not closing the connection actively, server
avoids TIME\_WAIT TCP state, and TCP stack is able to release the
memory immediately, without waiting for 2xMSL period. If the client
doesn't disconnect in 2000ms, the server closes the connection
actively.
- Add Hash library, which has a function to calculate SHA1 hash.
- SD, Adafruit\_ILI9341, and OneWire libraries are now bundled.
- Fix incorrect sector calculation in EEPROM library.
--------------
1.6.4-628-g545ffde
------------------
May 19, 2015
- Initial release of Boards Manager package for ESP8266 platform.

169
doc/conf.py Normal file
View File

@ -0,0 +1,169 @@
# -*- coding: utf-8 -*-
#
# ESP8266 Arduino Core documentation build configuration file, created by
# sphinx-quickstart on Sun Feb 19 14:51:34 2017.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'ESP8266 Arduino Core'
copyright = u'2017, Ivan Grokhotkov'
author = u'Ivan Grokhotkov'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'2.4.0'
# The full version, including alpha/beta/rc tags.
release = u'2.4.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'ESP8266ArduinoCoredoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'ESP8266ArduinoCore.tex', u'ESP8266 Arduino Core Documentation',
u'Ivan Grokhotkov', 'manual'),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'esp8266arduinocore', u'ESP8266 Arduino Core Documentation',
[author], 1)
]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'ESP8266ArduinoCore', u'ESP8266 Arduino Core Documentation',
author, 'ESP8266ArduinoCore', 'One line description of project.',
'Miscellaneous'),
]
linkcheck_anchors_ignore = ["/#!"]
# -- Use sphinx_rtd_theme for local builds --------------------------------
# ref. https://github.com/snide/sphinx_rtd_theme#using-this-theme-locally-then-building-on-read-the-docs
#
# on_rtd is whether we are on readthedocs.org
env_readthedocs = os.environ.get('READTHEDOCS', None)
print env_readthedocs
if not env_readthedocs: # only import and set the theme if we're building docs locally
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

38
doc/eclipse/eclipse.md
View File

@ -1,38 +0,0 @@
using Eclipse with Arduino ESP8266
===========================================
### What to Download ###
- [arduino IDE](https://www.arduino.cc/en/Main/Software)
- [Eclipse IDE for C/C++ Developers](http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/marsr)
- [Java](http://www.java.com/)
### Setup Arduino ###
see the [Readme](https://github.com/esp8266/Arduino#installing-with-boards-manager)
### Setup Eclipse ###
- [step 1](http://www.baeyens.it/eclipse/how_to.shtml#/c)
- [step 2](http://www.baeyens.it/eclipse/how_to.shtml#/e)
- go to Window --> preferences --> Arduino
- add as private hardware path the Part to the ESP8266
###### example private hardware path
Windows: C:\Users\[username]\AppData\Roaming\Arduino15\packages\esp8266\hardware
Linux: /home/[username]/.arduino15/packages/esp8266/hardware
### Eclipse wont build ###
if eclipse dont find the path to the Compiler add to the platform.txt
after:
```
version=1.6.4
```
this:
```
runtime.tools.xtensa-lx106-elf-gcc.path={runtime.platform.path}/../../../tools/xtensa-lx106-elf-gcc/1.20.0-26-gb404fb9
runtime.tools.esptool.path={runtime.platform.path}/../../../tools/esptool/0.4.4
```
Note:
- the path may changed, check the current version.
- each update over the Arduino IDE will remove the fix
- may not needed in future if Eclipse Plugin get an Update

53
doc/eclipse/eclipse.rst Normal file
View File

@ -0,0 +1,53 @@
Using Eclipse with Arduino ESP8266
==================================
What to Download
~~~~~~~~~~~~~~~~
- `arduino IDE <https://www.arduino.cc/en/Main/Software>`__
- `Eclipse IDE for C/C++
Developers <http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/marsr>`__
- `Java <http://www.java.com/>`__
Setup Arduino
~~~~~~~~~~~~~
See the
`Readme <https://github.com/esp8266/Arduino#installing-with-boards-manager>`__
Setup Eclipse
~~~~~~~~~~~~~
- `step 1 <http://www.baeyens.it/eclipse/how_to.shtml#/c>`__
- `step 2 <http://www.baeyens.it/eclipse/how_to.shtml#/e>`__
- go to Window --> preferences --> Arduino
- add as private hardware path the Part to the ESP8266
example private hardware path
::
Windows: C:\Users\[username]\AppData\Roaming\Arduino15\packages\esp8266\hardware
Linux: /home/[username]/.arduino15/packages/esp8266/hardware
Eclipse wont build
~~~~~~~~~~~~~~~~~~
if eclipse dont find the path to the Compiler add to the platform.txt
after:
::
version=1.6.4
this:
::
runtime.tools.xtensa-lx106-elf-gcc.path={runtime.platform.path}/../../../tools/xtensa-lx106-elf-gcc/1.20.0-26-gb404fb9
runtime.tools.esptool.path={runtime.platform.path}/../../../tools/esptool/0.4.4
Note: - the path may changed, check the current version. - each update
over the Arduino IDE will remove the fix - may not needed in future if
Eclipse Plugin get an Update

65
doc/esp8266wifi/client-class.md
View File

@ -1,65 +0,0 @@
---
title: ESP8266WiFi Client Class
---
[ESP8266WiFi Library :back:](readme.md#client)
## Client Class
Methods documented for [Client](https://www.arduino.cc/en/Reference/WiFiClientConstructor) in [Arduino](https://github.com/arduino/Arduino)
1. [WiFiClient()](https://www.arduino.cc/en/Reference/WiFiClient)
2. [connected()](https://www.arduino.cc/en/Reference/WiFiClientConnected)
3. [connect()](https://www.arduino.cc/en/Reference/WiFiClientConnect)
4. [write()](https://www.arduino.cc/en/Reference/WiFiClientWrite)
5. [print()](https://www.arduino.cc/en/Reference/WiFiClientPrint)
6. [println()](https://www.arduino.cc/en/Reference/WiFiClientPrintln)
7. [available()](https://www.arduino.cc/en/Reference/WiFiClientAvailable)
8. [read()](https://www.arduino.cc/en/Reference/WiFiClientRead)
9. [flush()](https://www.arduino.cc/en/Reference/WiFiClientFlush)
10. [stop()](https://www.arduino.cc/en/Reference/WiFIClientStop)
Methods and properties described further down are specific to ESP8266. They are not covered in [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi) documentation. Before they are fully documented please refer to information below.
### setNoDelay
```cpp
setNoDelay(nodelay)
```
With `nodelay` set to `true`, this function will to disable [Nagle algorithm](https://en.wikipedia.org/wiki/Nagle%27s_algorithm).
This algorithm is intended to reduce TCP/IP traffic of small packets sent over the network by combining a number of small outgoing messages, and sending them all at once. The downside of such approach is effectively delaying individual messages until a big enough packet is assembled.
*Example:*
```cpp
client.setNoDelay(true);
```
### Other Function Calls
```cpp
uint8_t status ()
virtual size_t write (const uint8_t *buf, size_t size)
size_t write_P (PGM_P buf, size_t size)
size_t write (Stream &stream)
size_t write (Stream &stream, size_t unitSize) __attribute__((deprecated))
virtual int read (uint8_t *buf, size_t size)
virtual int peek ()
virtual size_t peekBytes (uint8_t *buffer, size_t length)
size_t peekBytes (char *buffer, size_t length)
virtual operator bool ()
IPAddress remoteIP ()
uint16_t remotePort ()
IPAddress localIP ()
uint16_t localPort ()
bool getNoDelay ()
```
Documentation for the above functions is not yet prepared.
For code samples please refer to separate section with [examples :arrow_right:](client-examples.md) dedicated specifically to the Client Class.

62
doc/esp8266wifi/client-class.rst Normal file
View File

@ -0,0 +1,62 @@
:orphan:
Client Class
------------
Methods documented for `Client <https://www.arduino.cc/en/Reference/WiFiClientConstructor>`__ in `Arduino <https://github.com/arduino/Arduino>`__
1. `WiFiClient() <https://www.arduino.cc/en/Reference/WiFiClient>`__
2. `connected() <https://www.arduino.cc/en/Reference/WiFiClientConnected>`__
3. `connect() <https://www.arduino.cc/en/Reference/WiFiClientConnect>`__
4. `write() <https://www.arduino.cc/en/Reference/WiFiClientWrite>`__
5. `print() <https://www.arduino.cc/en/Reference/WiFiClientPrint>`__
6. `println() <https://www.arduino.cc/en/Reference/WiFiClientPrintln>`__
7. `available() <https://www.arduino.cc/en/Reference/WiFiClientAvailable>`__
8. `read() <https://www.arduino.cc/en/Reference/WiFiClientRead>`__
9. `flush() <https://www.arduino.cc/en/Reference/WiFiClientFlush>`__
10. `stop() <https://www.arduino.cc/en/Reference/WiFIClientStop>`__
Methods and properties described further down are specific to ESP8266. They are not covered in `Arduino WiFi library <https://www.arduino.cc/en/Reference/WiFi>`__ documentation. Before they are fully documented please refer to information below.
setNoDelay
~~~~~~~~~~
.. code:: cpp
setNoDelay(nodelay)
With ``nodelay`` set to ``true``, this function will to disable `Nagle algorithm <https://en.wikipedia.org/wiki/Nagle%27s_algorithm>`__.
This algorithm is intended to reduce TCP/IP traffic of small packets sent over the network by combining a number of small outgoing messages, and sending them all at once. The downside of such approach is effectively delaying individual messages until a big enough packet is assembled.
*Example:*
.. code:: cpp
client.setNoDelay(true);
Other Function Calls
~~~~~~~~~~~~~~~~~~~~
.. code:: cpp
uint8_t status ()
virtual size_t write (const uint8_t *buf, size_t size)
size_t write_P (PGM_P buf, size_t size)
size_t write (Stream &stream)
size_t write (Stream &stream, size_t unitSize) __attribute__((deprecated))
virtual int read (uint8_t *buf, size_t size)
virtual int peek ()
virtual size_t peekBytes (uint8_t *buffer, size_t length)
size_t peekBytes (char *buffer, size_t length)
virtual operator bool ()
IPAddress remoteIP ()
uint16_t remotePort ()
IPAddress localIP ()
uint16_t localPort ()
bool getNoDelay ()
Documentation for the above functions is not yet prepared.
For code samples please refer to separate section with `examples
:arrow\_right: <client-examples.md>`__ dedicated specifically to the Client Class.

256
doc/esp8266wifi/client-examples.md
View File

@ -1,256 +0,0 @@
---
title: ESP8266WiFi Client Class - Sketch Examples
---
[ESP8266WiFi Library :back:](readme.md#client)
## Client
Let's write a simple client program to access a single web page and display its contents on a serial monitor. This is typical operation performed by a client to access server's API to retrieve specific information. For instance we may want to contact GitHub's API to periodically check the number of open issues reported on [esp8266 / Arduino](https://github.com/esp8266/Arduino/issues) repository.
## Table of Contents
* [Introduction](#introduction)
* [Get Connected to Wi-Fi](#get-connected-to-wi-fi)
* [Select a Server](#select-a-server)
* [Instantiate the Client](#instantiate-the-client)
* [Get Connected to the Server](#get-connected-to-the-server)
* [Request the Data](#request-the-data)
* [Read Reply from the Server](#read-reply-from-the-server)
* [Now to the Sketch](#now-to-the-sketch)
* [Test it Live](#test-it-live)
* [Test it More](#test-it-more)
* [Conclusion](#conclusion)
### Introduction
This time we are going to concentrate just on retrieving a web page contents sent by a server, to demonstrate basic client's functionality. Once you are able to retrieve information from a server, you should be able to phrase it and extract specific data you need.
### Get Connected to Wi-Fi
We should start with connecting the module to an access point to obtain an access to internet. The code to provide this functionality has been already discussed in chapter [Quick Start](readme.md#quick-start). Please refer to it for details.
### Select a Server
Once connected to the network we should connect to the specific server. Web address of this server is declared in `host` character string as below.
```cpp
const char* host = "www.example.com";
```
I have selected `www.example.com` domain name and you can select any other. Just check if you can access it using a web browser.
![alt text](pictures/client-example-domain.png "A web page to be retreived by the clinet program")
### Instantiate the Client
Now we should declare a client that will be contacting the host (server):
```cpp
WiFiClient client;
```
### Get Connected to the Server
In next line we will connect to the host and check the connection result. Note `80`, that is the standard port number used for web access.
```cpp
if (client.connect(host, 80))
{
// we are connected to the host!
}
else
{
// connection failure
}
```
### Request the Data
If connection is successful, we should send request the host to provide specific information we need. This is done using the [HTTP GET](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) request as in the following lines:
```cpp
client.print(String("GET /") + " HTTP/1.1\r\n" +
"Host: " + host + "\r\n" +
"Connection: close\r\n" +
"\r\n"
);
```
### Read Reply from the Server
Then, while connection by our client is still alive (`while (client.connected())`, see below) we can read line by line and print out server's response:
```cpp
while (client.connected())
{
if (client.available())
{
String line = client.readStringUntil('\n');
Serial.println(line);
}
}
```
The inner `if (client.available())` is checking if there are any data available from the server. If so, then they are printed out.
Once server sends all requested data it will disconnect and program will exit the `while` loop.
### Now to the Sketch
Complete sketch, including a case when contention to the server fails, is presented below.
```cpp
#include <ESP8266WiFi.h>
const char* ssid = "********";
const char* password = "********";
const char* host = "www.example.com";
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.printf("Connecting to %s ", ssid);
WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.println(" connected");
}
void loop()
{
WiFiClient client;
Serial.printf("\n[Connecting to %s ... ", host);
if (client.connect(host, 80))
{
Serial.println("connected]");
Serial.println("[Sending a request]");
client.print(String("GET /") + " HTTP/1.1\r\n" +
"Host: " + host + "\r\n" +
"Connection: close\r\n" +
"\r\n"
);
Serial.println("[Response:]");
while (client.connected())
{
if (client.available())
{
String line = client.readStringUntil('\n');
Serial.println(line);
}
}
client.stop();
Serial.println("\n[Disconnected]");
}
else
{
Serial.println("connection failed!]");
client.stop();
}
delay(5000);
}
```
### Test it Live
Upload sketch the module and open serial monitor. You should see a log similar to presented below.
First, after establishing Wi-Fi connection, you should see confirmation, that client connected to the server and send the request:
```
Connecting to sensor-net ........ connected
[Connecting to www.example.com ... connected]
[Sending a request]
```
Then, after getting the request, server will first respond with a header that specifies what type of information will follow (e.g. `Content-Type: text/html`), how long it is (like `Content-Length: 1270`), etc.:
```
[Response:]
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: text/html
Date: Sat, 30 Jul 2016 12:30:45 GMT
Etag: "359670651+ident"
Expires: Sat, 06 Aug 2016 12:30:45 GMT
Last-Modified: Fri, 09 Aug 2013 23:54:35 GMT
Server: ECS (ewr/15BD)
Vary: Accept-Encoding
X-Cache: HIT
x-ec-custom-error: 1
Content-Length: 1270
Connection: close
```
End of header is marked with an empty line and then you should see the HTML code of requested web page.
```
<!doctype html>
<html>
<head>
<title>Example Domain</title>
<meta charset="utf-8" />
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<style type="text/css">
(...)
</head>
<body>
<div>
<h1>Example Domain</h1>
<p>This domain is established to be used for illustrative examples in documents. You may use this
domain in examples without prior coordination or asking for permission.</p>
<p><a href="http://www.iana.org/domains/example">More information...</a></p>
</div>
</body>
</html>
[Disconnected]
```
### Test it More
In case server's web address is incorrect, or server is not accessible, you should see the following short and simple message on the serial monitor:
```
Connecting to sensor-net ........ connected
[Connecting to www.wrong-example.com ... connection failed!]
```
### Conclusion
With this simple example we have demonstrated how to set up a client program, connect it to a server, request a web page and retrieve it. Now you should be able to write your own client program for ESP8266 and move to more advanced dialogue with a server, like e.g. using [HTTPS](https://en.wikipedia.org/wiki/HTTPS) protocol with the [Client Secure](readme.md#client-secure).
For more client examples please check
* [WiFiClientBasic.ino](https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiClientBasic/WiFiClientBasic.ino) - a simple sketch that sends a message to a TCP server
* [WiFiClient.ino](https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiClient/WiFiClient.ino) - this sketch sends data via HTTP GET requests to data.sparkfun.com service.
For the list of functions provided to manage clients, please refer to the [Client Class :arrow_right:](client-class.md) documentation.

260
doc/esp8266wifi/client-examples.rst Normal file
View File

@ -0,0 +1,260 @@
:orphan:
Client
------
Let's write a simple client program to access a single web page and display its contents on a serial monitor. This is typical operation performed by a client to access server's API to retrieve specific information. For instance we may want to contact GitHub's API to periodically check the number of open issues reported on `esp8266/Arduino <https://github.com/esp8266/Arduino/issues>`__ repository.
Table of Contents
-----------------
- `Introduction <#introduction>`__
- `Get Connected to Wi-Fi <#get-connected-to-wi-fi>`__
- `Select a Server <#select-a-server>`__
- `Instantiate the Client <#instantiate-the-client>`__
- `Get Connected to the Server <#get-connected-to-the-server>`__
- `Request the Data <#request-the-data>`__
- `Read Reply from the Server <#read-reply-from-the-server>`__
- `Now to the Sketch <#now-to-the-sketch>`__
- `Test it Live <#test-it-live>`__
- `Test it More <#test-it-more>`__
- `Conclusion <#conclusion>`__
Introduction
~~~~~~~~~~~~
This time we are going to concentrate just on retrieving a web page contents sent by a server, to demonstrate basic client's functionality. Once you are able to retrieve information from a server, you should be able to phrase it and extract specific data you need.
Get Connected to Wi-Fi
~~~~~~~~~~~~~~~~~~~~~~
We should start with connecting the module to an access point to obtain an access to internet. The code to provide this functionality has been already discussed in chapter `Quick Start <readme.md#quick-start>`__. Please refer to it for details.
Select a Server
~~~~~~~~~~~~~~~
Once connected to the network we should connect to the specific server. Web address of this server is declared in ``host`` character string as below.
.. code:: cpp
const char* host = "www.example.com";
I have selected ``www.example.com`` domain name and you can select any other. Just check if you can access it using a web browser.
.. figure:: pictures/client-example-domain.png
:alt: A web page to be retreived by the clinet program
alt text
Instantiate the Client
~~~~~~~~~~~~~~~~~~~~~~
Now we should declare a client that will be contacting the host (server):
.. code:: cpp
WiFiClient client;
Get Connected to the Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~
In next line we will connect to the host and check the connection result. Note ``80``, that is the standard port number used for web access.
.. code:: cpp
if (client.connect(host, 80))
{
// we are connected to the host!
}
else
{
// connection failure
}
Request the Data
~~~~~~~~~~~~~~~~
If connection is successful, we should send request the host to provide specific information we need. This is done using the `HTTP GET <https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods>`__ request as in the following lines:
.. code:: cpp
client.print(String("GET /") + " HTTP/1.1\r\n" +
"Host: " + host + "\r\n" +
"Connection: close\r\n" +
"\r\n"
);
Read Reply from the Server
~~~~~~~~~~~~~~~~~~~~~~~~~~
Then, while connection by our client is still alive (``while (client.connected())``, see below) we can read line by line and print out server's response:
.. code:: cpp
while (client.connected())
{
if (client.available())
{
String line = client.readStringUntil('\n');
Serial.println(line);
}
}
The inner ``if (client.available())`` is checking if there are any data available from the server. If so, then they are printed out.
Once server sends all requested data it will disconnect and program will exit the ``while`` loop.
Now to the Sketch
~~~~~~~~~~~~~~~~~
Complete sketch, including a case when contention to the server fails, is presented below.
.. code:: cpp
#include <ESP8266WiFi.h>
const char* ssid = "********";
const char* password = "********";
const char* host = "www.example.com";
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.printf("Connecting to %s ", ssid);
WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.println(" connected");
}
void loop()
{
WiFiClient client;
Serial.printf("\n[Connecting to %s ... ", host);
if (client.connect(host, 80))
{
Serial.println("connected]");
Serial.println("[Sending a request]");
client.print(String("GET /") + " HTTP/1.1\r\n" +
"Host: " + host + "\r\n" +
"Connection: close\r\n" +
"\r\n"
);
Serial.println("[Response:]");
while (client.connected())
{
if (client.available())
{
String line = client.readStringUntil('\n');
Serial.println(line);
}
}
client.stop();
Serial.println("\n[Disconnected]");
}
else
{
Serial.println("connection failed!]");
client.stop();
}
delay(5000);
}
Test it Live
~~~~~~~~~~~~
Upload sketch the module and open serial monitor. You should see a log similar to presented below.
First, after establishing Wi-Fi connection, you should see confirmation, that client connected to the server and send the request:
::
Connecting to sensor-net ........ connected
[Connecting to www.example.com ... connected]
[Sending a request]
Then, after getting the request, server will first respond with a header that specifies what type of information will follow (e.g. ``Content-Type: text/html``), how long it is (like ``Content-Length: 1270``), etc.:
::
[Response:]
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: text/html
Date: Sat, 30 Jul 2016 12:30:45 GMT
Etag: "359670651+ident"
Expires: Sat, 06 Aug 2016 12:30:45 GMT
Last-Modified: Fri, 09 Aug 2013 23:54:35 GMT
Server: ECS (ewr/15BD)
Vary: Accept-Encoding
X-Cache: HIT
x-ec-custom-error: 1
Content-Length: 1270
Connection: close
End of header is marked with an empty line and then you should see the HTML code of requested web page.
::
<!doctype html>
<html>
<head>
<title>Example Domain</title>
<meta charset="utf-8" />
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<style type="text/css">
(...)
</head>
<body>
<div>
<h1>Example Domain</h1>
<p>This domain is established to be used for illustrative examples in documents. You may use this
domain in examples without prior coordination or asking for permission.</p>
<p><a href="http://www.iana.org/domains/example">More information...</a></p>
</div>
</body>
</html>
[Disconnected]
Test it More
~~~~~~~~~~~~
In case server's web address is incorrect, or server is not accessible, you should see the following short and simple message on the serial monitor:
::
Connecting to sensor-net ........ connected
[Connecting to www.wrong-example.com ... connection failed!]
Conclusion
~~~~~~~~~~
With this simple example we have demonstrated how to set up a client program, connect it to a server, request a web page and retrieve it. Now you should be able to write your own client program for ESP8266 and move to more advanced dialogue with a server, like e.g. using `HTTPS <https://en.wikipedia.org/wiki/HTTPS>`__ protocol with the `Client Secure <readme.md#client-secure>`__.
For more client examples please check
- `WiFiClientBasic.ino <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiClientBasic/WiFiClientBasic.ino>`__ - a simple sketch that sends a message to a TCP server
- `WiFiClient.ino <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiClient/WiFiClient.ino>`__ - this sketch sends data via HTTP GET requests to data.sparkfun.com service.
For the list of functions provided to manage clients, please refer to the `Client Class :arrow\_right: <client-class.md>`__ documentation.

81
doc/esp8266wifi/client-secure-class.md
View File

@ -1,81 +0,0 @@
---
title: ESP8266WiFi Client Secure Class
---
[ESP8266WiFi Library :back:](readme.md#client-secure)
## Client Secure Class
Methods and properties described in this section are specific to ESP8266. They are not covered in [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi) documentation. Before they are fully documented please refer to information below.
### loadCertificate
Load client certificate from file system.
```cpp
loadCertificate(file)
```
*Declarations*
```cpp
#include <FS.h>
#include <ESP8266WiFi.h>
#include <WiFiClientSecure.h>
const char* certyficateFile = "/client.cer";
```
*setup() or loop()*
```cpp
if (!SPIFFS.begin())
{
Serial.println("Failed to mount the file system");
return;
}
Serial.printf("Opening %s", certyficateFile);
File crtFile = SPIFFS.open(certyficateFile, "r");
if (!crtFile)
{
Serial.println(" Failed!");
}
WiFiClientSecure client;
Serial.print("Loading %s", certyficateFile);
if (!client.loadCertificate(crtFile))
{
Serial.println(" Failed!");
}
// proceed with connecting of client to the host
```
### setCertificate
Load client certificate from C array.
```cpp
setCertificate (array, size)
```
For a practical example please check [this interesting blog](https://nofurtherquestions.wordpress.com/2016/03/14/making-an-esp8266-web-accessible/).
### Other Function Calls
```cpp
bool verify (const char *fingerprint, const char *domain_name)
void setPrivateKey (const uint8_t *pk, size_t size)
bool loadCertificate (Stream &stream, size_t size)
bool loadPrivateKey (Stream &stream, size_t size)
template<typename TFile > bool loadPrivateKey (TFile &file)
```
Documentation for the above functions is not yet prepared.
For code samples please refer to separate section with [examples :arrow_right:](client-secure-examples.md) dedicated specifically to the Client Secure Class.

78
doc/esp8266wifi/client-secure-class.rst Normal file
View File

@ -0,0 +1,78 @@
:orphan:
Client Secure Class
-------------------
Methods and properties described in this section are specific to ESP8266. They are not covered in `Arduino WiFi library <https://www.arduino.cc/en/Reference/WiFi>`__ documentation. Before they are fully documented please refer to information below.
loadCertificate
~~~~~~~~~~~~~~~
Load client certificate from file system.
.. code:: cpp
loadCertificate(file)
*Declarations*
.. code:: cpp
#include <FS.h>
#include <ESP8266WiFi.h>
#include <WiFiClientSecure.h>
const char* certyficateFile = "/client.cer";
*setup() or loop()*
.. code:: cpp
if (!SPIFFS.begin())
{
Serial.println("Failed to mount the file system");
return;
}
Serial.printf("Opening %s", certyficateFile);
File crtFile = SPIFFS.open(certyficateFile, "r");
if (!crtFile)
{
Serial.println(" Failed!");
}
WiFiClientSecure client;
Serial.print("Loading %s", certyficateFile);
if (!client.loadCertificate(crtFile))
{
Serial.println(" Failed!");
}
// proceed with connecting of client to the host
setCertificate
~~~~~~~~~~~~~~
Load client certificate from C array.
.. code:: cpp
setCertificate (array, size)
For a practical example please check `this interesting blog <https://nofurtherquestions.wordpress.com/2016/03/14/making-an-esp8266-web-accessible/>`__.
Other Function Calls
~~~~~~~~~~~~~~~~~~~~
.. code:: cpp
bool verify (const char *fingerprint, const char *domain_name)
void setPrivateKey (const uint8_t *pk, size_t size)
bool loadCertificate (Stream &stream, size_t size)
bool loadPrivateKey (Stream &stream, size_t size)
template<typename TFile > bool loadPrivateKey (TFile &file)
Documentation for the above functions is not yet prepared.
For code samples please refer to separate section with `examples <client-secure-examples.md>`__ dedicated specifically to the Client Secure Class.

172
doc/esp8266wifi/client-secure-examples.md
View File

@ -1,172 +0,0 @@
---
title: ESP8266WiFi Client Secure Class - Sketch Examples
---
[ESP8266WiFi Library :back:](readme.md#client-secure)
## Client Secure
The client secure is a [client](#client) but secure. Application example below will be easier to follow if you check similar and simpler [example](client-examples.md) for the "ordinary" client. That being said we will concentrate on discussing the code that is specific to the client secure.
## Table of Contents
* [Introduction](#introduction)
* [The Sketch](#the-sketch)
* [How to Verify Server's Identity?](#how-to-verify-server-s-identity)
* [Get the Fingerprint](#get-the-fingerprint)
* [Connect to the Server](#connect-to-the-server)
* [Is it THAT Server?](#is-it-that-server)
* [GET Response from the Server](#get-response-from-the-server)
* [Read and Check the Response](#read-and-check-the-response)
* [Does it Work?](#does-it-work)
* [Conclusion](#conclusion)
### Introduction
In this example we will be retrieving information from a secure server https://api.github.com. This server is set up in place to provide specific and structured information on [GitHub](https://github.com) repositories. For instance, we may ask it to provide us the build status or the latest version of [esp8266 / Adruino](https://github.com/esp8266/Arduino/) core.
The build status of esp8266 / Adruino may be checked on the repository's [home page](https://github.com/esp8266/Arduino#using-git-version) or on [Travis CI](https://travis-ci.org/esp8266/Arduino) site as below:
![alt text](pictures/esp8266-arduino-build-status-travisci.png "Build status of esp8266 / Arduino repository on Travis CI site")
GitHub provides a separate server with [API](https://developer.github.com/v3/) to access such information is structured form as [JSON](https://en.wikipedia.org/wiki/JSON).
As you may guess we will use the client secure to contact https://api.github.com server and request the [build status](https://developer.github.com/v3/repos/statuses/#get-the-combined-status-for-a-specific-ref). If we open specific resource provided in the API with a web browser, the following should show up:
![alt text](pictures/esp8266-arduino-build-status-json.png "Build status of esp8266 / Arduino repository in JSON fromat")
What we need to do, is to use client secure to connect to `https://api.github.com`, to GET `/repos/esp8266/Arduino/commits/master/status`, search for the line `"state": "success"` and display "Build Successful" if we find it, or "Build Failed" if otherwise.
### The Sketch
A classic [sketch](https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/HTTPSRequest/HTTPSRequest.ino) that is doing what we need is already available among [examples](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi/examples) of ESP8266WiFi library. Please open it to go through it step by step.
### How to Verify Server's Identity?
To establish a secure connection with a server we need to verify server's identity. Clients that run on "regular" computers do it by comparing server's certificate with locally stored list of trusted root certificates. Such certificates take several hundreds of KB, so it is not a good option for an ESP module. As an alternative we can use much smaller SHA1 fingerprint of specific certificate.
In declaration section of code we provide the name of `host` and the corresponding `fingerprint`.
```cpp
const char* host = "api.github.com";
const char* fingerprint = "CF 05 98 89 CA FF 8E D8 5E 5C E0 C2 E4 F7 E6 C3 C7 50 DD 5C";
```
### Get the Fingerprint
We can obtain the `fingerprint` for specific `host` using a web browser. For instance on Chrome press *Ctrl+Shift+I* and go to *Security > View Certificate > Details > Thumbprint*. This will show a window like below where you can copy the fingerprint and paste it into sketch.
![alt text](pictures/client-secure-check-fingerprint.png "Locating the fingerprint of GitHub api")
Remaining steps look almost identical as for the [non-secure client example](client-examples.md).
### Connect to the Server
Instantiate the `WiFiClientSecure` object and establish a connection (please note we need to use specific `httpsPort` for secure connections):
```cpp
WiFiClientSecure client;
Serial.print("connecting to ");
Serial.println(host);
if (!client.connect(host, httpsPort)) {
Serial.println("connection failed");
return;
}
```
### Is it THAT Server?
Now verify if the fingerprint we have matches this one provided by the server:
```cpp
if (client.verify(fingerprint, host)) {
Serial.println("certificate matches");
} else {
Serial.println("certificate doesn't match");
}
```
If this check fails, it is up to you to decide if to proceed further or abort connection. Also note that certificates have specific validity period. Therefore the fingerprint of certificate we have checked today, will certainly be invalid some time later.
### GET Response from the Server
In the next steps we should execute GET command. This is done is similar way as discussed in [non-secure client example](client-examples.md).
```cpp
client.print(String("GET ") + url + " HTTP/1.1\r\n" +
"Host: " + host + "\r\n" +
"User-Agent: BuildFailureDetectorESP8266\r\n" +
"Connection: close\r\n\r\n");
```
After sending the request we should wait for a reply and then process received information.
Out of received replay we can skip response header. This can be done by reading until an empty line `"\r"` that marks the end of the header:
```cpp
while (client.connected()) {
String line = client.readStringUntil('\n');
if (line == "\r") {
Serial.println("headers received");
break;
}
}
```
### Read and Check the Response
Finally we should read JSON provided by server and check if it contains `{"state": "success"`:
```cpp
String line = client.readStringUntil('\n');
if (line.startsWith("{\"state\":\"success\"")) {
Serial.println("esp8266/Arduino CI successfull!");
} else {
Serial.println("esp8266/Arduino CI has failed");
}
```
### Does it Work?
Now once you know how it should work, get the [sketch](https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/HTTPSRequest/HTTPSRequest.ino). Update credentials to your Wi-Fi network. Check the current fingerprint of `api.github.com` and update it if required. Then upload sketch and open a serial monitor.
If everything is fine (including build status of esp8266 / Arduino) you should see message as below:
```
connecting to sensor-net
........
WiFi connected
IP address:
192.168.1.104
connecting to api.github.com
certificate matches
requesting URL: /repos/esp8266/Arduino/commits/master/status
request sent
headers received
esp8266/Arduino CI successfull!
reply was:
==========
{"state":"success","statuses":[{"url":"https://api.github.com/repos/esp8266/Arduino/statuses/8cd331a8bae04a6f1443ff0c93539af4720d8ddf","id":677326372,"state":"success","description":"The Travis CI build passed","target_url":"https://travis-ci.org/esp8266/Arduino/builds/148827821","context":"continuous-integration/travis-ci/push","created_at":"2016-08-01T09:54:38Z","updated_at":"2016-08-01T09:54:38Z"},{"url":"https://api.github.com/repos/esp8266/Arduino/statuses/8cd331a8bae04a6f1443ff0c93539af4720d8ddf","id":677333081,"state":"success","description":"27.62% (+0.00%) compared to 0718188","target_url":"https://codecov.io/gh/esp8266/Arduino/commit/8cd331a8bae04a6f1443ff0c93539af4720d8ddf","context":"codecov/project","created_at":"2016-08-01T09:59:05Z","updated_at":"2016-08-01T09:59:05Z"},
(...)
==========
closing connection
```
### Conclusion
Programming a secure client is almost identical as programming a non-secure client. The difference gets down to one extra step to verify server's identity. Keep in mind limitations due to heavy memory usage that depends on the strength of the key used by the server and whether server is willing to negotiate the [TLS buffer size](https://www.igvita.com/2013/10/24/optimizing-tls-record-size-and-buffering-latency/).
For the list of functions provided to manage secure clients, please refer to the [Client Secure Class :arrow_right:](client-secure-class.md) documentation.

181
doc/esp8266wifi/client-secure-examples.rst Normal file
View File

@ -0,0 +1,181 @@
:orphan:
Client Secure
-------------
The client secure is a `client <#client>`__ but secure. Application example below will be easier to follow if you check similar and simpler `example <client-examples.md>`__ for the "ordinary" client. That being said we will concentrate on discussing the code that is specific to the client secure.
Table of Contents
-----------------
- `Introduction <#introduction>`__
- `The Sketch <#the-sketch>`__
- `How to Verify Server's
Identity? <#how-to-verify-server-s-identity>`__
- `Get the Fingerprint <#get-the-fingerprint>`__
- `Connect to the Server <#connect-to-the-server>`__
- `Is it THAT Server? <#is-it-that-server>`__
- `GET Response from the Server <#get-response-from-the-server>`__
- `Read and Check the Response <#read-and-check-the-response>`__
- `Does it Work? <#does-it-work>`__
- `Conclusion <#conclusion>`__
Introduction
~~~~~~~~~~~~
In this example we will be retrieving information from a secure server https://api.github.com. This server is set up in place to provide specific and structured information on `GitHub <https://github.com>`__ repositories. For instance, we may ask it to provide us the build status or the latest version of `esp8266 /
Adruino <https://github.com/esp8266/Arduino/>`__ core.
The build status of esp8266 / Adruino may be checked on the repository's `home page <https://github.com/esp8266/Arduino#using-git-version>`__ or on `Travis CI <https://travis-ci.org/esp8266/Arduino>`__ site as below:
.. figure:: pictures/esp8266-arduino-build-status-travisci.png
:alt: Build status of esp8266 / Arduino repository on Travis CI site
alt text
GitHub provides a separate server with `API <https://developer.github.com/v3/>`__ to access such information is structured form as `JSON <https://en.wikipedia.org/wiki/JSON>`__.
As you may guess we will use the client secure to contact https://api.github.com server and request the `build status <https://developer.github.com/v3/repos/statuses/#get-the-combined-status-for-a-specific-ref>`__. If we open specific resource provided in the API with a web browser, the following should show up:
.. figure:: pictures/esp8266-arduino-build-status-json.png
:alt: Build status of esp8266 / Arduino repository in JSON fromat
alt text
What we need to do, is to use client secure to connect to ``https://api.github.com``, to GET ``/repos/esp8266/Arduino/commits/master/status``, search for the line ``"state": "success"`` and display "Build Successful" if we find it, or "Build Failed" if otherwise.
The Sketch
~~~~~~~~~~
A classic `sketch <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/HTTPSRequest/HTTPSRequest.ino>`__ that is doing what we need is already available among `examples <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi/examples>`__ of ESP8266WiFi library. Please open it to go through it step by step.
How to Verify Server's Identity?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To establish a secure connection with a server we need to verify server's identity. Clients that run on "regular" computers do it by comparing server's certificate with locally stored list of trusted root certificates. Such certificates take several hundreds of KB, so it is not a good option for an ESP module. As an alternative we can use much smaller SHA1 fingerprint of specific certificate.
In declaration section of code we provide the name of ``host`` and the corresponding ``fingerprint``.
.. code:: cpp
const char* host = "api.github.com";
const char* fingerprint = "CF 05 98 89 CA FF 8E D8 5E 5C E0 C2 E4 F7 E6 C3 C7 50 DD 5C";
Get the Fingerprint
~~~~~~~~~~~~~~~~~~~
We can obtain the ``fingerprint`` for specific ``host`` using a web browser. For instance on Chrome press *Ctrl+Shift+I* and go to *Security > View Certificate > Details > Thumbprint*. This will show a window like below where you can copy the fingerprint and paste it into sketch.
.. figure:: pictures/client-secure-check-fingerprint.png
:alt: Locating the fingerprint of GitHub api
alt text
Remaining steps look almost identical as for the `non-secure client example <client-examples.md>`__.
Connect to the Server
~~~~~~~~~~~~~~~~~~~~~
Instantiate the ``WiFiClientSecure`` object and establish a connection (please note we need to use specific ``httpsPort`` for secure connections):
.. code:: cpp
WiFiClientSecure client;
Serial.print("connecting to ");
Serial.println(host);
if (!client.connect(host, httpsPort)) {
Serial.println("connection failed");
return;
}
Is it THAT Server?
~~~~~~~~~~~~~~~~~~
Now verify if the fingerprint we have matches this one provided by the server:
.. code:: cpp
if (client.verify(fingerprint, host)) {
Serial.println("certificate matches");
} else {
Serial.println("certificate doesn't match");
}
If this check fails, it is up to you to decide if to proceed further or abort connection. Also note that certificates have specific validity period. Therefore the fingerprint of certificate we have checked today, will certainly be invalid some time later.
GET Response from the Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the next steps we should execute GET command. This is done is similar way as discussed in `non-secure client example <client-examples.md>`__.
.. code:: cpp
client.print(String("GET ") + url + " HTTP/1.1\r\n" +
"Host: " + host + "\r\n" +
"User-Agent: BuildFailureDetectorESP8266\r\n" +
"Connection: close\r\n\r\n");
After sending the request we should wait for a reply and then process received information.
Out of received replay we can skip response header. This can be done by reading until an empty line ``"\r"`` that marks the end of the header:
.. code:: cpp
while (client.connected()) {
String line = client.readStringUntil('\n');
if (line == "\r") {
Serial.println("headers received");
break;
}
}
Read and Check the Response
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Finally we should read JSON provided by server and check if it contains ``{"state": "success"``:
.. code:: cpp
String line = client.readStringUntil('\n');
if (line.startsWith("{\"state\":\"success\"")) {
Serial.println("esp8266/Arduino CI successfull!");
} else {
Serial.println("esp8266/Arduino CI has failed");
}
Does it Work?
~~~~~~~~~~~~~
Now once you know how it should work, get the `sketch <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/HTTPSRequest/HTTPSRequest.ino>`__. Update credentials to your Wi-Fi network. Check the current fingerprint of ``api.github.com`` and update it if required. Then upload sketch and open a serial monitor.
If everything is fine (including build status of esp8266 / Arduino) you should see message as below:
::
connecting to sensor-net
........
WiFi connected
IP address:
192.168.1.104
connecting to api.github.com
certificate matches
requesting URL: /repos/esp8266/Arduino/commits/master/status
request sent
headers received
esp8266/Arduino CI successfull!
reply was:
==========
{"state":"success","statuses":[{"url":"https://api.github.com/repos/esp8266/Arduino/statuses/8cd331a8bae04a6f1443ff0c93539af4720d8ddf","id":677326372,"state":"success","description":"The Travis CI build passed","target_url":"https://travis-ci.org/esp8266/Arduino/builds/148827821","context":"continuous-integration/travis-ci/push","created_at":"2016-08-01T09:54:38Z","updated_at":"2016-08-01T09:54:38Z"},{"url":"https://api.github.com/repos/esp8266/Arduino/statuses/8cd331a8bae04a6f1443ff0c93539af4720d8ddf","id":677333081,"state":"success","description":"27.62% (+0.00%) compared to 0718188","target_url":"https://codecov.io/gh/esp8266/Arduino/commit/8cd331a8bae04a6f1443ff0c93539af4720d8ddf","context":"codecov/project","created_at":"2016-08-01T09:59:05Z","updated_at":"2016-08-01T09:59:05Z"},
(...)
==========
closing connection
Conclusion
~~~~~~~~~~
Programming a secure client is almost identical as programming a non-secure client. The difference gets down to one extra step to verify server's identity. Keep in mind limitations due to heavy memory usage that depends on the strength of the key used by the server and whether server is willing to negotiate the `TLS buffer size <https://www.igvita.com/2013/10/24/optimizing-tls-record-size-and-buffering-latency/>`__.
For the list of functions provided to manage secure clients, please refer to the `Client Secure Class
:arrow\_right: <client-secure-class.md>`__ documentation.

85
doc/esp8266wifi/generic-class.md
View File

@ -1,85 +0,0 @@
---
title: ESP8266WiFi Generic Class
---
[ESP8266WiFi Library :back:](readme.md#generic)
## Generic Class
Methods and properties described in this section are specific to ESP8266. They are not covered in [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi) documentation. Before they are fully documented please refer to information below.
### onEvent
```cpp
void onEvent (WiFiEventCb cb, WiFiEvent_t event=WIFI_EVENT_ANY) __attribute__((deprecated))
```
To see how to use `onEvent` please check example sketch [WiFiClientEvents.ino](https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiClientEvents/WiFiClientEvents.ino) available inside examples folder of the ESP8266WiFi library.
### WiFiEventHandler
```cpp
WiFiEventHandler onStationModeConnected (std::function< void(const WiFiEventStationModeConnected &)>)
WiFiEventHandler onStationModeDisconnected (std::function< void(const WiFiEventStationModeDisconnected &)>)
WiFiEventHandler onStationModeAuthModeChanged (std::function< void(const WiFiEventStationModeAuthModeChanged &)>)
WiFiEventHandler onStationModeGotIP (std::function< void(const WiFiEventStationModeGotIP &)>)
WiFiEventHandler onStationModeDHCPTimeout (std::function< void(void)>)
WiFiEventHandler onSoftAPModeStationConnected (std::function< void(const WiFiEventSoftAPModeStationConnected &)>)
WiFiEventHandler onSoftAPModeStationDisconnected (std::function< void(const WiFiEventSoftAPModeStationDisconnected &)>)
```
To see a sample application with `WiFiEventHandler`, please check separate section with [examples :arrow_right:](generic-examples.md) dedicated specifically to the Generic Class..
### persistent
```cpp
WiFi.persistent (persistent)
```
Module is able to reconnect to last used Wi-Fi network on power up or reset basing on settings stored in specific sectors of flash memory. By default these settings are written to flash each time they are used in functions like `WiFi.begin(ssid, password)`. This happens no matter if SSID or password has been actually changed.
This might result in some wear of flash memory depending on how often such functions are called.
Setting `persistent` to `false` will get SSID / password written to flash only if currently used values do not match what is already stored in flash.
Please note that functions `WiFi.disconnect` or `WiFi.softAPdisconnect` reset currently used SSID / password. If `persistent` is set to `false`, then using these functions will not affect SSID / password stored in flash.
To learn more about this functionality, and why it has been introduced, check issue report [#1054](https://github.com/esp8266/Arduino/issues/1054).
### mode
```cpp
WiFi.mode(m)
WiFi.getMode()
```
* `WiFi.mode(m)`: set mode to `WIFI_AP`, `WIFI_STA`, `WIFI_AP_STA` or `WIFI_OFF`
* `WiFi.getMode()`: return current Wi-Fi mode (one out of four modes above)
### Other Function Calls
```cpp
int32_t channel (void)
bool setSleepMode (WiFiSleepType_t type)
WiFiSleepType_t getSleepMode ()
bool setPhyMode (WiFiPhyMode_t mode)
WiFiPhyMode_t getPhyMode ()
void setOutputPower (float dBm)
WiFiMode_t getMode ()
bool enableSTA (bool enable)
bool enableAP (bool enable)
bool forceSleepBegin (uint32 sleepUs=0)
bool forceSleepWake ()
int hostByName (const char *aHostname, IPAddress &aResult)
```
Documentation for the above functions is not yet prepared.
For code samples please refer to separate section with [examples :arrow_right:](generic-examples.md) dedicated specifically to the Generic Class.

82
doc/esp8266wifi/generic-class.rst Normal file
View File

@ -0,0 +1,82 @@
:orphan:
Generic Class
-------------
Methods and properties described in this section are specific to ESP8266. They are not covered in `Arduino WiFi library <https://www.arduino.cc/en/Reference/WiFi>`__ documentation. Before they are fully documented please refer to information below.
onEvent
~~~~~~~
.. code:: cpp
void onEvent (WiFiEventCb cb, WiFiEvent_t event=WIFI_EVENT_ANY) __attribute__((deprecated))
To see how to use ``onEvent`` please check example sketch `WiFiClientEvents.ino <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiClientEvents/WiFiClientEvents.ino>`__ available inside examples folder of the ESP8266WiFi library.
WiFiEventHandler
~~~~~~~~~~~~~~~~
.. code:: cpp
WiFiEventHandler onStationModeConnected (std::function< void(const WiFiEventStationModeConnected &)>)
WiFiEventHandler onStationModeDisconnected (std::function< void(const WiFiEventStationModeDisconnected &)>)
WiFiEventHandler onStationModeAuthModeChanged (std::function< void(const WiFiEventStationModeAuthModeChanged &)>)
WiFiEventHandler onStationModeGotIP (std::function< void(const WiFiEventStationModeGotIP &)>)
WiFiEventHandler onStationModeDHCPTimeout (std::function< void(void)>)
WiFiEventHandler onSoftAPModeStationConnected (std::function< void(const WiFiEventSoftAPModeStationConnected &)>)
WiFiEventHandler onSoftAPModeStationDisconnected (std::function< void(const WiFiEventSoftAPModeStationDisconnected &)>)
To see a sample application with ``WiFiEventHandler``, please check separate section with `examples :arrow\_right: <generic-examples.md>`__ dedicated specifically to the Generic Class..
persistent
~~~~~~~~~~
.. code:: cpp
WiFi.persistent (persistent)
Module is able to reconnect to last used Wi-Fi network on power up or reset basing on settings stored in specific sectors of flash memory. By default these settings are written to flash each time they are used in functions like ``WiFi.begin(ssid, password)``. This happens no matter if SSID or password has been actually changed.
This might result in some wear of flash memory depending on how often such functions are called.
Setting ``persistent`` to ``false`` will get SSID / password written to flash only if currently used values do not match what is already stored in flash.
Please note that functions ``WiFi.disconnect`` or ``WiFi.softAPdisconnect`` reset currently used SSID / password. If ``persistent`` is set to ``false``, then using these functions will not affect SSID / password stored in flash.
To learn more about this functionality, and why it has been introduced, check issue report `#1054 <https://github.com/esp8266/Arduino/issues/1054>`__.
mode
~~~~
.. code:: cpp
WiFi.mode(m)
WiFi.getMode()
- ``WiFi.mode(m)``: set mode to ``WIFI_AP``, ``WIFI_STA``,
``WIFI_AP_STA`` or ``WIFI_OFF``
- ``WiFi.getMode()``: return current Wi-Fi mode (one out of four modes
above)
Other Function Calls
~~~~~~~~~~~~~~~~~~~~
.. code:: cpp
int32_t channel (void)
bool setSleepMode (WiFiSleepType_t type)
WiFiSleepType_t getSleepMode ()
bool setPhyMode (WiFiPhyMode_t mode)
WiFiPhyMode_t getPhyMode ()
void setOutputPower (float dBm)
WiFiMode_t getMode ()
bool enableSTA (bool enable)
bool enableAP (bool enable)
bool forceSleepBegin (uint32 sleepUs=0)
bool forceSleepWake ()
int hostByName (const char *aHostname, IPAddress &aResult)
Documentation for the above functions is not yet prepared.
For code samples please refer to separate section with `examples <generic-examples.md>`__ dedicated specifically to the Generic Class.

138
doc/esp8266wifi/generic-examples.md
View File

@ -1,138 +0,0 @@
---
title: ESP8266WiFi Generic Class - Sketch Examples
---
[ESP8266WiFi Library :back:](readme.md#generic)
## Generic
In the first [example](readme.md#quick-start) of the ESP8266WiFi library documentation we have discussed how to check when module connects to the Wi-Fi network. We were waiting until connection is established. If network is not available, the module could wait like that for ever doing nothing else. Another [example](scan-examples.md#async-scan) on the Wi-Fi asynchronous scan mode demonstrated how to wait for scan result and do in parallel something else - blink a LED not disturbing the blink pattern. Let's apply similar functionality when connecting the module to an access point.
## Table of Contents
* [Introduction](#introduction)
* [What are the Tasks?](#what-are-the-tasks)
* [Event Driven Methods](#event-driven-methods)
* [Register the Events](#register-the-events)
* [The Code](#the-code)
* [Check the Code](#check-the-code)
* [Conclusion](#conclusion)
### Introduction
In example below we will show another cool example of getting ESP perform couple of tasks at the same time and with very little programming.
### What are the Tasks?
We would like to write a code that will inform us that connection to Wi-Fi network has been established or lost. At the same time we want to perform some time critical task. We will simulate it with a blinking LED. Generic class provides specific, event driven methods, that will be executed asynchronously, depending on e.g. connection status, while we are already doing other tasks.
### Event Driven Methods
The list of all such methods is provided in [Generic Class](generic-class.md) documentation.
We would like to use two of them:
* `onStationModeGotIP` called when station is assigned IP address. This assignment may be done by DHCP client or by executing `WiFi.config(...)`.
* `onStationModeDisconnected` called when station is disconnected from Wi-Fi network. The reason of disconnection does not matter. Event will be triggered both if disconnection is done from the code by executing `WiFi.disconnect()`, because the Wi-Fi signal is weak, or because the access point is switched off.
### Register the Events
To get events to work we need to complete just two steps:
1. Declare the event handler:
```cpp
WiFiEventHandler disconnectedEventHandler;
```
2. Select particular event (in this case `onStationModeDisconnected`) and add the code to be executed when event is fired.
```cpp
disconnectedEventHandler = WiFi.onStationModeDisconnected([](const WiFiEventStationModeDisconnected& event)
{
Serial.println("Station disconnected");
});
```
If this event is fired the code will print out information that station has been disconnected.
That's it. It is all we need to do.
### The Code
The complete code, including both methods discussed at the beginning, is provided below.
```cpp
#include <ESP8266WiFi.h>
const char* ssid = "********";
const char* password = "********";
WiFiEventHandler gotIpEventHandler, disconnectedEventHandler;
bool ledState;
void setup()
{
Serial.begin(115200);
Serial.println();
pinMode(LED_BUILTIN, OUTPUT);
gotIpEventHandler = WiFi.onStationModeGotIP([](const WiFiEventStationModeGotIP& event)
{
Serial.print("Station connected, IP: ");
Serial.println(WiFi.localIP());
});
disconnectedEventHandler = WiFi.onStationModeDisconnected([](const WiFiEventStationModeDisconnected& event)
{
Serial.println("Station disconnected");
});
Serial.printf("Connecting to %s ...\n", ssid);
WiFi.begin(ssid, password);
}
void loop()
{
digitalWrite(LED_BUILTIN, ledState);
ledState = !ledState;
delay(250);
}
```
### Check the Code
After uploading above sketch and opening a serial monitor we should see a similar log:
```
Connecting to sensor-net ...
Station connected, IP: 192.168.1.10
```
If you switch off the access point, and put it back on, you will see the following:
```
Station disconnected
Station disconnected
Station disconnected
Station connected, IP: 192.168.1.10
```
The process of connection, disconnection and printing messages is done in background of the `loop()` that is responsible for blinking the LED. Therefore the blink pattern all the time remains undisturbed.
### Conclusion
Check out events from generic class. They will help you to write more compact code. Use them to practice splitting your code into separate tasks that are executed asynchronously.
For review of functions included in generic class, please refer to the [Generic Class :arrow_right:](generic-class.md) documentation.

125
doc/esp8266wifi/generic-examples.rst Normal file
View File

@ -0,0 +1,125 @@
:orphan:
Generic
-------
In the first `example <readme.md#quick-start>`__ of the ESP8266WiFi library documentation we have discussed how to check when module connects to the Wi-Fi network. We were waiting until connection is established. If network is not available, the module could wait like that for ever doing nothing else. Another `example <scan-examples.md#async-scan>`__ on the Wi-Fi asynchronous scan mode demonstrated how to wait for scan result and do in parallel something else - blink a LED not disturbing the blink pattern. Let's apply similar functionality when connecting the module to an access point.
Table of Contents
-----------------
- `Introduction <#introduction>`__
- `What are the Tasks? <#what-are-the-tasks>`__
- `Event Driven Methods <#event-driven-methods>`__
- `Register the Events <#register-the-events>`__
- `The Code <#the-code>`__
- `Check the Code <#check-the-code>`__
- `Conclusion <#conclusion>`__
Introduction
~~~~~~~~~~~~
In example below we will show another cool example of getting ESP perform couple of tasks at the same time and with very little programming.
What are the Tasks?
~~~~~~~~~~~~~~~~~~~
We would like to write a code that will inform us that connection to Wi-Fi network has been established or lost. At the same time we want to perform some time critical task. We will simulate it with a blinking LED. Generic class provides specific, event driven methods, that will be executed asynchronously, depending on e.g. connection status, while we are already doing other tasks.
Event Driven Methods
~~~~~~~~~~~~~~~~~~~~
The list of all such methods is provided in `Generic Class <generic-class.md>`__ documentation.
We would like to use two of them: \* ``onStationModeGotIP`` called when station is assigned IP address. This assignment may be done by DHCP client or by executing ``WiFi.config(...)``. \* ``onStationModeDisconnected`` called when station is disconnected from Wi-Fi network. The reason of disconnection does not matter. Event will be triggered both if disconnection is done from the code by executing ``WiFi.disconnect()``, because the Wi-Fi signal is weak, or because the access point is switched off.
Register the Events
~~~~~~~~~~~~~~~~~~~
To get events to work we need to complete just two steps:
1. Declare the event handler:
``cpp WiFiEventHandler disconnectedEventHandler;``
2. Select particular event (in this case ``onStationModeDisconnected``)
and add the code to be executed when event is fired.
``cpp disconnectedEventHandler = WiFi.onStationModeDisconnected([](const WiFiEventStationModeDisconnected& event) { Serial.println("Station disconnected"); });`` If this event is fired the code will print out information that station has been disconnected.
That's it. It is all we need to do.
The Code
~~~~~~~~
The complete code, including both methods discussed at the beginning, is provided below.
.. code:: cpp
#include <ESP8266WiFi.h>
const char* ssid = "********";
const char* password = "********";
WiFiEventHandler gotIpEventHandler, disconnectedEventHandler;
bool ledState;
void setup()
{
Serial.begin(115200);
Serial.println();
pinMode(LED_BUILTIN, OUTPUT);
gotIpEventHandler = WiFi.onStationModeGotIP([](const WiFiEventStationModeGotIP& event)
{
Serial.print("Station connected, IP: ");
Serial.println(WiFi.localIP());
});
disconnectedEventHandler = WiFi.onStationModeDisconnected([](const WiFiEventStationModeDisconnected& event)
{
Serial.println("Station disconnected");
});
Serial.printf("Connecting to %s ...\n", ssid);
WiFi.begin(ssid, password);
}
void loop()
{
digitalWrite(LED_BUILTIN, ledState);
ledState = !ledState;
delay(250);
}
Check the Code
~~~~~~~~~~~~~~
After uploading above sketch and opening a serial monitor we should see a similar log:
::
Connecting to sensor-net ...
Station connected, IP: 192.168.1.10
If you switch off the access point, and put it back on, you will see the following:
::
Station disconnected
Station disconnected
Station disconnected
Station connected, IP: 192.168.1.10
The process of connection, disconnection and printing messages is done in background of the ``loop()`` that is responsible for blinking the LED. Therefore the blink pattern all the time remains undisturbed.
Conclusion
~~~~~~~~~~
Check out events from generic class. They will help you to write more compact code. Use them to practice splitting your code into separate tasks that are executed asynchronously.
For review of functions included in generic class, please refer to the `Generic Class <generic-class.md>`__ documentation.

318
doc/esp8266wifi/readme.md
View File

@ -1,318 +0,0 @@
---
title: ESP8266WiFi Library
---
ESP8266 is all about Wi-Fi. If you are eager to connect your new ESP8266 module to Wi-Fi network to start sending and receiving data, this is a good place to start. If you are looking for more in depth details of how to program specific Wi-Fi networking functionality, you are also in the right place.
## Table of Contents
* [Introduction](#introduction)
* [Quick Start](#quick-start)
* [Who is Who](#who-is-who)
* [Class Description](class-description)
* [Station](#station)
* [Soft Access Point](#soft-access-point)
* [Scan](#scan)
* [Client](#client)
* [Client Secure](#client-secure)
* [Server](#server)
* [UDP](#udp)
* [Generic](#generic)
* [Diagnostics](#diagnostics)
* [Check Return Codes](#check-return-codes)
* [Use printDiag](#use-printdiag)
* [Enable Wi-Fi Diagnostic](#enable-wi-fi-diagnostic)
* [Enable Debugging in IDE](#enable-debugging-in-ide)
* [What's Inside?](#whats-inside)
## Introduction
The [Wi-Fi library for ESP8266](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi) has been developed basing on [ESP8266 SDK](http://bbs.espressif.com/viewtopic.php?f=51&t=1023), using naming convention and overall functionality philosophy of [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi). Over time the wealth Wi-Fi features ported from ESP9266 SDK to [esp8266 / Adruino](https://github.com/esp8266/Arduino) outgrow [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi) and it became apparent that we need to provide separate documentation on what is new and extra.
This documentation will walk you through several classes, methods and properties of [ESP8266WiFi](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi) library. If you are new to C++ and Arduino, don't worry. We will start from general concepts and then move to detailed description of members of each particular class including usage examples.
The scope of functionality offered by [ESP8266WiFi](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi) library is quite extensive and therefore this description has been broken up into separate documents marked with :arrow_right:.
### Quick Start
Hopefully you are already familiar how to load [Blink.ino](https://github.com/esp8266/Arduino/blob/master/libraries/esp8266/examples/Blink/Blink.ino) sketch to ESP8266 module and get the LED blinking. If not, please check [this tutorial](https://learn.adafruit.com/adafruit-huzzah-esp8266-breakout/using-arduino-ide) by Adafruit or [another great tutorial](https://learn.sparkfun.com/tutorials/esp8266-thing-hookup-guide/introduction) developed by Sparkfun.
To hook up ESP module to Wi-Fi (like hooking up a mobile phone to a hot spot), you need just couple of lines of code:
```cpp
#include <ESP8266WiFi.h>
void setup()
{
Serial.begin(115200);
Serial.println();
WiFi.begin("network-name", "pass-to-network");
Serial.print("Connecting");
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.println();
Serial.print("Connected, IP address: ");
Serial.println(WiFi.localIP());
}
void loop() {}
```
In the line `WiFi.begin("network-name", "pass-to-network")` replace `network-name` and `pass-to-network` with name and password to the Wi-Fi network you like to connect. Then upload this sketch to ESP module and open serial monitor. You should see something like:
![alt text](pictures/wifi-simple-connect-terminal.png "Connection log on Arduino IDE's Serial Monitor")
How does it work? In the first line of sketch `#include <ESP8266WiFi.h>` we are including [ESP8266WiFi](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi) library. This library provides ESP8266 specific Wi-Fi routines we are calling to connect to network.
Actual connection to Wi-Fi is initialized by calling:
```cpp
WiFi.begin("network-name", "pass-to-network");
```
Connection process can take couple of seconds and we are checking for this to complete in the following loop:
```cpp
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
```
The `while()` loop will keep looping while `WiFi.status()` is other than `WL_CONNECTED`. The loop will exit only if the status changes to `WL_CONNECTED`.
The last line will then print out IP address assigned to ESP module by [DHCP](http://whatismyipaddress.com/dhcp):
```cpp
Serial.println(WiFi.localIP());
```
If you don't see the last line but just more and more dots `.........`, then likely name or password to the Wi-Fi network in sketch is entered incorrectly. Verify name and password by connecting from scratch to this Wi-Fi a PC or a mobile phone.
*Note:* if connection is established, and then lost for some reason, ESP will automatically reconnect to last used access point once it is again back on-line. This will be done automatically by Wi-Fi library, without any user intervention.
That's all you need to connect ESP8266 to Wi-Fi. In the following chapters we will explain what cool things can be done by ESP once connected.
### Who is Who
Devices that connect to Wi-Fi network are called stations (STA). Connection to Wi-Fi is provided by an access point (AP), that acts as a hub for one or more stations. The access point on the other end is connected to a wired network. An access point is usually integrated with a router to provide access from Wi-Fi network to the internet. Each access point is recognized by a SSID (**S**ervice **S**et **ID**entifier), that essentially is the name of network you select when connecting a device (station) to the Wi-Fi.
ESP8266 module can operate as a station, so we can connect it to the Wi-Fi network. It can also operate as a soft access point (soft-AP), to establish its own Wi-Fi network. Therefore we can connect other stations to such ESP module. ESP8266 is also able to operate both in station and soft access point mode. This provides possibility of building e.g. [mesh networks](https://en.wikipedia.org/wiki/Mesh_networking).
![alt text](pictures/esp8266-station-soft-access-point.png "ESP8266 operating in the Station + Soft Access Point mode")
The [ESP8266WiFi](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi) library provides wide collection of C++ [methods](https://en.wikipedia.org/wiki/Method_(computer_programming)) (functions) and [properties](https://en.wikipedia.org/wiki/Property_(programming)) to configure and operate an ESP8266 module in station and / or soft access point mode. They are described in the following chapters.
## Class Description
The [ESP8266WiFi](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi) library is broken up into several classes. In most of cases, when writing the code, user is not concerned with this classification. We are using it to break up description of this library into more manageable pieces.
![alt text](pictures/doxygen-class-index.png "Index of classes of ESP8266WiFi library")
Chapters below describe all function calls ([methods](https://en.wikipedia.org/wiki/Method_(computer_programming)) and [properties](https://en.wikipedia.org/wiki/Property_(programming)) in C++ terms) listed in particular classes of [ESP8266WiFi](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi). Description is illustrated with application examples and code snippets to show how to use functions in practice. Most of this information is broken up into separate documents. Please follow :arrow_right: to access them.
### Station
Station (STA) mode is used to get ESP module connected to a Wi-Fi network established by an access point.
![alt text](pictures/esp8266-station.png "ESP8266 operating in the Station mode")
Station class has several features to facilitate management of Wi-Fi connection. In case the connection is lost, ESP8266 will automatically reconnect to the last used access point, once it is again available. The same happens on module reboot. This is possible since ESP is saving credentials to last used access point in flash (non-volatile) memory. Using the saved data ESP will also reconnect if sketch has been changed but code does not alter the Wi-Fi mode or credentials.
[Station Class documentation :arrow_right:](station-class.md) : [begin](station-class.md#begin) | [config](station-class.md#config) | [reconnect](station-class.md#reconnect) | [disconnect](station-class.md#disconnect) | [isConnected](station-class.md#isconnected) | [setAutoConnect](station-class.md#setautoconnect) | [getAutoConnect](station-class.md#getautoconnect) | [setAutoReconnect](station-class.md#setautoreconnect) | [waitForConnectResult](station-class.md#waitforconnectresult) | [macAddress](station-class.md#macAddress) | [localIP](station-class.md#localip) | [subnetMask](station-class.md#subnetmask) | [gatewayIP](station-class.md#gatewayip) | [dnsIP](station-class.md#dnsip) | [hostname](station-class.md#hostname) | [status](station-class.md#status) | [SSID](station-class.md#ssid) | [psk](station-class.md#psk) | [BSSID](station-class.md#bssid) | [RSSI](station-class.md#rssi) | [WPS](station-class.md#wps) | [Smart Config](station-class.md#smart-config)
Check out separate section with [examples :arrow_right:](station-examples.md)
### Soft Access Point
An [access point (AP)](https://en.wikipedia.org/wiki/Wireless_access_point) is a device that provides access to Wi-Fi network to other devices (stations) and connects them further to a wired network. ESP8266 can provide similar functionality except it does not have interface to a wired network. Such mode of operation is called soft access point (soft-AP). The maximum number of stations connected to the soft-AP is five.
![alt text](pictures/esp8266-soft-access-point.png "ESP8266 operating in the Soft Access Point mode")
The soft-AP mode is often used and an intermediate step before connecting ESP to a Wi-Fi in a station mode. This is when SSID and password to such network is not known upfront. ESP first boots in soft-AP mode, so we can connect to it using a laptop or a mobile phone. Then we are able to provide credentials to the target network. Once done ESP is switched to the station mode and can connect to the target Wi-Fi.
Another handy application of soft-AP mode is to set up [mesh networks](https://en.wikipedia.org/wiki/Mesh_networking). ESP can operate in both soft-AP and Station mode so it can act as a node of a mesh network.
[Soft Access Point Class documentation :arrow_right:](soft-access-point-class.md) : [softAP](soft-access-point-class.md#softap) | [softAPConfig](soft-access-point-class.md#softapconfig) | [softAPdisconnect](soft-access-point-class.md#softapdisconnect) | [softAPgetStationNum](soft-access-point-class.md#softapgetstationnum) | [softAPIP](soft-access-point-class.md#softapip) | [softAPmacAddress](soft-access-point-class.md#softapmacaddress)
Check out separate section with [examples :arrow_right:](soft-access-point-examples.md)
### Scan
To connect a mobile phone to a hot spot, you typically open Wi-Fi settings app, list available networks and pick the hot spot you need. Then enter a password (or not) and you are in. You can do the same with ESP. Functionality of scanning for, and listing of available networks in range is implemented by the Scan Class.
[Scan Class documentation :arrow_right:](scan-class.md) : [scanNetworks](scan-class.md#scannetworks) | [scanNetworksAsync](scan-class.md#scannetworksasync) | [scanComplete](scan-class.md#scancomplete) | [scanDelete](scan-class.md#scandelete) | [SSID](scan-class.md#ssid) | [encryptionType](scan-class.md#encryptiontype) | [BSSID](scan-class.md#bssid) | [BSSIDstr](scan-class.md#bssidstr) | [channel](scan-class.md#channel) | [isHidden](scan-class.md#ishidden) | [getNetworkInfo](scan-class.md#getnetworkinfo)
Check out separate section with [examples :arrow_right:](scan-examples.md)
### Client
The Client class creates [clients](https://en.wikipedia.org/wiki/Client_(computing)) that can access services provided by [servers](https://en.wikipedia.org/wiki/Server_(computing)) in order to send, receive and process data.
![alt text](pictures/esp8266-client.png "ESP8266 operating as the Client")
Check out separate section with [examples :arrow_right:](client-examples.md) / [list of functions :arrow_right:](client-class.md)
### Client Secure
The Client Secure is an extension of [Client Class](#client) where connection and data exchange with servers is done using a [secure protocol](https://en.wikipedia.org/wiki/Transport_Layer_Security). It supports [TLS 1.1](https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.1). The [TLS 1.2](https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.2) is not supported.
![alt text](pictures/esp8266-client-secure.png "ESP8266 operating as the Client Secure")
Secure applications have additional memory (and processing) overhead due to the need to run cryptography algorithms. The stronger the certificate's key, the more overhead is needed. In practice it is not possible to run more than a single secure client at a time. The problem concerns RAM memory we can not add, the flash memory size is usually not the issue. If you like to learn how [client secure library](https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/src/WiFiClientSecure.h) has been developed, access to what servers have been tested, and how memory limitations have been overcame, read fascinating issue report [#43](https://github.com/esp8266/Arduino/issues/43).
Check out separate section with [examples :arrow_right:](client-secure-examples.md) / [list of functions :arrow_right:](client-secure-class.md)
### Server
The Server Class creates [servers](https://en.wikipedia.org/wiki/Server_(computing)) that provide functionality to other programs or devices, called [clients](https://en.wikipedia.org/wiki/Client_(computing)).
![alt text](pictures/esp8266-server.png "ESP8266 operating as the Server")
Clients connect to sever to send and receive data and access provided functionality.
Check out separate section with [examples :arrow_right:](server-examples.md) / [list of functions :arrow_right:](server-class.md)
### UDP
The UDP Class enables the [User Datagram Protocol (UDP)](https://en.wikipedia.org/wiki/User_Datagram_Protocol) messages to be sent and received. The UDP uses a simple "fire and forget" transmission model with no guarantee of delivery, ordering, or duplicate protection. UDP provides checksums for data integrity, and port numbers for addressing different functions at the source and destination of the datagram.
Check out separate section with [examples :arrow_right:](udp-examples.md) / [list of functions :arrow_right:](udp-class.md)
### Generic
There are several functions offered by ESP8266's [SDK](http://bbs.espressif.com/viewtopic.php?f=51&t=1023) and not present in [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi). If such function does not fit into one of classes discussed above, it will likely be in Generic Class. Among them is handler to manage Wi-Fi events like connection, disconnection or obtaining an IP, Wi-Fi mode changes, functions to manage module sleep mode, hostname to an IP address resolution, etc.
Check out separate section with [examples :arrow_right:](generic-examples.md) / [list of functions :arrow_right:](generic-class.md)
## Diagnostics
There are several techniques available to diagnose and troubleshoot issues with getting connected to Wi-Fi and keeping connection alive.
### Check Return Codes
Almost each function described in chapters above returns some diagnostic information.
Such diagnostic may be provided as a simple `boolean` type `true' or `false` to indicate operation result. You may check this result as described in examples, for instance:
```cpp
Serial.printf("Wi-Fi mode set to WIFI_STA %s\n", WiFi.mode(WIFI_STA) ? "" : "Failed!");
```
Some functions provide more than just a binary status information. A good example is `WiFi.status()`.
```cpp
Serial.printf("Connection status: %d\n", WiFi.status());
```
This function returns following codes to describe what is going on with Wi-Fi connection:
* 0 : `WL_IDLE_STATUS` when Wi-Fi is in process of changing between statuses
* 1 : `WL_NO_SSID_AVAIL`in case configured SSID cannot be reached
* 3 : `WL_CONNECTED` after successful connection is established
* 4 : `WL_CONNECT_FAILED` if password is incorrect
* 6 : `WL_DISCONNECTED` if module is not configured in station mode
It is a good practice to display and check information returned by functions. Application development and troubleshooting will be easier with that.
### Use printDiag
There is a specific function available to print out key Wi-Fi diagnostic information:
```cpp
WiFi.printDiag(Serial);
```
A sample output of this function looks as follows:
```
Mode: STA+AP
PHY mode: N
Channel: 11
AP id: 0
Status: 5
Auto connect: 1
SSID (10): sensor-net
Passphrase (12): 123!$#0&*esP
BSSID set: 0
```
Use this function to provide snapshot of Wi-Fi status in these parts of application code, that you suspect may be failing.
### Enable Wi-Fi Diagnostic
By default the diagnostic output from Wi-Fi libraries is disabled when you call `Serial.begin`. To enable debug output again, call `Serial.setDebugOutput(true)`. To redirect debug output to `Serial1` instead, call `Serial1.setDebugOutput(true)`. For additional details regarding diagnostics using serial ports please refer to [documentation](https://github.com/esp8266/Arduino/blob/master/doc/reference.md).
Below is an example of output for sample sketch discussed in [Quick Start](#quick-start) above with `Serial.setDebugOutput(true)`:
```
Connectingscandone
state: 0 -> 2 (b0)
state: 2 -> 3 (0)
state: 3 -> 5 (10)
add 0
aid 1
cnt
connected with sensor-net, channel 6
dhcp client start...
chg_B1:-40
...ip:192.168.1.10,mask:255.255.255.0,gw:192.168.1.9
.
Connected, IP address: 192.168.1.10
```
The same sketch without `Serial.setDebugOutput(true)` will print out only the following:
```
Connecting....
Connected, IP address: 192.168.1.10
```
### Enable Debugging in IDE
Arduino IDE provides convenient method to [enable debugging](https://github.com/esp8266/Arduino/blob/master/doc/Troubleshooting/debugging.md) for specific libraries.
## What's Inside?
If you like to analyze in detail what is inside of the ESP8266WiFi library, go directly to the [ESP8266WiFi](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi/src) folder of esp8266 / Arduino repository on the GitHub.
To make the analysis easier, rather than looking into individual header or source files, use one of free tools to automatically generate documentation. The class index in chapter [Class Description](class-description) above has been prepared in no time using great [Doxygen](http://www.stack.nl/~dimitri/doxygen/), that is the de facto standard tool for generating documentation from annotated C++ sources.
![alt text](pictures/doxygen-esp8266wifi-documentation.png "Example of documentation prepared by Doxygen")
The tool crawls through all header and source files collecting information from formatted comment blocks. If developer of particular class annotated the code, you will see it like in examples below.
![alt text](pictures/doxygen-example-station-begin.png "Example of documentation for station begin method by Doxygen")
![alt text](pictures/doxygen-example-station-hostname.png "Example of documentation for station hostname propert by Doxygen")
If code is not annotated, you will still see the function prototype including types of arguments, and can use provided links to jump straight to the source code to check it out on your own. Doxygen provides really excellent navigation between members of library.
![alt text](pictures/doxygen-example-udp-begin.png "Example of documentation for UDP begin method (not annotaed in code)by Doxygen")
Several classes of [ESP8266WiFi](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi) are not annotated. When preparing this document, [Doxygen](http://www.stack.nl/~dimitri/doxygen/) has been tremendous help to quickly navigate through almost 30 files that make this library.

332
doc/esp8266wifi/readme.rst Normal file
View File

@ -0,0 +1,332 @@
ESP8266WiFi library
===================
ESP8266 is all about Wi-Fi. If you are eager to connect your new ESP8266 module to Wi-Fi network to start sending and receiving data, this is a good place to start. If you are looking for more in depth details of how to program specific Wi-Fi networking functionality, you are also in the right place.
Introduction
------------
The `Wi-Fi library for ESP8266 <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi>`__ has been developed basing on `ESP8266 SDK <http://bbs.espressif.com/viewtopic.php?f=51&t=1023>`__, using naming convention and overall functionality philosophy of `Arduino WiFi library <https://www.arduino.cc/en/Reference/WiFi>`__. Over time the wealth Wi-Fi features ported from ESP9266 SDK to `esp8266 /
Adruino <https://github.com/esp8266/Arduino>`__ outgrow `Arduino WiFi library <https://www.arduino.cc/en/Reference/WiFi>`__ and it became apparent that we need to provide separate documentation on what is new and extra.
This documentation will walk you through several classes, methods and properties of `ESP8266WiFi <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi>`__ library. If you are new to C++ and Arduino, don't worry. We will start from general concepts and then move to detailed description of members of each particular class including usage examples.
The scope of functionality offered by `ESP8266WiFi <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi>`__ library is quite extensive and therefore this description has been broken up into separate documents marked with :arrow\_right:.
Quick Start
~~~~~~~~~~~
Hopefully you are already familiar how to load `Blink.ino <https://github.com/esp8266/Arduino/blob/master/libraries/esp8266/examples/Blink/Blink.ino>`__ sketch to ESP8266 module and get the LED blinking. If not, please check `this tutorial <https://learn.adafruit.com/adafruit-huzzah-esp8266-breakout/using-arduino-ide>`__ by Adafruit or `another great tutorial <https://learn.sparkfun.com/tutorials/esp8266-thing-hookup-guide/introduction>`__ developed by Sparkfun.
To hook up ESP module to Wi-Fi (like hooking up a mobile phone to a hot spot), you need just couple of lines of code:
.. code:: cpp
#include <ESP8266WiFi.h>
void setup()
{
Serial.begin(115200);
Serial.println();
WiFi.begin("network-name", "pass-to-network");
Serial.print("Connecting");
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.println();
Serial.print("Connected, IP address: ");
Serial.println(WiFi.localIP());
}
void loop() {}
In the line ``WiFi.begin("network-name", "pass-to-network")`` replace ``network-name`` and ``pass-to-network`` with name and password to the Wi-Fi network you like to connect. Then upload this sketch to ESP module and open serial monitor. You should see something like:
.. figure:: pictures/wifi-simple-connect-terminal.png
:alt: Connection log on Arduino IDE's Serial Monitor
alt text
How does it work? In the first line of sketch ``#include <ESP8266WiFi.h>`` we are including `ESP8266WiFi <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi>`__ library. This library provides ESP8266 specific Wi-Fi routines we are calling to connect to network.
Actual connection to Wi-Fi is initialized by calling:
.. code:: cpp
WiFi.begin("network-name", "pass-to-network");
Connection process can take couple of seconds and we are checking for this to complete in the following loop:
.. code:: cpp
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
The ``while()`` loop will keep looping while ``WiFi.status()`` is other than ``WL_CONNECTED``. The loop will exit only if the status changes to ``WL_CONNECTED``.
The last line will then print out IP address assigned to ESP module by `DHCP <http://whatismyipaddress.com/dhcp>`__:
.. code:: cpp
Serial.println(WiFi.localIP());
If you don't see the last line but just more and more dots ``.........``, then likely name or password to the Wi-Fi network in sketch is entered incorrectly. Verify name and password by connecting from scratch to this Wi-Fi a PC or a mobile phone.
*Note:* if connection is established, and then lost for some reason, ESP will automatically reconnect to last used access point once it is again back on-line. This will be done automatically by Wi-Fi library, without any user intervention.
That's all you need to connect ESP8266 to Wi-Fi. In the following chapters we will explain what cool things can be done by ESP once connected.
Who is Who
~~~~~~~~~~
Devices that connect to Wi-Fi network are called stations (STA). Connection to Wi-Fi is provided by an access point (AP), that acts as a hub for one or more stations. The access point on the other end is connected to a wired network. An access point is usually integrated with a router to provide access from Wi-Fi network to the internet. Each access point is recognized by a SSID (**S**\ ervice **S**\ et **ID**\ entifier), that essentially is the name of network you select when connecting a device (station) to the Wi-Fi.
ESP8266 module can operate as a station, so we can connect it to the Wi-Fi network. It can also operate as a soft access point (soft-AP), to establish its own Wi-Fi network. Therefore we can connect other stations to such ESP module. ESP8266 is also able to operate both in station and soft access point mode. This provides possibility of building e.g. `mesh networks <https://en.wikipedia.org/wiki/Mesh_networking>`__.
.. figure:: pictures/esp8266-station-soft-access-point.png
:alt: ESP8266 operating in the Station + Soft Access Point mode
alt text
The `ESP8266WiFi <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi>`__ library provides wide collection of C++
`methods <https://en.wikipedia.org/wiki/Method_(computer_programming)>`__ (functions) and `properties <https://en.wikipedia.org/wiki/Property_(programming)>`__ to configure and operate an ESP8266 module in station and / or soft access point mode. They are described in the following chapters.
Class Description
-----------------
The `ESP8266WiFi <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi>`__ library is broken up into several classes. In most of cases, when writing the code, user is not concerned with this classification. We are using it to break up description of this library into more manageable pieces.
.. figure:: pictures/doxygen-class-index.png
:alt: Index of classes of ESP8266WiFi library
alt text
Chapters below describe all function calls (`methods <https://en.wikipedia.org/wiki/Method_(computer_programming)>`__ and `properties <https://en.wikipedia.org/wiki/Property_(programming)>`__ in C++ terms) listed in particular classes of `ESP8266WiFi <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi>`__. Description is illustrated with application examples and code snippets to show how to use functions in practice. Most of this information is broken up into separate documents. Please follow to access them.
Station
~~~~~~~
Station (STA) mode is used to get ESP module connected to a Wi-Fi network established by an access point.
.. figure:: pictures/esp8266-station.png
:alt: ESP8266 operating in the Station mode
alt text
Station class has several features to facilitate management of Wi-Fi connection. In case the connection is lost, ESP8266 will automatically reconnect to the last used access point, once it is again available. The same happens on module reboot. This is possible since ESP is saving credentials to last used access point in flash (non-volatile) memory. Using the saved data ESP will also reconnect if sketch has been changed but code does not alter the Wi-Fi mode or credentials.
:doc:`Station Class documentation <station-class>`
Check out separate section with :doc:`examples <station-examples>`.
Soft Access Point
~~~~~~~~~~~~~~~~~
An `access point (AP) <https://en.wikipedia.org/wiki/Wireless_access_point>`__ is a device that provides access to Wi-Fi network to other devices (stations)
and connects them further to a wired network. ESP8266 can provide similar functionality except it does not have interface to a wired network. Such mode of operation is called soft access point (soft-AP). The maximum number of stations connected to the soft-AP is five.
.. figure:: pictures/esp8266-soft-access-point.png
:alt: ESP8266 operating in the Soft Access Point mode
alt text
The soft-AP mode is often used and an intermediate step before connecting ESP to a Wi-Fi in a station mode. This is when SSID and password to such network is not known upfront. ESP first boots in soft-AP mode, so we can connect to it using a laptop or a mobile phone. Then we are able to provide credentials to the target network. Once done ESP is switched to the station mode and can connect to the target Wi-Fi.
Another handy application of soft-AP mode is to set up `mesh networks <https://en.wikipedia.org/wiki/Mesh_networking>`__. ESP can operate in both soft-AP and Station mode so it can act as a node of a mesh network.
:doc:`Soft Access Point Class documentation <soft-access-point-class>`
Check out separate section with :doc:`examples <soft-access-point-examples>`.
Scan
~~~~
To connect a mobile phone to a hot spot, you typically open Wi-Fi settings app, list available networks and pick the hot spot you need. Then enter a password (or not) and you are in. You can do the same with ESP. Functionality of scanning for, and listing of available networks in range is implemented by the Scan Class.
:doc:`Scan Class documentation <scan-class>`.
Check out separate section with :doc:`examples <scan-examples>`.
Client
~~~~~~
The Client class creates `clients <https://en.wikipedia.org/wiki/Client_(computing)>`__ that can access services provided by `servers <https://en.wikipedia.org/wiki/Server_(computing)>`__ in order to send, receive and process data.
.. figure:: pictures/esp8266-client.png
:alt: ESP8266 operating as the Client
alt text
Check out separate section with :doc:`examples <client-examples>` / :doc:`list of functions
<client-class>`
Client Secure
~~~~~~~~~~~~~
The Client Secure is an extension of `Client Class <#client>`__ where connection and data exchange with servers is done using a `secure protocol <https://en.wikipedia.org/wiki/Transport_Layer_Security>`__. It supports `TLS 1.1 <https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.1>`__. The `TLS 1.2 <https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.2>`__ is not supported.
.. figure:: pictures/esp8266-client-secure.png
:alt: ESP8266 operating as the Client Secure
alt text
Secure applications have additional memory (and processing) overhead due to the need to run cryptography algorithms. The stronger the certificate's key, the more overhead is needed. In practice it is not possible to run more than a single secure client at a time. The problem concerns RAM memory we can not add, the flash memory size is usually not the issue. If you like to learn how `client secure library <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/src/WiFiClientSecure.h>`__ has been developed, access to what servers have been tested, and how memory limitations have been overcame, read fascinating issue report `#43 <https://github.com/esp8266/Arduino/issues/43>`__.
Check out separate section with :doc:`examples <client-secure-examples>` / :doc:`list of functions <client-secure-class>`
Server
~~~~~~
The Server Class creates `servers <https://en.wikipedia.org/wiki/Server_(computing)>`__ that provide functionality to other programs or devices, called `clients <https://en.wikipedia.org/wiki/Client_(computing)>`__.
.. figure:: pictures/esp8266-server.png
:alt: ESP8266 operating as the Server
alt text
Clients connect to sever to send and receive data and access provided functionality.
Check out separate section with :doc:`examples <server-examples>` / :doc:`list of functions <server-class>`.
UDP
~~~
The UDP Class enables the `User Datagram Protocol (UDP) <https://en.wikipedia.org/wiki/User_Datagram_Protocol>`__ messages to be sent and received. The UDP uses a simple "fire and forget" transmission model with no guarantee of delivery, ordering, or duplicate protection. UDP provides checksums for data integrity, and port numbers for addressing different functions at the source and destination of the datagram.
Check out separate section with :doc:`examples <udp-examples>` / :doc:`list of functions <udp-class>`.
Generic
~~~~~~~
There are several functions offered by ESP8266's `SDK <http://bbs.espressif.com/viewtopic.php?f=51&t=1023>`__ and not present in `Arduino WiFi library <https://www.arduino.cc/en/Reference/WiFi>`__. If such function does not fit into one of classes discussed above, it will likely be in Generic Class. Among them is handler to manage Wi-Fi events like connection, disconnection or obtaining an IP, Wi-Fi mode changes, functions to manage module sleep mode, hostname to an IP address resolution, etc.
Check out separate section with :doc:`examples <generic-examples>` / :doc:`list of functions <generic-class>`.
Diagnostics
-----------
There are several techniques available to diagnose and troubleshoot issues with getting connected to Wi-Fi and keeping connection alive.
Check Return Codes
~~~~~~~~~~~~~~~~~~
Almost each function described in chapters above returns some diagnostic information.
Such diagnostic may be provided as a simple ``boolean`` type ``true' or``\ false\` to indicate operation result. You may check this result as described in examples, for instance:
.. code:: cpp
Serial.printf("Wi-Fi mode set to WIFI_STA %s\n", WiFi.mode(WIFI_STA) ? "" : "Failed!");
Some functions provide more than just a binary status information. A good example is ``WiFi.status()``.
.. code:: cpp
Serial.printf("Connection status: %d\n", WiFi.status());
This function returns following codes to describe what is going on with Wi-Fi connection: \* 0 : ``WL_IDLE_STATUS`` when Wi-Fi is in process of changing between statuses \* 1 : ``WL_NO_SSID_AVAIL``\ in case configured SSID cannot be reached \* 3 : ``WL_CONNECTED`` after successful connection is established \* 4 : ``WL_CONNECT_FAILED`` if password is incorrect \* 6 : ``WL_DISCONNECTED`` if module is not configured in station mode
It is a good practice to display and check information returned by functions. Application development and troubleshooting will be easier with that.
Use printDiag
~~~~~~~~~~~~~
There is a specific function available to print out key Wi-Fi diagnostic information:
.. code:: cpp
WiFi.printDiag(Serial);
A sample output of this function looks as follows:
::
Mode: STA+AP
PHY mode: N
Channel: 11
AP id: 0
Status: 5
Auto connect: 1
SSID (10): sensor-net
Passphrase (12): 123!$#0&*esP
BSSID set: 0
Use this function to provide snapshot of Wi-Fi status in these parts of application code, that you suspect may be failing.
Enable Wi-Fi Diagnostic
~~~~~~~~~~~~~~~~~~~~~~~
By default the diagnostic output from Wi-Fi libraries is disabled when you call ``Serial.begin``. To enable debug output again, call ``Serial.setDebugOutput(true)``. To redirect debug output to ``Serial1`` instead, call ``Serial1.setDebugOutput(true)``. For additional details regarding diagnostics using serial ports please refer to :doc:`the documentation <../reference>`.
Below is an example of output for sample sketch discussed in `Quick Start <#quick-start>`__ above with ``Serial.setDebugOutput(true)``:
::
Connectingscandone
state: 0 -> 2 (b0)
state: 2 -> 3 (0)
state: 3 -> 5 (10)
add 0
aid 1
cnt
connected with sensor-net, channel 6
dhcp client start...
chg_B1:-40
...ip:192.168.1.10,mask:255.255.255.0,gw:192.168.1.9
.
Connected, IP address: 192.168.1.10
The same sketch without ``Serial.setDebugOutput(true)`` will print out only the following:
::
Connecting....
Connected, IP address: 192.168.1.10
Enable Debugging in IDE
~~~~~~~~~~~~~~~~~~~~~~~
Arduino IDE provides convenient method to `enable debugging <https://github.com/esp8266/Arduino/blob/master/doc/Troubleshooting/debugging.md>`__ for specific libraries.
What's Inside?
--------------
If you like to analyze in detail what is inside of the ESP8266WiFi library, go directly to the `ESP8266WiFi <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi/src>`__ folder of esp8266 / Arduino repository on the GitHub.
To make the analysis easier, rather than looking into individual header or source files, use one of free tools to automatically generate documentation. The class index in chapter `Class Description <class-description>`__ above has been prepared in no time using great `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`__, that is the de facto standard tool for generating documentation from annotated C++ sources.
.. figure:: pictures/doxygen-esp8266wifi-documentation.png
:alt: Example of documentation prepared by Doxygen
alt text
The tool crawls through all header and source files collecting information from formatted comment blocks. If developer of particular class annotated the code, you will see it like in examples below.
.. figure:: pictures/doxygen-example-station-begin.png
:alt: Example of documentation for station begin method by Doxygen
alt text
.. figure:: pictures/doxygen-example-station-hostname.png
:alt: Example of documentation for station hostname propert by Doxygen
alt text
If code is not annotated, you will still see the function prototype including types of arguments, and can use provided links to jump straight to the source code to check it out on your own. Doxygen provides really excellent navigation between members of library.
.. figure:: pictures/doxygen-example-udp-begin.png
:alt: Example of documentation for UDP begin method (not annotaed in code)by Doxygen
alt text
Several classes of `ESP8266WiFi <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi>`__ are not annotated. When preparing this document, `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`__ has been tremendous help to quickly navigate through almost 30 files that make this library.

267
doc/esp8266wifi/scan-class.md
View File

@ -1,267 +0,0 @@
---
title: ESP8266WiFi Scan Class
---
[ESP8266WiFi Library :back:](readme.md#scan)
## Scan Class
This class is represented in [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi) by [scanNetworks()](https://www.arduino.cc/en/Reference/WiFiScanNetworks) function. Developers of esp8266 / Arduino core extend this functionality by additional methods and properties.
## Table of Contents
* [Scan for Networks](#scan-for-networks)
* [scanNetworks](#scannetworks)
* [scanNetworksAsync](#scannetworksasync)
* [scanComplete](#scancomplete)
* [scanDelete](#scandelete)
* [Show Results](#show-results)
* [SSID](#ssid)
* [encryptionType](#encryptiontype)
* [BSSID](#bssid)
* [BSSIDstr](#bssidstr)
* [channel](#channel)
* [isHidden](#ishidden)
* [getNetworkInfo](#getnetworkinfo)
Documentation of this class is divided into two parts. First covers functions to scan for available networks. Second describes what information is collected during scanning process and how to access it.
### Scan for Networks
Scanning for networks takes hundreds of milliseconds to complete. This may be done in a single run when we are triggering scan process, waiting for completion, and providing result - all by a single function. Another option is to split this into steps, each done by a separate function. This way we can execute other tasks while scanning is in progress. This is called asynchronous scanning. Both methods of scanning are documented below.
#### scanNetworks
Scan for available Wi-Fi networks in one run and return the number of networks that has been discovered.
```cpp
WiFi.scanNetworks()
```
There is on [overload](https://en.wikipedia.org/wiki/Function_overloading) of this function that accepts two optional parameters to provide extended functionality of asynchronous scanning as well as looking for hidden networks.
```cpp
WiFi.scanNetworks(async, show_hidden)
```
Both function parameters are of `boolean` type. They provide the flowing functionality:
* `asysnc` - if set to `true` then scanning will start in background and function will exit without waiting for result. To check for result use separate function `scanComplete` that is described below.
* `show_hidden` - set it to `true` to include in scan result networks with hidden SSID.
#### scanComplete
Check for result of asynchronous scanning.
```cpp
WiFi.scanComplete()
```
On scan completion function returns the number of discovered networks.
If scan is not done, then returned value is < 0 as follows:
* Scanning still in progress: -1
* Scanning has not been triggered: -2
#### scanDelete
Delete the last scan result from memory.
```cpp
WiFi.scanDelete()
```
#### scanNetworksAsync
Start scanning for available Wi-Fi networks. On completion execute another function.
```cpp
WiFi.scanNetworksAsync(onComplete, show_hidden)
```
Function parameters:
* `onComplete` - the event handler executed when the scan is done
* `show_hidden` - optional `boolean` parameter, set it to `true` to scan for hidden networks
*Example code:*
```cpp
#include "ESP8266WiFi.h"
void prinScanResult(int networksFound)
{
Serial.printf("%d network(s) found\n", networksFound);
for (int i = 0; i < networksFound; i++)
{
Serial.printf("%d: %s, Ch:%d (%ddBm) %s\n", i + 1, WiFi.SSID(i).c_str(), WiFi.channel(i), WiFi.RSSI(i), WiFi.encryptionType(i) == ENC_TYPE_NONE ? "open" : "");
}
}
void setup()
{
Serial.begin(115200);
Serial.println();
WiFi.mode(WIFI_STA);
WiFi.disconnect();
delay(100);
WiFi.scanNetworksAsync(prinScanResult);
}
void loop() {}
```
*Example output:*
```
5 network(s) found
1: Tech_D005107, Ch:6 (-72dBm)
2: HP-Print-A2-Photosmart 7520, Ch:6 (-79dBm)
3: ESP_0B09E3, Ch:9 (-89dBm) open
4: Hack-4-fun-net, Ch:9 (-91dBm)
5: UPC Wi-Free, Ch:11 (-79dBm)
```
### Show Results
Functions below provide access to result of scanning. It does not matter if scanning has been done in synchronous or asynchronous mode, scan results are available using the same API.
Individual results are accessible by providing a `networkItem' that identifies the index (zero based) of discovered network.
#### SSID
Return the SSID of a network discovered during the scan.
```cpp
WiFi.SSID(networkItem)
```
Returned SSID is of the `String` type.
The `networkItem` is a zero based index of network discovered during scan.
#### encryptionType
Return the encryption type of a network discovered during the scan.
```cpp
WiFi.encryptionType(networkItem)
```
Function returns a number that encodes encryption type as follows:
* 5 : `ENC_TYPE_WEP` - WEP
* 2 : `ENC_TYPE_TKIP` - WPA / PSK
* 4 : `ENC_TYPE_CCMP` - WPA2 / PSK
* 7 : `ENC_TYPE_NONE` - open network
* 8 : `ENC_TYPE_AUTO` - WPA / WPA2 / PSK
The `networkItem` is a zero based index of network discovered during scan.
#### RSSI
Return the [RSSI](https://en.wikipedia.org/wiki/Received_signal_strength_indication) (Received Signal Strength Indication) of a network discovered during the scan.
```cpp
WiFi.RSSI(networkItem)
```
Returned RSSI is of the `int32_t` type.
The `networkItem` is a zero based index of network discovered during scan.
#### BSSID
Return the [BSSID](https://en.wikipedia.org/wiki/Service_set_(802.11_network)#Basic_service_set_identification_.28BSSID.29) (Basic Service Set Identification) that is another name of MAC address of a network discovered during the scan.
```cpp
WiFi.BSSID(networkItem)
```
Function returns a pointer to the memory location (an `uint8_t` array with the size of 6 elements) where the BSSID is saved.
If you do not like to pointers, then there is another version of this function that returns a `String`.
```cpp
WiFi.BSSIDstr(networkItem)
```
The `networkItem` is a zero based index of network discovered during scan.
#### channel
Return the channel of a network discovered during the scan.
```cpp
WiFi.channel(networkItem)
```
Returned channel is of the `int32_t` type.
The `networkItem` is a zero based index of network discovered during scan.
#### isHidden
Return information if a network discovered during the scan is hidden or not.
```cpp
WiFi.isHidden(networkItem)
```
Returned value if the `bolean` type, and `true` means that network is hidden.
The `networkItem` is a zero based index of network discovered during scan.
#### getNetworkInfo
Return all the network information discussed in this chapter above in a single function call.
```cpp
WiFi.getNetworkInfo(networkItem, &ssid, &encryptionType, &RSSI, *&BSSID, &channel, &isHidden)
```
The `networkItem` is a zero based index of network discovered during scan.
All other input parameters are passed to function by reference. Therefore they will be updated with actual values retrieved for particular `networkItem`.
The function itself returns `boolean` `true` or `false` to confirm if information retrieval was successful or not.
*Example code:*
```cpp
int n = WiFi.scanNetworks(false, true);
String ssid;
uint8_t encryptionType;
int32_t RSSI;
uint8_t* BSSID;
int32_t channel;
bool isHidden;
for (int i = 0; i < n; i++)
{
WiFi.getNetworkInfo(i, ssid, encryptionType, RSSI, BSSID, channel, isHidden);
Serial.printf("%d: %s, Ch:%d (%ddBm) %s %s\n", i + 1, ssid.c_str(), channel, RSSI, encryptionType == ENC_TYPE_NONE ? "open" : "", isHidden ? "hidden" : "");
}
```
*Example output:*
```
6 network(s) found
1: Tech_D005107, Ch:6 (-72dBm)
2: HP-Print-A2-Photosmart 7520, Ch:6 (-79dBm)
3: ESP_0B09E3, Ch:9 (-89dBm) open
4: Hack-4-fun-net, Ch:9 (-91dBm)
5: , Ch:11 (-77dBm) hidden
6: UPC Wi-Free, Ch:11 (-79dBm)
```
For code samples please refer to separate section with [examples :arrow_right:](scan-examples.md) dedicated specifically to the Scan Class.

238
doc/esp8266wifi/scan-class.rst Normal file
View File

@ -0,0 +1,238 @@
:orphan:
Scan Class
~~~~~~~~~~
This class is represented in `Arduino WiFi library <https://www.arduino.cc/en/Reference/WiFi>`__ by `scanNetworks() <https://www.arduino.cc/en/Reference/WiFiScanNetworks>`__ function. Developers of esp8266 / Arduino core extend this functionality by additional methods and properties.
Documentation of this class is divided into two parts. First covers functions to scan for available networks. Second describes what information is collected during scanning process and how to access it.
Scan for Networks
~~~~~~~~~~~~~~~~~
Scanning for networks takes hundreds of milliseconds to complete. This may be done in a single run when we are triggering scan process, waiting for completion, and providing result - all by a single function. Another option is to split this into steps, each done by a separate function. This way we can execute other tasks while scanning is in progress. This is called asynchronous scanning. Both methods of scanning are documented below.
scanNetworks
^^^^^^^^^^^^
Scan for available Wi-Fi networks in one run and return the number of networks that has been discovered.
.. code:: cpp
WiFi.scanNetworks()
There is on `overload <https://en.wikipedia.org/wiki/Function_overloading>`__ of this function that accepts two optional parameters to provide extended functionality of asynchronous scanning as well as looking for hidden networks.
.. code:: cpp
WiFi.scanNetworks(async, show_hidden)
Both function parameters are of ``boolean`` type. They provide the flowing functionality: \* ``asysnc`` - if set to ``true`` then scanning will start in background and function will exit without waiting for result. To check for result use separate function ``scanComplete`` that is described below. \* ``show_hidden`` - set it to ``true`` to include in scan result networks with hidden SSID.
scanComplete
^^^^^^^^^^^^
Check for result of asynchronous scanning.
.. code:: cpp
WiFi.scanComplete()
On scan completion function returns the number of discovered networks.
If scan is not done, then returned value is < 0 as follows: \* Scanning still in progress: -1 \* Scanning has not been triggered: -2
scanDelete
^^^^^^^^^^
Delete the last scan result from memory.
.. code:: cpp
WiFi.scanDelete()
scanNetworksAsync
^^^^^^^^^^^^^^^^^
Start scanning for available Wi-Fi networks. On completion execute another function.
.. code:: cpp
WiFi.scanNetworksAsync(onComplete, show_hidden)
| Function parameters: \* ``onComplete`` - the event handler executed
when the scan is done
| \* ``show_hidden`` - optional ``boolean`` parameter, set it to
``true`` to scan for hidden networks
*Example code:*
.. code:: cpp
#include "ESP8266WiFi.h"
void prinScanResult(int networksFound)
{
Serial.printf("%d network(s) found\n", networksFound);
for (int i = 0; i < networksFound; i++)
{
Serial.printf("%d: %s, Ch:%d (%ddBm) %s\n", i + 1, WiFi.SSID(i).c_str(), WiFi.channel(i), WiFi.RSSI(i), WiFi.encryptionType(i) == ENC_TYPE_NONE ? "open" : "");
}
}
void setup()
{
Serial.begin(115200);
Serial.println();
WiFi.mode(WIFI_STA);
WiFi.disconnect();
delay(100);
WiFi.scanNetworksAsync(prinScanResult);
}
void loop() {}
*Example output:*
::
5 network(s) found
1: Tech_D005107, Ch:6 (-72dBm)
2: HP-Print-A2-Photosmart 7520, Ch:6 (-79dBm)
3: ESP_0B09E3, Ch:9 (-89dBm) open
4: Hack-4-fun-net, Ch:9 (-91dBm)
5: UPC Wi-Free, Ch:11 (-79dBm)
Show Results
~~~~~~~~~~~~
Functions below provide access to result of scanning. It does not matter if scanning has been done in synchronous or asynchronous mode, scan results are available using the same API.
Individual results are accessible by providing a \`networkItem' that identifies the index (zero based) of discovered network.
SSID
^^^^
Return the SSID of a network discovered during the scan.
.. code:: cpp
WiFi.SSID(networkItem)
Returned SSID is of the ``String`` type. The ``networkItem`` is a zero based index of network discovered during scan.
encryptionType
^^^^^^^^^^^^^^
Return the encryption type of a network discovered during the scan.
.. code:: cpp
WiFi.encryptionType(networkItem)
Function returns a number that encodes encryption type as follows: \* 5
: ``ENC_TYPE_WEP`` - WEP \* 2 : ``ENC_TYPE_TKIP`` - WPA / PSK \* 4 :
``ENC_TYPE_CCMP`` - WPA2 / PSK \* 7 : ``ENC_TYPE_NONE`` - open network
\* 8 : ``ENC_TYPE_AUTO`` - WPA / WPA2 / PSK
The ``networkItem`` is a zero based index of network discovered during scan.
RSSI
^^^^
Return the `RSSI <https://en.wikipedia.org/wiki/Received_signal_strength_indication>`__ (Received Signal Strength Indication) of a network discovered during the scan.
.. code:: cpp
WiFi.RSSI(networkItem)
Returned RSSI is of the ``int32_t`` type. The ``networkItem`` is a zero based index of network discovered during scan.
BSSID
^^^^^
Return the `BSSID <https://en.wikipedia.org/wiki/Service_set_(802.11_network)#Basic_service_set_identification_.28BSSID.29>`__ (Basic Service Set Identification) that is another name of MAC address of a network discovered during the scan.
.. code:: cpp
WiFi.BSSID(networkItem)
Function returns a pointer to the memory location (an ``uint8_t`` array with the size of 6 elements) where the BSSID is saved.
If you do not like to pointers, then there is another version of this function that returns a ``String``.
.. code:: cpp
WiFi.BSSIDstr(networkItem)
The ``networkItem`` is a zero based index of network discovered during scan.
channel
^^^^^^^
Return the channel of a network discovered during the scan.
.. code:: cpp
WiFi.channel(networkItem)
Returned channel is of the ``int32_t`` type. The ``networkItem`` is a zero based index of network discovered during scan.
isHidden
^^^^^^^^
Return information if a network discovered during the scan is hidden or not.
.. code:: cpp
WiFi.isHidden(networkItem)
Returned value if the ``bolean`` type, and ``true`` means that network is hidden. The ``networkItem`` is a zero based index of network discovered during scan.
getNetworkInfo
^^^^^^^^^^^^^^
Return all the network information discussed in this chapter above in a single function call.
.. code:: cpp
WiFi.getNetworkInfo(networkItem, &ssid, &encryptionType, &RSSI, *&BSSID, &channel, &isHidden)
The ``networkItem`` is a zero based index of network discovered during scan. All other input parameters are passed to function by reference. Therefore they will be updated with actual values retrieved for particular ``networkItem``. The function itself returns ``boolean`` ``true`` or ``false`` to confirm if information retrieval was successful or not.
*Example code:*
.. code:: cpp
int n = WiFi.scanNetworks(false, true);
String ssid;
uint8_t encryptionType;
int32_t RSSI;
uint8_t* BSSID;
int32_t channel;
bool isHidden;
for (int i = 0; i < n; i++)
{
WiFi.getNetworkInfo(i, ssid, encryptionType, RSSI, BSSID, channel, isHidden);
Serial.printf("%d: %s, Ch:%d (%ddBm) %s %s\n", i + 1, ssid.c_str(), channel, RSSI, encryptionType == ENC_TYPE_NONE ? "open" : "", isHidden ? "hidden" : "");
}
*Example output:*
::
6 network(s) found
1: Tech_D005107, Ch:6 (-72dBm)
2: HP-Print-A2-Photosmart 7520, Ch:6 (-79dBm)
3: ESP_0B09E3, Ch:9 (-89dBm) open
4: Hack-4-fun-net, Ch:9 (-91dBm)
5: , Ch:11 (-77dBm) hidden
6: UPC Wi-Free, Ch:11 (-79dBm)
For code samples please refer to separate section with `examples <scan-examples.md>`__ dedicated specifically to the Scan Class.

261
doc/esp8266wifi/scan-examples.md
View File

@ -1,261 +0,0 @@
---
title: ESP8266WiFi Scan Class - Sketch Examples
---
[ESP8266WiFi Library :back:](readme.md#scan)
### Scan
To connect a mobile phone to a hot spot, you typically open Wi-Fi settings app, list available networks and then pick the hot spot you need. You can also list the networks with ESP8266 and here is how.
## Table of Contents
* [Simple Scan](#simple-scan)
* [Disconnect](#disconnect)
* [Scan for Networks](#scan-for-networks)
* [Complete Example](#complete-example)
* [Example in Action](#example-in-action)
* [Async Scan](#async-scan)
* [No delay()](#no-delay)
* [Setup](#setup)
* [When to Start](#when-to-start)
* [Check When Done](#check-when-done)
* [Complete Example](#complete-example-1)
* [Example in Action](#example-in-action-1)
* [Conclusion](#conclusion)
### Simple Scan
This example shows the bare minimum code we need to check for the list of available networks.
#### Disconnect
To start with, enable module in station mode and then disconnect.
```cpp
WiFi.mode(WIFI_STA);
WiFi.disconnect();
```
Running `WiFi.disconnect()` is to shut down a connection to an access point that module may have automatically made using previously saved credentials.
#### Scan for Networks
After some delay to let the module disconnect, go to scanning for available networks:
```cpp
int n = WiFi.scanNetworks();
```
Now just check if returned `n` if greater than 0 and list found networks:
```cpp
for (int i = 0; i < n; i++)
{
Serial.println(WiFi.SSID(i));
}
```
This is that simple.
#### Complete Example
The sketch should have obligatory `#include <ESP8266WiFi.h>` and looks as follows:
```cpp
#include "ESP8266WiFi.h"
void setup()
{
Serial.begin(115200);
Serial.println();
WiFi.mode(WIFI_STA);
WiFi.disconnect();
delay(100);
}
void loop()
{
Serial.print("Scan start ... ");
int n = WiFi.scanNetworks();
Serial.print(n);
Serial.println(" network(s) found");
for (int i = 0; i < n; i++)
{
Serial.println(WiFi.SSID(i));
}
Serial.println();
delay(5000);
}
```
#### Example in Action
Upload this sketch to ESP module and open a serial monitor. If there are access points around (sure there are) you will see a similar list repeatedly printed out:
```
Scan start ... 5 network(s) found
Tech_D005107
HP-Print-A2-Photosmart 7520
ESP_0B09E3
Hack-4-fun-net
UPC Wi-Free
```
When looking for the text `scan start ...` displayed, you will notice that it takes noticeable time for the following text `n network(s) found` to show up. This is because execution of `WiFi.scanNetworks()` takes time and our program is waiting for it to complete before moving to the next line of code. What if at the same time we would like ESP to run time critical process (e.g. animation) that should not be disturbed?
It turns out that this is fairly easy to do by scanning networks in async mode.
Check it out in next example below that will also demonstrate printing out other parameters of available networks besides SSID.
### Async Scan
What we like to do, is to trigger process of scanning for networks and then return to executing code inside the `loop()`. Once scanning is complete, at a convenient time, we will check the list of networks. The "time critical process" will be simulated by a blinking LED at 250ms period.
We would like the blinking pattern not be disturbed at any time.
#### No delay()
To implement such functionality we should refrain from using any `delay()` inside the `loop()`. Instead we will define period when to trigger particular action. Then inside `loop()` we will check `millis()` (internal clock that counts milliseconds) and fire the action if the period expires.
Please check how this is done in [BlinkWithoutDelay.ino](BlinkWithoutDelay.ino) example sketch. Identical technique can be used to periodically trigger scanning for Wi-Fi networks.
#### Setup
First we should define scanning period and internal variable `lastScanMillis` that will hold time when the last scan has been made.
```cpp
#define SCAN_PERIOD 5000
long lastScanMillis;
```
#### When to Start
Then inside the `loop()` we will check if `SCAN_PERIOD` expired, so it is time to fire next scan:
```cpp
if (currentMillis - lastScanMillis > SCAN_PERIOD)
{
WiFi.scanNetworks(true);
Serial.print("\nScan start ... ");
lastScanMillis = currentMillis;
}
```
Please note that `WiFi.scanNetworks(true)` has an extra parameter `true` that was not present in [previous example](#simple-scan) above. This is an instruction to scan in asynchronous mode, i.e. trigger scanning process, do not wait for result (processing will be done in background) and move to the next line of code. We need to use asynchronous mode otherwise 250ms LED blinking pattern would be disturbed as scanning takes longer than 250ms.
#### Check When Done
Finally we should periodically check for scan completion to print out the result once ready. To do so, we will use function `WiFi.scanComplete()`, that upon completion returns the number of found networks. If scanning is still in progress it returns -1. If scanning has not been triggered yet, it would return -2.
```cpp
int n = WiFi.scanComplete();
if(n >= 0)
{
Serial.printf("%d network(s) found\n", n);
for (int i = 0; i < n; i++)
{
Serial.printf("%d: %s, Ch:%d (%ddBm) %s\n", i+1, WiFi.SSID(i).c_str(), WiFi.channel(i), WiFi.RSSI(i), WiFi.encryptionType(i) == ENC_TYPE_NONE ? "open" : "");
}
WiFi.scanDelete();
}
```
Please note function `WiFi.scanDelete()` that is deleting scanning result from memory, so it is not printed out over and over again on each `loop()` run.
#### Complete Example
Complete sketch is below. The code inside `setup()` is the same as described in [previous example](#simple-scan) except for an additional `pinMode()` to configure the output pin for LED.
```cpp
#include "ESP8266WiFi.h"
#define BLINK_PERIOD 250
long lastBlinkMillis;
boolean ledState;
#define SCAN_PERIOD 5000
long lastScanMillis;
void setup()
{
Serial.begin(115200);
Serial.println();
pinMode(LED_BUILTIN, OUTPUT);
WiFi.mode(WIFI_STA);
WiFi.disconnect();
delay(100);
}
void loop()
{
long currentMillis = millis();
// blink LED
if (currentMillis - lastBlinkMillis > BLINK_PERIOD)
{
digitalWrite(LED_BUILTIN, ledState);
ledState = !ledState;
lastBlinkMillis = currentMillis;
}
// trigger Wi-Fi network scan
if (currentMillis - lastScanMillis > SCAN_PERIOD)
{
WiFi.scanNetworks(true);
Serial.print("\nScan start ... ");
lastScanMillis = currentMillis;
}
// print out Wi-Fi network scan result uppon completion
int n = WiFi.scanComplete();
if(n >= 0)
{
Serial.printf("%d network(s) found\n", n);
for (int i = 0; i < n; i++)
{
Serial.printf("%d: %s, Ch:%d (%ddBm) %s\n", i+1, WiFi.SSID(i).c_str(), WiFi.channel(i), WiFi.RSSI(i), WiFi.encryptionType(i) == ENC_TYPE_NONE ? "open" : "");
}
WiFi.scanDelete();
}
}
```
#### Example in Action
Upload above sketch to ESP module and open a serial monitor. You should see similar list printed out every 5 seconds:
```
Scan start ... 5 network(s) found
1: Tech_D005107, Ch:6 (-72dBm)
2: HP-Print-A2-Photosmart 7520, Ch:6 (-79dBm)
3: ESP_0B09E3, Ch:9 (-89dBm) open
4: Hack-4-fun-net, Ch:9 (-91dBm)
5: UPC Wi-Free, Ch:11 (-79dBm)
```
Check the LED. It should be blinking undisturbed four times per second.
### Conclusion
The scan class API provides comprehensive set of methods to do scanning in both synchronous as well as in asynchronous mode. Therefore we can easy implement code that is doing scanning in background without disturbing other processes running on ESP8266 module.
For the list of functions provided to manage scan mode please refer to the [Scan Class :arrow_right:](scan-class.md) documentation.

243
doc/esp8266wifi/scan-examples.rst Normal file
View File

@ -0,0 +1,243 @@
:orphan:
Scan
~~~~
To connect a mobile phone to a hot spot, you typically open Wi-Fi settings app, list available networks and then pick the hot spot you need. You can also list the networks with ESP8266 and here is how.
Simple Scan
~~~~~~~~~~~
This example shows the bare minimum code we need to check for the list of available networks.
Disconnect
^^^^^^^^^^
To start with, enable module in station mode and then disconnect.
.. code:: cpp
WiFi.mode(WIFI_STA);
WiFi.disconnect();
Running ``WiFi.disconnect()`` is to shut down a connection to an access point that module may have automatically made using previously saved credentials.
Scan for Networks
^^^^^^^^^^^^^^^^^
After some delay to let the module disconnect, go to scanning for available networks:
.. code:: cpp
int n = WiFi.scanNetworks();
Now just check if returned ``n`` if greater than 0 and list found networks:
.. code:: cpp
for (int i = 0; i < n; i++)
{
Serial.println(WiFi.SSID(i));
}
This is that simple.
Complete Example
^^^^^^^^^^^^^^^^
The sketch should have obligatory ``#include <ESP8266WiFi.h>`` and looks as follows:
.. code:: cpp
#include "ESP8266WiFi.h"
void setup()
{
Serial.begin(115200);
Serial.println();
WiFi.mode(WIFI_STA);
WiFi.disconnect();
delay(100);
}
void loop()
{
Serial.print("Scan start ... ");
int n = WiFi.scanNetworks();
Serial.print(n);
Serial.println(" network(s) found");
for (int i = 0; i < n; i++)
{
Serial.println(WiFi.SSID(i));
}
Serial.println();
delay(5000);
}
Example in Action
^^^^^^^^^^^^^^^^^
Upload this sketch to ESP module and open a serial monitor. If there are access points around (sure there are) you will see a similar list repeatedly printed out:
::
Scan start ... 5 network(s) found
Tech_D005107
HP-Print-A2-Photosmart 7520
ESP_0B09E3
Hack-4-fun-net
UPC Wi-Free
When looking for the text ``scan start ...`` displayed, you will notice that it takes noticeable time for the following text ``n network(s) found`` to show up. This is because execution of ``WiFi.scanNetworks()`` takes time and our program is waiting for it to complete before moving to the next line of code. What if at the same time we would like ESP to run time critical process (e.g. animation)
that should not be disturbed?
It turns out that this is fairly easy to do by scanning networks in async mode.
Check it out in next example below that will also demonstrate printing out other parameters of available networks besides SSID.
Async Scan
~~~~~~~~~~
What we like to do, is to trigger process of scanning for networks and then return to executing code inside the ``loop()``. Once scanning is complete, at a convenient time, we will check the list of networks. The "time critical process" will be simulated by a blinking LED at 250ms period.
We would like the blinking pattern not be disturbed at any time.
No delay()
^^^^^^^^^^
To implement such functionality we should refrain from using any ``delay()`` inside the ``loop()``. Instead we will define period when to trigger particular action. Then inside ``loop()`` we will check ``millis()`` (internal clock that counts milliseconds) and fire the action if the period expires.
Please check how this is done in `BlinkWithoutDelay.ino <BlinkWithoutDelay.ino>`__ example sketch. Identical technique can be used to periodically trigger scanning for Wi-Fi networks.
Setup
^^^^^
First we should define scanning period and internal variable ``lastScanMillis`` that will hold time when the last scan has been made.
.. code:: cpp
#define SCAN_PERIOD 5000
long lastScanMillis;
When to Start
^^^^^^^^^^^^^
Then inside the ``loop()`` we will check if ``SCAN_PERIOD`` expired, so it is time to fire next scan:
.. code:: cpp
if (currentMillis - lastScanMillis > SCAN_PERIOD)
{
WiFi.scanNetworks(true);
Serial.print("\nScan start ... ");
lastScanMillis = currentMillis;
}
Please note that ``WiFi.scanNetworks(true)`` has an extra parameter ``true`` that was not present in `previous example <#simple-scan>`__ above. This is an instruction to scan in asynchronous mode, i.e. trigger scanning process, do not wait for result (processing will be done in background) and move to the next line of code. We need to use asynchronous mode otherwise 250ms LED blinking pattern would be disturbed as scanning takes longer than 250ms.
Check When Done
^^^^^^^^^^^^^^^
Finally we should periodically check for scan completion to print out the result once ready. To do so, we will use function ``WiFi.scanComplete()``, that upon completion returns the number of found networks. If scanning is still in progress it returns -1. If scanning has not been triggered yet, it would return -2.
.. code:: cpp
int n = WiFi.scanComplete();
if(n >= 0)
{
Serial.printf("%d network(s) found\n", n);
for (int i = 0; i < n; i++)
{
Serial.printf("%d: %s, Ch:%d (%ddBm) %s\n", i+1, WiFi.SSID(i).c_str(), WiFi.channel(i), WiFi.RSSI(i), WiFi.encryptionType(i) == ENC_TYPE_NONE ? "open" : "");
}
WiFi.scanDelete();
}
Please note function ``WiFi.scanDelete()`` that is deleting scanning result from memory, so it is not printed out over and over again on each ``loop()`` run.
Complete Example
^^^^^^^^^^^^^^^^
Complete sketch is below. The code inside ``setup()`` is the same as described in `previous example <#simple-scan>`__ except for an additional ``pinMode()`` to configure the output pin for LED.
.. code:: cpp
#include "ESP8266WiFi.h"
#define BLINK_PERIOD 250
long lastBlinkMillis;
boolean ledState;
#define SCAN_PERIOD 5000
long lastScanMillis;
void setup()
{
Serial.begin(115200);
Serial.println();
pinMode(LED_BUILTIN, OUTPUT);
WiFi.mode(WIFI_STA);
WiFi.disconnect();
delay(100);
}
void loop()
{
long currentMillis = millis();
// blink LED
if (currentMillis - lastBlinkMillis > BLINK_PERIOD)
{
digitalWrite(LED_BUILTIN, ledState);
ledState = !ledState;
lastBlinkMillis = currentMillis;
}
// trigger Wi-Fi network scan
if (currentMillis - lastScanMillis > SCAN_PERIOD)
{
WiFi.scanNetworks(true);
Serial.print("\nScan start ... ");
lastScanMillis = currentMillis;
}
// print out Wi-Fi network scan result uppon completion
int n = WiFi.scanComplete();
if(n >= 0)
{
Serial.printf("%d network(s) found\n", n);
for (int i = 0; i < n; i++)
{
Serial.printf("%d: %s, Ch:%d (%ddBm) %s\n", i+1, WiFi.SSID(i).c_str(), WiFi.channel(i), WiFi.RSSI(i), WiFi.encryptionType(i) == ENC_TYPE_NONE ? "open" : "");
}
WiFi.scanDelete();
}
}
Example in Action
^^^^^^^^^^^^^^^^^
Upload above sketch to ESP module and open a serial monitor. You should see similar list printed out every 5 seconds:
::
Scan start ... 5 network(s) found
1: Tech_D005107, Ch:6 (-72dBm)
2: HP-Print-A2-Photosmart 7520, Ch:6 (-79dBm)
3: ESP_0B09E3, Ch:9 (-89dBm) open
4: Hack-4-fun-net, Ch:9 (-91dBm)
5: UPC Wi-Free, Ch:11 (-79dBm)
Check the LED. It should be blinking undisturbed four times per second.
Conclusion
~~~~~~~~~~
The scan class API provides comprehensive set of methods to do scanning in both synchronous as well as in asynchronous mode. Therefore we can easy implement code that is doing scanning in background without disturbing other processes running on ESP8266 module.
For the list of functions provided to manage scan mode please refer to the `Scan Class <scan-class.md>`__ documentation.

54
doc/esp8266wifi/server-class.md
View File

@ -1,54 +0,0 @@
---
title: ESP8266WiFi Server Class
---
[ESP8266WiFi Library :back:](readme.md#server)
## Server Class
Methods documented for the [Server Class](https://www.arduino.cc/en/Reference/WiFiServerConstructor) in [Arduino](https://github.com/arduino/Arduino)
1. [WiFiServer()](https://www.arduino.cc/en/Reference/WiFiServer)
2. [begin()](https://www.arduino.cc/en/Reference/WiFiServerBegin)
3. [available()](https://www.arduino.cc/en/Reference/WiFiServerAvailable)
4. [write()](https://www.arduino.cc/en/Reference/WiFiServerWrite)
5. [print()](https://www.arduino.cc/en/Reference/WiFiServerPrint)
6. [println()](https://www.arduino.cc/en/Reference/WiFiServerPrintln)
Methods and properties described further down are specific to ESP8266. They are not covered in [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi) documentation. Before they are fully documented please refer to information below.
### setNoDelay
```cpp
setNoDelay(nodelay)
```
With `nodelay` set to `true`, this function will to disable [Nagle algorithm](https://en.wikipedia.org/wiki/Nagle%27s_algorithm).
This algorithm is intended to reduce TCP/IP traffic of small packets sent over the network by combining a number of small outgoing messages, and sending them all at once. The downside of such approach is effectively delaying individual messages until a big enough packet is assembled.
*Example:*
```cpp
server.begin();
server.setNoDelay(true);
```
### Other Function Calls
```cpp
bool hasClient ()
bool getNoDelay ()
virtual size_t write (const uint8_t *buf, size_t size)
uint8_t status ()
void close ()
void stop ()
```
Documentation for the above functions is not yet prepared.
For code samples please refer to separate section with [examples :arrow_right:](server-examples.md) dedicated specifically to the Server Class.

49
doc/esp8266wifi/server-class.rst Normal file
View File

@ -0,0 +1,49 @@
:orphan:
Server Class
------------
Methods documented for the `Server Class <https://www.arduino.cc/en/Reference/WiFiServerConstructor>`__ in `Arduino <https://github.com/arduino/Arduino>`__
1. `WiFiServer() <https://www.arduino.cc/en/Reference/WiFiServer>`__
2. `begin() <https://www.arduino.cc/en/Reference/WiFiServerBegin>`__
3. `available() <https://www.arduino.cc/en/Reference/WiFiServerAvailable>`__
4. `write() <https://www.arduino.cc/en/Reference/WiFiServerWrite>`__
5. `print() <https://www.arduino.cc/en/Reference/WiFiServerPrint>`__
6. `println() <https://www.arduino.cc/en/Reference/WiFiServerPrintln>`__
Methods and properties described further down are specific to ESP8266. They are not covered in `Arduino WiFi library <https://www.arduino.cc/en/Reference/WiFi>`__ documentation. Before they are fully documented please refer to information below.
setNoDelay
~~~~~~~~~~
.. code:: cpp
setNoDelay(nodelay)
With ``nodelay`` set to ``true``, this function will to disable `Nagle algorithm <https://en.wikipedia.org/wiki/Nagle%27s_algorithm>`__.
This algorithm is intended to reduce TCP/IP traffic of small packets sent over the network by combining a number of small outgoing messages, and sending them all at once. The downside of such approach is effectively delaying individual messages until a big enough packet is assembled.
*Example:*
.. code:: cpp
server.begin();
server.setNoDelay(true);
Other Function Calls
~~~~~~~~~~~~~~~~~~~~
.. code:: cpp
bool hasClient ()
bool getNoDelay ()
virtual size_t write (const uint8_t *buf, size_t size)
uint8_t status ()
void close ()
void stop ()
Documentation for the above functions is not yet prepared.
For code samples please refer to separate section with :doc:`examples <server-examples>` dedicated specifically to the Server Class.

253
doc/esp8266wifi/server-examples.md
View File

@ -1,253 +0,0 @@
---
title: ESP8266WiFi Server Class - Sketch Examples
---
[ESP8266WiFi Library :back:](readme.md#server)
## Server
Setting up web a server on ESP8266 requires very little code and is surprisingly straightforward. This is thanks to functionality provided by the versatile ESP8266WiFi library.
The purpose of this example will be to prepare a web page that can be opened in a web browser. This page should show the current raw reading of ESP's analog input pin.
## Table of Contents
* [The Object](#the-object)
* [The Page](#the-page)
* [Header First](#header-first)
* [The Page is Served](#the-page-is-served)
* [Get it Together](#put-it-together)
* [Get it Run](#get-it-run)
* [What Else?](#what-else)
* [Conclusion](#conclusion)
### The Object
We will start off by creating a server object.
```cpp
WiFiServer server(80);
```
The server responds to clients (in this case - web browsers) on port 80, which is a standard port web browsers talk to web servers.
### The Page
Then let's write a short function `prepareHtmlPage()`, that will return a `String` class variable containing the contents of the web page. We will then pass this variable to server to pass it over to a client.
```cpp
String prepareHtmlPage()
{
String htmlPage =
String("HTTP/1.1 200 OK\r\n") +
"Content-Type: text/html\r\n" +
"Connection: close\r\n" + // the connection will be closed after completion of the response
"Refresh: 5\r\n" + // refresh the page automatically every 5 sec
"\r\n" +
"<!DOCTYPE HTML>" +
"<html>" +
"Analog input: " + String(analogRead(A0)) +
"</html>" +
"\r\n";
return htmlPage;
}
```
The function does nothing fancy but just puts together a text header and [HTML](http://www.w3schools.com/html/) contents of the page.
### Header First
The header is to inform client what type of contents is to follow and how it will be served:
```
Content-Type: text/html
Connection: close
Refresh: 5
```
In our example the content type is `text/html`, the connection will be closed after serving and the content should be requested by the client again every 5 seconds. The header is concluded with an empty line `\r\n`. This is to distinguish header from the content to follow.
```
<!DOCTYPE HTML>
<html>
Analog input: [Value]
</html>
```
The content contains two basic [HTML](http://www.w3schools.com/html/) tags, one to denote HTML document type `<!DOCTYPE HTML>` and another to mark beginning `<html>` and end `</html>` of the document. Inside there is a raw value read from ESP's analog input `analogRead(A0)` converted to the `String` type.
```cpp
String(analogRead(A0))
```
### The Page is Served
Serving of this web page will be done in the `loop()` where server is waiting for a new client to connect and send some data containing a request:
```cpp
void loop()
{
WiFiClient client = server.available();
if (client)
{
// we have a new client sending some request
}
}
```
Once a new client is connected, server will read the client's request and print it out on a serial monitor.
```cpp
while (client.connected())
{
if (client.available())
{
String line = client.readStringUntil('\r');
Serial.print(line);
}
}
```
Request from the client is marked with an empty new line. If we find this mark, we can send back the web page and exit `while()` loop using `break`.
```cpp
if (line.length() == 1 && line[0] == '\n')
{
client.println(prepareHtmlPage());
break;
}
```
The whole process is concluded by stopping the connection with client:
```cpp
client.stop();
```
### Put it Together
Complete sketch is presented below.
```cpp
#include <ESP8266WiFi.h>
const char* ssid = "********";
const char* password = "********";
WiFiServer server(80);
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.printf("Connecting to %s ", ssid);
WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.println(" connected");
server.begin();
Serial.printf("Web server started, open %s in a web browser\n", WiFi.localIP().toString().c_str());
}
// prepare a web page to be send to a client (web browser)
String prepareHtmlPage()
{
String htmlPage =
String("HTTP/1.1 200 OK\r\n") +
"Content-Type: text/html\r\n" +
"Connection: close\r\n" + // the connection will be closed after completion of the response
"Refresh: 5\r\n" + // refresh the page automatically every 5 sec
"\r\n" +
"<!DOCTYPE HTML>" +
"<html>" +
"Analog input: " + String(analogRead(A0)) +
"</html>" +
"\r\n";
return htmlPage;
}
void loop()
{
WiFiClient client = server.available();
// wait for a client (web browser) to connect
if (client)
{
Serial.println("\n[Client connected]");
while (client.connected())
{
// read line by line what the client (web browser) is requesting
if (client.available())
{
String line = client.readStringUntil('\r');
Serial.print(line);
// wait for end of client's request, that is marked with an empty line
if (line.length() == 1 && line[0] == '\n')
{
client.println(prepareHtmlPage());
break;
}
}
}
delay(1); // give the web browser time to receive the data
// close the connection:
client.stop();
Serial.println("[Client disonnected]");
}
}
```
### Get it Run
Update `ssid` and `password` in sketch to match credentials of your access point. Load sketch to ESP module and open a serial monitor. First you should see confirmation that module connected to the access point and the web server started.
```
Connecting to sensor-net ........ connected
Web server started, open 192.168.1.104 in a web browser
```
Enter provided IP address in a web browser. You should see the page served by ESP8266:
![alt text](pictures/server-browser-output.png "Output from server in a web browser")
The page would be refreshed every 5 seconds. Each time this happens, you should see a request from the client (your web browser) printed out on the serial monitor:
```
[Client connected]
GET / HTTP/1.1
Accept: text/html, application/xhtml+xml, */*
Accept-Language: en-US
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko
Accept-Encoding: gzip, deflate
Host: 192.168.1.104
DNT: 1
Connection: Keep-Alive
[client disonnected]
```
### What Else?
Looking on [client examples](client-examples.md) you will quickly find out the similarities in protocol to the server. The protocol starts with a header that contains information what communication will be about. It contains what content type is communicated or accepted like `text/html`. It states whether connection will be kept alive or closed after submission of the header. It contains identification of the sender like `User-Agent: Mozilla/5.0 (Windows NT 6.1)`, etc.
### Conclusion
The above example shows that a web server on ESP8266 can be set up in almost no time. Such server can easily stand up requests from much more powerful hardware and software like a PC with a web browser. Check out other classes like [ESP8266WebServer](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer) that let you program more advanced applications.
If you like to try another server example, check out [WiFiWebServer.ino](https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiWebServer/WiFiWebServer.ino), that provides functionality of toggling the GPIO pin on and off out of a web browser.
For the list of functions provided to implement and manage servers, please refer to the [Server Class :arrow_right:](server-class.md) documentation.

255
doc/esp8266wifi/server-examples.rst Normal file
View File

@ -0,0 +1,255 @@
:orphan:
Server
------
Setting up web a server on ESP8266 requires very little code and is surprisingly straightforward. This is thanks to functionality provided by the versatile ESP8266WiFi library.
The purpose of this example will be to prepare a web page that can be opened in a web browser. This page should show the current raw reading of ESP's analog input pin.
Table of Contents
-----------------
- `The Object <#the-object>`__
- `The Page <#the-page>`__
- `Header First <#header-first>`__
- `The Page is Served <#the-page-is-served>`__
- `Get it Together <#put-it-together>`__
- `Get it Run <#get-it-run>`__
- `What Else? <#what-else>`__
- `Conclusion <#conclusion>`__
The Object
~~~~~~~~~~
We will start off by creating a server object.
.. code:: cpp
WiFiServer server(80);
The server responds to clients (in this case - web browsers) on port 80, which is a standard port web browsers talk to web servers.
The Page
~~~~~~~~
Then let's write a short function ``prepareHtmlPage()``, that will return a ``String`` class variable containing the contents of the web page. We will then pass this variable to server to pass it over to a client.
.. code:: cpp
String prepareHtmlPage()
{
String htmlPage =
String("HTTP/1.1 200 OK\r\n") +
"Content-Type: text/html\r\n" +
"Connection: close\r\n" + // the connection will be closed after completion of the response
"Refresh: 5\r\n" + // refresh the page automatically every 5 sec
"\r\n" +
"<!DOCTYPE HTML>" +
"<html>" +
"Analog input: " + String(analogRead(A0)) +
"</html>" +
"\r\n";
return htmlPage;
}
The function does nothing fancy but just puts together a text header and `HTML <http://www.w3schools.com/html/>`__ contents of the page.
Header First
~~~~~~~~~~~~
The header is to inform client what type of contents is to follow and how it will be served:
::
Content-Type: text/html
Connection: close
Refresh: 5
In our example the content type is ``text/html``, the connection will be closed after serving and the content should be requested by the client again every 5 seconds. The header is concluded with an empty line ``\r\n``. This is to distinguish header from the content to follow.
::
<!DOCTYPE HTML>
<html>
Analog input: [Value]
</html>
The content contains two basic `HTML <http://www.w3schools.com/html/>`__ tags, one to denote HTML document type ``<!DOCTYPE HTML>`` and another to mark beginning ``<html>`` and end ``</html>`` of the document. Inside there is a raw value read from ESP's analog input ``analogRead(A0)`` converted to the ``String`` type.
.. code:: cpp
String(analogRead(A0))
The Page is Served
~~~~~~~~~~~~~~~~~~
Serving of this web page will be done in the ``loop()`` where server is waiting for a new client to connect and send some data containing a request:
.. code:: cpp
void loop()
{
WiFiClient client = server.available();
if (client)
{
// we have a new client sending some request
}
}
Once a new client is connected, server will read the client's request and print it out on a serial monitor.
.. code:: cpp
while (client.connected())
{
if (client.available())
{
String line = client.readStringUntil('\r');
Serial.print(line);
}
}
Request from the client is marked with an empty new line. If we find this mark, we can send back the web page and exit ``while()`` loop using ``break``.
.. code:: cpp
if (line.length() == 1 && line[0] == '\n')
{
client.println(prepareHtmlPage());
break;
}
The whole process is concluded by stopping the connection with client:
.. code:: cpp
client.stop();
Put it Together
~~~~~~~~~~~~~~~
Complete sketch is presented below.
.. code:: cpp
#include <ESP8266WiFi.h>
const char* ssid = "********";
const char* password = "********";
WiFiServer server(80);
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.printf("Connecting to %s ", ssid);
WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.println(" connected");
server.begin();
Serial.printf("Web server started, open %s in a web browser\n", WiFi.localIP().toString().c_str());
}
// prepare a web page to be send to a client (web browser)
String prepareHtmlPage()
{
String htmlPage =
String("HTTP/1.1 200 OK\r\n") +
"Content-Type: text/html\r\n" +
"Connection: close\r\n" + // the connection will be closed after completion of the response
"Refresh: 5\r\n" + // refresh the page automatically every 5 sec
"\r\n" +
"<!DOCTYPE HTML>" +
"<html>" +
"Analog input: " + String(analogRead(A0)) +
"</html>" +
"\r\n";
return htmlPage;
}
void loop()
{
WiFiClient client = server.available();
// wait for a client (web browser) to connect
if (client)
{
Serial.println("\n[Client connected]");
while (client.connected())
{
// read line by line what the client (web browser) is requesting
if (client.available())
{
String line = client.readStringUntil('\r');
Serial.print(line);
// wait for end of client's request, that is marked with an empty line
if (line.length() == 1 && line[0] == '\n')
{
client.println(prepareHtmlPage());
break;
}
}
}
delay(1); // give the web browser time to receive the data
// close the connection:
client.stop();
Serial.println("[Client disonnected]");
}
}
Get it Run
~~~~~~~~~~
Update ``ssid`` and ``password`` in sketch to match credentials of your access point. Load sketch to ESP module and open a serial monitor. First you should see confirmation that module connected to the access point and the web server started.
::
Connecting to sensor-net ........ connected
Web server started, open 192.168.1.104 in a web browser
Enter provided IP address in a web browser. You should see the page served by ESP8266:
.. figure:: pictures/server-browser-output.png
:alt: Output from server in a web browser
alt text
The page would be refreshed every 5 seconds. Each time this happens, you should see a request from the client (your web browser) printed out on the serial monitor:
::
[Client connected]
GET / HTTP/1.1
Accept: text/html, application/xhtml+xml, */*
Accept-Language: en-US
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko
Accept-Encoding: gzip, deflate
Host: 192.168.1.104
DNT: 1
Connection: Keep-Alive
[client disonnected]
What Else?
~~~~~~~~~~
Looking on :doc:`client examples <client-examples>` you will quickly find out the similarities in protocol to the server. The protocol starts with a header that contains information what communication will be about. It contains what content type is communicated or accepted like ``text/html``. It states whether connection will be kept alive or closed after submission of the header. It contains identification of the sender like ``User-Agent: Mozilla/5.0 (Windows NT 6.1)``, etc.
Conclusion
~~~~~~~~~~
The above example shows that a web server on ESP8266 can be set up in almost no time. Such server can easily stand up requests from much more powerful hardware and software like a PC with a web browser. Check out other classes like `ESP8266WebServer <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer>`__ that let you program more advanced applications.
If you like to try another server example, check out `WiFiWebServer.ino <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiWebServer/WiFiWebServer.ino>`__, that provides functionality of toggling the GPIO pin on and off out of a web browser.
For the list of functions provided to implement and manage servers, please refer to the :doc:`Server Class <server-class>` documentation.

211
doc/esp8266wifi/soft-access-point-class.md
View File

@ -1,211 +0,0 @@
---
title: ESP8266WiFi Access Point Class
---
[ESP8266WiFi Library :back:](readme.md#soft-access-point)
## Soft Access Point Class
Section below is ESP8266 specific as [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi) documentation does not cover soft access point. The API description is broken down into three short chapters. They cover how to setup soft-AP, manage connection, and obtain information on soft-AP interface configuration.
## Table of Contents
* [Set up Network](#set-up-network)
* [softAP](#softap)
* [softAPConfig](#softapconfig)
* [Manage Network](#manage-network)
* [softAPdisconnect](#softapdisconnect)
* [softAPgetStationNum](#softapgetstationnum)
* [Network Configuration](#network-configuration)
* [softAPIP](#softapip)
* [softAPmacAddress](#softapmacaddress)
### Set up Network
This section describes functions to set up and configure ESP8266 in the soft access point (soft-AP) mode.
#### softAP
Set up a soft access point to establish a Wi-Fi network.
The simplest version ([an overload in C++ terms](https://en.wikipedia.org/wiki/Function_overloading)) of this function requires only one parameter and is used to set up an open Wi-Fi network.
```cpp
WiFi.softAP(ssid)
```
To set up password protected network, or to configure additional network parameters, use the following overload:
```cpp
WiFi.softAP(ssid, password, channel, hidden)
```
The first parameter of this function is required, remaining three are optional.
Meaning of all parameters is as follows:
- `ssid` - character string containing network SSID (max. 63 characters)
* `password` - optional character string with a password. For WPA2-PSK network it should be at least 8 character long. If not specified, the access point will be open for anybody to connect.
* `channel` - optional parameter to set Wi-Fi channel, from 1 to 13. Default channel = 1.
* `hidden` - optional parameter, if set to `true` will hide SSID
Function will return `true` or `false` depending on result of setting the soft-AP.
Notes:
* The network established by softAP will have default IP address of 192.168.4.1. This address may be changed using `softAPConfig` (see below).
* Even though ESP8266 can operate in soft-AP + station mode, it actually has only one hardware channel. Therefore in soft-AP + station mode, the soft-AP channel will default to the number used by station. For more information how this may affect operation of stations connected to ESP8266's soft-AP, please check [this FAQ entry](http://bbs.espressif.com/viewtopic.php?f=10&t=324) on Espressif forum.
#### softAPConfig
Configure the soft access point's network interface.
```cpp
softAPConfig (local_ip, gateway, subnet)
```
All parameters are the type of `IPAddress` and defined as follows:
* `local_ip` - IP address of the soft access point
* `gateway` - gateway IP address
* `subnet` - subnet mask
Function will return `true` or `false` depending on result of changing the configuration.
*Example code:*
```cpp
#include <ESP8266WiFi.h>
IPAddress local_IP(192,168,4,22);
IPAddress gateway(192,168,4,9);
IPAddress subnet(255,255,255,0);
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.print("Setting soft-AP configuration ... ");
Serial.println(WiFi.softAPConfig(local_IP, gateway, subnet) ? "Ready" : "Failed!");
Serial.print("Setting soft-AP ... ");
Serial.println(WiFi.softAP("ESPsoftAP_01") ? "Ready" : "Failed!");
Serial.print("Soft-AP IP address = ");
Serial.println(WiFi.softAPIP());
}
void loop() {}
```
*Example output:*
```
Setting soft-AP configuration ... Ready
Setting soft-AP ... Ready
Soft-AP IP address = 192.168.4.22
```
### Manage Network
Once soft-AP is established you may check the number of stations connected, or shut it down, using the following functions.
#### softAPgetStationNum
Get the count of the stations that are connected to the soft-AP interface.
```cpp
WiFi.softAPgetStationNum()
```
*Example code:*
```cpp
Serial.printf("Stations connected to soft-AP = %d\n", WiFi.softAPgetStationNum());
```
*Example output:*
```
Stations connected to soft-AP = 2
```
Note: the maximum number of stations that may be connected to ESP8266 soft-AP is five.
#### softAPdisconnect
Disconnect stations from the network established by the soft-AP.
```cpp
WiFi.softAPdisconnect(wifioff)
```
Function will set currently configured SSID and password of the soft-AP to null values. The parameter `wifioff` is optional. If set to `true` it will switch the soft-AP mode off.
Function will return `true` if operation was successful or `false` if otherwise.
### Network Configuration
Functions below provide IP and MAC address of ESP8266's soft-AP.
#### softAPIP
Return IP address of the soft access point's network interface.
```cpp
WiFi.softAPIP()
```
Returned value is of `IPAddress` type.
*Example code:*
```cpp
Serial.print("Soft-AP IP address = ");
Serial.println(WiFi.softAPIP());
```
*Example output:*
```
Soft-AP IP address = 192.168.4.1
```
#### softAPmacAddress
Return MAC address of soft access point. This function comes in two versions, which differ in type of returned values. First returns a pointer, the second a `String`.
##### Pointer to MAC
```cpp
WiFi.softAPmacAddress(mac)
```
Function accepts one parameter `mac` that is a pointer to memory location (an `uint8_t` array the size of 6 elements) to save the mac address. The same pointer value is returned by the function itself.
*Example code:*
```cpp
uint8_t macAddr[6];
WiFi.softAPmacAddress(macAddr);
Serial.printf("MAC address = %02x:%02x:%02x:%02x:%02x:%02x\n", macAddr[0], macAddr[1], macAddr[2], macAddr[3], macAddr[4], macAddr[5]);
```
*Example output:*
```
MAC address = 5e:cf:7f:8b:10:13
```
##### MAC as a String
Optionally you can use function without any parameters that returns a `String` type value.
```cpp
WiFi.softAPmacAddress()
```
*Example code:*
```cpp
Serial.printf("MAC address = %s\n", WiFi.softAPmacAddress().c_str());
```
*Example output:*
```
MAC address = 5E:CF:7F:8B:10:13
```
For code samples please refer to separate section with [examples :arrow_right:](soft-access-point-examples.md) dedicated specifically to the Soft Access Point Class.

227
doc/esp8266wifi/soft-access-point-class.rst Normal file
View File

@ -0,0 +1,227 @@
:orphan:
Soft Access Point Class
-----------------------
Section below is ESP8266 specific as `Arduino WiFi library <https://www.arduino.cc/en/Reference/WiFi>`__ documentation does not cover soft access point. The API description is broken down into three short chapters. They cover how to setup soft-AP, manage connection, and obtain information on soft-AP interface configuration.
Table of Contents
-----------------
- `Set up Network <#set-up-network>`__
- `softAP <#softap>`__
- `softAPConfig <#softapconfig>`__
- `Manage Network <#manage-network>`__
- `softAPdisconnect <#softapdisconnect>`__
- `softAPgetStationNum <#softapgetstationnum>`__
- `Network Configuration <#network-configuration>`__
- `softAPIP <#softapip>`__
- `softAPmacAddress <#softapmacaddress>`__
Set up Network
~~~~~~~~~~~~~~
This section describes functions to set up and configure ESP8266 in the soft access point (soft-AP) mode.
softAP
^^^^^^
Set up a soft access point to establish a Wi-Fi network.
The simplest version (`an overload in C++
terms <https://en.wikipedia.org/wiki/Function_overloading>`__) of this function requires only one parameter and is used to set up an open Wi-Fi network.
.. code:: cpp
WiFi.softAP(ssid)
To set up password protected network, or to configure additional network parameters, use the following overload:
.. code:: cpp
WiFi.softAP(ssid, password, channel, hidden)
The first parameter of this function is required, remaining three are optional.
Meaning of all parameters is as follows: - ``ssid`` - character string containing network SSID (max. 63 characters) \* ``password`` - optional character string with a password. For WPA2-PSK network it should be at least 8 character long. If not specified, the access point will be open for anybody to connect. \* ``channel`` - optional parameter to set Wi-Fi channel, from 1 to 13. Default channel = 1. \* ``hidden`` - optional parameter, if set to ``true`` will hide SSID
Function will return ``true`` or ``false`` depending on result of setting the soft-AP.
Notes: \* The network established by softAP will have default IP address of 192.168.4.1. This address may be changed using ``softAPConfig`` (see below). \* Even though ESP8266 can operate in soft-AP + station mode, it actually has only one hardware channel. Therefore in soft-AP + station mode, the soft-AP channel will default to the number used by station. For more information how this may affect operation of stations connected to ESP8266's soft-AP, please check `this FAQ entry <http://bbs.espressif.com/viewtopic.php?f=10&t=324>`__ on Espressif forum.
softAPConfig
^^^^^^^^^^^^
Configure the soft access point's network interface.
.. code:: cpp
softAPConfig (local_ip, gateway, subnet)
| All parameters are the type of ``IPAddress`` and defined as follows:
\* ``local_ip`` - IP address of the soft access point \* ``gateway`` -
gateway IP address
| \* ``subnet`` - subnet mask
Function will return ``true`` or ``false`` depending on result of changing the configuration.
*Example code:*
.. code:: cpp
#include <ESP8266WiFi.h>
IPAddress local_IP(192,168,4,22);
IPAddress gateway(192,168,4,9);
IPAddress subnet(255,255,255,0);
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.print("Setting soft-AP configuration ... ");
Serial.println(WiFi.softAPConfig(local_IP, gateway, subnet) ? "Ready" : "Failed!");
Serial.print("Setting soft-AP ... ");
Serial.println(WiFi.softAP("ESPsoftAP_01") ? "Ready" : "Failed!");
Serial.print("Soft-AP IP address = ");
Serial.println(WiFi.softAPIP());
}
void loop() {}
*Example output:*
::
Setting soft-AP configuration ... Ready
Setting soft-AP ... Ready
Soft-AP IP address = 192.168.4.22
Manage Network
~~~~~~~~~~~~~~
Once soft-AP is established you may check the number of stations connected, or shut it down, using the following functions.
softAPgetStationNum
^^^^^^^^^^^^^^^^^^^
Get the count of the stations that are connected to the soft-AP interface.
.. code:: cpp
WiFi.softAPgetStationNum()
*Example code:*
.. code:: cpp
Serial.printf("Stations connected to soft-AP = %d\n", WiFi.softAPgetStationNum());
*Example output:*
::
Stations connected to soft-AP = 2
Note: the maximum number of stations that may be connected to ESP8266 soft-AP is five.
softAPdisconnect
^^^^^^^^^^^^^^^^
Disconnect stations from the network established by the soft-AP.
.. code:: cpp
WiFi.softAPdisconnect(wifioff)
Function will set currently configured SSID and password of the soft-AP to null values. The parameter ``wifioff`` is optional. If set to ``true`` it will switch the soft-AP mode off.
Function will return ``true`` if operation was successful or ``false`` if otherwise.
Network Configuration
~~~~~~~~~~~~~~~~~~~~~
Functions below provide IP and MAC address of ESP8266's soft-AP.
softAPIP
^^^^^^^^
Return IP address of the soft access point's network interface.
.. code:: cpp
WiFi.softAPIP()
Returned value is of ``IPAddress`` type.
*Example code:*
.. code:: cpp
Serial.print("Soft-AP IP address = ");
Serial.println(WiFi.softAPIP());
*Example output:*
::
Soft-AP IP address = 192.168.4.1
softAPmacAddress
^^^^^^^^^^^^^^^^
Return MAC address of soft access point. This function comes in two versions, which differ in type of returned values. First returns a pointer, the second a ``String``.
Pointer to MAC
''''''''''''''
.. code:: cpp
WiFi.softAPmacAddress(mac)
Function accepts one parameter ``mac`` that is a pointer to memory location (an ``uint8_t`` array the size of 6 elements) to save the mac address. The same pointer value is returned by the function itself.
*Example code:*
.. code:: cpp
uint8_t macAddr[6];
WiFi.softAPmacAddress(macAddr);
Serial.printf("MAC address = %02x:%02x:%02x:%02x:%02x:%02x\n", macAddr[0], macAddr[1], macAddr[2], macAddr[3], macAddr[4], macAddr[5]);
*Example output:*
::
MAC address = 5e:cf:7f:8b:10:13
MAC as a String
'''''''''''''''
Optionally you can use function without any parameters that returns a ``String`` type value.
.. code:: cpp
WiFi.softAPmacAddress()
*Example code:*
.. code:: cpp
Serial.printf("MAC address = %s\n", WiFi.softAPmacAddress().c_str());
*Example output:*
::
MAC address = 5E:CF:7F:8B:10:13
For code samples please refer to separate section with :doc:`examples <soft-access-point-examples>` dedicated specifically to the Soft Access Point Class.

134
doc/esp8266wifi/soft-access-point-examples.md
View File

@ -1,134 +0,0 @@
---
title: ESP8266WiFi Soft Access Point Class - Sketch Examples
---
[ESP8266WiFi Library :back:](readme.md#soft-access-point)
## Soft Access Point
Example below presents how to configure ESP8266 to run in soft access point mode so Wi-Fi stations can connect to it. The Wi-Fi network established by the soft-AP will be identified with the SSID set during configuration. The network may be protected with a password. The network may be also open, if no password is set during configuration.
## Table of Contents
* [The Sketch](#the-sketch)
* [How to Use It?](#how-to-use-it)
* [How Does it Work?](#how-does-it-work)
* [Can we Make it Simpler?](#can-we-make-it-simpler)
* [Conclusion](#conclusion)
### The Sketch
Setting up soft-AP with ESP8266 can be done with just couple lines of code.
```cpp
#include <ESP8266WiFi.h>
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.print("Setting soft-AP ... ");
boolean result = WiFi.softAP("ESPsoftAP_01", "pass-to-soft-AP");
if(result == true)
{
Serial.println("Ready");
}
else
{
Serial.println("Failed!");
}
}
void loop()
{
Serial.printf("Stations connected = %d\n", WiFi.softAPgetStationNum());
delay(3000);
}
```
### How to Use It?
In line `boolean result = WiFi.softAP("ESPsoftAP_01", "pass-to-soft-AP")` change `pass-to-soft-AP` to some meaningful password and upload sketch. Open serial monitor and you should see:
```
Setting soft-AP ... Ready
Stations connected = 0
Stations connected = 0
...
```
Then take your mobile phone or a PC, open the list of available access points, find ` ESPsoftAP_01 ` and connect to it. This should be reflected on serial monitor as a new station connected:
```
Stations connected = 1
Stations connected = 1
...
```
If you have another Wi-Fi station available then connect it as well. Check serial monitor again where you should now see two stations reported.
### How Does it Work?
Sketch is small so analysis shouldn't be difficult. In first line we are including ` ESP8266WiFi ` library:
```cpp
#include <ESP8266WiFi.h>
```
Setting up of the access point `ESPsoftAP_01` is done by executing:
```cpp
boolean result = WiFi.softAP("ESPsoftAP_01", "pass-to-soft-AP");
```
If this operation is successful then `result` will be `true` or `false` if otherwise. Basing on that either `Ready` or `Failed!` will be printed out by the following `if - else` conditional statement.
### Can we Make it Simpler?
Can we make this sketch even simpler? Yes, we can!
We can do it by using alternate `if - else` statement as below:
```cpp
WiFi.softAP("ESPsoftAP_01", "pass-to-soft-AP") ? "Ready" : "Failed!"
```
Such statement will return either `Ready` or `Failed!` depending on result of `WiFi.softAP(...)`. This way we can considerably shorten our sketch without any changes to functionality:
```cpp
#include <ESP8266WiFi.h>
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.print("Setting soft-AP ... ");
Serial.println(WiFi.softAP("ESPsoftAP_01", "pass-to-soft-AP") ? "Ready" : "Failed!");
}
void loop()
{
Serial.printf("Stations connected = %d\n", WiFi.softAPgetStationNum());
delay(3000);
}
```
I believe this is very neat piece of code. If `? :` conditional operator is new to you, I recommend to start using it and make your code shorter and more elegant.
### Conclusion
[ESP8266WiFi](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi) library makes it easy to turn ESP8266 into soft access point.
Once you try above sketch check out [WiFiAccessPoint.ino](https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiAccessPoint/WiFiAccessPoint.ino) as a next step. It demonstrates how to access ESP operating in soft-AP mode from a web browser.
For the list of functions to manage ESP module in soft-AP mode please refer to the [Soft Access Point Class :arrow_right:](soft-access-point-class.md) documentation.

125
doc/esp8266wifi/soft-access-point-examples.rst Normal file
View File

@ -0,0 +1,125 @@
:orphan:
Soft Access Point
-----------------
Example below presents how to configure ESP8266 to run in soft access point mode so Wi-Fi stations can connect to it. The Wi-Fi network established by the soft-AP will be identified with the SSID set during configuration. The network may be protected with a password. The network may be also open, if no password is set during configuration.
Table of Contents
-----------------
- `The Sketch <#the-sketch>`__
- `How to Use It? <#how-to-use-it>`__
- `How Does it Work? <#how-does-it-work>`__
- `Can we Make it Simpler? <#can-we-make-it-simpler>`__
- `Conclusion <#conclusion>`__
The Sketch
~~~~~~~~~~
Setting up soft-AP with ESP8266 can be done with just couple lines of code.
.. code:: cpp
#include <ESP8266WiFi.h>
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.print("Setting soft-AP ... ");
boolean result = WiFi.softAP("ESPsoftAP_01", "pass-to-soft-AP");
if(result == true)
{
Serial.println("Ready");
}
else
{
Serial.println("Failed!");
}
}
void loop()
{
Serial.printf("Stations connected = %d\n", WiFi.softAPgetStationNum());
delay(3000);
}
How to Use It?
~~~~~~~~~~~~~~
In line ``boolean result = WiFi.softAP("ESPsoftAP_01", "pass-to-soft-AP")`` change ``pass-to-soft-AP`` to some meaningful password and upload sketch. Open serial monitor and you should see:
::
Setting soft-AP ... Ready
Stations connected = 0
Stations connected = 0
...
Then take your mobile phone or a PC, open the list of available access points, find ``ESPsoftAP_01`` and connect to it. This should be reflected on serial monitor as a new station connected:
::
Stations connected = 1
Stations connected = 1
...
If you have another Wi-Fi station available then connect it as well. Check serial monitor again where you should now see two stations reported.
How Does it Work?
~~~~~~~~~~~~~~~~~
Sketch is small so analysis shouldn't be difficult. In first line we are including ``ESP8266WiFi`` library:
.. code:: cpp
#include <ESP8266WiFi.h>
Setting up of the access point ``ESPsoftAP_01`` is done by executing:
``cpp boolean result = WiFi.softAP("ESPsoftAP_01", "pass-to-soft-AP");``
If this operation is successful then ``result`` will be ``true`` or ``false`` if otherwise. Basing on that either ``Ready`` or ``Failed!`` will be printed out by the following ``if - else`` conditional statement.
Can we Make it Simpler?
~~~~~~~~~~~~~~~~~~~~~~~
Can we make this sketch even simpler? Yes, we can! We can do it by using alternate ``if - else`` statement as below:
.. code:: cpp
WiFi.softAP("ESPsoftAP_01", "pass-to-soft-AP") ? "Ready" : "Failed!"
Such statement will return either ``Ready`` or ``Failed!`` depending on result of ``WiFi.softAP(...)``. This way we can considerably shorten our sketch without any changes to functionality:
.. code:: cpp
#include <ESP8266WiFi.h>
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.print("Setting soft-AP ... ");
Serial.println(WiFi.softAP("ESPsoftAP_01", "pass-to-soft-AP") ? "Ready" : "Failed!");
}
void loop()
{
Serial.printf("Stations connected = %d\n", WiFi.softAPgetStationNum());
delay(3000);
}
I believe this is very neat piece of code. If ``? :`` conditional operator is new to you, I recommend to start using it and make your code shorter and more elegant.
Conclusion
~~~~~~~~~~
`ESP8266WiFi <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi>`__ library makes it easy to turn ESP8266 into soft access point.
Once you try above sketch check out `WiFiAccessPoint.ino <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiAccessPoint/WiFiAccessPoint.ino>`__ as a next step. It demonstrates how to access ESP operating in soft-AP mode from a web browser.
For the list of functions to manage ESP module in soft-AP mode please refer to the :doc:`Soft Access Point Class <soft-access-point-class>` documentation.

600
doc/esp8266wifi/station-class.md
View File

@ -1,600 +0,0 @@
---
title: ESP8266WiFi Station Class
---
[ESP8266WiFi Library :back:](readme.md#station)
## Station Class
The number of features provided by ESP8266 in the station mode is far more extensive than covered in original [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi). Therefore, instead of supplementing original documentation, we have decided to write a new one from scratch.
Description of station class has been broken down into four parts. First discusses methods to establish connection to an access point. Second provides methods to manage connection like e.g. `reconnect` or `isConnected`. Third covers properties to obtain information about connection like MAC or IP address. Finally the fourth section provides alternate methods to connect like e.g. Wi-Fi Protected Setup (WPS).
## Table of Contents
* [Start Here](#start-here)
* [begin](#begin)
* [config](#config)
* [Manage Connection](#manage-connection)
* [reconnect](#reconnect)
* [disconnect](#disconnect)
* [isConnected](#isconnected)
* [setAutoConnect](#setautoconnect)
* [getAutoConnect](#getautoconnect)
* [setAutoReconnect](#setautoreconnect)
* [waitForConnectResult](#waitforconnectresult)
* [Configuration](#configuration)
* [macAddress](#macAddress)
* [localIP](#localip)
* [subnetMask](#subnetmask)
* [gatewayIP](#gatewayip)
* [dnsIP](#dnsip)
* [hostname](#hostname)
* [status](#status)
* [SSID](#ssid)
* [psk](#psk)
* [BSSID](#bssid)
* [RSSI](#rssi)
* [Connect Different](#connect-different)
* [WPS](#wps)
* [Smart Config](#smart-config)
Points below provide description and code snippets how to use particular methods.
For more code samples please refer to separate section with [examples :arrow_right:](station-examples.md) dedicated specifically to the Station Class.
### Start Here
Switching the module to Station mode is done with `begin` function. Typical parameters passed to `begin` include SSID and password, so module can connect to specific Access Point.
```cpp
WiFi.begin(ssid, password)
```
By default, ESP will attempt to reconnect to Wi-Fi network whenever it is disconnected. There is no need to handle this by separate code. A good way to simulate disconnection would be to reset the access point. ESP will report disconnection, and then try to reconnect automatically.
#### begin
There are several version (called *[function overloads](https://en.wikipedia.org/wiki/Function_overloading)* in C++) of `begin` function. One was presented just above: `WiFi.begin(ssid, password)`. Overloads provide flexibility in number or type of accepted parameters.
The simplest overload of `begin` is as follows:
```cpp
WiFi.begin()
```
Calling it will instruct module to switch to the station mode and connect to the last used access point basing on configuration saved in flash memory.
Below is the syntax of another overload of `begin` with the all possible parameters:
```cpp
WiFi.begin(ssid, password, channel, bssid, connect)
```
Meaning of parameters is as follows:
* `ssid` - a character string containing the SSID of Access Point we would like to connect to, may have up to 32 characters
* `password` to the access point, a character string that should be minimum 8 characters long and not longer than 64 characters
* `channel` of AP, if we like to operate using specific channel, otherwise this parameter may be omitted
* `bssid` - mac address of AP, this parameter is also optional
* `connect` - a `boolean` parameter that if set to `false`, will instruct module just to save the other parameters without actually establishing connection to the access point
#### config
Disable [DHCP](https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol) client (Dynamic Host Configuration Protocol) and set the IP configuration of station interface to user defined arbitrary values. The interface will be a static IP configuration instead of values provided by DHCP.
```cpp
WiFi.config(local_ip, gateway, subnet, dns1, dns2)
```
Function will return `true` if configuration change is applied successfully. If configuration can not be applied, because e.g. module is not in station or station + soft access point mode, then `false` will be returned.
The following IP configuration may be provided:
* `local_ip` - enter here IP address you would like to assign the ESP station's interface
* `gateway` - should contain IP address of gateway (a router) to access external networks
* `subnet` - this is a mask that defines the range of IP addresses of the local network
* `dns1`, `dns2` - optional parameters that define IP addresses of Domain Name Servers (DNS) that maintain a directory of domain names (like e.g. *www.google.co.uk*) and translate them for us to IP addresses
*Example code:*
```cpp
#include <ESP8266WiFi.h>
const char* ssid = "********";
const char* password = "********";
IPAddress staticIP(192,168,1,22);
IPAddress gateway(192,168,1,9);
IPAddress subnet(255,255,255,0);
void setup(void)
{
Serial.begin(115200);
Serial.println();
Serial.printf("Connecting to %s\n", ssid);
WiFi.begin(ssid, password);
WiFi.config(staticIP, gateway, subnet);
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.println();
Serial.print("Connected, IP address: ");
Serial.println(WiFi.localIP());
}
void loop() {}
```
*Example output:*
```
Connecting to sensor-net
.
Connected, IP address: 192.168.1.22
```
Please note that station with static IP configuration usually connects to the network faster. In the above example it took about 500ms (one dot `.` displayed). This is because obtaining of IP configuration by DHCP client takes time and in this case this step is skipped. If you pass all three parameter as 0.0.0.0 ( local_ip, gateway and subnet), it will re enable DHCP. You need to re connect the device to get new IPs.
### Manage Connection
#### reconnect
Reconnect the station. This is done by disconnecting from the access point an then initiating connection back to the same AP.
```cpp
WiFi.reconnect()
```
Notes:
1. Station should be already connected to an access point. If this is not the case, then function will return `false` not performing any action.
2. If `true` is returned it means that connection sequence has been successfully started. User should still check for connection status, waiting until `WL_CONNECTED` is reported:
```cpp
WiFi.reconnect();
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
```
#### disconnect
Sets currently configured SSID and password to `null` values and disconnects the station from an access point.
```cpp
WiFi.disconnect(wifioff)
```
The `wifioff` is an optional `boolean` parameter. If set to `true`, then the station mode will be turned off.
#### isConnected
Returns `true` if Station is connected to an access point or `false` if not.
```cpp
WiFi.isConnected()
```
#### setAutoConnect
Configure module to automatically connect on power on to the last used access point.
```cpp
WiFi.setAutoConnect(autoConnect)
```
The `autoConnect` is an optional parameter. If set to `false` then auto connection functionality up will be disabled. If omitted or set to `true`, then auto connection will be enabled.
#### getAutoConnect
This is "companion" function to `setAutoConnect()`. It returns `true` if module is configured to automatically connect to last used access point on power on.
```cpp
WiFi.getAutoConnect()
```
If auto connection functionality is disabled, then function returns `false`.
#### setAutoReconnect
Set whether module will attempt to reconnect to an access point in case it is disconnected.
```cpp
WiFi.setAutoReconnect(autoReconnect)
```
If parameter `autoReconnect` is set to `true`, then module will try to reestablish lost connection to the AP. If set to `false` then module will stay disconnected.
Note: running `setAutoReconnect(true)` when module is already disconnected will not make it reconnect to the access point. Instead `reconnect()` should be used.
#### waitForConnectResult
Wait until module connects to the access point. This function is intended for module configured in station or station + soft access point mode.
```cpp
WiFi.waitForConnectResult()
```
Function returns one of the following connection statuses:
* `WL_CONNECTED` after successful connection is established
* `WL_NO_SSID_AVAIL`in case configured SSID cannot be reached
* `WL_CONNECT_FAILED` if password is incorrect
* `WL_IDLE_STATUS` when Wi-Fi is in process of changing between statuses
* `WL_DISCONNECTED` if module is not configured in station mode
### Configuration
#### macAddress
Get the MAC address of the ESP station's interface.
```cpp
WiFi.macAddress(mac)
```
Function should be provided with `mac` that is a pointer to memory location (an `uint8_t` array the size of 6 elements) to save the mac address. The same pointer value is returned by the function itself.
*Example code:*
```cpp
if (WiFi.status() == WL_CONNECTED)
{
uint8_t macAddr[6];
WiFi.macAddress(macAddr);
Serial.printf("Connected, mac address: %02x:%02x:%02x:%02x:%02x:%02x\n", macAddr[0], macAddr[1], macAddr[2], macAddr[3], macAddr[4], macAddr[5]);
}
```
*Example output:*
```
Mac address: 5C:CF:7F:08:11:17
```
If you do not feel comfortable with pointers, then there is optional version of this function available. Instead of the pointer, it returns a formatted `String` that contains the same mac address.
```cpp
WiFi.macAddress()
```
*Example code:*
```cpp
if (WiFi.status() == WL_CONNECTED)
{
Serial.printf("Connected, mac address: %s\n", WiFi.macAddress().c_str());
}
```
#### localIP
Function used to obtain IP address of ESP station's interface.
```cpp
WiFi.localIP()
```
The type of returned value is [IPAddress](https://github.com/esp8266/Arduino/blob/master/cores/esp8266/IPAddress.h). There is a couple of methods available to display this type of data. They are presented in examples below that cover description of `subnetMask`, `gatewayIP` and `dnsIP` that return the IPAdress as well.
*Example code:*
```cpp
if (WiFi.status() == WL_CONNECTED)
{
Serial.print("Connected, IP address: ");
Serial.println(WiFi.localIP());
}
```
*Example output:*
```
Connected, IP address: 192.168.1.10
```
#### subnetMask
Get the subnet mask of the station's interface.
```cpp
WiFi.subnetMask()
```
Module should be connected to the access point to obtain the subnet mask.
*Example code:*
```cpp
Serial.print("Subnet mask: ");
Serial.println(WiFi.subnetMask());
```
*Example output:*
```
Subnet mask: 255.255.255.0
```
#### gatewayIP
Get the IP address of the gateway.
```cpp
WiFi.gatewayIP()
```
*Example code:*
```cpp
Serial.printf("Gataway IP: %s\n", WiFi.gatewayIP().toString().c_str());
```
*Example output:*
```
Gataway IP: 192.168.1.9
```
#### dnsIP
Get the IP addresses of Domain Name Servers (DNS).
```cpp
WiFi.dnsIP(dns_no)
```
With the input parameter `dns_no` we can specify which Domain Name Server's IP we need. This parameter is zero based and allowed values are none, 0 or 1. If no parameter is provided, then IP of DNS #1 is returned.
*Example code:*
```cpp
Serial.print("DNS #1, #2 IP: ");
WiFi.dnsIP().printTo(Serial);
Serial.print(", ");
WiFi.dnsIP(1).printTo(Serial);
Serial.println();
```
*Example output:*
```
DNS #1, #2 IP: 62.179.1.60, 62.179.1.61
```
#### hostname
Get the DHCP hostname assigned to ESP station.
```cpp
WiFi.hostname()
```
Function returns `String` type. Default hostname is in format `ESP_24xMAC`where 24xMAC are the last 24 bits of module's MAC address.
The hostname may be changed using the following function:
```cpp
WiFi.hostname(aHostname)
```
Input parameter `aHostname` may be a type of `char*`, `const char*` or `String`. Maximum length of assigned hostname is 32 characters. Function returns either `true` or `false` depending on result. For instance, if the limit of 32 characters is exceeded, function will return `false` without assigning the new hostname.
*Example code:*
```cpp
Serial.printf("Default hostname: %s\n", WiFi.hostname().c_str());
WiFi.hostname("Station_Tester_02");
Serial.printf("New hostname: %s\n", WiFi.hostname().c_str());
```
*Example output:*
```
Default hostname: ESP_081117
New hostname: Station_Tester_02
```
#### status
Return the status of Wi-Fi connection.
```cpp
WiFi.status()
```
Function returns one of the following connection statuses:
* `WL_CONNECTED` after successful connection is established
* `WL_NO_SSID_AVAIL`in case configured SSID cannot be reached
* `WL_CONNECT_FAILED` if password is incorrect
* `WL_IDLE_STATUS` when Wi-Fi is in process of changing between statuses
* `WL_DISCONNECTED` if module is not configured in station mode
Returned value is type of `wl_status_t` defined in [wl_definitions.h](https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/src/include/wl_definitions.h)
*Example code:*
```cpp
#include <ESP8266WiFi.h>
void setup(void)
{
Serial.begin(115200);
Serial.printf("Connection status: %d\n", WiFi.status());
Serial.printf("Connecting to %s\n", ssid);
WiFi.begin(ssid, password);
Serial.printf("Connection status: %d\n", WiFi.status());
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.printf("\nConnection status: %d\n", WiFi.status());
Serial.print("Connected, IP address: ");
Serial.println(WiFi.localIP());
}
void loop() {}
```
*Example output:*
```
Connection status: 6
Connecting to sensor-net
Connection status: 6
......
Connection status: 3
Connected, IP address: 192.168.1.10
```
Particular connection statuses 6 and 3 may be looked up in [wl_definitions.h](https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/src/include/wl_definitions.h) as follows:
```
3 - WL_CONNECTED
6 - WL_DISCONNECTED
```
Basing on this example, when running above code, module is initially disconnected from the network and returns connection status `6 - WL_DISCONNECTED`. It is also disconnected immediately after running ` WiFi.begin(ssid, password)`. Then after about 3 seconds (basing on number of dots displayed every 500ms), it finally gets connected returning status `3 - WL_CONNECTED`.
#### SSID
Return the name of Wi-Fi network, formally called [Service Set Identification (SSID)](http://www.juniper.net/techpubs/en_US/network-director1.1/topics/concept/wireless-ssid-bssid-essid.html#jd0e34).
```cpp
WiFi.SSID()
```
Returned value is of the `String` type.
*Example code:*
```cpp
Serial.printf("SSID: %s\n", WiFi.SSID().c_str());
```
*Example output:*
```
SSID: sensor-net
```
#### psk
Return current pre shared key (password) associated with the Wi-Fi network.
```cpp
WiFi.psk()
```
Function returns value of the `String` type.
#### BSSID
Return the mac address the access point where ESP module is connected to. This address is formally called [Basic Service Set Identification (BSSID)](http://www.juniper.net/techpubs/en_US/network-director1.1/topics/concept/wireless-ssid-bssid-essid.html#jd0e47).
```cpp
WiFi.BSSID()
```
The `BSSID()` function returns a pointer to the memory location (an `uint8_t` array with the size of 6 elements) where the BSSID is saved.
Below is similar function, but returning BSSID but as a `String` type.
```cpp
WiFi.BSSIDstr()
```
*Example code:*
```cpp
Serial.printf("BSSID: %s\n", WiFi.BSSIDstr().c_str());
```
*Example output:*
```
BSSID: 00:1A:70:DE:C1:68
```
#### RSSI
Return the signal strength of Wi-Fi network, that is formally called [Received Signal Strength Indication (RSSI)](https://en.wikipedia.org/wiki/Received_signal_strength_indication).
```cpp
WiFi.RSSI()
```
Signal strength value is provided in dBm. The type of returned value is `int32_t`.
*Example code:*
```cpp
Serial.printf("RSSI: %d dBm\n", WiFi.RSSI());
```
*Example output:*
```
RSSI: -68 dBm
```
### Connect Different
[ESP8266 SDK](http://bbs.espressif.com/viewtopic.php?f=51&t=1023) provides alternate methods to connect ESP station to an access point. Out of them [esp8266 / Arduino](https://github.com/esp8266/Arduino) core implements [WPS](#wps) and [Smart Config](#smart-config) as described in more details below.
#### WPS
The following `beginWPSConfig` function allows connecting to a network using [Wi-Fi Protected Setup (WPS)](https://en.wikipedia.org/wiki/Wi-Fi_Protected_Setup). Currently only [push-button configuration](http://www.wi-fi.org/knowledge-center/faq/how-does-wi-fi-protected-setup-work) (`WPS_TYPE_PBC` mode) is supported (SDK 1.5.4).
```cpp
WiFi.beginWPSConfig()
```
Depending on connection result function returns either `true` or `false` (`boolean` type).
*Example code:*
```cpp
#include <ESP8266WiFi.h>
void setup(void)
{
Serial.begin(115200);
Serial.println();
Serial.printf("Wi-Fi mode set to WIFI_STA %s\n", WiFi.mode(WIFI_STA) ? "" : "Failed!");
Serial.print("Begin WPS (press WPS button on your router) ... ");
Serial.println(WiFi.beginWPSConfig() ? "Success" : "Failed");
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.println();
Serial.print("Connected, IP address: ");
Serial.println(WiFi.localIP());
}
void loop() {}
```
*Example output:*
```
Wi-Fi mode set to WIFI_STA
Begin WPS (press WPS button on your router) ... Success
.........
Connected, IP address: 192.168.1.102
```
#### Smart Config
The Smart Config connection of an ESP module an access point is done by sniffing for special packets that contain SSID and password of desired AP. To do so the mobile device or computer should have functionality of broadcasting of encoded SSID and password.
The following three functions are provided to implement Smart Config.
Start smart configuration mode by sniffing for special packets that contain SSID and password of desired Access Point. Depending on result either `true` or `false is returned.
```cpp
beginSmartConfig()
```
Query Smart Config status, to decide when stop configuration. Function returns either `true` or `false of `boolean` type.
```cpp
smartConfigDone()
```
Stop smart config, free the buffer taken by `beginSmartConfig()`. Depending on result function return either `true` or `false` of `boolean` type.
```cpp
stopSmartConfig()
```
For additional details regarding Smart Config please refer to [ESP8266 API User Guide](http://bbs.espressif.com/viewtopic.php?f=51&t=1023).

642
doc/esp8266wifi/station-class.rst Normal file
View File

@ -0,0 +1,642 @@
:orphan:
Station Class
-------------
The number of features provided by ESP8266 in the station mode is far more extensive than covered in original `Arduino WiFi library <https://www.arduino.cc/en/Reference/WiFi>`__. Therefore, instead of supplementing original documentation, we have decided to write a new one from scratch.
Description of station class has been broken down into four parts. First discusses methods to establish connection to an access point. Second provides methods to manage connection like e.g. ``reconnect`` or ``isConnected``. Third covers properties to obtain information about connection like MAC or IP address. Finally the fourth section provides alternate methods to connect like e.g. Wi-Fi Protected Setup (WPS).
Table of Contents
-----------------
- `Start Here <#start-here>`__
- `begin <#begin>`__
- `config <#config>`__
- `Manage Connection <#manage-connection>`__
- `reconnect <#reconnect>`__
- `disconnect <#disconnect>`__
- `isConnected <#isconnected>`__
- `setAutoConnect <#setautoconnect>`__
- `getAutoConnect <#getautoconnect>`__
- `setAutoReconnect <#setautoreconnect>`__
- `waitForConnectResult <#waitforconnectresult>`__
- `Configuration <#configuration>`__
- `macAddress <#macAddress>`__
- `localIP <#localip>`__
- `subnetMask <#subnetmask>`__
- `gatewayIP <#gatewayip>`__
- `dnsIP <#dnsip>`__
- `hostname <#hostname>`__
- `status <#status>`__
- `SSID <#ssid>`__
- `psk <#psk>`__
- `BSSID <#bssid>`__
- `RSSI <#rssi>`__
- `Connect Different <#connect-different>`__
- `WPS <#wps>`__
- `Smart Config <#smart-config>`__
Points below provide description and code snippets how to use particular methods.
For more code samples please refer to separate section with :doc:`examples <station-examples>` dedicated specifically to the Station Class.
Start Here
~~~~~~~~~~
Switching the module to Station mode is done with ``begin`` function. Typical parameters passed to ``begin`` include SSID and password, so module can connect to specific Access Point.
.. code:: cpp
WiFi.begin(ssid, password)
By default, ESP will attempt to reconnect to Wi-Fi network whenever it is disconnected. There is no need to handle this by separate code. A good way to simulate disconnection would be to reset the access point. ESP will report disconnection, and then try to reconnect automatically.
begin
^^^^^
There are several versions (called *`function overloads <https://en.wikipedia.org/wiki/Function_overloading>`__* in C++) of ``begin`` function. One was presented just above:
``WiFi.begin(ssid, password)``. Overloads provide flexibility in number or type of accepted parameters.
The simplest overload of ``begin`` is as follows:
.. code:: cpp
WiFi.begin()
Calling it will instruct module to switch to the station mode and connect to the last used access point basing on configuration saved in flash memory.
Below is the syntax of another overload of ``begin`` with the all possible parameters:
.. code:: cpp
WiFi.begin(ssid, password, channel, bssid, connect)
Meaning of parameters is as follows: \* ``ssid`` - a character string containing the SSID of Access Point we would like to connect to, may have up to 32 characters \* ``password`` to the access point, a character string that should be minimum 8 characters long and not longer than 64 characters \* ``channel`` of AP, if we like to operate using specific channel, otherwise this parameter may be omitted \* ``bssid`` -
mac address of AP, this parameter is also optional \* ``connect`` - a ``boolean`` parameter that if set to ``false``, will instruct module just to save the other parameters without actually establishing connection to the access point
config
^^^^^^
Disable `DHCP <https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol>`__ client (Dynamic Host Configuration Protocol) and set the IP configuration of station interface to user defined arbitrary values. The interface will be a static IP configuration instead of values provided by DHCP.
.. code:: cpp
WiFi.config(local_ip, gateway, subnet, dns1, dns2)
Function will return ``true`` if configuration change is applied successfully. If configuration can not be applied, because e.g. module is not in station or station + soft access point mode, then ``false`` will be returned.
The following IP configuration may be provided:
- ``local_ip`` - enter here IP address you would like to assign the ESP
station's interface
- ``gateway`` - should contain IP address of gateway (a router) to
access external networks
- ``subnet`` - this is a mask that defines the range of IP addresses of
the local network
- ``dns1``, ``dns2`` - optional parameters that define IP addresses of
Domain Name Servers (DNS) that maintain a directory of domain names
(like e.g. *www.google.co.uk*) and translate them for us to IP
addresses
*Example code:*
.. code:: cpp
#include <ESP8266WiFi.h>
const char* ssid = "********";
const char* password = "********";
IPAddress staticIP(192,168,1,22);
IPAddress gateway(192,168,1,9);
IPAddress subnet(255,255,255,0);
void setup(void)
{
Serial.begin(115200);
Serial.println();
Serial.printf("Connecting to %s\n", ssid);
WiFi.begin(ssid, password);
WiFi.config(staticIP, gateway, subnet);
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.println();
Serial.print("Connected, IP address: ");
Serial.println(WiFi.localIP());
}
void loop() {}
*Example output:*
::
Connecting to sensor-net
.
Connected, IP address: 192.168.1.22
Please note that station with static IP configuration usually connects to the network faster. In the above example it took about 500ms (one dot `.` displayed). This is because obtaining of IP configuration by DHCP client takes time and in this case this step is skipped. If you pass all three parameter as 0.0.0.0 (local_ip, gateway and subnet), it will re enable DHCP. You need to re-connect the device to get new IPs.
Manage Connection
~~~~~~~~~~~~~~~~~
reconnect
^^^^^^^^^
Reconnect the station. This is done by disconnecting from the access point an then initiating connection back to the same AP.
.. code:: cpp
WiFi.reconnect()
Notes: 1. Station should be already connected to an access point. If this is not the case, then function will return ``false`` not performing any action. 2. If ``true`` is returned it means that connection sequence has been successfully started. User should still check for connection status, waiting until ``WL_CONNECTED`` is reported:
.. code:: cpp
WiFi.reconnect();
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
disconnect
^^^^^^^^^^
Sets currently configured SSID and password to ``null`` values and disconnects the station from an access point.
.. code:: cpp
WiFi.disconnect(wifioff)
The ``wifioff`` is an optional ``boolean`` parameter. If set to ``true``, then the station mode will be turned off.
isConnected
^^^^^^^^^^^
Returns ``true`` if Station is connected to an access point or ``false`` if not.
.. code:: cpp
WiFi.isConnected()
setAutoConnect
^^^^^^^^^^^^^^
Configure module to automatically connect on power on to the last used access point.
.. code:: cpp
WiFi.setAutoConnect(autoConnect)
The ``autoConnect`` is an optional parameter. If set to ``false`` then auto connection functionality up will be disabled. If omitted or set to ``true``, then auto connection will be enabled.
getAutoConnect
^^^^^^^^^^^^^^
This is "companion" function to ``setAutoConnect()``. It returns ``true`` if module is configured to automatically connect to last used access point on power on.
.. code:: cpp
WiFi.getAutoConnect()
If auto connection functionality is disabled, then function returns ``false``.
setAutoReconnect
^^^^^^^^^^^^^^^^
Set whether module will attempt to reconnect to an access point in case it is disconnected.
.. code:: cpp
WiFi.setAutoReconnect(autoReconnect)
If parameter ``autoReconnect`` is set to ``true``, then module will try to reestablish lost connection to the AP. If set to ``false`` then module will stay disconnected.
Note: running ``setAutoReconnect(true)`` when module is already disconnected will not make it reconnect to the access point. Instead ``reconnect()`` should be used.
waitForConnectResult
^^^^^^^^^^^^^^^^^^^^
Wait until module connects to the access point. This function is intended for module configured in station or station + soft access point mode.
.. code:: cpp
WiFi.waitForConnectResult()
Function returns one of the following connection statuses: \* ``WL_CONNECTED`` after successful connection is established \* ``WL_NO_SSID_AVAIL``\ in case configured SSID cannot be reached \* ``WL_CONNECT_FAILED`` if password is incorrect \* ``WL_IDLE_STATUS`` when Wi-Fi is in process of changing between statuses \* ``WL_DISCONNECTED`` if module is not configured in station mode
Configuration
~~~~~~~~~~~~~
macAddress
^^^^^^^^^^
Get the MAC address of the ESP station's interface.
.. code:: cpp
WiFi.macAddress(mac)
Function should be provided with ``mac`` that is a pointer to memory location (an ``uint8_t`` array the size of 6 elements) to save the mac address. The same pointer value is returned by the function itself.
*Example code:*
.. code:: cpp
if (WiFi.status() == WL_CONNECTED)
{
uint8_t macAddr[6];
WiFi.macAddress(macAddr);
Serial.printf("Connected, mac address: %02x:%02x:%02x:%02x:%02x:%02x\n", macAddr[0], macAddr[1], macAddr[2], macAddr[3], macAddr[4], macAddr[5]);
}
*Example output:*
::
Mac address: 5C:CF:7F:08:11:17
If you do not feel comfortable with pointers, then there is optional version of this function available. Instead of the pointer, it returns a formatted ``String`` that contains the same mac address.
.. code:: cpp
WiFi.macAddress()
*Example code:*
.. code:: cpp
if (WiFi.status() == WL_CONNECTED)
{
Serial.printf("Connected, mac address: %s\n", WiFi.macAddress().c_str());
}
localIP
^^^^^^^
Function used to obtain IP address of ESP station's interface.
.. code:: cpp
WiFi.localIP()
The type of returned value is `IPAddress <https://github.com/esp8266/Arduino/blob/master/cores/esp8266/IPAddress.h>`__. There is a couple of methods available to display this type of data. They are presented in examples below that cover description of ``subnetMask``, ``gatewayIP`` and ``dnsIP`` that return the IPAdress as well.
*Example code:*
.. code:: cpp
if (WiFi.status() == WL_CONNECTED)
{
Serial.print("Connected, IP address: ");
Serial.println(WiFi.localIP());
}
*Example output:*
::
Connected, IP address: 192.168.1.10
subnetMask
^^^^^^^^^^
Get the subnet mask of the station's interface.
.. code:: cpp
WiFi.subnetMask()
Module should be connected to the access point to obtain the subnet mask.
*Example code:*
.. code:: cpp
Serial.print("Subnet mask: ");
Serial.println(WiFi.subnetMask());
*Example output:*
::
Subnet mask: 255.255.255.0
gatewayIP
^^^^^^^^^
Get the IP address of the gateway.
.. code:: cpp
WiFi.gatewayIP()
*Example code:*
.. code:: cpp
Serial.printf("Gataway IP: %s\n", WiFi.gatewayIP().toString().c_str());
*Example output:*
::
Gataway IP: 192.168.1.9
dnsIP
^^^^^
Get the IP addresses of Domain Name Servers (DNS).
.. code:: cpp
WiFi.dnsIP(dns_no)
With the input parameter ``dns_no`` we can specify which Domain Name Server's IP we need. This parameter is zero based and allowed values are none, 0 or 1. If no parameter is provided, then IP of DNS #1 is returned.
*Example code:*
.. code:: cpp
Serial.print("DNS #1, #2 IP: ");
WiFi.dnsIP().printTo(Serial);
Serial.print(", ");
WiFi.dnsIP(1).printTo(Serial);
Serial.println();
*Example output:*
::
DNS #1, #2 IP: 62.179.1.60, 62.179.1.61
hostname
^^^^^^^^
Get the DHCP hostname assigned to ESP station.
.. code:: cpp
WiFi.hostname()
Function returns ``String`` type. Default hostname is in format ``ESP_24xMAC``\ where 24xMAC are the last 24 bits of module's MAC address.
The hostname may be changed using the following function:
.. code:: cpp
WiFi.hostname(aHostname)
Input parameter ``aHostname`` may be a type of ``char*``, ``const char*`` or ``String``. Maximum length of assigned hostname is 32 characters. Function returns either ``true`` or ``false`` depending on result. For instance, if the limit of 32 characters is exceeded, function will return ``false`` without assigning the new hostname.
*Example code:*
.. code:: cpp
Serial.printf("Default hostname: %s\n", WiFi.hostname().c_str());
WiFi.hostname("Station_Tester_02");
Serial.printf("New hostname: %s\n", WiFi.hostname().c_str());
*Example output:*
::
Default hostname: ESP_081117
New hostname: Station_Tester_02
status
^^^^^^
Return the status of Wi-Fi connection.
.. code:: cpp
WiFi.status()
Function returns one of the following connection statuses: \* ``WL_CONNECTED`` after successful connection is established \* ``WL_NO_SSID_AVAIL``\ in case configured SSID cannot be reached \* ``WL_CONNECT_FAILED`` if password is incorrect \* ``WL_IDLE_STATUS`` when Wi-Fi is in process of changing between statuses \* ``WL_DISCONNECTED`` if module is not configured in station mode
Returned value is type of ``wl_status_t`` defined in `wl\_definitions.h <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/src/include/wl_definitions.h>`__
*Example code:*
.. code:: cpp
#include <ESP8266WiFi.h>
void setup(void)
{
Serial.begin(115200);
Serial.printf("Connection status: %d\n", WiFi.status());
Serial.printf("Connecting to %s\n", ssid);
WiFi.begin(ssid, password);
Serial.printf("Connection status: %d\n", WiFi.status());
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.printf("\nConnection status: %d\n", WiFi.status());
Serial.print("Connected, IP address: ");
Serial.println(WiFi.localIP());
}
void loop() {}
*Example output:*
::
Connection status: 6
Connecting to sensor-net
Connection status: 6
......
Connection status: 3
Connected, IP address: 192.168.1.10
Particular connection statuses 6 and 3 may be looked up in `wl\_definitions.h <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/src/include/wl_definitions.h>`__ as follows:
::
3 - WL_CONNECTED
6 - WL_DISCONNECTED
Basing on this example, when running above code, module is initially disconnected from the network and returns connection status ``6 - WL_DISCONNECTED``. It is also disconnected immediately after running ``WiFi.begin(ssid, password)``. Then after about 3 seconds (basing on number of dots displayed every 500ms), it finally gets connected returning status ``3 - WL_CONNECTED``.
SSID
^^^^
Return the name of Wi-Fi network, formally called `Service Set Identification (SSID) <http://www.juniper.net/techpubs/en_US/network-director1.1/topics/concept/wireless-ssid-bssid-essid.html#jd0e34>`__.
.. code:: cpp
WiFi.SSID()
Returned value is of the ``String`` type.
*Example code:*
.. code:: cpp
Serial.printf("SSID: %s\n", WiFi.SSID().c_str());
*Example output:*
::
SSID: sensor-net
psk
^^^
Return current pre shared key (password) associated with the Wi-Fi network.
.. code:: cpp
WiFi.psk()
Function returns value of the ``String`` type.
BSSID
^^^^^
Return the mac address the access point where ESP module is connected to. This address is formally called `Basic Service Set Identification (BSSID) <http://www.juniper.net/techpubs/en_US/network-director1.1/topics/concept/wireless-ssid-bssid-essid.html#jd0e47>`__.
.. code:: cpp
WiFi.BSSID()
The ``BSSID()`` function returns a pointer to the memory location (an ``uint8_t`` array with the size of 6 elements) where the BSSID is saved.
Below is similar function, but returning BSSID but as a ``String`` type.
.. code:: cpp
WiFi.BSSIDstr()
*Example code:*
.. code:: cpp
Serial.printf("BSSID: %s\n", WiFi.BSSIDstr().c_str());
*Example output:*
::
BSSID: 00:1A:70:DE:C1:68
RSSI
^^^^
Return the signal strength of Wi-Fi network, that is formally called `Received Signal Strength Indication (RSSI) <https://en.wikipedia.org/wiki/Received_signal_strength_indication>`__.
.. code:: cpp
WiFi.RSSI()
Signal strength value is provided in dBm. The type of returned value is ``int32_t``.
*Example code:*
.. code:: cpp
Serial.printf("RSSI: %d dBm\n", WiFi.RSSI());
*Example output:*
::
RSSI: -68 dBm
Connect Different
~~~~~~~~~~~~~~~~~
`ESP8266 SDK <http://bbs.espressif.com/viewtopic.php?f=51&t=1023>`__ provides alternate methods to connect ESP station to an access point. Out of them `esp8266 / Arduino <https://github.com/esp8266/Arduino>`__ core implements `WPS <#wps>`__ and `Smart Config <#smart-config>`__ as described in more details below.
WPS
^^^
The following ``beginWPSConfig`` function allows connecting to a network using `Wi-Fi Protected Setup (WPS) <https://en.wikipedia.org/wiki/Wi-Fi_Protected_Setup>`__. Currently only `push-button configuration <http://www.wi-fi.org/knowledge-center/faq/how-does-wi-fi-protected-setup-work>`__ (``WPS_TYPE_PBC`` mode) is supported (SDK 1.5.4).
.. code:: cpp
WiFi.beginWPSConfig()
Depending on connection result function returns either ``true`` or ``false`` (``boolean`` type).
*Example code:*
.. code:: cpp
#include <ESP8266WiFi.h>
void setup(void)
{
Serial.begin(115200);
Serial.println();
Serial.printf("Wi-Fi mode set to WIFI_STA %s\n", WiFi.mode(WIFI_STA) ? "" : "Failed!");
Serial.print("Begin WPS (press WPS button on your router) ... ");
Serial.println(WiFi.beginWPSConfig() ? "Success" : "Failed");
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.println();
Serial.print("Connected, IP address: ");
Serial.println(WiFi.localIP());
}
void loop() {}
*Example output:*
::
Wi-Fi mode set to WIFI_STA
Begin WPS (press WPS button on your router) ... Success
.........
Connected, IP address: 192.168.1.102
Smart Config
^^^^^^^^^^^^
The Smart Config connection of an ESP module an access point is done by sniffing for special packets that contain SSID and password of desired AP. To do so the mobile device or computer should have functionality of broadcasting of encoded SSID and password.
The following three functions are provided to implement Smart Config.
Start smart configuration mode by sniffing for special packets that contain SSID and password of desired Access Point. Depending on result either ``true`` or \`false is returned.
.. code:: cpp
beginSmartConfig()
Query Smart Config status, to decide when stop configuration. Function returns either ``true`` or ``false of``\ boolean\` type.
.. code:: cpp
smartConfigDone()
Stop smart config, free the buffer taken by ``beginSmartConfig()``. Depending on result function return either ``true`` or ``false`` of ``boolean`` type.
.. code:: cpp
stopSmartConfig()
For additional details regarding Smart Config please refer to `ESP8266 API User Guide <http://bbs.espressif.com/viewtopic.php?f=51&t=1023>`__.

205
doc/esp8266wifi/station-examples.md
View File

@ -1,205 +0,0 @@
---
title: ESP8266WiFi Station Class - Sketch Examples
---
[ESP8266WiFi Library :back:](readme.md#station)
## Station
Example of connecting to an access point has been shown in chapter [Quick Start](readme.md#quick-start). In case connection is lost, ESP8266 will automatically reconnect to the last used access point, once it is again available.
Can we provide more robust connection to Wi-Fi than that?
## Table of Contents
* [Introduction](#introduction)
* [Prepare Access Points](#prepare-access-points)
* [Try it Out](#try-it-out)
* [Can we Make it Simpler?](#can-we-make-it-simpler)
* [Conclusion](#conclusion)
### Introduction
Following the example in[Quick Start](readme.md#quick-start), we would like to go one step further and made ESP connect to next available access point if current connection is lost. This functionality is provided with 'ESP8266WiFiMulti' class and demonstrated in sketch below.
```cpp
#include <ESP8266WiFi.h>
#include <ESP8266WiFiMulti.h>
ESP8266WiFiMulti wifiMulti;
boolean connectioWasAlive = true;
void setup()
{
Serial.begin(115200);
Serial.println();
wifiMulti.addAP("primary-network-name", "pass-to-primary-network");
wifiMulti.addAP("secondary-network-name", "pass-to-secondary-network");
wifiMulti.addAP("tertiary-network-name", "pass-to-tertiary-network");
}
void monitorWiFi()
{
if (wifiMulti.run() != WL_CONNECTED)
{
if (connectioWasAlive == true)
{
connectioWasAlive = false;
Serial.print("Looking for WiFi ");
}
Serial.print(".");
delay(500);
}
else if (connectioWasAlive == false)
{
connectioWasAlive = true;
Serial.printf(" connected to %s\n", WiFi.SSID().c_str());
}
}
void loop()
{
monitorWiFi();
}
```
### Prepare Access Points
To try this sketch in action you need two (or more) access points. In lines below replace `primary-network-name` and `pass-to-primary-network` with name and password to your primary network. Do the same for secondary network.
```cpp
wifiMulti.addAP("primary-network-name", "pass-to-primary-network");
wifiMulti.addAP("secondary-network-name", "pass-to-secondary-network");
```
You may add more networks if you have more access points.
```cpp
wifiMulti.addAP("tertiary-network-name", "pass-to-tertiary-network");
...
```
### Try it Out
Now upload updated sketch to ESP module and open serial monitor. Module will first scan for available networks. Then it will select and connect to the network with stronger signal. In case connection is lost, module will connect to next one available.
This process may look something like:
```
Looking for WiFi ..... connected to sensor-net-1
Looking for WiFi ....... connected to sensor-net-2
Looking for WiFi .... connected to sensor-net-1
```
In above example ESP connected first to `sensor-net-1`. Then I have switched `sensor-net-1` off. ESP discovered that connection is lost and started searching for another configured network. That happened to be `sensor-net-2` so ESP connected to it. Then I have switched `sensor-net-1` back on and shut down `sensor-net-2`. ESP reconnected automatically to `sensor-net-1`.
Function `monitorWiFi()` is in place to show when connection is lost by displaying `Looking for WiFi`. Dots ` ....` are displayed during process of searching for another configured access point. Then a message like `connected to sensor-net-2` is shown when connection is established.
### Can we Make it Simpler?
Please note that you may simplify this sketch by removing function `monitorWiFi()` and putting inside `loop()` only `wifiMulti.run()`. ESP will still reconnect between configured access points if required. Now you won't be able to see it on serial monitor unless you add `Serial.setDebugOutput(true)` as described in point [Enable Wi-Fi Diagnostic](readme.md#enable-wi-fi-diagnostic).
Updated sketch for such scenario will look as follows:
```cpp
#include <ESP8266WiFi.h>
#include <ESP8266WiFiMulti.h>
ESP8266WiFiMulti wifiMulti;
void setup()
{
Serial.begin(115200);
Serial.setDebugOutput(true);
Serial.println();
wifiMulti.addAP("primary-network-name", "pass-to-primary-network");
wifiMulti.addAP("secondary-network-name", "pass-to-secondary-network");
wifiMulti.addAP("tertiary-network-name", "pass-to-tertiary-network");
}
void loop()
{
wifiMulti.run();
}
```
That's it! This is really all the code you need to make ESP automatically reconnecting between available networks.
After uploading sketch and opening the serial monitor, the messages will look as below.
*Initial connection to sensor-net-1 on power up:*
```
f r0, scandone
f r0, scandone
state: 0 -> 2 (b0)
state: 2 -> 3 (0)
state: 3 -> 5 (10)
add 0
aid 1
cnt
chg_B1:-40
connected with sensor-net-1, channel 1
dhcp client start...
ip:192.168.1.10,mask:255.255.255.0,gw:192.168.1.9
```
*Lost connection to sensor-net-1 and establishing connection to sensor-net-2:*
```
bcn_timout,ap_probe_send_start
ap_probe_send over, rest wifi status to disassoc
state: 5 -> 0 (1)
rm 0
f r-40, scandone
f r-40, scandone
f r-40, scandone
state: 0 -> 2 (b0)
state: 2 -> 3 (0)
state: 3 -> 5 (10)
add 0
aid 1
cnt
connected with sensor-net-2, channel 11
dhcp client start...
ip:192.168.1.102,mask:255.255.255.0,gw:192.168.1.234
```
*Lost connection to sensor-net-2 and establishing connection back to sensor-net-1:*
```
bcn_timout,ap_probe_send_start
ap_probe_send over, rest wifi status to disassoc
state: 5 -> 0 (1)
rm 0
f r-40, scandone
f r-40, scandone
f r-40, scandone
state: 0 -> 2 (b0)
state: 2 -> 3 (0)
state: 3 -> 5 (10)
add 0
aid 1
cnt
connected with sensor-net-1, channel 6
dhcp client start...
ip:192.168.1.10,mask:255.255.255.0,gw:192.168.1.9
```
### Conclusion
I believe the minimalist sketch with `ESP8266WiFiMulti` class is a cool example what ESP8266 can do for us behind the scenes with just couple lines of code.
As shown in above example, reconnecting between access points takes time and is not seamless. Therefore, in practical applications, you will likely need to monitor connection status to decide e.g. if you can send the data to external system or should wait until connection is back.
For detailed review of functions provided to manage station mode please refer to the [Station Class :arrow_right:](station-class.md) documentation.

205
doc/esp8266wifi/station-examples.rst Normal file
View File

@ -0,0 +1,205 @@
:orphan:
Station
-------
Example of connecting to an access point has been shown in chapter `Quick Start <readme.md#quick-start>`__. In case connection is lost, ESP8266 will automatically reconnect to the last used access point, once it is again available.
Can we provide more robust connection to Wi-Fi than that?
Table of Contents
-----------------
- `Introduction <#introduction>`__
- `Prepare Access Points <#prepare-access-points>`__
- `Try it Out <#try-it-out>`__
- `Can we Make it Simpler? <#can-we-make-it-simpler>`__
- `Conclusion <#conclusion>`__
Introduction
~~~~~~~~~~~~
Following the example in\ `Quick Start <readme.md#quick-start>`__, we would like to go one step further and made ESP connect to next available access point if current connection is lost. This functionality is provided with 'ESP8266WiFiMulti' class and demonstrated in sketch below.
.. code:: cpp
#include <ESP8266WiFi.h>
#include <ESP8266WiFiMulti.h>
ESP8266WiFiMulti wifiMulti;
boolean connectioWasAlive = true;
void setup()
{
Serial.begin(115200);
Serial.println();
wifiMulti.addAP("primary-network-name", "pass-to-primary-network");
wifiMulti.addAP("secondary-network-name", "pass-to-secondary-network");
wifiMulti.addAP("tertiary-network-name", "pass-to-tertiary-network");
}
void monitorWiFi()
{
if (wifiMulti.run() != WL_CONNECTED)
{
if (connectioWasAlive == true)
{
connectioWasAlive = false;
Serial.print("Looking for WiFi ");
}
Serial.print(".");
delay(500);
}
else if (connectioWasAlive == false)
{
connectioWasAlive = true;
Serial.printf(" connected to %s\n", WiFi.SSID().c_str());
}
}
void loop()
{
monitorWiFi();
}
Prepare Access Points
~~~~~~~~~~~~~~~~~~~~~
To try this sketch in action you need two (or more) access points. In lines below replace ``primary-network-name`` and ``pass-to-primary-network`` with name and password to your primary network. Do the same for secondary network.
.. code:: cpp
wifiMulti.addAP("primary-network-name", "pass-to-primary-network");
wifiMulti.addAP("secondary-network-name", "pass-to-secondary-network");
You may add more networks if you have more access points.
.. code:: cpp
wifiMulti.addAP("tertiary-network-name", "pass-to-tertiary-network");
...
Try it Out
~~~~~~~~~~
Now upload updated sketch to ESP module and open serial monitor. Module will first scan for available networks. Then it will select and connect to the network with stronger signal. In case connection is lost, module will connect to next one available.
This process may look something like:
::
Looking for WiFi ..... connected to sensor-net-1
Looking for WiFi ....... connected to sensor-net-2
Looking for WiFi .... connected to sensor-net-1
In above example ESP connected first to ``sensor-net-1``. Then I have switched ``sensor-net-1`` off. ESP discovered that connection is lost and started searching for another configured network. That happened to be ``sensor-net-2`` so ESP connected to it. Then I have switched ``sensor-net-1`` back on and shut down ``sensor-net-2``. ESP reconnected automatically to ``sensor-net-1``.
Function ``monitorWiFi()`` is in place to show when connection is lost by displaying ``Looking for WiFi``. Dots ``....`` are displayed during process of searching for another configured access point. Then a message like ``connected to sensor-net-2`` is shown when connection is established.
Can we Make it Simpler?
~~~~~~~~~~~~~~~~~~~~~~~
Please note that you may simplify this sketch by removing function ``monitorWiFi()`` and putting inside ``loop()`` only ``wifiMulti.run()``. ESP will still reconnect between configured access points if required. Now you won't be able to see it on serial monitor unless you add ``Serial.setDebugOutput(true)`` as described in point `Enable Wi-Fi Diagnostic <readme.md#enable-wi-fi-diagnostic>`__.
Updated sketch for such scenario will look as follows:
.. code:: cpp
#include <ESP8266WiFi.h>
#include <ESP8266WiFiMulti.h>
ESP8266WiFiMulti wifiMulti;
void setup()
{
Serial.begin(115200);
Serial.setDebugOutput(true);
Serial.println();
wifiMulti.addAP("primary-network-name", "pass-to-primary-network");
wifiMulti.addAP("secondary-network-name", "pass-to-secondary-network");
wifiMulti.addAP("tertiary-network-name", "pass-to-tertiary-network");
}
void loop()
{
wifiMulti.run();
}
That's it! This is really all the code you need to make ESP automatically reconnecting between available networks.
After uploading sketch and opening the serial monitor, the messages will look as below.
*Initial connection to sensor-net-1 on power up:*
::
f r0, scandone
f r0, scandone
state: 0 -> 2 (b0)
state: 2 -> 3 (0)
state: 3 -> 5 (10)
add 0
aid 1
cnt
chg_B1:-40
connected with sensor-net-1, channel 1
dhcp client start...
ip:192.168.1.10,mask:255.255.255.0,gw:192.168.1.9
*Lost connection to sensor-net-1 and establishing connection to sensor-net-2:*
::
bcn_timout,ap_probe_send_start
ap_probe_send over, rest wifi status to disassoc
state: 5 -> 0 (1)
rm 0
f r-40, scandone
f r-40, scandone
f r-40, scandone
state: 0 -> 2 (b0)
state: 2 -> 3 (0)
state: 3 -> 5 (10)
add 0
aid 1
cnt
connected with sensor-net-2, channel 11
dhcp client start...
ip:192.168.1.102,mask:255.255.255.0,gw:192.168.1.234
*Lost connection to sensor-net-2 and establishing connection back to sensor-net-1:*
::
bcn_timout,ap_probe_send_start
ap_probe_send over, rest wifi status to disassoc
state: 5 -> 0 (1)
rm 0
f r-40, scandone
f r-40, scandone
f r-40, scandone
state: 0 -> 2 (b0)
state: 2 -> 3 (0)
state: 3 -> 5 (10)
add 0
aid 1
cnt
connected with sensor-net-1, channel 6
dhcp client start...
ip:192.168.1.10,mask:255.255.255.0,gw:192.168.1.9
Conclusion
~~~~~~~~~~
I believe the minimalist sketch with ``ESP8266WiFiMulti`` class is a cool example what ESP8266 can do for us behind the scenes with just couple lines of code.
As shown in above example, reconnecting between access points takes time and is not seamless. Therefore, in practical applications, you will likely need to monitor connection status to decide e.g. if you can send the data to external system or should wait until connection is back.
For detailed review of functions provided to manage station mode please refer to the :doc:`Station Class <station-class>` documentation.

41
doc/esp8266wifi/udp-class.md
View File

@ -1,41 +0,0 @@
---
title: ESP8266WiFi UDP Class
---
[ESP8266WiFi Library :back:](readme.md#udp)
## UDP Class
Methods documented for [WiFiUDP Class](https://www.arduino.cc/en/Reference/WiFiUDPConstructor) in [Arduino](https://github.com/arduino/Arduino)
1. [begin()](https://www.arduino.cc/en/Reference/WiFiUDPBegin)
2. [available()](https://www.arduino.cc/en/Reference/WiFiUDPAvailable)
3. [beginPacket()](https://www.arduino.cc/en/Reference/WiFiUDPBeginPacket)
4. [endPacket()](https://www.arduino.cc/en/Reference/WiFiUDPEndPacket)
5. [write()](https://www.arduino.cc/en/Reference/WiFiUDPWrite)
6. [parsePacket()](https://www.arduino.cc/en/Reference/WiFiUDPParsePacket)
7. [peek()](https://www.arduino.cc/en/Reference/WiFiUDPPeek)
8. [read()](https://www.arduino.cc/en/Reference/WiFiUDPRead)
9. [flush()](https://www.arduino.cc/en/Reference/WiFiUDPFlush)
10. [stop()](https://www.arduino.cc/en/Reference/WiFIUDPStop)
11. [remoteIP()](https://www.arduino.cc/en/Reference/WiFiUDPRemoteIP)
12. [remotePort()](https://www.arduino.cc/en/Reference/WiFiUDPRemotePort)
Methods and properties described further down are specific to ESP8266. They are not covered in [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi) documentation. Before they are fully documented please refer to information below.
### Multicast UDP
```cpp
uint8_t beginMulticast (IPAddress interfaceAddr, IPAddress multicast, uint16_t port)
virtual int beginPacketMulticast (IPAddress multicastAddress, uint16_t port, IPAddress interfaceAddress, int ttl=1)
IPAddress destinationIP ()
uint16_t localPort ()
```
The `WiFiUDP` class supports sending and receiving multicast packets on STA interface. When sending a multicast packet, replace `udp.beginPacket(addr, port)` with `udp.beginPacketMulticast(addr, port, WiFi.localIP())`. When listening to multicast packets, replace `udp.begin(port)` with `udp.beginMulticast(WiFi.localIP(), multicast_ip_addr, port)`. You can use `udp.destinationIP()` to tell whether the packet received was sent to the multicast or unicast address.
For code samples please refer to separate section with [examples :arrow_right:](udp-examples.md) dedicated specifically to the UDP Class.

36
doc/esp8266wifi/udp-class.rst Normal file
View File

@ -0,0 +1,36 @@
:orphan:
UDP Class
---------
Methods documented for `WiFiUDP Class <https://www.arduino.cc/en/Reference/WiFiUDPConstructor>`__ in `Arduino <https://github.com/arduino/Arduino>`__
1. `begin() <https://www.arduino.cc/en/Reference/WiFiUDPBegin>`__
2. `available() <https://www.arduino.cc/en/Reference/WiFiUDPAvailable>`__
3. `beginPacket() <https://www.arduino.cc/en/Reference/WiFiUDPBeginPacket>`__
4. `endPacket() <https://www.arduino.cc/en/Reference/WiFiUDPEndPacket>`__
5. `write() <https://www.arduino.cc/en/Reference/WiFiUDPWrite>`__
6. `parsePacket() <https://www.arduino.cc/en/Reference/WiFiUDPParsePacket>`__
7. `peek() <https://www.arduino.cc/en/Reference/WiFiUDPPeek>`__
8. `read() <https://www.arduino.cc/en/Reference/WiFiUDPRead>`__
9. `flush() <https://www.arduino.cc/en/Reference/WiFiUDPFlush>`__
10. `stop() <https://www.arduino.cc/en/Reference/WiFIUDPStop>`__
11. `remoteIP() <https://www.arduino.cc/en/Reference/WiFiUDPRemoteIP>`__
12. `remotePort() <https://www.arduino.cc/en/Reference/WiFiUDPRemotePort>`__
Methods and properties described further down are specific to ESP8266.
They are not covered in `Arduino WiFi library <https://www.arduino.cc/en/Reference/WiFi>`__ documentation. Before they are fully documented please refer to information below.
Multicast UDP
~~~~~~~~~~~~~
.. code:: cpp
uint8_t beginMulticast (IPAddress interfaceAddr, IPAddress multicast, uint16_t port)
virtual int beginPacketMulticast (IPAddress multicastAddress, uint16_t port, IPAddress interfaceAddress, int ttl=1)
IPAddress destinationIP ()
uint16_t localPort ()
The ``WiFiUDP`` class supports sending and receiving multicast packets on STA interface. When sending a multicast packet, replace ``udp.beginPacket(addr, port)`` with ``udp.beginPacketMulticast(addr, port, WiFi.localIP())``. When listening to multicast packets, replace ``udp.begin(port)`` with ``udp.beginMulticast(WiFi.localIP(), multicast_ip_addr, port)``. You can use ``udp.destinationIP()`` to tell whether the packet received was sent to the multicast or unicast address.
For code samples please refer to separate section with :doc:`examples <udp-examples>` dedicated specifically to the UDP Class.

198
doc/esp8266wifi/udp-examples.md
View File

@ -1,198 +0,0 @@
---
title: ESP8266WiFi UDP Class - Sketch Examples
---
[ESP8266WiFi Library :back:](readme.md#udp)
## UDP
The purpose of example application below is to demonstrate UDP communication between ESP8266 and an external client. The application (performing the role of a server) is checking inside the `loop()` for an UDP packet to arrive. When a valid packet is received, an acknowledge packet is sent back to the client to the same port it has been sent out.
## Table of Contents
* [Declarations](#declarations)
* [Wi-Fi Connection](#wi-fi-connection)
* [UDP Setup](#udp-setup)
* [An UDP Packet Arrived!](#an-udp-packet-arrived)
* [An Acknowledge Send Out](#an-acknowledge-send-out)
* [Complete Sketch](#complete-sketch)
* [How to Check It?](#how-to-check-it)
* [Conclusion](#conclusion)
### Declarations
At the beginning of sketch we need to include two libraries:
```cpp
#include <ESP8266WiFi.h>
#include <WiFiUdp.h>
```
The first library `ESP8266WiFi.h` is required by default if we are using ESP8266's Wi-Fi. The second one `WiFiUdp.h` is needed specifically for programming of UDP routines.
Once we have libraries in place we need to create a `WiFiUDP` object. Then we should specify a port to listen to incoming packets. There are conventions on usage of port numbers, for information please refer to the [List of TCP and UDP port numbers](https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers). Finally we need to set up a buffer for incoming packets and define a reply message.
```cpp
WiFiUDP Udp;
unsigned int localUdpPort = 4210;
char incomingPacket[255];
char replyPacekt[] = "Hi there! Got the message :-)";
```
### Wi-Fi Connection
At the beginning of `setup()` let's implement typical code to connect to an access point. This has been discussed in [Quick Start](readme.md#quick-start). Please refer to it if required.
### UDP Setup
Once connection is established, you can start listening to incoming packets.
```cpp
Udp.begin(localUdpPort);
```
That is all required preparation. We can move to the `loop()` that will be handling actual UDP communication.
### An UDP Packet Arrived!
Waiting for incoming UDP packed is done by the following code:
```cpp
int packetSize = Udp.parsePacket();
if (packetSize)
{
Serial.printf("Received %d bytes from %s, port %d\n", packetSize, Udp.remoteIP().toString().c_str(), Udp.remotePort());
int len = Udp.read(incomingPacket, 255);
if (len > 0)
{
incomingPacket[len] = 0;
}
Serial.printf("UDP packet contents: %s\n", incomingPacket);
(...)
}
```
Once a packet is received, the code will printing out the IP address and port of the sender as well as the length of received packet. If the packet is not empty, its contents will be printed out as well.
### An Acknowledge Send Out
For each received packet we are sending back an acknowledge packet:
```cpp
Udp.beginPacket(Udp.remoteIP(), Udp.remotePort());
Udp.write(replyPacekt);
Udp.endPacket();
```
Please note we are sending reply to the IP and port of the sender by using `Udp.remoteIP()` and `Udp.remotePort()`.
### Complete Sketch
The sketch performing all described functionality is presented below:
```cpp
#include <ESP8266WiFi.h>
#include <WiFiUdp.h>
const char* ssid = "********";
const char* password = "********";
WiFiUDP Udp;
unsigned int localUdpPort = 4210; // local port to listen on
char incomingPacket[255]; // buffer for incoming packets
char replyPacekt[] = "Hi there! Got the message :-)"; // a reply string to send back
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.printf("Connecting to %s ", ssid);
WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.println(" connected");
Udp.begin(localUdpPort);
Serial.printf("Now listening at IP %s, UDP port %d\n", WiFi.localIP().toString().c_str(), localUdpPort);
}
void loop()
{
int packetSize = Udp.parsePacket();
if (packetSize)
{
// receive incoming UDP packets
Serial.printf("Received %d bytes from %s, port %d\n", packetSize, Udp.remoteIP().toString().c_str(), Udp.remotePort());
int len = Udp.read(incomingPacket, 255);
if (len > 0)
{
incomingPacket[len] = 0;
}
Serial.printf("UDP packet contents: %s\n", incomingPacket);
// send back a reply, to the IP address and port we got the packet from
Udp.beginPacket(Udp.remoteIP(), Udp.remotePort());
Udp.write(replyPacekt);
Udp.endPacket();
}
}
```
### How to Check It?
Upload sketch to module and open serial monitor. You should see confirmation that ESP has connected to Wi-Fi and started listening to UDP packets:
```
Connecting to twc-net-3 ........ connected
Now listening at IP 192.168.1.104, UDP port 4210
```
Now we need another application to send some packets to IP and port shown by ESP above.
Instead of programming another ESP, let's make it easier and use a purpose build application. I have selected the [Packet Sender](https://packetsender.com/download). It is available for popular operating systems. Download, install and execute it.
Once Packet Sender's window show up enter the following information:
* *Name* of the packet
* *ASCII* text of the message to be send inside the packet
* IP *Address* shown by our ESP
* *Port* shown by the ESP
* Select *UDP*
What I have entered is shown below:
![alt text](pictures/udp-packet-sender.png "Testing UDP with packet sender")
Now click *Send*.
Immediately after that you should see the following on ESP's serial monitor:
```
Received 12 bytes from 192.168.1.106, port 55056
UDP packet contents: Hello World!
```
The text `192.168.1.106, port 55056` identifies a PC where the packet is send from. You will likely see different values.
As ESP sends an acknowledge packet back, you should see it in the log in the bottom part of the Packet Sender's window.
### Conclusion
This simple example shows how to send and receive UDP packets between ESP and an external application. Once tested in this minimal set up, you should be able to program ESP to talk to any other UDP device. In case of issues to establish communication with a new device, use the [Packet Sender](https://packetsender.com) or other similar program for troubleshooting
For review of functions provided to send and receive UDP packets, please refer to the [UDP Class :arrow_right:](udp-class.md) documentation.

194
doc/esp8266wifi/udp-examples.rst Normal file
View File

@ -0,0 +1,194 @@
:orphan:
UDP
---
The purpose of example application below is to demonstrate UDP communication between ESP8266 and an external client. The application (performing the role of a server) is checking inside the ``loop()`` for an UDP packet to arrive. When a valid packet is received, an acknowledge packet is sent back to the client to the same port it has been sent out.
Table of Contents
-----------------
- `Declarations <#declarations>`__
- `Wi-Fi Connection <#wi-fi-connection>`__
- `UDP Setup <#udp-setup>`__
- `An UDP Packet Arrived! <#an-udp-packet-arrived>`__
- `An Acknowledge Send Out <#an-acknowledge-send-out>`__
- `Complete Sketch <#complete-sketch>`__
- `How to Check It? <#how-to-check-it>`__
- `Conclusion <#conclusion>`__
Declarations
~~~~~~~~~~~~
At the beginning of sketch we need to include two libraries:
.. code:: cpp
#include <ESP8266WiFi.h>
#include <WiFiUdp.h>
The first library ``ESP8266WiFi.h`` is required by default if we are using ESP8266's Wi-Fi. The second one ``WiFiUdp.h`` is needed specifically for programming of UDP routines.
Once we have libraries in place we need to create a ``WiFiUDP`` object. Then we should specify a port to listen to incoming packets. There are conventions on usage of port numbers, for information please refer to the `List of TCP and UDP port numbers <https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers>`__. Finally we need to set up a buffer for incoming packets and define a reply message.
.. code:: cpp
WiFiUDP Udp;
unsigned int localUdpPort = 4210;
char incomingPacket[255];
char replyPacekt[] = "Hi there! Got the message :-)";
Wi-Fi Connection
~~~~~~~~~~~~~~~~
At the beginning of ``setup()`` let's implement typical code to connect to an access point. This has been discussed in `Quick Start <readme.md#quick-start>`__. Please refer to it if required.
UDP Setup
~~~~~~~~~
Once connection is established, you can start listening to incoming packets.
.. code:: cpp
Udp.begin(localUdpPort);
That is all required preparation. We can move to the ``loop()`` that will be handling actual UDP communication.
An UDP Packet Arrived!
~~~~~~~~~~~~~~~~~~~~~~
Waiting for incoming UDP packed is done by the following code:
.. code:: cpp
int packetSize = Udp.parsePacket();
if (packetSize)
{
Serial.printf("Received %d bytes from %s, port %d\n", packetSize, Udp.remoteIP().toString().c_str(), Udp.remotePort());
int len = Udp.read(incomingPacket, 255);
if (len > 0)
{
incomingPacket[len] = 0;
}
Serial.printf("UDP packet contents: %s\n", incomingPacket);
(...)
}
Once a packet is received, the code will printing out the IP address and port of the sender as well as the length of received packet. If the packet is not empty, its contents will be printed out as well.
An Acknowledge Send Out
~~~~~~~~~~~~~~~~~~~~~~~
For each received packet we are sending back an acknowledge packet:
.. code:: cpp
Udp.beginPacket(Udp.remoteIP(), Udp.remotePort());
Udp.write(replyPacekt);
Udp.endPacket();
Please note we are sending reply to the IP and port of the sender by using ``Udp.remoteIP()`` and ``Udp.remotePort()``.
Complete Sketch
~~~~~~~~~~~~~~~
The sketch performing all described functionality is presented below:
.. code:: cpp
#include <ESP8266WiFi.h>
#include <WiFiUdp.h>
const char* ssid = "********";
const char* password = "********";
WiFiUDP Udp;
unsigned int localUdpPort = 4210; // local port to listen on
char incomingPacket[255]; // buffer for incoming packets
char replyPacekt[] = "Hi there! Got the message :-)"; // a reply string to send back
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.printf("Connecting to %s ", ssid);
WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.println(" connected");
Udp.begin(localUdpPort);
Serial.printf("Now listening at IP %s, UDP port %d\n", WiFi.localIP().toString().c_str(), localUdpPort);
}
void loop()
{
int packetSize = Udp.parsePacket();
if (packetSize)
{
// receive incoming UDP packets
Serial.printf("Received %d bytes from %s, port %d\n", packetSize, Udp.remoteIP().toString().c_str(), Udp.remotePort());
int len = Udp.read(incomingPacket, 255);
if (len > 0)
{
incomingPacket[len] = 0;
}
Serial.printf("UDP packet contents: %s\n", incomingPacket);
// send back a reply, to the IP address and port we got the packet from
Udp.beginPacket(Udp.remoteIP(), Udp.remotePort());
Udp.write(replyPacekt);
Udp.endPacket();
}
}
How to Check It?
~~~~~~~~~~~~~~~~
Upload sketch to module and open serial monitor. You should see confirmation that ESP has connected to Wi-Fi and started listening to UDP packets:
::
Connecting to twc-net-3 ........ connected
Now listening at IP 192.168.1.104, UDP port 4210
Now we need another application to send some packets to IP and port shown by ESP above.
Instead of programming another ESP, let's make it easier and use a purpose build application. I have selected the `Packet Sender <https://packetsender.com/download>`__. It is available for popular operating systems. Download, install and execute it.
Once Packet Sender's window show up enter the following information: \* *Name* of the packet \* *ASCII* text of the message to be send inside the packet \* IP *Address* shown by our ESP \* *Port* shown by the ESP
\* Select *UDP*
What I have entered is shown below:
.. figure:: pictures/udp-packet-sender.png
:alt: Testing UDP with packet sender
alt text
Now click *Send*.
Immediately after that you should see the following on ESP's serial monitor:
::
Received 12 bytes from 192.168.1.106, port 55056
UDP packet contents: Hello World!
The text ``192.168.1.106, port 55056`` identifies a PC where the packet is send from. You will likely see different values.
As ESP sends an acknowledge packet back, you should see it in the log in the bottom part of the Packet Sender's window.
Conclusion
~~~~~~~~~~
This simple example shows how to send and receive UDP packets between ESP and an external application. Once tested in this minimal set up, you should be able to program ESP to talk to any other UDP device. In case of issues to establish communication with a new device, use the `Packet Sender <https://packetsender.com>`__ or other similar program for troubleshooting
For review of functions provided to send and receive UDP packets, please refer to the :doc:`UDP Class <udp-class>` documentation.

38
doc/exception_causes.md
View File

@ -1,38 +0,0 @@
Exception Causes (EXCCAUSE)
===========================================
| EXC-CAUSE Code | Cause Name | Cause Description | Required Option | EXC-VADDR Loaded |
|:--------------:|:---------------------------|:------------------------------------------------------------------------------------------------------------|:-------------------------|:----------------:|
| 0 | IllegalInstructionCause | Illegal instruction | Exception | No |
| 1 | SyscallCause | SYSCALL instruction | Exception | No |
| 2 | InstructionFetchErrorCause | Processor internal physical address or data error during instruction fetch | Exception | Yes |
| 3 | LoadStoreErrorCause | Processor internal physical address or data error during load or store | Exception | Yes |
| 4 | Level1InterruptCause | Level-1 interrupt as indicated by set level-1 bits in the INTERRUPT register | Interrupt | No |
| 5 | AllocaCause | MOVSP instruction, if caller’s registers are not in the register file | Windowed Register | No |
| 6 | IntegerDivideByZeroCause | QUOS, QUOU, REMS, or REMU divisor operand is zero | 32-bit Integer Divide | No |
| 7 | Reserved for Tensilica | | | |
| 8 | PrivilegedCause | Attempt to execute a privileged operation when CRING ? 0 | MMU | No |
| 9 | LoadStoreAlignmentCause | Load or store to an unaligned address | Unaligned Exception | Yes |
| 10..11 | Reserved for Tensilica | | | |
| 12 | InstrPIFDataErrorCause | PIF data error during instruction fetch | Processor Interface | Yes |
| 13 | LoadStorePIFDataErrorCause | Synchronous PIF data error during LoadStore access | Processor Interface | Yes |
| 14 | InstrPIFAddrErrorCause | PIF address error during instruction fetch | Processor Interface | Yes |
| 15 | LoadStorePIFAddrErrorCause | Synchronous PIF address error during LoadStore access | Processor Interface | Yes |
| 16 | InstTLBMissCause | Error during Instruction TLB refill | MMU | Yes |
| 17 | InstTLBMultiHitCause | Multiple instruction TLB entries matched | MMU | Yes |
| 18 | InstFetchPrivilegeCause | An instruction fetch referenced a virtual address at a ring level less than CRING | MMU | Yes |
| 19 | Reserved for Tensilica | | | |
| 20 | InstFetchProhibitedCause | An instruction fetch referenced a page mapped with an attribute that does not permit instruction fetch | Region Protection or MMU | Yes |
| 21..23 | Reserved for Tensilica | | | |
| 24 | LoadStoreTLBMissCause | Error during TLB refill for a load or store | MMU | Yes |
| 25 | LoadStoreTLBMultiHitCause | Multiple TLB entries matched for a load or store | MMU | Yes |
| 26 | LoadStorePrivilegeCause | A load or store referenced a virtual address at a ring level less than CRING | MMU | Yes |
| 27 | Reserved for Tensilica | | | |
| 28 | LoadProhibitedCause | A load referenced a page mapped with an attribute that does not permit loads | Region Protection or MMU | Yes |
| 29 | StoreProhibitedCause | A store referenced a page mapped with an attribute that does not permit stores | Region Protection or MMU | Yes |
| 30..31 | Reserved for Tensilica | | | |
| 32..39 | CoprocessornDisabled | Coprocessor n instruction when cpn disabled. n varies 0..7 as the cause varies 32..39 | Coprocessor | No |
| 40..63 | Reserved | | | |
Infos from Xtensa Instruction Set Architecture (ISA) Reference Manual

124
doc/exception_causes.rst Normal file
View File

@ -0,0 +1,124 @@
Exception Causes (EXCCAUSE)
===========================
+--------+------------+-----------------------------------------+-----------+--------+
| EXCCAU | Cause Name | Cause Description | Required | EXCVAD |
| SE | | | Option | DR |
| Code | | | | Loaded |
+========+============+=========================================+===========+========+
| 0 | IllegalIns | Illegal instruction | Exception | No |
| | tructionCa | | | |
| | use | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 1 | SyscallCau | SYSCALL instruction | Exception | No |
| | se | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 2 | Instructio | Processor internal physical address or | Exception | Yes |
| | nFetchErro | data error during instruction fetch | | |
| | rCause | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 3 | LoadStoreE | Processor internal physical address or | Exception | Yes |
| | rrorCause | data error during load or store | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 4 | Level1Inte | Level-1 interrupt as indicated by set | Interrupt | No |
| | rruptCause | level-1 bits in the INTERRUPT register | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 5 | AllocaCaus | MOVSP instruction, if caller’s | Windowed | No |
| | e | registers are not in the register file | Register | |
+--------+------------+-----------------------------------------+-----------+--------+
| 6 | IntegerDiv | QUOS, QUOU, REMS, or REMU divisor | 32-bit | No |
| | ideByZeroC | operand is zero | Integer | |
| | ause | | Divide | |
+--------+------------+-----------------------------------------+-----------+--------+
| 7 | Reserved | | | |
| | for | | | |
| | Tensilica | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 8 | Privileged | Attempt to execute a privileged | MMU | No |
| | Cause | operation when CRING != 0 | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 9 | LoadStoreA | Load or store to an unaligned address | Unaligned | Yes |
| | lignmentCa | | Exception | |
| | use | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 10..11 | Reserved | | | |
| | for | | | |
| | Tensilica | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 12 | InstrPIFDa | PIF data error during instruction fetch | Processor | Yes |
| | taErrorCau | | Interface | |
| | se | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 13 | LoadStoreP | Synchronous PIF data error during | Processor | Yes |
| | IFDataErro | LoadStore access | Interface | |
| | rCause | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 14 | InstrPIFAd | PIF address error during instruction | Processor | Yes |
| | drErrorCau | fetch | Interface | |
| | se | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 15 | LoadStoreP | Synchronous PIF address error during | Processor | Yes |
| | IFAddrErro | LoadStore access | Interface | |
| | rCause | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 16 | InstTLBMis | Error during Instruction TLB refill | MMU | Yes |
| | sCause | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 17 | InstTLBMul | Multiple instruction TLB entries | MMU | Yes |
| | tiHitCause | matched | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 18 | InstFetchP | An instruction fetch referenced a | MMU | Yes |
| | rivilegeCa | virtual address at a ring level less | | |
| | use | than CRING | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 19 | Reserved | | | |
| | for | | | |
| | Tensilica | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 20 | InstFetchP | An instruction fetch referenced a page | Region | Yes |
| | rohibitedC | mapped with an attribute that does not | Protectio | |
| | ause | permit instruction fetch | n | |
| | | | or MMU | |
+--------+------------+-----------------------------------------+-----------+--------+
| 21..23 | Reserved | | | |
| | for | | | |
| | Tensilica | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 24 | LoadStoreT | Error during TLB refill for a load or | MMU | Yes |
| | LBMissCaus | store | | |
| | e | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 25 | LoadStoreT | Multiple TLB entries matched for a load | MMU | Yes |
| | LBMultiHit | or store | | |
| | Cause | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 26 | LoadStoreP | A load or store referenced a virtual | MMU | Yes |
| | rivilegeCa | address at a ring level less than CRING | | |
| | use | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 27 | Reserved | | | |
| | for | | | |
| | Tensilica | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 28 | LoadProhib | A load referenced a page mapped with an | Region | Yes |
| | itedCause | attribute that does not permit loads | Protectio | |
| | | | n | |
| | | | or MMU | |
+--------+------------+-----------------------------------------+-----------+--------+
| 29 | StoreProhi | A store referenced a page mapped with | Region | Yes |
| | bitedCause | an attribute that does not permit | Protectio | |
| | | stores | n | |
| | | | or MMU | |
+--------+------------+-----------------------------------------+-----------+--------+
| 30..31 | Reserved | | | |
| | for | | | |
| | Tensilica | | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 32..39 | Coprocesso | Coprocessor n instruction when cpn | Coprocess | No |
| | rnDisabled | disabled. n varies 0..7 as the cause | or | |
| | | varies 32..39 | | |
+--------+------------+-----------------------------------------+-----------+--------+
| 40..63 | Reserved | | | |
+--------+------------+-----------------------------------------+-----------+--------+
Infos from Xtensa Instruction Set Architecture (ISA) Reference Manual

284
doc/faq/a01-espcomm_sync-failed.md
View File

@ -1,284 +0,0 @@
---
title: Frequently Asked Questions / Troubleshooting
---
[FAQ list :back:](readme.md)
## I am getting "espcomm_sync failed" error when trying to upload my ESP. How to resolve this issue?
- [Introduction](#Introduction)
- [Initial Checks](#initial-checks)
- [Advanced Checks](#advanced-checks)
- [Reset Methods](#reset-methods)
- [Ck](#ck)
- [Nodemcu](#nodemcu)
- [I'm Stuck](#im-stuck)
- [Conclusion](#conclusion)
### Introduction
This message indicates issue with uploading ESP module over a serial connection. There are couple of possible causes, that depend on the type of module, if you use separate USB to serial converter, what parameters are selected for upload, etc. As result there is no single answer on the root cause. To find it out you may need to complete couple of troubleshooting steps.
> Note: If you are just starting with ESP, to reduce potential issues with uploading, select ESP board with integrated USB to serial converter. This will considerably reduce number of user depended factors or configuration settings that influence upload process.
Example boards with USB to serial converter build in, that will make your initial project development easier, are shown below.
![Example boards with integrated USB to serial converter](pictures/a01-example-boards-with-usb.png)
If you are using a Generic ESP8266 module, separate USB to serial converter and connect them by yourself, please make sure you have the following three things right:
1. Module is provided with enough power,
2. GPIO0, GPIO15 and CH_PD are connected using pull up / pull down resistors,
3. Module is put into boot loader mode.
For specific details please refer to section on [Generic ESP8266 modules](../boards.md#generic-esp8266-modules). Example modules without USB to serial converter on board are shown below.
![Example ESP8266 modules without USB to serial converter](pictures/a01-example-boards-without-usb.png)
### Initial Checks
In order to troubleshoot "espcomm_sync failed" error, please proceed step by step through the checklist below. This list is organized starting with most common and simple to more complex issues.
1. Start with reading exact message displayed in debug window of Arduino IDE. In many cases it provides direct information where the issue is.
!["espcomm_open failed" error](pictures/a01-espcomm_open-failed.png)
For instance message above suggests that Arduino IDE is unable to open a serial port COM3. Check if you have selected port where your module is connected to.
![Serial port selection](pictures/a01-serial-port-selection.png)
2. If a module is connected to the serial port but not responding as a valid ESP8266 device, the message will read slightly different (see below). If you have other modules connected to your PC, make sure that you are uploading code to ESP8266 and not to e.g. Arduino UNO.
![Serial port selection](pictures/a01-espcomm_sync-failed.png)
3. To have your PC talking to ESP, select exact ESP type in upload menu. If selection is incorrect then the upload may fail.
![Board selection](pictures/a01-board-selection.png)
Basing on selected board type, Arduino IDE will apply specific "reset method" to enter the board into boot loading mode. Reset methods are board specific. Some boards do not have the h/w in place to support reset by Arduino IDE. If this is the case, you need to enter such board into boot loading mode manually.
4. Upload may be also failing due to too high speed. If you have long or poor quality USB cable, try reducing selection under *Upload Speed*.
![Serial speed selection](pictures/a01-serial-speed-selection.png)
### Advanced Checks
1. If you are still facing issues, test if module is indeed entering the boot loading mode. You can do it by connecting secondary USB to serial converter and checking the message displayed. Attach RX and GND pins of converter to TX and GND pin of ESP as shown on example below ([get fzz source](pictures/a01-secondary-serial-hookup.fzz)).
![Secondary USB to serial converter hookup](pictures/a01-secondary-serial-hookup.png)
Then open a terminal at 74880 baud, and look what message is reported when ESP is being reset for programming. Correct message looks as follows:
```
ets Jan 8 2013,rst cause:2, boot mode:(1,7)
```
If you see similar message but different values then decode them using [Boot Messages and Modes](../boards.md#boot-messages-and-modes). The key information is contained in first digit / three right-most bits of the boot mode message as shown below.
![Decoding of boot mode](pictures/a01-boot-mode-decoding.png)
For instance message ``` boot mode (3,3) ``` indicates that pins GPIO2 and GPIO0 are set HIGH and GPIO15 is set LOW. This is configuration for [normal operation](../boards.md#minimal-hardware-setup-for-running-only) of module (to execute application from flash), not for [boot loading](../boards.md#minimal-hardware-setup-for-bootloading-only) (flash programming).
> Note: Without having this step right you will not be able to upload your module over a serial port.
2. You have confirmed that module is in boot loading mode but upload still fails. If you are using external USB to serial converter, then check if it operates correctly by looping it back. This is quite simple check. Just connect TX and RX of your converter together like on picture below. Then open Serial Monitor and type some characters. If everything is fine, then you should see what you type immediately printed back on the monitor. For an ESP with USB to serial converter on board, this check may involve breaking some PCB traces. I would not do it unless being desperate. Instead try steps below.
![USB to serial converter loop back](pictures/a01-usb-to-serial-loop-back.png)
3. Next step to try, if not done already, is checking detailed debug messages. Go to *File > Preferences*, enable *Show verbose output during: upload* and try uploading again. For successful upload this log should look similar to example shown below:
```
C:\Users\Krzysztof\AppData\Local\Arduino15\packages\esp8266\tools\esptool\0.4.8/esptool.exe -vv -cd ck -cb 115200 -cp COM3 -ca 0x00000 -cf C:\Users\KRZYSZ~1\AppData\Local\Temp\build7e44b372385012e74d64fb272d24b802.tmp/Blink.ino.bin
esptool v0.4.8 - (c) 2014 Ch. Klippel <ck@atelier-klippel.de>
setting board to ck
setting baudrate from 115200 to 115200
setting port from COM1 to COM3
setting address from 0x00000000 to 0x00000000
espcomm_upload_file
espcomm_upload_mem
setting serial port timeouts to 1000 ms
opening bootloader
resetting board
trying to connect
flush start
setting serial port timeouts to 1 ms
setting serial port timeouts to 1000 ms
flush complete
espcomm_send_command: sending command header
espcomm_send_command: sending command payload
read 0, requested 1
trying to connect
flush start
setting serial port timeouts to 1 ms
setting serial port timeouts to 1000 ms
flush complete
espcomm_send_command: sending command header
espcomm_send_command: sending command payload
espcomm_send_command: receiving 2 bytes of data
espcomm_send_command: receiving 2 bytes of data
espcomm_send_command: receiving 2 bytes of data
espcomm_send_command: receiving 2 bytes of data
espcomm_send_command: receiving 2 bytes of data
espcomm_send_command: receiving 2 bytes of data
espcomm_send_command: receiving 2 bytes of data
espcomm_send_command: receiving 2 bytes of data
Uploading 226368 bytes from to flash at 0x00000000
erasing flash
size: 037440 address: 000000
first_sector_index: 0
total_sector_count: 56
head_sector_count: 16
adjusted_sector_count: 40
erase_size: 028000
espcomm_send_command: sending command header
espcomm_send_command: sending command payload
setting serial port timeouts to 15000 ms
setting serial port timeouts to 1000 ms
espcomm_send_command: receiving 2 bytes of data
writing flash
..............................................................................................................................................................................................................................
starting app without reboot
espcomm_send_command: sending command header
espcomm_send_command: sending command payload
espcomm_send_command: receiving 2 bytes of data
closing bootloader
flush start
setting serial port timeouts to 1 ms
setting serial port timeouts to 1000 ms
flush complete
```
Upload log may be longer depending on number of connection attempts made by esptool. Analyze it for any anomalies to configuration you have selected in Arduino IDE, like different serial port, reset method, baud rate, etc. Resolve all noted differences.
### Reset Methods
If you got to this point and still see ``` espcomm_sync failed ```, then now you need to bring in the heavy guns.
Connect scope or logic analyzer to GPIO0, RST and RXD pins of the ESP to check what's happening.
Then compare your measurements with wave-forms collected for circuits below. They document two standard methods of resetting ESP8266 for upload, that you can select in Arduino IDE - [ck](#ck) and [nodemcu](#nodemcu).
#### Ck
Circuit below has been prepared to collect wave-forms for ck reset method ([get fzz source](pictures/a01-circuit-ck-reset.fzz)). It is simpler than for [nodemcu](#nodemcu) reset and therefore often used to wire up generic ESP modules on a breadboard. Check it against your wiring when comparing your measurements against wave-forms below.
![Sample circuit to check ck method](pictures/a01-circuit-ck-reset.png)
The following wave-forms below show voltage signals on GPIO0 and RST pins of the ESP board when uploading the firmware.
Close up of ck reset method signal sequence at the beginning of upload is shown below.
![Reset Method: ck, close up at the beginning of upload](pictures/a01-reset-ck-closeup.png)
Next picture shows complete upload of [Blink.ino](https://github.com/esp8266/Arduino/blob/master/libraries/esp8266/examples/Blink/Blink.ino) example at 921600 baud. This is quite high speed, so the upload takes only about 8s.
![Reset Method: ck, complete upload](pictures/a01-reset-ck-complete.png)
Please note that when esptool is not able to initialize upload at the first time, then it retries reset procedure. Case of one such retry is shown on wave-form below.
![Reset Method: ck, complete upload](pictures/a01-reset-ck-complete-1-retry.png)
Each retry is reported in upload log as follows:
```
resetting board
trying to connect
flush start
setting serial port timeouts to 1 ms
setting serial port timeouts to 1000 ms
flush complete
espcomm_send_command: sending command header
espcomm_send_command: sending command payload
read 0, requested 1
```
Presented circuit has one important limitation when it comes to work with Arduino IDE. After opening Serial Monitor (Ctrl-Shift-M), both RTS and DTR lines are permanently pulled down. As RTS line is connected to REST input of ESP, the module is hold in reset state / not able to run. Therefore after uploading module, you need to disconnect both lines or use different serial terminal program that is not pulling down RTS and DTR lines. Otherwise the module will get stuck waiting for releasing the REST signal and you will see nothing on the Serial Monitor.
As for different serial terminal program you can check Arduino IDE add-on [Serial Monitor for ESP8266]((https://github.com/esp8266/Arduino/issues/1360)) developed by user [@mytrain](https://github.com/mytrain) and discussed in [#1360](https://github.com/esp8266/Arduino/issues/1360).
If you prefer external terminal program, then for Windows users we can recommend free and handy [Termite](http://www.compuphase.com/software_termite.htm).
#### Nodemcu
Nodemcu reset method is named after [NodeMCU](https://github.com/nodemcu/nodemcu-devkit) board where it has been introduced for the first time. It overcomes limitations with handling of RTS and DTR lines discussed for [ck](#ck) reset method above.
Sample circuit to measure wave-form is shown below ([get fzz source](pictures/a01-circuit-nodemcu-reset.fzz)).
![Sample circuit to check nodemcu reset method](pictures/a01-circuit-nodemcu-reset.png)
Close up of voltage signals on GPIO0 and RST pins at the beginning of firmware upload is shown below.
![Reset Method: nodemcu, close up at the beginning of upload](pictures/a01-reset-nodemcu-closeup.png)
Please note that the reset sequence is about 10x shorter comparing to [ck](@ck) reset (about 25ms vs. 250ms).
Next picture covers complete upload of [Blink.ino](https://github.com/esp8266/Arduino/blob/master/libraries/esp8266/examples/Blink/Blink.ino) example at 921600 baud. Except for difference of the reset signal sequence, the complete upload looks similar to that of [ck](@ck).
![Reset Method: nodemcu, complete upload](pictures/a01-reset-nodemcu-complete.png)
A sample wave-form below shows another upload of [Blink.ino](https://github.com/esp8266/Arduino/blob/master/libraries/esp8266/examples/Blink/Blink.ino) example at 921600 baud, but with two reset retries.
![Reset Method: nodemcu, reset retries](pictures/a01-reset-nodemcu-complete-2-retries.png)
If you are interested how noodemcu reset method is implemented, then check circuit below. As indicated it does not pull to ground RTS and DTR lines once you open Serial Monitor in Arduino IDE.
![Implementation of noodemcu reset](pictures/a01-nodemcu-reset-implementation.png)
It consists of two transistors and resistors that you can locate on NodeMCU board on right. On left you can see complete circuit and the truth table how RTS and DTR signals of the serial interface are translated to RST and GPIO0 on the ESP. For more details please refer to [nodemcu](https://github.com/nodemcu/nodemcu-devkit) repository on GitHub.
### I'm Stuck
Hopefully at this point you were able to resolve ``` espcomm_sync failed ``` issue and now enjoy quick and reliable uploads of your ESP modules.
If this is still not the case, then review once more all discussed steps in the checklist below.
**Initial Checks**
* [ ] Is your module connected to serial port and visible in IDE?
* [ ] Is connected device responding to IDE? What is exact message in debug window?
* [ ] Have you selected correct ESP module type in *Board* menu? What is the selection?
* [ ] Have you tried to reduce upload speed? What speeds have you tried?
**Advanced Checks**
* [ ] What message is reported by ESP at 74880 baud when entering boot loading mode?
* [ ] Have you checked your USB to serial converter by looping it back? What is the result?
* [ ] Is your detailed upload log consistent with settings in IDE? What is the log?
**Reset Method**
* [ ] What reset method do you use?
* [ ] What is your connection diagram? Does it match diagram in this FAQ?
* [ ] What is your wave-form of board reset? Does it match wave-form in this FAQ?
* [ ] What is your wave-form of complete upload? Does it match wave-form in this FAQ?
**Software**
* [ ] Do you use the latest stable version of [esp8266 / Arduino](https://github.com/esp8266/Arduino)? What is it?
* [ ] What is the name and version of your IDE and O/S?
If you are stuck at certain step, then post this list on [ESP8266 Community Forum](http://www.esp8266.com/) asking for support.
### Conclusion
With variety of available ESP8266 modules and boards, as well as possible connection methods, troubleshooting of upload issues may take several steps.
If you are a beginner, then use boards with integrated power supply and USB to serial converter. Check carefully message in debug window and act accordingly. Select your exact module type in IDE and try to adjust upload speed. Check if board is indeed entering boot loading mode. Check operation of your USB to serial converter with loop back. Analyze detailed upload log for inconsistencies with IDE settings.
Verify your connection diagram and wave-form for consistency with selected reset method.
If you get stuck, then ask [community](http://www.esp8266.com/) for support providing summary of all completed checks.
![Test stand used during checking of ck reset method](pictures/a01-test-stand.jpg)
Test stand used for checking of ck reset method is shown above.
No any ESP module has been harmed during preparation of this FAQ item.
[FAQ list :back:](readme.md)

394
doc/faq/a01-espcomm_sync-failed.rst Normal file
View File

@ -0,0 +1,394 @@
:orphan:
I am getting "espcomm\_sync failed" error when trying to upload my ESP. How to resolve this issue?
--------------------------------------------------------------------------------------------------
- `Introduction <#Introduction>`__
- `Initial Checks <#initial-checks>`__
- `Advanced Checks <#advanced-checks>`__
- `Reset Methods <#reset-methods>`__
- `Ck <#ck>`__
- `Nodemcu <#nodemcu>`__
- `I'm Stuck <#im-stuck>`__
- `Conclusion <#conclusion>`__
Introduction
~~~~~~~~~~~~
This message indicates issue with uploading ESP module over a serial
connection. There are couple of possible causes, that depend on the type
of module, if you use separate USB to serial converter, what parameters
are selected for upload, etc. As result there is no single answer on the
root cause. To find it out you may need to complete couple of
troubleshooting steps.
Note: If you are just starting with ESP, to reduce potential issues
with uploading, select ESP board with integrated USB to serial
converter. This will considerably reduce number of user depended
factors or configuration settings that influence upload process.
Example boards with USB to serial converter build in, that will make
your initial project development easier, are shown below.
.. figure:: pictures/a01-example-boards-with-usb.png
:alt: Example boards with integrated USB to serial converter
Example boards with integrated USB to serial converter
If you are using a Generic ESP8266 module, separate USB to serial
converter and connect them by yourself, please make sure you have the
following three things right: 1. Module is provided with enough power,
2. GPIO0, GPIO15 and CH\_PD are connected using pull up / pull down
resistors, 3. Module is put into boot loader mode.
For specific details please refer to section on `Generic ESP8266
modules <../boards.md#generic-esp8266-modules>`__. Example modules
without USB to serial converter on board are shown below.
.. figure:: pictures/a01-example-boards-without-usb.png
:alt: Example ESP8266 modules without USB to serial converter
Example ESP8266 modules without USB to serial converter
Initial Checks
~~~~~~~~~~~~~~
In order to troubleshoot "espcomm\_sync failed" error, please proceed
step by step through the checklist below. This list is organized
starting with most common and simple to more complex issues.
1. Start with reading exact message displayed in debug window of Arduino
IDE. In many cases it provides direct information where the issue is.
.. figure:: pictures/a01-espcomm_open-failed.png
:alt: "espcomm\_open failed" error
"espcomm\_open failed" error
For instance message above suggests that Arduino IDE is unable to open a
serial port COM3. Check if you have selected port where your module is
connected to.
.. figure:: pictures/a01-serial-port-selection.png
:alt: Serial port selection
Serial port selection
2. If a module is connected to the serial port but not responding as a
valid ESP8266 device, the message will read slightly different (see
below). If you have other modules connected to your PC, make sure
that you are uploading code to ESP8266 and not to e.g. Arduino UNO.
.. figure:: pictures/a01-espcomm_sync-failed.png
:alt: Serial port selection
Serial port selection
3. To have your PC talking to ESP, select exact ESP type in upload menu.
If selection is incorrect then the upload may fail.
.. figure:: pictures/a01-board-selection.png
:alt: Board selection
Board selection
Basing on selected board type, Arduino IDE will apply specific "reset
method" to enter the board into boot loading mode. Reset methods are
board specific. Some boards do not have the h/w in place to support
reset by Arduino IDE. If this is the case, you need to enter such board
into boot loading mode manually.
4. Upload may be also failing due to too high speed. If you have long or
poor quality USB cable, try reducing selection under *Upload Speed*.
.. figure:: pictures/a01-serial-speed-selection.png
:alt: Serial speed selection
Serial speed selection
Advanced Checks
~~~~~~~~~~~~~~~
1. If you are still facing issues, test if module is indeed entering the
boot loading mode. You can do it by connecting secondary USB to
serial converter and checking the message displayed. Attach RX and
GND pins of converter to TX and GND pin of ESP as shown on example
below (`get fzz
source <pictures/a01-secondary-serial-hookup.fzz>`__).
.. figure:: pictures/a01-secondary-serial-hookup.png
:alt: Secondary USB to serial converter hookup
Secondary USB to serial converter hookup
Then open a terminal at 74880 baud, and look what message is reported
when ESP is being reset for programming. Correct message looks as
follows:
``ets Jan 8 2013,rst cause:2, boot mode:(1,7)``
If you see similar message but different values then decode them using
`Boot Messages and Modes <../boards.md#boot-messages-and-modes>`__. The
key information is contained in first digit / three right-most bits of
the boot mode message as shown below.
.. figure:: pictures/a01-boot-mode-decoding.png
:alt: Decoding of boot mode
Decoding of boot mode
For instance message ``boot mode (3,3)`` indicates that pins GPIO2 and
GPIO0 are set HIGH and GPIO15 is set LOW. This is configuration for
`normal
operation <../boards.md#minimal-hardware-setup-for-running-only>`__ of
module (to execute application from flash), not for `boot
loading <../boards.md#minimal-hardware-setup-for-bootloading-only>`__
(flash programming).
Note: Without having this step right you will not be able to upload
your module over a serial port.
2. You have confirmed that module is in boot loading mode but upload
still fails. If you are using external USB to serial converter, then
check if it operates correctly by looping it back. This is quite
simple check. Just connect TX and RX of your converter together like
on picture below. Then open Serial Monitor and type some characters.
If everything is fine, then you should see what you type immediately
printed back on the monitor. For an ESP with USB to serial converter
on board, this check may involve breaking some PCB traces. I would
not do it unless being desperate. Instead try steps below.
.. figure:: pictures/a01-usb-to-serial-loop-back.png
:alt: USB to serial converter loop back
USB to serial converter loop back
3. Next step to try, if not done already, is checking detailed debug
messages. Go to *File > Preferences*, enable *Show verbose output
during: upload* and try uploading again. For successful upload this
log should look similar to example shown below:
``C:\Users\Krzysztof\AppData\Local\Arduino15\packages\esp8266\tools\esptool\0.4.8/esptool.exe -vv -cd ck -cb 115200 -cp COM3 -ca 0x00000 -cf C:\Users\KRZYSZ~1\AppData\Local\Temp\build7e44b372385012e74d64fb272d24b802.tmp/Blink.ino.bin esptool v0.4.8 - (c) 2014 Ch. Klippel <ck@atelier-klippel.de> setting board to ck setting baudrate from 115200 to 115200 setting port from COM1 to COM3 setting address from 0x00000000 to 0x00000000 espcomm_upload_file espcomm_upload_mem setting serial port timeouts to 1000 ms opening bootloader resetting board trying to connect flush start setting serial port timeouts to 1 ms setting serial port timeouts to 1000 ms flush complete espcomm_send_command: sending command header espcomm_send_command: sending command payload read 0, requested 1 trying to connect flush start setting serial port timeouts to 1 ms setting serial port timeouts to 1000 ms flush complete espcomm_send_command: sending command header espcomm_send_command: sending command payload espcomm_send_command: receiving 2 bytes of data espcomm_send_command: receiving 2 bytes of data espcomm_send_command: receiving 2 bytes of data espcomm_send_command: receiving 2 bytes of data espcomm_send_command: receiving 2 bytes of data espcomm_send_command: receiving 2 bytes of data espcomm_send_command: receiving 2 bytes of data espcomm_send_command: receiving 2 bytes of data Uploading 226368 bytes from to flash at 0x00000000 erasing flash size: 037440 address: 000000 first_sector_index: 0 total_sector_count: 56 head_sector_count: 16 adjusted_sector_count: 40 erase_size: 028000 espcomm_send_command: sending command header espcomm_send_command: sending command payload setting serial port timeouts to 15000 ms setting serial port timeouts to 1000 ms espcomm_send_command: receiving 2 bytes of data writing flash .............................................................................................................................................................................................................................. starting app without reboot espcomm_send_command: sending command header espcomm_send_command: sending command payload espcomm_send_command: receiving 2 bytes of data closing bootloader flush start setting serial port timeouts to 1 ms setting serial port timeouts to 1000 ms flush complete``
Upload log may be longer depending on number of connection attempts made
by esptool. Analyze it for any anomalies to configuration you have
selected in Arduino IDE, like different serial port, reset method, baud
rate, etc. Resolve all noted differences.
Reset Methods
~~~~~~~~~~~~~
If you got to this point and still see ``espcomm_sync failed``, then now
you need to bring in the heavy guns.
Connect scope or logic analyzer to GPIO0, RST and RXD pins of the ESP to
check what's happening.
Then compare your measurements with wave-forms collected for circuits
below. They document two standard methods of resetting ESP8266 for
upload, that you can select in Arduino IDE - `ck <#ck>`__ and
`nodemcu <#nodemcu>`__.
Ck
^^
Circuit below has been prepared to collect wave-forms for ck reset
method (`get fzz source <pictures/a01-circuit-ck-reset.fzz>`__). It is
simpler than for `nodemcu <#nodemcu>`__ reset and therefore often used
to wire up generic ESP modules on a breadboard. Check it against your
wiring when comparing your measurements against wave-forms below.
.. figure:: pictures/a01-circuit-ck-reset.png
:alt: Sample circuit to check ck method
Sample circuit to check ck method
The following wave-forms below show voltage signals on GPIO0 and RST
pins of the ESP board when uploading the firmware.
Close up of ck reset method signal sequence at the beginning of upload
is shown below.
.. figure:: pictures/a01-reset-ck-closeup.png
:alt: Reset Method: ck, close up at the beginning of upload
Reset Method: ck, close up at the beginning of upload
Next picture shows complete upload of
`Blink.ino <https://github.com/esp8266/Arduino/blob/master/libraries/esp8266/examples/Blink/Blink.ino>`__
example at 921600 baud. This is quite high speed, so the upload takes
only about 8s.
.. figure:: pictures/a01-reset-ck-complete.png
:alt: Reset Method: ck, complete upload
Reset Method: ck, complete upload
Please note that when esptool is not able to initialize upload at the
first time, then it retries reset procedure. Case of one such retry is
shown on wave-form below.
.. figure:: pictures/a01-reset-ck-complete-1-retry.png
:alt: Reset Method: ck, complete upload
Reset Method: ck, complete upload
Each retry is reported in upload log as follows:
::
resetting board
trying to connect
flush start
setting serial port timeouts to 1 ms
setting serial port timeouts to 1000 ms
flush complete
espcomm_send_command: sending command header
espcomm_send_command: sending command payload
read 0, requested 1
Presented circuit has one important limitation when it comes to work
with Arduino IDE. After opening Serial Monitor (Ctrl-Shift-M), both RTS
and DTR lines are permanently pulled down. As RTS line is connected to
REST input of ESP, the module is hold in reset state / not able to run.
Therefore after uploading module, you need to disconnect both lines or
use different serial terminal program that is not pulling down RTS and
DTR lines. Otherwise the module will get stuck waiting for releasing the
REST signal and you will see nothing on the Serial Monitor.
As for different serial terminal program you can check Arduino IDE
add-on `Serial Monitor for
ESP8266 <(https://github.com/esp8266/Arduino/issues/1360)>`__ developed
by user [@mytrain](https://github.com/mytrain) and discussed in
`#1360 <https://github.com/esp8266/Arduino/issues/1360>`__.
If you prefer external terminal program, then for Windows users we can
recommend free and handy
`Termite <http://www.compuphase.com/software_termite.htm>`__.
Nodemcu
^^^^^^^
Nodemcu reset method is named after
`NodeMCU <https://github.com/nodemcu/nodemcu-devkit>`__ board where it
has been introduced for the first time. It overcomes limitations with
handling of RTS and DTR lines discussed for `ck <#ck>`__ reset method
above.
Sample circuit to measure wave-form is shown below (`get fzz
source <pictures/a01-circuit-nodemcu-reset.fzz>`__).
.. figure:: pictures/a01-circuit-nodemcu-reset.png
:alt: Sample circuit to check nodemcu reset method
Sample circuit to check nodemcu reset method
Close up of voltage signals on GPIO0 and RST pins at the beginning of
firmware upload is shown below.
.. figure:: pictures/a01-reset-nodemcu-closeup.png
:alt: Reset Method: nodemcu, close up at the beginning of upload
Reset Method: nodemcu, close up at the beginning of upload
Please note that the reset sequence is about 10x shorter comparing to
`ck <@ck>`__ reset (about 25ms vs. 250ms).
Next picture covers complete upload of
`Blink.ino <https://github.com/esp8266/Arduino/blob/master/libraries/esp8266/examples/Blink/Blink.ino>`__
example at 921600 baud. Except for difference of the reset signal
sequence, the complete upload looks similar to that of `ck <@ck>`__.
.. figure:: pictures/a01-reset-nodemcu-complete.png
:alt: Reset Method: nodemcu, complete upload
Reset Method: nodemcu, complete upload
A sample wave-form below shows another upload of
`Blink.ino <https://github.com/esp8266/Arduino/blob/master/libraries/esp8266/examples/Blink/Blink.ino>`__
example at 921600 baud, but with two reset retries.
.. figure:: pictures/a01-reset-nodemcu-complete-2-retries.png
:alt: Reset Method: nodemcu, reset retries
Reset Method: nodemcu, reset retries
If you are interested how noodemcu reset method is implemented, then
check circuit below. As indicated it does not pull to ground RTS and DTR
lines once you open Serial Monitor in Arduino IDE.
.. figure:: pictures/a01-nodemcu-reset-implementation.png
:alt: Implementation of noodemcu reset
Implementation of noodemcu reset
It consists of two transistors and resistors that you can locate on
NodeMCU board on right. On left you can see complete circuit and the
truth table how RTS and DTR signals of the serial interface are
translated to RST and GPIO0 on the ESP. For more details please refer to
`nodemcu <https://github.com/nodemcu/nodemcu-devkit>`__ repository on
GitHub.
I'm Stuck
~~~~~~~~~
Hopefully at this point you were able to resolve ``espcomm_sync failed``
issue and now enjoy quick and reliable uploads of your ESP modules.
If this is still not the case, then review once more all discussed steps
in the checklist below.
**Initial Checks** \* [ ] Is your module connected to serial port and
visible in IDE? \* [ ] Is connected device responding to IDE? What is
exact message in debug window? \* [ ] Have you selected correct ESP
module type in *Board* menu? What is the selection? \* [ ] Have you
tried to reduce upload speed? What speeds have you tried?
**Advanced Checks** \* [ ] What message is reported by ESP at 74880 baud
when entering boot loading mode? \* [ ] Have you checked your USB to
serial converter by looping it back? What is the result? \* [ ] Is your
detailed upload log consistent with settings in IDE? What is the log?
**Reset Method** \* [ ] What reset method do you use? \* [ ] What is
your connection diagram? Does it match diagram in this FAQ? \* [ ] What
is your wave-form of board reset? Does it match wave-form in this FAQ?
\* [ ] What is your wave-form of complete upload? Does it match
wave-form in this FAQ?
**Software** \* [ ] Do you use the latest stable version of `esp8266 /
Arduino <https://github.com/esp8266/Arduino>`__? What is it? \* [ ] What
is the name and version of your IDE and O/S?
If you are stuck at certain step, then post this list on `ESP8266
Community Forum <http://www.esp8266.com/>`__ asking for support.
Conclusion
~~~~~~~~~~
With variety of available ESP8266 modules and boards, as well as
possible connection methods, troubleshooting of upload issues may take
several steps.
If you are a beginner, then use boards with integrated power supply and
USB to serial converter. Check carefully message in debug window and act
accordingly. Select your exact module type in IDE and try to adjust
upload speed. Check if board is indeed entering boot loading mode. Check
operation of your USB to serial converter with loop back. Analyze
detailed upload log for inconsistencies with IDE settings.
Verify your connection diagram and wave-form for consistency with
selected reset method.
If you get stuck, then ask `community <http://www.esp8266.com/>`__ for
support providing summary of all completed checks.
.. figure:: pictures/a01-test-stand.jpg
:alt: Test stand used during checking of ck reset method
Test stand used during checking of ck reset method
Test stand used for checking of ck reset method is shown above.
No any ESP module has been harmed during preparation of this FAQ item.
`FAQ list :back: <readme.md>`__

169
doc/faq/a02-my-esp-crashes.md
View File

@ -1,169 +0,0 @@
---
title: Frequently Asked Questions / Troubleshooting
---
[FAQ list :back:](readme.md)
## My ESP crashes running some code. How to troubleshoot it?
* [Introduction](#introduction)
* [What ESP has to Say](#what-esp-has-to-say)
* [Get Your H/W Right](#get-your-hw-right)
* [What is the Cause of Restart?](#what-is-the-cause-of-restart)
* [Exception](#exception)
* [Watchdog](#watchdog)
* [Check Where the Code Crashes](#check-where-the-code-crashes)
* [If at the Wall, Enter an Issue Report](#if-at-the-wall-enter-an-issue-report)
* [Conclusion](#conclusion)
### Introduction
Your ESP is self restarting. You don't know why and what to do about it.
Do not panic.
In most of cases ESP provides enough clues on serial monitor, that you can interpret to pin down the root cause. The first step is then checking what ESP is saying on serial monitor when it crashes.
### What ESP has to Say
Start off by opening a Serial Monitor (Ctrl+Shift+M) to observe the output. Typical crash log looks as follows:
![Typical crash log](pictures/a02-typical-crash-log.png)
Before rushing to copy and paste displayed code to Google, reflect for a while on the nature of observed restarts:
* Does ESP restart on random basis, or under certain conditions, like serving a web page?
* Do you see always the same exception code and stack trace or it changes?
* Does this issue occur with unmodified standard example code (Arduino IDE > *File > Examples*)?
If restarts are random or the exception code differs between restarts, then the problem may be caused by h/w. If the issue occurs for standard examples and stable [esp8266 / arduino](https://github.com/esp8266/Arduino) core, them the issue is almost certainly caused by h/w.
### Get Your H/W Right
If you suspect the h/w, before troubleshooting the s/w, make sure to get your h/w right. There is no much sense in diagnosing the s/w if you board is randomly crashing because of not enough power, missing boot strapping resistors or loose connections.
If you are using generic ESP modules, please follow [recommendations](Generic ESP8266 modules) on power supply and boot strapping resistors.
For boards with integrated USB to serial converter and power supply, usually it is enough to connect it to an USB hub that provides standard 0.5A and is not shared with other USB devices.
In any case make sure that your module is able to stable run standard example sketches that establish Wi-Fi connection like e.g. [HelloServer.ino](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer/examples/HelloServer).
### What is the Cause of Restart?
You have verified that the ESP h/w is healthy but it still restarts. This is how ESP reacts to abnormal behavior of application. If something is wrong, it restarts itself to tell you about it.
There are two typical scenarios that trigger ESP restarts:
* **Exception** - when code is performing [illegal operation](https://github.com/esp8266/Arduino/blob/master/doc/exception_causes.md), like trying to write to non-existent memory location.
* **Watchdog** - if code is [locked up](https://en.wikipedia.org/wiki/Watchdog_timer) staying too long in a loop or processing some task, so vital processes like Wi-Fi communication are not able to run.
Please check below how to recognize [exception](#exception) and [watchdog](#watchdog) scenarios and what to do about it.
#### Exception
Typical restart because of exception looks like follows:
![Exception cause decoding](pictures/a02-exception-cause-decoding.png)
Start with looking up exception code in the [Exception Causes (EXCCAUSE)](https://github.com/esp8266/Arduino/blob/master/doc/exception_causes.md) table to understand what kind of issue it is. If you have no clues what it's about and where it happens, then use [Arduino ESP8266/ESP32 Exception Stack Trace Decoder](https://github.com/me-no-dev/EspExceptionDecoder) to find out in which line of application it is triggered. Please refer to [Check Where the Code Crashes](#check-where-the-code-crashes) point below for a quick example how to do it.
#### Watchdog
ESP provides two watchdog timers (wdt) that observe application for lock up.
* **Software Watchdog** - provided by [SDK](http://bbs.espressif.com/viewforum.php?f=46), that is part of [esp8266 / arduino](https://github.com/esp8266/Arduino) core loaded to module together with your application.
* **Hardware Watchdog** - build in ESP8266 hardware and acting if software watchdog is disabled for too long, in case it fails, or if it is not provided at all.
Restart by particular type of watchdog is clearly identified by ESP on serial monitor.
An example of application crash triggered by software wdt is shown below.
![Example of restart by s/w watchdog](pictures/a02-sw-watchdog-example.png)
Restart by the software watchdog is generally easier to troubleshoot since log includes the stack trace. The trace can be then used to find particular line in code where wdt has been triggered.
Reset by hardware watchdog timer is shown on picture below.
![Example of restart by h/w watchdog](pictures/a02-hw-watchdog-example.png)
Hardware wdt is the last resort of ESP to tell you that application is locked up (if s/w wdt timer is disabled or not working).
Please note that for restarts initialized by h/w wdt, there is no stack trace to help you identify the place in code where the lockup has happened. In such case, to identify the place of lock up, you need to rely on debug messages like ``` Serial.print ``` distributed across the application. Then by observing what was the last debug message printed out before restart, you should be able to narrow down part of code firing the h/w wdt reset. If diagnosed application or library has debug option then switch it on to aid this troubleshooting.
### Check Where the Code Crashes
Decoding of ESP stack trace is now easy and available to everybody thanks to great [Arduino ESP8266/ESP32 Exception Stack Trace Decoder](https://github.com/me-no-dev/EspExceptionDecoder) developed by @me-no-dev.
Installation for Arduino IDE is quick and easy following the [installation](https://github.com/me-no-dev/EspExceptionDecoder#installation) instructions.
If you don't have any code for troubleshooting, use the example below:
```
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.println("Let's provoke the s/w wdt firing...");
//
// wait for s/w wdt in infinite loop below
//
while(true);
//
Serial.println("This line will not ever print out");
}
void loop(){}
```
Upload this code to your ESP (Ctrl+U) and start Serial Monitor (Ctrl+Shift+M). You should shortly see ESP restarting every couple of seconds and ``` Soft WDT reset ``` message together with stack trace showing up on each restart. Click the Autoscroll check-box on Serial Monitor to stop the messages scrolling up. Select and copy the stack trace, go to the *Tools* and open the *ESP Exception Decoder*.
![Decode the stack trace, steps 1 and 2](pictures/a02-decode-stack-tace-1-2.png)
Now paste the stack trace to Exception Decoder's window. At the bottom of this window you should see a list of decoded lines of sketch you have just uploaded to your ESP. On the top of the list, like on the top of the stack trace, there is a reference to the last line executed just before the software watchdog timer fired causing the ESP's restart. Check the number of this line and look it up on the sketch. It should be the line ``` Serial.println("Let's provoke the s/w wdt firing...") ```, that happens to be just before ``` while(true) ``` that made the watchdog fired (ignore the lines with comments, that are discarded by compiler).
![Decode the stack trace, steps 3 through 6](pictures/a02-decode-stack-tace-3-6.png)
Armed with [Arduino ESP8266/ESP32 Exception Stack Trace Decoder](https://github.com/me-no-dev/EspExceptionDecoder) you can track down where the module is crashing whenever you see the stack trace dropped. The same procedure applies to crashes caused by exceptions.
> Note: To decode the exact line of code where the application crashed, you need to use ESP Exception Decoder in context of sketch you have just loaded to the module for diagnosis. Decoder is not able to correctly decode the stack trace dropped by some other application not compiled and loaded from your Arduino IDE.
### If at the Wall, Enter an Issue Report
Using the procedure above you should be able to troubleshoot all the code you write. It may happen that ESP is crashing inside some library or code you are not familiar enough to troubleshoot. If this is the case then contact the application author by writing an issue report.
Follow the guidelines on issue reporting that may be provided by the author of code in his / her repository.
If there are no guidelines, include in your report the following:
* [ ] Exact steps by step instructions to reproduce the issue
* [ ] Your exact hardware configuration including the schematic
* [ ] If the issue concerns standard, commercially available ESP board with power supply and USB interface, without extra h/w attached, then provide just the board type or link to description
* [ ] Configuration settings in Arduino IDE used to upload the application
* [ ] Error log & messages produced by the application (enable debugging for more details)
* [ ] Decoded stack trace
* [ ] Copy of your sketch
* [ ] Copy of all the libraries used by the sketch
* [ ] If you are using standard libraries available in Library Manager, then provide just version numbers
* [ ] Version of [esp8266 / Arduino](https://github.com/esp8266/Arduino) core
* [ ] Name and version of your programming IDE and O/S
With plenty of ESP module types available, several versions of libraries or [esp8266 / Arduino](https://github.com/esp8266/Arduino) core, types and versions of O/S, you need to provide exact information what your application is about. Only then people willing to look into your issue may be able to refer it to configuration they have. If you are lucky, they may even attempt to reproduce your issue on their equipment. This will be far more difficult if you are providing only vague details, so somebody would need to ask you to find out what is really happening.
On the other hand if you flood your issue report with hundreds lines of code, you may also have difficulty to find somebody willing to analyze it. Therefore reduce your code to the bare minimum that is still causing the issue. It will help you as well to isolate the issue and pin done the root cause.
### Conclusion
Do not be afraid to troubleshoot ESP exception and watchdog restarts. [Esp8266 / Arduino](https://github.com/esp8266/Arduino) core provides detailed diagnostics that will help you pin down the issue. Before checking the s/w, get your h/w right. Use [ESP Exception Decoder](https://github.com/me-no-dev/EspExceptionDecoder) to find out where the code fails. If you do you homework and still unable to identify the root cause, enter the issue report. Provide enough details. Be specific and isolate the issue. Then ask community for support. There are plenty of people that like to work with ESP and willing to help with your problem.
[FAQ list :back:](readme.md)

292
doc/faq/a02-my-esp-crashes.rst Normal file
View File

@ -0,0 +1,292 @@
:orphan:
My ESP crashes running some code. How to troubleshoot it?
---------------------------------------------------------
- `Introduction <#introduction>`__
- `What ESP has to Say <#what-esp-has-to-say>`__
- `Get Your H/W Right <#get-your-hw-right>`__
- `What is the Cause of Restart? <#what-is-the-cause-of-restart>`__
- `Exception <#exception>`__
- `Watchdog <#watchdog>`__
- `Check Where the Code Crashes <#check-where-the-code-crashes>`__
- `If at the Wall, Enter an Issue
Report <#if-at-the-wall-enter-an-issue-report>`__
- `Conclusion <#conclusion>`__
Introduction
~~~~~~~~~~~~
Your ESP is self restarting. You don't know why and what to do about it.
Do not panic.
In most of cases ESP provides enough clues on serial monitor, that you
can interpret to pin down the root cause. The first step is then
checking what ESP is saying on serial monitor when it crashes.
What ESP has to Say
~~~~~~~~~~~~~~~~~~~
Start off by opening a Serial Monitor (Ctrl+Shift+M) to observe the
output. Typical crash log looks as follows:
.. figure:: pictures/a02-typical-crash-log.png
:alt: Typical crash log
Typical crash log
Before rushing to copy and paste displayed code to Google, reflect for a
while on the nature of observed restarts:
- Does ESP restart on random basis, or under certain conditions, like
serving a web page?
- Do you see always the same exception code and stack trace or it
changes?
- Does this issue occur with unmodified standard example code (Arduino
IDE > *File > Examples*)?
If restarts are random or the exception code differs between restarts,
then the problem may be caused by h/w. If the issue occurs for standard
examples and stable `esp8266 /
arduino <https://github.com/esp8266/Arduino>`__ core, them the issue is
almost certainly caused by h/w.
Get Your H/W Right
~~~~~~~~~~~~~~~~~~
If you suspect the h/w, before troubleshooting the s/w, make sure to get
your h/w right. There is no much sense in diagnosing the s/w if you
board is randomly crashing because of not enough power, missing boot
strapping resistors or loose connections.
If you are using generic ESP modules, please follow
`recommendations <Generic%20ESP8266%20modules>`__ on power supply and
boot strapping resistors.
For boards with integrated USB to serial converter and power supply,
usually it is enough to connect it to an USB hub that provides standard
0.5A and is not shared with other USB devices.
In any case make sure that your module is able to stable run standard
example sketches that establish Wi-Fi connection like e.g.
`HelloServer.ino <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer/examples/HelloServer>`__.
What is the Cause of Restart?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You have verified that the ESP h/w is healthy but it still restarts.
This is how ESP reacts to abnormal behavior of application. If something
is wrong, it restarts itself to tell you about it.
There are two typical scenarios that trigger ESP restarts:
- **Exception** - when code is performing `illegal
operation <https://github.com/esp8266/Arduino/blob/master/doc/exception_causes.md>`__,
like trying to write to non-existent memory location.
- **Watchdog** - if code is `locked
up <https://en.wikipedia.org/wiki/Watchdog_timer>`__ staying too long
in a loop or processing some task, so vital processes like Wi-Fi
communication are not able to run.
Please check below how to recognize `exception <#exception>`__ and
`watchdog <#watchdog>`__ scenarios and what to do about it.
Exception
^^^^^^^^^
Typical restart because of exception looks like follows:
.. figure:: pictures/a02-exception-cause-decoding.png
:alt: Exception cause decoding
Exception cause decoding
Start with looking up exception code in the `Exception Causes
(EXCCAUSE) <https://github.com/esp8266/Arduino/blob/master/doc/exception_causes.md>`__
table to understand what kind of issue it is. If you have no clues what
it's about and where it happens, then use `Arduino ESP8266/ESP32
Exception Stack Trace
Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ to find
out in which line of application it is triggered. Please refer to `Check
Where the Code Crashes <#check-where-the-code-crashes>`__ point below
for a quick example how to do it.
Watchdog
^^^^^^^^
ESP provides two watchdog timers (wdt) that observe application for lock
up.
- **Software Watchdog** - provided by
`SDK <http://bbs.espressif.com/viewforum.php?f=46>`__, that is part
of `esp8266 / arduino <https://github.com/esp8266/Arduino>`__ core
loaded to module together with your application.
- **Hardware Watchdog** - build in ESP8266 hardware and acting if
software watchdog is disabled for too long, in case it fails, or if
it is not provided at all.
Restart by particular type of watchdog is clearly identified by ESP on
serial monitor.
An example of application crash triggered by software wdt is shown
below.
.. figure:: pictures/a02-sw-watchdog-example.png
:alt: Example of restart by s/w watchdog
Example of restart by s/w watchdog
Restart by the software watchdog is generally easier to troubleshoot
since log includes the stack trace. The trace can be then used to find
particular line in code where wdt has been triggered.
Reset by hardware watchdog timer is shown on picture below.
.. figure:: pictures/a02-hw-watchdog-example.png
:alt: Example of restart by h/w watchdog
Example of restart by h/w watchdog
Hardware wdt is the last resort of ESP to tell you that application is
locked up (if s/w wdt timer is disabled or not working).
Please note that for restarts initialized by h/w wdt, there is no stack
trace to help you identify the place in code where the lockup has
happened. In such case, to identify the place of lock up, you need to
rely on debug messages like ``Serial.print`` distributed across the
application. Then by observing what was the last debug message printed
out before restart, you should be able to narrow down part of code
firing the h/w wdt reset. If diagnosed application or library has debug
option then switch it on to aid this troubleshooting.
Check Where the Code Crashes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Decoding of ESP stack trace is now easy and available to everybody
thanks to great `Arduino ESP8266/ESP32 Exception Stack Trace
Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ developed
by @me-no-dev.
Installation for Arduino IDE is quick and easy following the
`installation <https://github.com/me-no-dev/EspExceptionDecoder#installation>`__
instructions.
If you don't have any code for troubleshooting, use the example below:
::
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.println("Let's provoke the s/w wdt firing...");
//
// wait for s/w wdt in infinite loop below
//
while(true);
//
Serial.println("This line will not ever print out");
}
void loop(){}
Upload this code to your ESP (Ctrl+U) and start Serial Monitor
(Ctrl+Shift+M). You should shortly see ESP restarting every couple of
seconds and ``Soft WDT reset`` message together with stack trace showing
up on each restart. Click the Autoscroll check-box on Serial Monitor to
stop the messages scrolling up. Select and copy the stack trace, go to
the *Tools* and open the *ESP Exception Decoder*.
.. figure:: pictures/a02-decode-stack-tace-1-2.png
:alt: Decode the stack trace, steps 1 and 2
Decode the stack trace, steps 1 and 2
Now paste the stack trace to Exception Decoder's window. At the bottom
of this window you should see a list of decoded lines of sketch you have
just uploaded to your ESP. On the top of the list, like on the top of
the stack trace, there is a reference to the last line executed just
before the software watchdog timer fired causing the ESP's restart.
Check the number of this line and look it up on the sketch. It should be
the line ``Serial.println("Let's provoke the s/w wdt firing...")``, that
happens to be just before ``while(true)`` that made the watchdog fired
(ignore the lines with comments, that are discarded by compiler).
.. figure:: pictures/a02-decode-stack-tace-3-6.png
:alt: Decode the stack trace, steps 3 through 6
Decode the stack trace, steps 3 through 6
Armed with `Arduino ESP8266/ESP32 Exception Stack Trace
Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ you can
track down where the module is crashing whenever you see the stack trace
dropped. The same procedure applies to crashes caused by exceptions.
Note: To decode the exact line of code where the application
crashed, you need to use ESP Exception Decoder in context of sketch
you have just loaded to the module for diagnosis. Decoder is not
able to correctly decode the stack trace dropped by some other
application not compiled and loaded from your Arduino IDE.
If at the Wall, Enter an Issue Report
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using the procedure above you should be able to troubleshoot all the
code you write. It may happen that ESP is crashing inside some library
or code you are not familiar enough to troubleshoot. If this is the case
then contact the application author by writing an issue report.
Follow the guidelines on issue reporting that may be provided by the
author of code in his / her repository.
If there are no guidelines, include in your report the following:
- [ ] Exact steps by step instructions to reproduce the issue
- [ ] Your exact hardware configuration including the schematic
- [ ] If the issue concerns standard, commercially available ESP board
with power supply and USB interface, without extra h/w attached, then
provide just the board type or link to description
- [ ] Configuration settings in Arduino IDE used to upload the
application
- [ ] Error log & messages produced by the application (enable
debugging for more details)
- [ ] Decoded stack trace
- [ ] Copy of your sketch
- [ ] Copy of all the libraries used by the sketch
- [ ] If you are using standard libraries available in Library Manager,
then provide just version numbers
- [ ] Version of `esp8266 /
Arduino <https://github.com/esp8266/Arduino>`__ core
- [ ] Name and version of your programming IDE and O/S
With plenty of ESP module types available, several versions of libraries
or `esp8266 / Arduino <https://github.com/esp8266/Arduino>`__ core,
types and versions of O/S, you need to provide exact information what
your application is about. Only then people willing to look into your
issue may be able to refer it to configuration they have. If you are
lucky, they may even attempt to reproduce your issue on their equipment.
This will be far more difficult if you are providing only vague details,
so somebody would need to ask you to find out what is really happening.
On the other hand if you flood your issue report with hundreds lines of
code, you may also have difficulty to find somebody willing to analyze
it. Therefore reduce your code to the bare minimum that is still causing
the issue. It will help you as well to isolate the issue and pin done
the root cause.
Conclusion
~~~~~~~~~~
Do not be afraid to troubleshoot ESP exception and watchdog restarts.
`Esp8266 / Arduino <https://github.com/esp8266/Arduino>`__ core provides
detailed diagnostics that will help you pin down the issue. Before
checking the s/w, get your h/w right. Use `ESP Exception
Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ to find
out where the code fails. If you do you homework and still unable to
identify the root cause, enter the issue report. Provide enough details.
Be specific and isolate the issue. Then ask community for support. There
are plenty of people that like to work with ESP and willing to help with
your problem.
`FAQ list :back: <readme.md>`__

85
doc/faq/a03-library-does-not-work.md
View File

@ -1,85 +0,0 @@
---
title: Frequently Asked Questions / Troubleshooting
---
[FAQ list :back:](readme.md)
## This Arduino library doesn't work on ESP. How do I make it working?
* [Introduction](#introduction)
* [Identify the Issues](#identify-the-issues)
* [Fix it Yourself](#fix-it-yourself)
* [Compilation Errors](#compilation-errors)
* [Exceptions / Watchdog Resets](#exceptions--watchdog-resets)
* [Functionality Issues](#functionality-issues)
* [Conclusion](#conclusion)
### Introduction
You would like to use this Arduino library with ESP8266 and it doesn't perform. It is not listed among [libraries verified to work with ESP8266](../doc/libraries.md#other-libraries-not-included-with-the-ide). You couldn't find any evidence on internet that it is compatible.
What are the odds to make it working?
### Identify the Issues
Start with looking for all the symptoms that it is not compatible with ESP8266. Ideally use example sketches provided with the library. Then list all the issues you are able to identify.
You are likely to see one or more of the following:
* Compilation drops errors
* There are no issues with compilation but application restarts because of exception or watchdog (wdt)
* Application seems to work, but does not function as expected, e.g. calculation results are incorrect.
Armed with the list of issues, contact the library author asking for comments. If issues are legitimate, then ask for his / her support to implement it for ESP8266. Being specific you have bigger chances convincing the author to help you either by updating the library or guiding you how to resolve the issues.
### Fix it Yourself
If library author is unable to provide support, then assess the chances of fixing it yourself.
#### Compilation Errors
*Issue:* Compiler complains about usage of AVR registers (PORTx, PINx, TCR1A, etc).
*Solution:* Check if usage of registers is well localized in a few functions, try to replace GPIO registers usage with digitalRead / digitalWrite, timer registers usage with timerX_ functions. If usage of AVR registers happens all over the code, this library might not be worth the effort. Also may be worth checking if someone got the library working on ARM (Due/STM), PIC, etc. If this is the case, maybe there already is a version of the library which uses Arduino APIs instead of raw registers.
*Issue:* Compiler complains about ``` <avr/pgmspace.h> ```.
*Solution:* modify the library by adding conditional include of ESP's pgmspace.h.
```
#ifdef ESP8266
#include <pgmspace.h>
#else
#include <avr/pgmspace.h>
#endif
```
#### Exceptions / Watchdog Resets
To troubleshoot resets follow FAQ item [My ESP crashes running some code](a02-my-esp-crashes.md).
#### Functionality Issues
*Issue:* Application works but returns weird numerical values.
*Solution:*: Check the usage of `int` type in the library. On AVRs integers are 16 bit, and on ESPs they are 32 bit (just like on ARM).
*Issue:* Some device with time critical control like a servo drive or a strip pf LEDs does not operate smoothly and tends to randomly change position or displayed pattern.
*Solution:*: Check for usage of interrupts that may get in conflict with Wi-Fi activity of ESP8266. You may temporarily disable Wi-Fi communication ``` WiFi.mode(WIFI_OFF); ``` to check if it helps.
### Conclusion
Identify compatibility issues and ask library author for support. If left on your own, then check for usage of controller's low level access functionality. Use [Esp Exception Decoder](https://github.com/me-no-dev/EspExceptionDecoder) if confronted with exceptions / watchdogs resets.
The good news is that the number of libraries which aren't supported on the ESP8266 is shrinking. Community of ESP8266 enthusiasts is growing. If you are unable to resolve the issues yourself, there are very good odds that you will be able to find somebody else to help you.
[FAQ list :back:](readme.md)

112
doc/faq/a03-library-does-not-work.rst Normal file
View File

@ -0,0 +1,112 @@
:orphan:
This Arduino library doesn't work on ESP. How do I make it working?
-------------------------------------------------------------------
- `Introduction <#introduction>`__
- `Identify the Issues <#identify-the-issues>`__
- `Fix it Yourself <#fix-it-yourself>`__
- `Compilation Errors <#compilation-errors>`__
- `Exceptions / Watchdog Resets <#exceptions--watchdog-resets>`__
- `Functionality Issues <#functionality-issues>`__
- `Conclusion <#conclusion>`__
Introduction
~~~~~~~~~~~~
You would like to use this Arduino library with ESP8266 and it doesn't
perform. It is not listed among `libraries verified to work with
ESP8266 <../doc/libraries.md#other-libraries-not-included-with-the-ide>`__.
You couldn't find any evidence on internet that it is compatible.
What are the odds to make it working?
Identify the Issues
~~~~~~~~~~~~~~~~~~~
Start with looking for all the symptoms that it is not compatible with
ESP8266. Ideally use example sketches provided with the library. Then
list all the issues you are able to identify.
You are likely to see one or more of the following: \* Compilation drops
errors \* There are no issues with compilation but application restarts
because of exception or watchdog (wdt) \* Application seems to work, but
does not function as expected, e.g. calculation results are incorrect.
Armed with the list of issues, contact the library author asking for
comments. If issues are legitimate, then ask for his / her support to
implement it for ESP8266. Being specific you have bigger chances
convincing the author to help you either by updating the library or
guiding you how to resolve the issues.
Fix it Yourself
~~~~~~~~~~~~~~~
If library author is unable to provide support, then assess the chances
of fixing it yourself.
Compilation Errors
^^^^^^^^^^^^^^^^^^
*Issue:* Compiler complains about usage of AVR registers (PORTx, PINx,
TCR1A, etc).
*Solution:* Check if usage of registers is well localized in a few
functions, try to replace GPIO registers usage with digitalRead /
digitalWrite, timer registers usage with timerX\_ functions. If usage of
AVR registers happens all over the code, this library might not be worth
the effort. Also may be worth checking if someone got the library
working on ARM (Due/STM), PIC, etc. If this is the case, maybe there
already is a version of the library which uses Arduino APIs instead of
raw registers.
*Issue:* Compiler complains about ``<avr/pgmspace.h>``.
*Solution:* modify the library by adding conditional include of ESP's
pgmspace.h.
::
#ifdef ESP8266
#include <pgmspace.h>
#else
#include <avr/pgmspace.h>
#endif
Exceptions / Watchdog Resets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To troubleshoot resets follow FAQ item `My ESP crashes running some
code <a02-my-esp-crashes.md>`__.
Functionality Issues
^^^^^^^^^^^^^^^^^^^^
*Issue:* Application works but returns weird numerical values.
*Solution:*: Check the usage of ``int`` type in the library. On AVRs
integers are 16 bit, and on ESPs they are 32 bit (just like on ARM).
*Issue:* Some device with time critical control like a servo drive or a
strip pf LEDs does not operate smoothly and tends to randomly change
position or displayed pattern.
*Solution:*: Check for usage of interrupts that may get in conflict with
Wi-Fi activity of ESP8266. You may temporarily disable Wi-Fi
communication ``WiFi.mode(WIFI_OFF);`` to check if it helps.
Conclusion
~~~~~~~~~~
Identify compatibility issues and ask library author for support. If
left on your own, then check for usage of controller's low level access
functionality. Use `Esp Exception
Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ if
confronted with exceptions / watchdogs resets.
The good news is that the number of libraries which aren't supported on
the ESP8266 is shrinking. Community of ESP8266 enthusiasts is growing.
If you are unable to resolve the issues yourself, there are very good
odds that you will be able to find somebody else to help you.
`FAQ list :back: <readme.md>`__

99
doc/faq/a04-board-generic-is-unknown.md
View File

@ -1,99 +0,0 @@
---
title: Frequently Asked Questions / Troubleshooting
---
[FAQ list :back:](readme.md)
## How to resolve "Board generic (platform esp8266, package esp8266) is unknown" error?
This error may pop up after switching between [staging](https://github.com/esp8266/Arduino#staging-version-) and [stable](https://github.com/esp8266/Arduino#stable-version-) esp8266 / Arduino package installations, or after upgrading the package version.
![alt text](pictures/a04-board-is-unknown-error.png "Board nodemcu2 (platform esp8266, package esp8266) is unknown error")
If you face this issue, you will not be able to compile any sketch for any ESP8266 module type.
Read below what is the error root cause or jump straight to the [resolution](#how-to-fix-it)
### The Root Cause
This issue is attributed to Arduino IDE Boards Manager not cleaning up previous package installation before a new one is applied. As this is not done, then it is user responsibility to remove previous package before applying a new one.
To prevent it from happening, if you are changing between **staging** and **stable**, first press *Remove* button to delete currently used installation.
![alt text](pictures/a04-remove-package-yes.png "If changing between staging and stable, remove currently installed package")
There is no need to remove the installed package if you are changing it to another version (without switching between staging and stable).
![alt text](pictures/a04-remove-package-no.png "No need to remove installed package if changing its version")
Depending on selected module the error message is slightly different. For instance, if you choose *Generic ESP8266 Module*, it will look as follows:
```
Board generic (platform esp8266, package esp8266) is unknown
Error compiling for board Generic ESP8266 Module.
```
Below is an example messages for [WeMos](https://github.com/esp8266/Arduino/blob/master/doc/boards.md#wemos-d1):
```
Board d1_mini (platform esp8266, package esp8266) is unknown
Error compiling for board WeMos D1 R2 & mini.
```
... and another one for [Adafruit HUZZAH](https://github.com/esp8266/Arduino/blob/master/doc/boards.md#adafruit-huzzah-esp8266-esp-12):
```
Board huzzah (platform esp8266, package esp8266) is unknown
Error compiling for board Adafruit HUZZAH ESP8266.
```
If the issue already happens, then uninstalling and re-installing the package with *Boards Manager* typically will not fix it.
Uninstalling and re-installing the Arduino IDE will not fix it as well.
Well, OK, fine. You will be able to fix it with Boards Manager. To do so, you need to carefully go step by step through the effort of removing new and then the old package. Once done you can install again the new package. Did I mention that in between you need to change twice [JOSN](https://github.com/esp8266/Arduino#installing-with-boards-manager) in *Additional Boards Manager URLs*?
Fortunately there is a quicker and more effective fix. See below.
### How to Fix it?
Issue resolution is as simple as deleting a folder with older esp8266 / Arduino installation.
Procedure is identical on Windows, Linux and Mac OS. The only difference is folder path. For instance, on Mac, it will be `/Users/$USER/Library/Arduino15/packages/esp8266/hardware/esp8266`. Example below shows the path for Windows.
1. Check location of installation folder by going to *File > Preferences* (Ctrl+,). The folder location is at the very bottom of the *Preferences* window.
![alt text](pictures/a04-arduino-ide-preferences.png "Checking of Arduino IDE Preferences")
2. Click provided link to open the folder. For Windows 7 it will look as follows:
![alt text](pictures/a04-contents-of-preferences-folder.png "Contents of Arduino IDE preferences folder")
3. Navigate further down to `Arduino15\packages\esp8266\hardware\esp8266` directory. Inside you will find two folders with different esp8266 / Arduino package installations.
![alt text](pictures/a04-contents-of-package-folder.png "Checking of contents of esp8266 / Arduino package folder")
4. Delete the older folder. Restart Arduino IDE, select your ESP module and the error should be gone.
Note: If you are not sure which folder to delete, then remove both of them. Restart Arduino IDE, go to *Tools > Board: > Boards Manager* and install the esp8266 / Arduino package again. Select ESP8266 module and the issue should be resolved.
### More Information
This issue has been reported quite frequently in [Issues](https://github.com/esp8266/Arduino/issues) section of esp8266 / Arduino repository. The most appreciated solution was provided by [@anhhuy0501](https://github.com/anhhuy0501) in
[#1387](https://github.com/esp8266/Arduino/issues/1387#issuecomment-204865028).
If you are interested in more details, please refer to [#2297](https://github.com/esp8266/Arduino/issues/2297),
[#2156](https://github.com/esp8266/Arduino/issues/2156),
[#2022](https://github.com/esp8266/Arduino/issues/2022),
[#1802](https://github.com/esp8266/Arduino/issues/1802),
[#1514](https://github.com/esp8266/Arduino/issues/1514),
[#1387](https://github.com/esp8266/Arduino/issues/1387),
[#1377](https://github.com/esp8266/Arduino/issues/1377),
[#1251](https://github.com/esp8266/Arduino/issues/1251),
[#1247](https://github.com/esp8266/Arduino/issues/1247),
[#948](https://github.com/esp8266/Arduino/issues/948)

151
doc/faq/a04-board-generic-is-unknown.rst Normal file
View File

@ -0,0 +1,151 @@
:orphan:
How to resolve "Board generic (platform esp8266, package esp8266) is unknown" error?
------------------------------------------------------------------------------------
This error may pop up after switching between
`staging <https://github.com/esp8266/Arduino#staging-version->`__ and
`stable <https://github.com/esp8266/Arduino#stable-version->`__ esp8266
/ Arduino package installations, or after upgrading the package version.
.. figure:: pictures/a04-board-is-unknown-error.png
:alt: Board nodemcu2 (platform esp8266, package esp8266) is unknown error
alt text
If you face this issue, you will not be able to compile any sketch for
any ESP8266 module type.
Read below what is the error root cause or jump straight to the
`resolution <#how-to-fix-it>`__
The Root Cause
~~~~~~~~~~~~~~
This issue is attributed to Arduino IDE Boards Manager not cleaning up
previous package installation before a new one is applied. As this is
not done, then it is user responsibility to remove previous package
before applying a new one.
To prevent it from happening, if you are changing between **staging**
and **stable**, first press *Remove* button to delete currently used
installation.
.. figure:: pictures/a04-remove-package-yes.png
:alt: If changing between staging and stable, remove currently installed package
alt text
There is no need to remove the installed package if you are changing it
to another version (without switching between staging and stable).
.. figure:: pictures/a04-remove-package-no.png
:alt: No need to remove installed package if changing its version
alt text
Depending on selected module the error message is slightly different.
For instance, if you choose *Generic ESP8266 Module*, it will look as
follows:
::
Board generic (platform esp8266, package esp8266) is unknown
Error compiling for board Generic ESP8266 Module.
Below is an example messages for
`WeMos <https://github.com/esp8266/Arduino/blob/master/doc/boards.md#wemos-d1>`__:
::
Board d1_mini (platform esp8266, package esp8266) is unknown
Error compiling for board WeMos D1 R2 & mini.
... and another one for `Adafruit
HUZZAH <https://github.com/esp8266/Arduino/blob/master/doc/boards.md#adafruit-huzzah-esp8266-esp-12>`__:
::
Board huzzah (platform esp8266, package esp8266) is unknown
Error compiling for board Adafruit HUZZAH ESP8266.
If the issue already happens, then uninstalling and re-installing the
package with *Boards Manager* typically will not fix it.
Uninstalling and re-installing the Arduino IDE will not fix it as well.
Well, OK, fine. You will be able to fix it with Boards Manager. To do
so, you need to carefully go step by step through the effort of removing
new and then the old package. Once done you can install again the new
package. Did I mention that in between you need to change twice
`JOSN <https://github.com/esp8266/Arduino#installing-with-boards-manager>`__
in *Additional Boards Manager URLs*?
Fortunately there is a quicker and more effective fix. See below.
How to Fix it?
~~~~~~~~~~~~~~
Issue resolution is as simple as deleting a folder with older esp8266 /
Arduino installation.
Procedure is identical on Windows, Linux and Mac OS. The only difference
is folder path. For instance, on Mac, it will be
``/Users/$USER/Library/Arduino15/packages/esp8266/hardware/esp8266``.
Example below shows the path for Windows.
1. Check location of installation folder by going to *File >
Preferences* (Ctrl+,). The folder location is at the very bottom of
the *Preferences* window.
.. figure:: pictures/a04-arduino-ide-preferences.png
:alt: Checking of Arduino IDE Preferences
alt text
2. Click provided link to open the folder. For Windows 7 it will look as
follows:
.. figure:: pictures/a04-contents-of-preferences-folder.png
:alt: Contents of Arduino IDE preferences folder
alt text
3. Navigate further down to
``Arduino15\packages\esp8266\hardware\esp8266`` directory. Inside you
will find two folders with different esp8266 / Arduino package
installations.
.. figure:: pictures/a04-contents-of-package-folder.png
:alt: Checking of contents of esp8266 / Arduino package folder
alt text
4. Delete the older folder. Restart Arduino IDE, select your ESP module
and the error should be gone.
Note: If you are not sure which folder to delete, then remove both of
them. Restart Arduino IDE, go to *Tools > Board: > Boards Manager* and
install the esp8266 / Arduino package again. Select ESP8266 module and
the issue should be resolved.
More Information
~~~~~~~~~~~~~~~~
This issue has been reported quite frequently in
`Issues <https://github.com/esp8266/Arduino/issues>`__ section of
esp8266 / Arduino repository. The most appreciated solution was provided
by [@anhhuy0501](https://github.com/anhhuy0501) in
`#1387 <https://github.com/esp8266/Arduino/issues/1387#issuecomment-204865028>`__.
If you are interested in more details, please refer to
`#2297 <https://github.com/esp8266/Arduino/issues/2297>`__,
`#2156 <https://github.com/esp8266/Arduino/issues/2156>`__,
`#2022 <https://github.com/esp8266/Arduino/issues/2022>`__,
`#1802 <https://github.com/esp8266/Arduino/issues/1802>`__,
`#1514 <https://github.com/esp8266/Arduino/issues/1514>`__,
`#1387 <https://github.com/esp8266/Arduino/issues/1387>`__,
`#1377 <https://github.com/esp8266/Arduino/issues/1377>`__,
`#1251 <https://github.com/esp8266/Arduino/issues/1251>`__,
`#1247 <https://github.com/esp8266/Arduino/issues/1247>`__,
`#948 <https://github.com/esp8266/Arduino/issues/948>`__

50
doc/faq/readme.md
View File

@ -1,50 +0,0 @@
---
title: Frequently Asked Questions / Troubleshooting
---
The purpose of this FAQ / Troubleshooting is to respond to questions commonly asked in [Issues](https://github.com/esp8266/Arduino/issues) section and on [ESP8266 Community forum](http://www.esp8266.com/).
Where possible we are going right to the answer and provide it within one or two paragraphs. If it takes more than that, you will see a link :arrow_right: to more details.
Please feel free to contribute if you believe that some frequent issues are not covered below.
### I am getting "espcomm_sync failed" error when trying to upload my ESP. How to resolve this issue?
This message indicates issue with uploading ESP module over a serial connection. There are couple of possible causes, that depend on the type of your module, if you use separate USB to serial converter [:arrow_right:](a01-espcomm_sync-failed.md)
### Why esptool is not listed in "Programmer" menu? How do I upload ESP without it?
Do not worry about "Programmer" menu of Arduino IDE. It doesn't matter what is selected in it — upload now always defaults to using esptool.
Ref. [#138](https://github.com/esp8266/Arduino/issues/138), [#653](https://github.com/esp8266/Arduino/issues/653) and [#739](https://github.com/esp8266/Arduino/issues/739).
### My ESP crashes running some code. How to troubleshoot it?
The code may crash because of s/w bug or issue with your h/w. Before entering an issue report, please perform initial troubleshooting [:arrow_right:](a02-my-esp-crashes.md)
### This Arduino library doesn't work on ESP. How do I make it working?
You would like to use this Arduino library with ESP8266 and it does not perform. It is not listed among libraries verified to work with ESP8266 [:arrow_right:](a03-library-does-not-work.md)
### In the IDE, for ESP-12E that has 4M flash, I can choose 4M (1M SPIFFS) or 4M (3M SPIFFS). No matter what I select, the IDE tells me the maximum code space is about 1M. Where does my flash go?
The reason we cannot have more than 1MB of code in flash has to do with a hardware limitation. Flash cache hardware on the ESP8266 only allows mapping 1MB of code into the CPU address space at any given time. You can switch mapping offset, so technically you can have more than 1MB total, but switching such "banks" on the fly is not easy and efficient, so we don't bother doing that. Besides, no one has so far complained about 1MB of code space being insufficient for practical purposes.
The option to choose 4M or 1M SPIFFS is to optimize the upload time. Uploading 3MB takes a long time so sometimes you can just use 1MB. Other 2MB of flash can still be used with ``` ESP.flashRead ``` and ``` ESP.flashWrite ``` APIs if necessary.
### I have observed a case when ESP.restart() doesn't work. What is the reason for that?
You will see this issue only if serial upload was not followed by a physical reset (e.g. power-on reset). For a device being in that state `ESP.restart` will not work. Apparently the issue is caused by [one of internal registers not being properly updated until physical reset](https://github.com/esp8266/Arduino/issues/1017#issuecomment-200605576). This issue concerns only serial uploads. OTA uploads are not affected. If you are using `ESP.restart`, the work around is to reset ESP once after each serial upload.
Ref. [#1017](https://github.com/esp8266/Arduino/issues/1017), [#1107](https://github.com/esp8266/Arduino/issues/1107), [#1782](https://github.com/esp8266/Arduino/issues/1782)
### How to resolve "Board generic (platform esp8266, package esp8266) is unknown" error?
This error may pop up after switching between [staging](https://github.com/esp8266/Arduino#staging-version-) and [stable](https://github.com/esp8266/Arduino#stable-version-) esp8266 / Arduino package installations, or after upgrading the package version [:arrow_right:](a04-board-generic-is-unknown.md)

90
doc/faq/readme.rst Normal file
View File

@ -0,0 +1,90 @@
FAQ
===
The purpose of this FAQ / Troubleshooting is to respond to questions
commonly asked in `Issues <https://github.com/esp8266/Arduino/issues>`__
section and on `ESP8266 Community forum <http://www.esp8266.com/>`__.
Where possible we are going right to the answer and provide it within
one or two paragraphs. If it takes more than that, you will see a link
:arrow\_right: to more details.
Please feel free to contribute if you believe that some frequent issues
are not covered below.
I am getting "espcomm\_sync failed" error when trying to upload my ESP. How to resolve this issue?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This message indicates issue with uploading ESP module over a serial
connection. There are couple of possible causes, that depend on the type
of your module, if you use separate USB to serial converter.
:doc:`Read more <a01-espcomm_sync-failed>`.
Why esptool is not listed in "Programmer" menu? How do I upload ESP without it?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Do not worry about "Programmer" menu of Arduino IDE. It doesn't matter
what is selected in it — upload now always defaults to using esptool.
Ref. `#138 <https://github.com/esp8266/Arduino/issues/138>`__,
`#653 <https://github.com/esp8266/Arduino/issues/653>`__ and
`#739 <https://github.com/esp8266/Arduino/issues/739>`__.
My ESP crashes running some code. How to troubleshoot it?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The code may crash because of s/w bug or issue with your h/w. Before
entering an issue report, please perform initial troubleshooting.
:doc:`Read more <a02-my-esp-crashes>`.
This Arduino library doesn't work on ESP. How do I make it working?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You would like to use this Arduino library with ESP8266 and it does not
perform. It is not listed among libraries verified to work with ESP8266.
:doc:`Read more <a03-library-does-not-work>`.
In the IDE, for ESP-12E that has 4M flash, I can choose 4M (1M SPIFFS) or 4M (3M SPIFFS). No matter what I select, the IDE tells me the maximum code space is about 1M. Where does my flash go?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The reason we cannot have more than 1MB of code in flash has to do with
a hardware limitation. Flash cache hardware on the ESP8266 only allows
mapping 1MB of code into the CPU address space at any given time. You
can switch mapping offset, so technically you can have more than 1MB
total, but switching such "banks" on the fly is not easy and efficient,
so we don't bother doing that. Besides, no one has so far complained
about 1MB of code space being insufficient for practical purposes.
The option to choose 4M or 1M SPIFFS is to optimize the upload time.
Uploading 3MB takes a long time so sometimes you can just use 1MB. Other
2MB of flash can still be used with ``ESP.flashRead`` and
``ESP.flashWrite`` APIs if necessary.
I have observed a case when ESP.restart() doesn't work. What is the reason for that?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You will see this issue only if serial upload was not followed by a
physical reset (e.g. power-on reset). For a device being in that state
``ESP.restart`` will not work. Apparently the issue is caused by `one of
internal registers not being properly updated until physical
reset <https://github.com/esp8266/Arduino/issues/1017#issuecomment-200605576>`__.
This issue concerns only serial uploads. OTA uploads are not affected.
If you are using ``ESP.restart``, the work around is to reset ESP once
after each serial upload.
Ref. `#1017 <https://github.com/esp8266/Arduino/issues/1017>`__,
`#1107 <https://github.com/esp8266/Arduino/issues/1107>`__,
`#1782 <https://github.com/esp8266/Arduino/issues/1782>`__
How to resolve "Board generic (platform esp8266, package esp8266) is unknown" error?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This error may pop up after switching between
`staging <https://github.com/esp8266/Arduino#staging-version->`__ and
`stable <https://github.com/esp8266/Arduino#stable-version->`__ esp8266
/ Arduino package installations, or after upgrading the package version
:doc:`Read more <a04-board-generic-is-unknown>`.

308
doc/filesystem.md
View File

@ -1,308 +0,0 @@
---
title: File System
---
## Table of Contents
* [Flash layout](#flash-layout)
* [File system limitations](#file-system-limitations)
* [Uploading files to file system](#uploading-files-to-file-system)
* [File system object (SPIFFS)](#file-system-object-spiffs)
* [begin](#begin)
* [end](#end)
* [format](#format)
* [open](#open)
* [exists](#exists)
* [openDir](#opendir)
* [remove](#remove)
* [rename](#rename)
* [info](#info)
* [Filesystem information structure](#filesystem-information-structure)
* [Directory object (Dir)](#directory-object-dir)
* [File object](#file-object)
* [seek](#seek)
* [position](#position)
* [size](#size)
* [name](#name)
* [close](#close)
## Flash layout
Even though file system is stored on the same flash chip as the program, programming new sketch will not modify file system contents. This allows to use file system to store sketch data, configuration files, or content for Web server.
The following diagram illustrates flash layout used in Arduino environment:
|--------------|-------|---------------|--|--|--|--|--|
^ ^ ^ ^ ^
Sketch OTA update File system EEPROM WiFi config (SDK)
File system size depends on the flash chip size. Depending on the board which is selected in IDE, you have the following options for flash size:
Board | Flash chip size, bytes | File system size, bytes
------|-----------------|-----------------
Generic module | 512k | 64k, 128k
Generic module | 1M | 64k, 128k, 256k, 512k
Generic module | 2M | 1M
Generic module | 4M | 3M
Adafruit HUZZAH | 4M | 1M, 3M
ESPresso Lite 1.0 | 4M | 1M, 3M
ESPresso Lite 2.0 | 4M | 1M, 3M
NodeMCU 0.9 | 4M | 1M, 3M
NodeMCU 1.0 | 4M | 1M, 3M
Olimex MOD-WIFI-ESP8266(-DEV)| 2M | 1M
SparkFun Thing | 512k | 64k
SweetPea ESP-210 | 4M | 1M, 3M
WeMos D1 & D1 mini | 4M | 1M, 3M
ESPDuino | 4M | 1M, 3M
**Note:** to use any of file system functions in the sketch, add the following include to the sketch:
```c++
#include "FS.h"
```
## File system limitations
The filesystem implementation for ESP8266 had to accomodate the constraints of the chip, among which its limited RAM. [SPIFFS](https://github.com/pellepl/spiffs) was selected because it is designed for small systems, but that comes at the cost of some simplifications and limitations.
First, behind the scenes, SPIFFS does not support directories, it just stores a "flat" list of files.
But contrary to traditional filesystems, the slash character `'/'` is allowed in filenames, so the functions that deal with directory listing (e.g. `openDir("/website")`) basically just filter the filenames and keep the ones that start with the requested prefix (`/website/`).
Practically speaking, that makes little difference though.
Second, there is a limit of 32 chars in total for filenames. One `'\0'` char is reserved for C string termination, so that leaves us with 31 usable characters.
Combined, that means it is advised to keep filenames short and not use deeply nested directories, as the full path of each file (including directories, `'/'` characters, base name, dot and extension) has to be 31 chars at a maximum.
For example, the filename `/website/images/bird_thumbnail.jpg` is 34 chars and will cause some problems if used, for example in `exists()` or in case another file starts with the same first 31 characters.
**Warning**: That limit is easily reached and if ignored, problems might go unnoticed because no error message will appear at compilation nor runtime.
For more details on the internals of SPIFFS implementation, see the [SPIFFS readme file](https://github.com/esp8266/Arduino/blob/master/cores/esp8266/spiffs/README.md).
## Uploading files to file system
*ESP8266FS* is a tool which integrates into the Arduino IDE. It adds a menu item to *Tools* menu for uploading the contents of sketch data directory into ESP8266 flash file system.
- Download the tool: https://github.com/esp8266/arduino-esp8266fs-plugin/releases/download/0.3.0/ESP8266FS-0.3.0.zip.
- In your Arduino sketchbook directory, create `tools` directory if it doesn't exist yet
- Unpack the tool into `tools` directory (the path will look like `<home_dir>/Arduino/tools/ESP8266FS/tool/esp8266fs.jar`)
- Restart Arduino IDE
- Open a sketch (or create a new one and save it)
- Go to sketch directory (choose Sketch > Show Sketch Folder)
- Create a directory named `data` and any files you want in the file system there
- Make sure you have selected a board, port, and closed Serial Monitor
- Select Tools > ESP8266 Sketch Data Upload. This should start uploading the files into ESP8266 flash file system. When done, IDE status bar will display `SPIFFS Image Uploaded` message.
## File system object (SPIFFS)
### begin
```c++
SPIFFS.begin()
```
This method mounts SPIFFS file system. It must be called before any other
FS APIs are used. Returns *true* if file system was mounted successfully, false
otherwise.
### end
```c++
SPIFFS.end()
```
This method unmounts SPIFFS file system. Use this method before updating SPIFFS using OTA.
### format
```c++
SPIFFS.format()
```
Formats the file system. May be called either before or after calling `begin`.
Returns *true* if formatting was successful.
### open
```c++
SPIFFS.open(path, mode)
```
Opens a file. `path` should be an absolute path starting with a slash
(e.g. `/dir/filename.txt`). `mode` is a string specifying access mode. It can be
one of "r", "w", "a", "r+", "w+", "a+". Meaning of these modes is the same as
for `fopen` C function.
r Open text file for reading. The stream is positioned at the
beginning of the file.
r+ Open for reading and writing. The stream is positioned at the
beginning of the file.
w Truncate file to zero length or create text file for writing.
The stream is positioned at the beginning of the file.
w+ Open for reading and writing. The file is created if it does
not exist, otherwise it is truncated. The stream is
positioned at the beginning of the file.
a Open for appending (writing at end of file). The file is
created if it does not exist. The stream is positioned at the
end of the file.
a+ Open for reading and appending (writing at end of file). The
file is created if it does not exist. The initial file
position for reading is at the beginning of the file, but
output is always appended to the end of the file.
Returns *File* object. To check whether the file was opened successfully, use
the boolean operator.
```c++
File f = SPIFFS.open("/f.txt", "w");
if (!f) {
Serial.println("file open failed");
}
```
### exists
```c++
SPIFFS.exists(path)
```
Returns *true* if a file with given path exists, *false* otherwise.
### openDir
```c++
SPIFFS.openDir(path)
```
Opens a directory given its absolute path. Returns a *Dir* object.
### remove
```c++
SPIFFS.remove(path)
```
Deletes the file given its absolute path. Returns *true* if file was deleted successfully.
### rename
```c++
SPIFFS.rename(pathFrom, pathTo)
```
Renames file from `pathFrom` to `pathTo`. Paths must be absolute. Returns *true*
if file was renamed successfully.
### info
```c++
FSInfo fs_info;
SPIFFS.info(fs_info);
```
Fills [FSInfo structure](#filesystem-information-structure) with information about
the file system. Returns `true` is successful, `false` otherwise.
## Filesystem information structure
```c++
struct FSInfo {
size_t totalBytes;
size_t usedBytes;
size_t blockSize;
size_t pageSize;
size_t maxOpenFiles;
size_t maxPathLength;
};
```
This is the structure which may be filled using FS::info method.
- `totalBytes` — total size of useful data on the file system
- `usedBytes` — number of bytes used by files
- `blockSize` — SPIFFS block size
- `pageSize` — SPIFFS logical page size
- `maxOpenFiles` — max number of files which may be open simultaneously
- `maxPathLength` — max file name length (including one byte for zero termination)
## Directory object (Dir)
The purpose of *Dir* object is to iterate over files inside a directory.
It provides three methods: `next()`, `fileName()`, and `openFile(mode)`.
The following example shows how it should be used:
```c++
Dir dir = SPIFFS.openDir("/data");
while (dir.next()) {
Serial.print(dir.fileName());
File f = dir.openFile("r");
Serial.println(f.size());
}
```
`dir.next()` returns true while there are files in the directory to iterate over.
It must be called before calling `fileName` and `openFile` functions.
`openFile` method takes *mode* argument which has the same meaning as for `SPIFFS.open` function.
## File object
`SPIFFS.open` and `dir.openFile` functions return a *File* object. This object
supports all the functions of *Stream*, so you can use `readBytes`, `findUntil`,
`parseInt`, `println`, and all other *Stream* methods.
There are also some functions which are specific to *File* object.
### seek
```c++
file.seek(offset, mode)
```
This function behaves like `fseek` C function. Depending on the value of `mode`,
it moves current position in a file as follows:
- if `mode` is `SeekSet`, position is set to `offset` bytes from the beginning.
- if `mode` is `SeekCur`, current position is moved by `offset` bytes.
- if `mode` is `SeekEnd`, position is set to `offset` bytes from the end of the
file.
Returns *true* if position was set successfully.
### position
```c++
file.position()
```
Returns the current position inside the file, in bytes.
### size
```c++
file.size()
```
Returns file size, in bytes.
### name
```c++
String name = file.name();
```
Returns file name, as `const char*`. Convert it to *String* for storage.
### close
```c++
file.close()
```
Close the file. No other operations should be performed on *File* object after `close` function was called.

365
doc/filesystem.rst Normal file
View File

@ -0,0 +1,365 @@
Filesystem
==========
Flash layout
------------
Even though file system is stored on the same flash chip as the program,
programming new sketch will not modify file system contents. This allows
to use file system to store sketch data, configuration files, or content
for Web server.
The following diagram illustrates flash layout used in Arduino
environment:
::
|--------------|-------|---------------|--|--|--|--|--|
^ ^ ^ ^ ^
Sketch OTA update File system EEPROM WiFi config (SDK)
File system size depends on the flash chip size. Depending on the board
which is selected in IDE, you have the following options for flash size:
+---------------------------------+--------------------------+---------------------------+
| Board | Flash chip size, bytes | File system size, bytes |
+=================================+==========================+===========================+
| Generic module | 512k | 64k, 128k |
+---------------------------------+--------------------------+---------------------------+
| Generic module | 1M | 64k, 128k, 256k, 512k |
+---------------------------------+--------------------------+---------------------------+
| Generic module | 2M | 1M |
+---------------------------------+--------------------------+---------------------------+
| Generic module | 4M | 3M |
+---------------------------------+--------------------------+---------------------------+
| Adafruit HUZZAH | 4M | 1M, 3M |
+---------------------------------+--------------------------+---------------------------+
| ESPresso Lite 1.0 | 4M | 1M, 3M |
+---------------------------------+--------------------------+---------------------------+
| ESPresso Lite 2.0 | 4M | 1M, 3M |
+---------------------------------+--------------------------+---------------------------+
| NodeMCU 0.9 | 4M | 1M, 3M |
+---------------------------------+--------------------------+---------------------------+
| NodeMCU 1.0 | 4M | 1M, 3M |
+---------------------------------+--------------------------+---------------------------+
| Olimex MOD-WIFI-ESP8266(-DEV) | 2M | 1M |
+---------------------------------+--------------------------+---------------------------+
| SparkFun Thing | 512k | 64k |
+---------------------------------+--------------------------+---------------------------+
| SweetPea ESP-210 | 4M | 1M, 3M |
+---------------------------------+--------------------------+---------------------------+
| WeMos D1 & D1 mini | 4M | 1M, 3M |
+---------------------------------+--------------------------+---------------------------+
| ESPDuino | 4M | 1M, 3M |
+---------------------------------+--------------------------+---------------------------+
**Note:** to use any of file system functions in the sketch, add the
following include to the sketch:
.. code:: cpp
#include "FS.h"
File system limitations
-----------------------
The filesystem implementation for ESP8266 had to accomodate the
constraints of the chip, among which its limited RAM.
`SPIFFS <https://github.com/pellepl/spiffs>`__ was selected because it
is designed for small systems, but that comes at the cost of some
simplifications and limitations.
First, behind the scenes, SPIFFS does not support directories, it just
stores a "flat" list of files. But contrary to traditional filesystems,
the slash character ``'/'`` is allowed in filenames, so the functions
that deal with directory listing (e.g. ``openDir("/website")``)
basically just filter the filenames and keep the ones that start with
the requested prefix (``/website/``). Practically speaking, that makes
little difference though.
Second, there is a limit of 32 chars in total for filenames. One
``'\0'`` char is reserved for C string termination, so that leaves us
with 31 usable characters.
Combined, that means it is advised to keep filenames short and not use
deeply nested directories, as the full path of each file (including
directories, ``'/'`` characters, base name, dot and extension) has to be
31 chars at a maximum. For example, the filename
``/website/images/bird_thumbnail.jpg`` is 34 chars and will cause some
problems if used, for example in ``exists()`` or in case another file
starts with the same first 31 characters.
**Warning**: That limit is easily reached and if ignored, problems might
go unnoticed because no error message will appear at compilation nor
runtime.
For more details on the internals of SPIFFS implementation, see the
`SPIFFS readme
file <https://github.com/esp8266/Arduino/blob/master/cores/esp8266/spiffs/README.md>`__.
Uploading files to file system
------------------------------
*ESP8266FS* is a tool which integrates into the Arduino IDE. It adds a
menu item to *Tools* menu for uploading the contents of sketch data
directory into ESP8266 flash file system.
- Download the tool: https://github.com/esp8266/arduino-esp8266fs-plugin/releases/download/0.3.0/ESP8266FS-0.3.0.zip.
- In your Arduino sketchbook directory, create ``tools`` directory if
it doesn't exist yet
- Unpack the tool into ``tools`` directory (the path will look like
``<home_dir>/Arduino/tools/ESP8266FS/tool/esp8266fs.jar``)
- Restart Arduino IDE
- Open a sketch (or create a new one and save it)
- Go to sketch directory (choose Sketch > Show Sketch Folder)
- Create a directory named ``data`` and any files you want in the file
system there
- Make sure you have selected a board, port, and closed Serial Monitor
- Select Tools > ESP8266 Sketch Data Upload. This should start
uploading the files into ESP8266 flash file system. When done, IDE
status bar will display ``SPIFFS Image Uploaded`` message.
File system object (SPIFFS)
---------------------------
begin
~~~~~
.. code:: cpp
SPIFFS.begin()
This method mounts SPIFFS file system. It must be called before any
other FS APIs are used. Returns *true* if file system was mounted
successfully, false otherwise.
end
~~~
.. code:: cpp
SPIFFS.end()
This method unmounts SPIFFS file system. Use this method before updating
SPIFFS using OTA.
format
~~~~~~
.. code:: cpp
SPIFFS.format()
Formats the file system. May be called either before or after calling
``begin``. Returns *true* if formatting was successful.
open
~~~~
.. code:: cpp
SPIFFS.open(path, mode)
Opens a file. ``path`` should be an absolute path starting with a slash
(e.g. ``/dir/filename.txt``). ``mode`` is a string specifying access
mode. It can be one of "r", "w", "a", "r+", "w+", "a+". Meaning of these
modes is the same as for ``fopen`` C function.
::
r Open text file for reading. The stream is positioned at the
beginning of the file.
r+ Open for reading and writing. The stream is positioned at the
beginning of the file.
w Truncate file to zero length or create text file for writing.
The stream is positioned at the beginning of the file.
w+ Open for reading and writing. The file is created if it does
not exist, otherwise it is truncated. The stream is
positioned at the beginning of the file.
a Open for appending (writing at end of file). The file is
created if it does not exist. The stream is positioned at the
end of the file.
a+ Open for reading and appending (writing at end of file). The
file is created if it does not exist. The initial file
position for reading is at the beginning of the file, but
output is always appended to the end of the file.
Returns *File* object. To check whether the file was opened
successfully, use the boolean operator.
.. code:: cpp
File f = SPIFFS.open("/f.txt", "w");
if (!f) {
Serial.println("file open failed");
}
exists
~~~~~~
.. code:: cpp
SPIFFS.exists(path)
Returns *true* if a file with given path exists, *false* otherwise.
openDir
~~~~~~~
.. code:: cpp
SPIFFS.openDir(path)
Opens a directory given its absolute path. Returns a *Dir* object.
remove
~~~~~~
.. code:: cpp
SPIFFS.remove(path)
Deletes the file given its absolute path. Returns *true* if file was
deleted successfully.
rename
~~~~~~
.. code:: cpp
SPIFFS.rename(pathFrom, pathTo)
Renames file from ``pathFrom`` to ``pathTo``. Paths must be absolute.
Returns *true* if file was renamed successfully.
info
~~~~
.. code:: cpp
FSInfo fs_info;
SPIFFS.info(fs_info);
Fills `FSInfo structure <#filesystem-information-structure>`__ with
information about the file system. Returns ``true`` is successful,
``false`` otherwise.
Filesystem information structure
--------------------------------
.. code:: cpp
struct FSInfo {
size_t totalBytes;
size_t usedBytes;
size_t blockSize;
size_t pageSize;
size_t maxOpenFiles;
size_t maxPathLength;
};
This is the structure which may be filled using FS::info method. -
``totalBytes`` — total size of useful data on the file system -
``usedBytes`` — number of bytes used by files - ``blockSize`` — SPIFFS
block size - ``pageSize`` — SPIFFS logical page size - ``maxOpenFiles``
— max number of files which may be open simultaneously -
``maxPathLength`` — max file name length (including one byte for zero
termination)
Directory object (Dir)
----------------------
The purpose of *Dir* object is to iterate over files inside a directory.
It provides three methods: ``next()``, ``fileName()``, and
``openFile(mode)``.
The following example shows how it should be used:
.. code:: cpp
Dir dir = SPIFFS.openDir("/data");
while (dir.next()) {
Serial.print(dir.fileName());
File f = dir.openFile("r");
Serial.println(f.size());
}
``dir.next()`` returns true while there are files in the directory to
iterate over. It must be called before calling ``fileName`` and
``openFile`` functions.
``openFile`` method takes *mode* argument which has the same meaning as
for ``SPIFFS.open`` function.
File object
-----------
``SPIFFS.open`` and ``dir.openFile`` functions return a *File* object.
This object supports all the functions of *Stream*, so you can use
``readBytes``, ``findUntil``, ``parseInt``, ``println``, and all other
*Stream* methods.
There are also some functions which are specific to *File* object.
seek
~~~~
.. code:: cpp
file.seek(offset, mode)
This function behaves like ``fseek`` C function. Depending on the value
of ``mode``, it moves current position in a file as follows:
- if ``mode`` is ``SeekSet``, position is set to ``offset`` bytes from
the beginning.
- if ``mode`` is ``SeekCur``, current position is moved by ``offset``
bytes.
- if ``mode`` is ``SeekEnd``, position is set to ``offset`` bytes from
the end of the file.
Returns *true* if position was set successfully.
position
~~~~~~~~
.. code:: cpp
file.position()
Returns the current position inside the file, in bytes.
size
~~~~
.. code:: cpp
file.size()
Returns file size, in bytes.
name
~~~~
.. code:: cpp
String name = file.name();
Returns file name, as ``const char*``. Convert it to *String* for
storage.
close
~~~~~
.. code:: cpp
file.close()
Close the file. No other operations should be performed on *File* object
after ``close`` function was called.

22
doc/index.rst Normal file
View File

@ -0,0 +1,22 @@
Welcome to ESP8266 Arduino Core's documentation!
================================================
.. toctree::
:maxdepth: 2
:caption: Contents:
Installing <installing>
Reference <reference>
Libraries <libraries>
File system <filesystem>
ESP8266WiFi <esp8266wifi/readme>
OTA Updates <ota_updates/readme>
Boards <boards>
FAQ <faq/readme>
Exception causes <exception_causes>
Debugging <Troubleshooting/debugging>
Stack Dump <Troubleshooting/stack_dump>
Using with Eclipse <eclipse/eclipse>
Changelog <changes>

80
doc/installing.md
View File

@ -1,80 +0,0 @@
---
title: Installation
---
## Boards Manager ##
This is the suggested installation method for end users.
### Prerequisites
- Arduino 1.6.8, get it from [Arduino website](https://www.arduino.cc/en/Main/OldSoftwareReleases#previous).
- Internet connection
### Instructions
- Start Arduino and open Preferences window.
- Enter ```http://arduino.esp8266.com/stable/package_esp8266com_index.json``` into *Additional Board Manager URLs* field. You can add multiple URLs, separating them with commas.
- Open Boards Manager from Tools > Board menu and find *esp8266* platform.
- Select the version you need from a drop-down box.
- Click *install* button.
- Don't forget to select your ESP8266 board from Tools > Board menu after installation.
You may optionally use *staging* boards manager package link:
`http://arduino.esp8266.com/staging/package_esp8266com_index.json`. This may contain some new features, but at the same time, some things might be broken.
## Using git version
This is the suggested installation method for contributors and library developers.
### Prerequisites
- Arduino 1.6.8 (or newer, if you know what you are doing)
- git
- python 2.7
- terminal, console, or command prompt (depending on you OS)
- Internet connection
### Instructions
- Open the console and go to Arduino directory. This can be either your *sketchbook* directory (usually `<Documents>/Arduino`), or the directory of Arduino application itself, the choice is up to you.
- Clone this repository into hardware/esp8266com/esp8266 directory. Alternatively, clone it elsewhere and create a symlink, if your OS supports them.
```bash
cd hardware
mkdir esp8266com
cd esp8266com
git clone https://github.com/esp8266/Arduino.git esp8266
```
You should end up with the following directory structure:
```bash
Arduino
|
--- hardware
|
--- esp8266com
|
--- esp8266
|
--- bootloaders
--- cores
--- doc
--- libraries
--- package
--- tests
--- tools
--- variants
--- platform.txt
--- programmers.txt
--- README.md
--- boards.txt
--- LICENSE
```
- Download binary tools
```bash
cd esp8266/tools
python get.py
```
- Restart Arduino

101
doc/installing.rst Normal file
View File

@ -0,0 +1,101 @@
Installing
==========
Boards Manager
--------------
This is the suggested installation method for end users.
Prerequisites
~~~~~~~~~~~~~
- Arduino 1.6.8, get it from `Arduino
website <https://www.arduino.cc/en/Main/OldSoftwareReleases#previous>`__.
- Internet connection
Instructions
~~~~~~~~~~~~
- Start Arduino and open Preferences window.
- Enter
``http://arduino.esp8266.com/stable/package_esp8266com_index.json``
into *Additional Board Manager URLs* field. You can add multiple
URLs, separating them with commas.
- Open Boards Manager from Tools > Board menu and find *esp8266*
platform.
- Select the version you need from a drop-down box.
- Click *install* button.
- Don't forget to select your ESP8266 board from Tools > Board menu
after installation.
You may optionally use *staging* boards manager package link:
``http://arduino.esp8266.com/staging/package_esp8266com_index.json``.
This may contain some new features, but at the same time, some things
might be broken.
Using git version
-----------------
This is the suggested installation method for contributors and library
developers.
Prerequisites
~~~~~~~~~~~~~
- Arduino 1.6.8 (or newer, if you know what you are doing)
- git
- python 2.7
- terminal, console, or command prompt (depending on you OS)
- Internet connection
Instructions
~~~~~~~~~~~~
- Open the console and go to Arduino directory. This can be either your
*sketchbook* directory (usually ``<Documents>/Arduino``), or the
directory of Arduino application itself, the choice is up to you.
- Clone this repository into hardware/esp8266com/esp8266 directory.
Alternatively, clone it elsewhere and create a symlink, if your OS
supports them.
.. code:: bash
cd hardware
mkdir esp8266com
cd esp8266com
git clone https://github.com/esp8266/Arduino.git esp8266
You should end up with the following directory structure:
.. code:: bash
Arduino
|
--- hardware
|
--- esp8266com
|
--- esp8266
|
--- bootloaders
--- cores
--- doc
--- libraries
--- package
--- tests
--- tools
--- variants
--- platform.txt
--- programmers.txt
--- README.md
--- boards.txt
--- LICENSE
- Download binary tools
.. code:: bash
cd esp8266/tools
python get.py
- Restart Arduino

193
doc/libraries.md
View File

@ -1,193 +0,0 @@
---
title: Libraries
---
## Table of Contents
* [WiFi(ESP8266WiFi library)](#wifiesp8266wifi-library)
* [Ticker](#ticker)
* [EEPROM](#eeprom)
* [I2C (Wire library)](#i2c-wire-library)
* [SPI](#spi)
* [SoftwareSerial](#softwareserial)
* [ESP\-specific APIs](#esp-specific-apis)
* [mDNS and DNS\-SD responder (ESP8266mDNS library)](#mdns-and-dns-sd-responder-esp8266mdns-library)
* [SSDP responder (ESP8266SSDP)](#ssdp-responder-esp8266ssdp)
* [DNS server (DNSServer library)](#dns-server-dnsserver-library)
* [Servo](#servo)
* [Other libraries (not included with the IDE)](#other-libraries-not-included-with-the-ide)
## WiFi(ESP8266WiFi library)
The [Wi-Fi library for ESP8266](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi) has been developed basing on [ESP8266 SDK](http://bbs.espressif.com/viewtopic.php?f=51&t=1023), using naming convention and overall functionality philosophy of [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi). Over time the wealth Wi-Fi features ported from ESP9266 SDK to [esp8266 / Arduino](https://github.com/esp8266/Arduino) outgrow [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi) and it became apparent that we need to provide separate documentation on what is new and extra.
[ESP8266WiFi library documentation](esp8266wifi/readme.md) : [Quick Start](esp8266wifi/readme.md#quick-start) | [Who is Who](esp8266wifi/readme.md#who-is-who) | [Station](esp8266wifi/readme.md#station) | [Soft Access Point](esp8266wifi/readme.md#soft-access-point) | [Scan](esp8266wifi/readme.md#scan) | [Client](esp8266wifi/readme.md#client) | [Client Secure](esp8266wifi/readme.md#client-secure) | [Server](esp8266wifi/readme.md#server) | [UDP](esp8266wifi/readme.md#udp) | [Generic](esp8266wifi/readme.md#generic) | [Diagnostics](esp8266wifi/readme.md#diagnostics)
## Ticker
Library for calling functions repeatedly with a certain period. Two examples included.
It is currently not recommended to do blocking IO operations (network, serial, file) from Ticker
callback functions. Instead, set a flag inside the ticker callback and check for that flag inside the loop function.
Here is library to simplificate `Ticker` usage and avoid WDT reset: [TickerScheduler](https://github.com/Toshik/TickerScheduler)
## EEPROM
This is a bit different from standard EEPROM class. You need to call `EEPROM.begin(size)`
before you start reading or writing, size being the number of bytes you want to use.
Size can be anywhere between 4 and 4096 bytes.
`EEPROM.write` does not write to flash immediately, instead you must call `EEPROM.commit()`
whenever you wish to save changes to flash. `EEPROM.end()` will also commit, and will
release the RAM copy of EEPROM contents.
EEPROM library uses one sector of flash located just after the SPIFFS.
Three examples included.
## I2C (Wire library)
Wire library currently supports master mode up to approximately 450KHz.
Before using I2C, pins for SDA and SCL need to be set by calling
`Wire.begin(int sda, int scl)`, i.e. `Wire.begin(0, 2)` on ESP-01,
else they default to pins 4(SDA) and 5(SCL).
## SPI
SPI library supports the entire Arduino SPI API including transactions, including setting phase (CPHA).
Setting the Clock polarity (CPOL) is not supported, yet (SPI_MODE2 and SPI_MODE3 not working).
The usual SPI pins are:
- `MOSI` = GPIO13
- `MISO` = GPIO12
- `SCLK` = GPIO14
There's an extended mode where you can swap the normal pins to the pin0 hardware pins.
This is enabled by calling `SPI.pins(6, 7, 8, 0)` before the call to `SPI.begin()`. The pins would
change to:
- `MOSI` = SD1
- `MISO` = SD0
- `SCLK` = CLK
- `HWCS` = GPIO0
This mode shares the SPI pins with the controller that reads the program code from flash and is
controlled by a hardware arbiter (the flash has always higher priority). For this mode the CS
will be controlled by hardware as you can't handle the CS line with a GPIO, you never actually
know when the arbiter is going to grant you access to the bus so you must let it handle CS
automatically.
## SoftwareSerial
An ESP8266 port of SoftwareSerial library done by Peter Lerup (@plerup) supports baud rate up to 115200 and multiples SoftwareSerial instances. See https://github.com/plerup/espsoftwareserial if you want to suggest an improvement or open an issue related to SoftwareSerial.
## ESP-specific APIs
APIs related to deep sleep and watchdog timer are available in the `ESP` object, only available in Alpha version.
`ESP.deepSleep(microseconds, mode)` will put the chip into deep sleep. `mode` is one of `WAKE_RF_DEFAULT`, `WAKE_RFCAL`, `WAKE_NO_RFCAL`, `WAKE_RF_DISABLED`. (GPIO16 needs to be tied to RST to wake from deepSleep.)
`ESP.rtcUserMemoryWrite(offset, &data, sizeof(data))` and `ESP.rtcUserMemoryRead(offset, &data, sizeof(data))` allow data to be stored in and retrieved from the RTC user memory of the chip respectively. Total size of RTC user memory is 512 bytes, so offset + sizeof(data) shouldn't exceed 512. Data should be 4-byte aligned. The stored data can be retained between deep sleep cycles. However, the data might be lost after power cycling the chip.
`ESP.restart()` restarts the CPU.
`ESP.getResetReason()` returns a String containing the last reset reason in human readable format.
`ESP.getFreeHeap()` returns the free heap size.
`ESP.getChipId()` returns the ESP8266 chip ID as a 32-bit integer.
`ESP.getCoreVersion()` returns a String containing the core version.
`ESP.getSdkVersion()` returns the SDK version as a char.
`ESP.getCpuFreqMHz()` returns the CPU frequency in MHz as an unsigned 8-bit integer.
`ESP.getSketchSize()` returns the size of the current sketch as an unsigned 32-bit integer.
`ESP.getFreeSketchSpace()` returns the free sketch space as an unsigned 32-bit integer.
`ESP.getSketchMD5()` returns a lowercase String containing the MD5 of the current sketch.
`ESP.getFlashChipId()` returns the flash chip ID as a 32-bit integer.
`ESP.getFlashChipSize()` returns the flash chip size, in bytes, as seen by the SDK (may be less than actual size).
`ESP.getFlashChipRealSize()` returns the real chip size, in bytes, based on the flash chip ID.
`ESP.getFlashChipSpeed(void)` returns the flash chip frequency, in Hz.
`ESP.getCycleCount()` returns the cpu instruction cycle count since start as an unsigned 32-bit. This is useful for accurate timing of very short actions like bit banging.
`ESP.getVcc()` may be used to measure supply voltage. ESP needs to reconfigure the ADC
at startup in order for this feature to be available. Add the following line to the top
of your sketch to use `getVcc`:
```c++
ADC_MODE(ADC_VCC);
```
TOUT pin has to be disconnected in this mode.
Note that by default ADC is configured to read from TOUT pin using `analogRead(A0)`, and
`ESP.getVCC()` is not available.
## mDNS and DNS-SD responder (ESP8266mDNS library)
Allows the sketch to respond to multicast DNS queries for domain names like "foo.local", and DNS-SD (service discovery) queries.
See attached example for details.
## SSDP responder (ESP8266SSDP)
SSDP is another service discovery protocol, supported on Windows out of the box. See attached example for reference.
## DNS server (DNSServer library)
Implements a simple DNS server that can be used in both STA and AP modes. The DNS server currently supports only one domain (for all other domains it will reply with NXDOMAIN or custom status code). With it, clients can open a web server running on ESP8266 using a domain name, not an IP address.
See attached example for details.
## Servo
This library exposes the ability to control RC (hobby) servo motors. It will support upto 24 servos on any available output pin. By defualt the first 12 servos will use Timer0 and currently this will not interfere with any other support. Servo counts above 12 will use Timer1 and features that use it will be effected.
While many RC servo motors will accept the 3.3V IO data pin from a ESP8266, most will not be able to run off 3.3v and will require another power source that matches their specifications. Make sure to connect the grounds between the ESP8266 and the servo motor power supply.
## Other libraries (not included with the IDE)
Libraries that don't rely on low-level access to AVR registers should work well. Here are a few libraries that were verified to work:
- [Adafruit_ILI9341](https://github.com/Links2004/Adafruit_ILI9341) - Port of the Adafruit ILI9341 for the ESP8266
- [arduinoVNC](https://github.com/Links2004/arduinoVNC) - VNC Client for Arduino
- [arduinoWebSockets](https://github.com/Links2004/arduinoWebSockets) - WebSocket Server and Client compatible with ESP8266 (RFC6455)
- [aREST](https://github.com/marcoschwartz/aREST) - REST API handler library.
- [Blynk](https://github.com/blynkkk/blynk-library) - easy IoT framework for Makers (check out the [Kickstarter page](http://tiny.cc/blynk-kick)).
- [DallasTemperature](https://github.com/milesburton/Arduino-Temperature-Control-Library.git)
- [DHT-sensor-library](https://github.com/adafruit/DHT-sensor-library) - Arduino library for the DHT11/DHT22 temperature and humidity sensors. Download latest v1.1.1 library and no changes are necessary. Older versions should initialize DHT as follows: `DHT dht(DHTPIN, DHTTYPE, 15)`
- [DimSwitch](https://github.com/krzychb/DimSwitch) - Control electronic dimmable ballasts for fluorescent light tubes remotely as if using a wall switch.
- [Encoder](https://github.com/PaulStoffregen/Encoder) - Arduino library for rotary encoders. Version 1.4 supports ESP8266.
- [esp8266_mdns](https://github.com/mrdunk/esp8266_mdns) - mDNS queries and responses on esp8266. Or to describe it another way: An mDNS Client or Bonjour Client library for the esp8266.
- [ESPAsyncTCP](https://github.com/me-no-dev/ESPAsyncTCP) - Asynchronous TCP Library for ESP8266 and ESP32/31B
- [ESPAsyncWebServer](https://github.com/me-no-dev/ESPAsyncWebServer) - Asynchronous Web Server Library for ESP8266 and ESP32/31B
- [Homie for ESP8266](https://github.com/marvinroger/homie-esp8266) - Arduino framework for ESP8266 implementing Homie, an MQTT convention for the IoT.
- [NeoPixel](https://github.com/adafruit/Adafruit_NeoPixel) - Adafruit's NeoPixel library, now with support for the ESP8266 (use version 1.0.2 or higher from Arduino's library manager).
- [NeoPixelBus](https://github.com/Makuna/NeoPixelBus) - Arduino NeoPixel library compatible with ESP8266. Use the "DmaDriven" or "UartDriven" branches for ESP8266. Includes HSL color support and more.
- [PubSubClient](https://github.com/Imroy/pubsubclient) - MQTT library by @Imroy.
- [RTC](https://github.com/Makuna/Rtc) - Arduino Library for Ds1307 & Ds3231 compatible with ESP8266.
- [Souliss, Smart Home](https://github.com/souliss/souliss) - Framework for Smart Home based on Arduino, Android and openHAB.
- [ST7735](https://github.com/nzmichaelh/Adafruit-ST7735-Library) - Adafruit's ST7735 library modified to be compatible with ESP8266. Just make sure to modify the pins in the examples as they are still AVR specific.
- [Task](https://github.com/Makuna/Task) - Arduino Nonpreemptive multitasking library. While similiar to the included Ticker library in the functionality provided, this library was meant for cross Arduino compatibility.
- [TickerScheduler](https://github.com/Toshik/TickerScheduler) - Library provides simple scheduler for `Ticker` to avoid WDT reset
- [Teleinfo](https://github.com/hallard/LibTeleinfo) - Generic French Power Meter library to read Teleinfo energy monitoring data such as consuption, contract, power, period, ... This library is cross platform, ESP8266, Arduino, Particle, and simple C++. French dedicated [post](https://hallard.me/libteleinfo/) on author's blog and all related information about [Teleinfo](https://hallard.me/category/tinfo/) also available.
- [UTFT-ESP8266](https://github.com/gnulabis/UTFT-ESP8266) - UTFT display library with support for ESP8266. Only serial interface (SPI) displays are supported for now (no 8-bit parallel mode, etc). Also includes support for the hardware SPI controller of the ESP8266.
- [WiFiManager](https://github.com/tzapu/WiFiManager) - WiFi Connection manager with web captive portal. If it can't connect, it starts AP mode and a configuration portal so you can choose and enter WiFi credentials.
- [OneWire](https://github.com/PaulStoffregen/OneWire) - Library for Dallas/Maxim 1-Wire Chips.
- [Adafruit-PCD8544-Nokia-5110-LCD-Library](https://github.com/WereCatf/Adafruit-PCD8544-Nokia-5110-LCD-library) - Port of the Adafruit PCD8544 - library for the ESP8266.
- [PCF8574_ESP](https://github.com/WereCatf/PCF8574_ESP) - A very simplistic library for using the PCF8574/PCF8574A I2C 8-pin GPIO-expander.
- [Dot Matrix Display Library 2](https://github.com/freetronics/DMD2) - Freetronics DMD & Generic 16 x 32 P10 style Dot Matrix Display Library
- [SdFat-beta](https://github.com/greiman/SdFat-beta) - SD-card library with support for long filenames, software- and hardware-based SPI and lots more.
- [FastLED](https://github.com/FastLED/FastLED) - a library for easily & efficiently controlling a wide variety of LED chipsets, like the Neopixel (WS2812B), DotStar, LPD8806 and many more. Includes fading, gradient, color conversion functions.
- [OLED](https://github.com/klarsys/esp8266-OLED) - a library for controlling I2C connected OLED displays. Tested with 0.96 inch OLED graphics display.
- [MFRC522](https://github.com/miguelbalboa/rfid) - A library for using the Mifare RC522 RFID-tag reader/writer.
- [Ping](https://github.com/dancol90/ESP8266Ping) - lets the ESP8266 ping a remote machine.
- [AsyncPing](https://github.com/akaJes/AsyncPing) - fully asynchronous Ping library (have full ping statistic and hardware MAC address).

176
doc/libraries.rst Normal file
View File

@ -0,0 +1,176 @@
Libraries
=========
WiFi(ESP8266WiFi library)
-------------------------
ESP8266WiFi library has been developed basing on ESP8266 SDK, using naming convention and overall functionality philosophy of the `Arduino WiFi Shield library <https://www.arduino.cc/en/Reference/WiFi>`__. Over time the wealth Wi-Fi features ported from ESP8266 SDK to this library outgrew the APIs of WiFi Shield library and it became apparent that we need to provide separate documentation on what is new and extra.
:doc:`ESP8266WiFi library documentation <esp8266wifi/readme>`.
Ticker
------
Library for calling functions repeatedly with a certain period. Two examples included.
It is currently not recommended to do blocking IO operations (network, serial, file) from Ticker callback functions. Instead, set a flag inside the ticker callback and check for that flag inside the loop function.
Here is library to simplificate ``Ticker`` usage and avoid WDT reset:
`TickerScheduler <https://github.com/Toshik/TickerScheduler>`__
EEPROM
------
This is a bit different from standard EEPROM class. You need to call ``EEPROM.begin(size)`` before you start reading or writing, size being the number of bytes you want to use. Size can be anywhere between 4 and 4096 bytes.
``EEPROM.write`` does not write to flash immediately, instead you must call ``EEPROM.commit()`` whenever you wish to save changes to flash. ``EEPROM.end()`` will also commit, and will release the RAM copy of EEPROM contents.
EEPROM library uses one sector of flash located just after the SPIFFS.
Three examples included.
I2C (Wire library)
------------------
Wire library currently supports master mode up to approximately 450KHz. Before using I2C, pins for SDA and SCL need to be set by calling ``Wire.begin(int sda, int scl)``, i.e. ``Wire.begin(0, 2)`` on ESP-01, else they default to pins 4(SDA) and 5(SCL).
SPI
---
SPI library supports the entire Arduino SPI API including transactions, including setting phase (CPHA). Setting the Clock polarity (CPOL) is not supported, yet (SPI\_MODE2 and SPI\_MODE3 not working).
The usual SPI pins are:
- ``MOSI`` = GPIO13
- ``MISO`` = GPIO12
- ``SCLK`` = GPIO14
There's an extended mode where you can swap the normal pins to the SPI0 hardware pins.
This is enabled by calling ``SPI.pins(6, 7, 8, 0)`` before the call to ``SPI.begin()``. The pins would
change to:
- ``MOSI`` = SD1
- ``MISO`` = SD0
- ``SCLK`` = CLK
- ``HWCS`` = GPIO0
This mode shares the SPI pins with the controller that reads the program code from flash and is
controlled by a hardware arbiter (the flash has always higher priority). For this mode the CS
will be controlled by hardware as you can't handle the CS line with a GPIO, you never actually
know when the arbiter is going to grant you access to the bus so you must let it handle CS
automatically.
SoftwareSerial
--------------
An ESP8266 port of SoftwareSerial library done by Peter Lerup (@plerup) supports baud rate up to 115200 and multiples SoftwareSerial instances. See https://github.com/plerup/espsoftwareserial if you want to suggest an improvement or open an issue related to SoftwareSerial.
ESP-specific APIs
-----------------
Some ESP-specific APIs related to deep sleep, RTC and flash memories are available in the ``ESP`` object.
``ESP.deepSleep(microseconds, mode)`` will put the chip into deep sleep. ``mode`` is one of ``WAKE_RF_DEFAULT``, ``WAKE_RFCAL``, ``WAKE_NO_RFCAL``, ``WAKE_RF_DISABLED``. (GPIO16 needs to be tied to RST to wake from deepSleep.)
``ESP.rtcUserMemoryWrite(offset, &data, sizeof(data))`` and ``ESP.rtcUserMemoryRead(offset, &data, sizeof(data))`` allow data to be stored in and retrieved from the RTC user memory of the chip respectively. Total size of RTC user memory is 512 bytes, so ``offset + sizeof(data)`` shouldn't exceed 512. Data should be 4-byte aligned. The stored data can be retained between deep sleep cycles. However, the data might be lost after power cycling the chip.
``ESP.restart()`` restarts the CPU.
``ESP.getResetReason()`` returns a String containing the last reset reason in human readable format.
``ESP.getFreeHeap()`` returns the free heap size.
``ESP.getChipId()`` returns the ESP8266 chip ID as a 32-bit integer.
``ESP.getCoreVersion()`` returns a String containing the core version.
``ESP.getSdkVersion()`` returns the SDK version as a char.
``ESP.getCpuFreqMHz()`` returns the CPU frequency in MHz as an unsigned 8-bit integer.
``ESP.getSketchSize()`` returns the size of the current sketch as an unsigned 32-bit integer.
``ESP.getFreeSketchSpace()`` returns the free sketch space as an unsigned 32-bit integer.
``ESP.getSketchMD5()`` returns a lowercase String containing the MD5 of the current sketch.
``ESP.getFlashChipId()`` returns the flash chip ID as a 32-bit integer.
``ESP.getFlashChipSize()`` returns the flash chip size, in bytes, as seen by the SDK (may be less than actual size).
``ESP.getFlashChipRealSize()`` returns the real chip size, in bytes, based on the flash chip ID.
``ESP.getFlashChipSpeed(void)`` returns the flash chip frequency, in Hz.
``ESP.getCycleCount()`` returns the cpu instruction cycle count since start as an unsigned 32-bit. This is useful for accurate timing of very short actions like bit banging.
``ESP.getVcc()`` may be used to measure supply voltage. ESP needs to reconfigure the ADC at startup in order for this feature to be available. Add the following line to the top of your sketch to use ``getVcc``:
.. code:: cpp
ADC_MODE(ADC_VCC);
TOUT pin has to be disconnected in this mode.
Note that by default ADC is configured to read from TOUT pin using ``analogRead(A0)``, and ``ESP.getVCC()`` is not available.
mDNS and DNS-SD responder (ESP8266mDNS library)
-----------------------------------------------
Allows the sketch to respond to multicast DNS queries for domain names like "foo.local", and DNS-SD (service discovery) queries. See attached example for details.
SSDP responder (ESP8266SSDP)
----------------------------
SSDP is another service discovery protocol, supported on Windows out of the box. See attached example for reference.
DNS server (DNSServer library)
------------------------------
Implements a simple DNS server that can be used in both STA and AP modes. The DNS server currently supports only one domain (for all other domains it will reply with NXDOMAIN or custom status code). With it, clients can open a web server running on ESP8266 using a domain name, not an IP address.
Servo
-----
This library exposes the ability to control RC (hobby) servo motors. It will support upto 24 servos on any available output pin. By defualt the first 12 servos will use Timer0 and currently this will not interfere with any other support. Servo counts above 12 will use Timer1 and features that use it will be effected. While many RC servo motors will accept the 3.3V IO data pin from a ESP8266, most will not be able to run off 3.3v and will require another power source that matches their specifications. Make sure to connect the grounds between the ESP8266 and the servo motor power supply.
Other libraries (not included with the IDE)
-------------------------------------------
Libraries that don't rely on low-level access to AVR registers should work well. Here are a few libraries that were verified to work:
- `Adafruit\_ILI9341 <https://github.com/Links2004/Adafruit_ILI9341>`__ - Port of the Adafruit ILI9341 for the ESP8266
- `arduinoVNC <https://github.com/Links2004/arduinoVNC>`__ - VNC Client for Arduino
- `arduinoWebSockets <https://github.com/Links2004/arduinoWebSockets>`__ - WebSocket Server and Client compatible with ESP8266 (RFC6455)
- `aREST <https://github.com/marcoschwartz/aREST>`__ - REST API handler library.
- `Blynk <https://github.com/blynkkk/blynk-library>`__ - easy IoT framework for Makers (check out the `Kickstarter page <http://tiny.cc/blynk-kick>`__).
- `DallasTemperature <https://github.com/milesburton/Arduino-Temperature-Control-Library.git>`__
- `DHT-sensor-library <https://github.com/adafruit/DHT-sensor-library>`__ - Arduino library for the DHT11/DHT22 temperature and humidity sensors. Download latest v1.1.1 library and no changes are necessary. Older versions should initialize DHT as follows: ``DHT dht(DHTPIN, DHTTYPE, 15)``
- `DimSwitch <https://github.com/krzychb/DimSwitch>`__ - Control electronic dimmable ballasts for fluorescent light tubes remotely as if using a wall switch.
- `Encoder <https://github.com/PaulStoffregen/Encoder>`__ - Arduino library for rotary encoders. Version 1.4 supports ESP8266.
- `esp8266\_mdns <https://github.com/mrdunk/esp8266_mdns>`__ - mDNS queries and responses on esp8266. Or to describe it another way: An mDNS Client or Bonjour Client library for the esp8266.
- `ESPAsyncTCP <https://github.com/me-no-dev/ESPAsyncTCP>`__ - Asynchronous TCP Library for ESP8266 and ESP32/31B
- `ESPAsyncWebServer <https://github.com/me-no-dev/ESPAsyncWebServer>`__ - Asynchronous Web Server Library for ESP8266 and ESP32/31B
- `Homie for ESP8266 <https://github.com/marvinroger/homie-esp8266>`__ - Arduino framework for ESP8266 implementing Homie, an MQTT convention for the IoT.
- `NeoPixel <https://github.com/adafruit/Adafruit_NeoPixel>`__ - Adafruit's NeoPixel library, now with support for the ESP8266 (use version 1.0.2 or higher from Arduino's library manager).
- `NeoPixelBus <https://github.com/Makuna/NeoPixelBus>`__ - Arduino NeoPixel library compatible with ESP8266. Use the "DmaDriven" or "UartDriven" branches for ESP8266. Includes HSL color support and more.
- `PubSubClient <https://github.com/Imroy/pubsubclient>`__ - MQTT library by @Imroy.
- `RTC <https://github.com/Makuna/Rtc>`__ - Arduino Library for Ds1307 & Ds3231 compatible with ESP8266.
- `Souliss, Smart Home <https://github.com/souliss/souliss>`__ - Framework for Smart Home based on Arduino, Android and openHAB.
- `ST7735 <https://github.com/nzmichaelh/Adafruit-ST7735-Library>`__ - Adafruit's ST7735 library modified to be compatible with ESP8266. Just make sure to modify the pins in the examples as they are still AVR specific.
- `Task <https://github.com/Makuna/Task>`__ - Arduino Nonpreemptive multitasking library. While similiar to the included Ticker library in the functionality provided, this library was meant for cross Arduino compatibility.
- `TickerScheduler <https://github.com/Toshik/TickerScheduler>`__ - Library provides simple scheduler for ``Ticker`` to avoid WDT reset
- `Teleinfo <https://github.com/hallard/LibTeleinfo>`__ - Generic French Power Meter library to read Teleinfo energy monitoring data such as consuption, contract, power, period, ... This library is cross platform, ESP8266, Arduino, Particle, and simple C++. French dedicated `post <https://hallard.me/libteleinfo/>`__ on author's blog and all related information about `Teleinfo <https://hallard.me/category/tinfo/>`__ also available.
- `UTFT-ESP8266 <https://github.com/gnulabis/UTFT-ESP8266>`__ - UTFT display library with support for ESP8266. Only serial interface (SPI) displays are supported for now (no 8-bit parallel mode, etc). Also includes support for the hardware SPI controller of the ESP8266.
- `WiFiManager <https://github.com/tzapu/WiFiManager>`__ - WiFi Connection manager with web captive portal. If it can't connect, it starts AP mode and a configuration portal so you can choose and enter WiFi credentials.
- `OneWire <https://github.com/PaulStoffregen/OneWire>`__ - Library for Dallas/Maxim 1-Wire Chips.
- `Adafruit-PCD8544-Nokia-5110-LCD-Library <https://github.com/WereCatf/Adafruit-PCD8544-Nokia-5110-LCD-library>`__ - Port of the Adafruit PCD8544 - library for the ESP8266.
- `PCF8574\_ESP <https://github.com/WereCatf/PCF8574_ESP>`__ - A very simplistic library for using the PCF857//PCF8574A I2C 8-pin GPIO-expander.
- `Dot Matrix Display Library 2 <https://github.com/freetronics/DMD2>`__ - Freetronics DMD & Generic 16 x 32 P10 style Dot Matrix Display Library
- `SdFat-beta <https://github.com/greiman/SdFat-beta>`__ - SD-card library with support for long filenames, software- and hardware-based SPI and lots more.
- `FastLED <https://github.com/FastLED/FastLED>`__ - a library for easily & efficiently controlling a wide variety of LED chipsets, like the Neopixel (WS2812B), DotStar, LPD8806 and many more. Includes fading, gradient, color conversion functions.
- `OLED <https://github.com/klarsys/esp8266-OLED>`__ - a library for controlling I2C connected OLED displays. Tested with 0.96 inch OLED graphics display.
- `MFRC522 <https://github.com/miguelbalboa/rfid>`__ - A library for using the Mifare RC522 RFID-tag reader/writer.
- `Ping <https://github.com/dancol90/ESP8266Ping>`__ - lets the ESP8266 ping a remote machine.
- `AsyncPing <https://github.com/akaJes/AsyncPing>`__ - fully asynchronous Ping library (have full ping statistic and hardware MAC address).

483
doc/ota_updates/readme.md
View File

@ -1,483 +0,0 @@
---
title: OTA Update
---
## Table of Contents
* [Introduction](#introduction)
* [Security](#security)
* [Safety](#safety)
* [Basic Requirements](#basic-requirements)
* [Arduino IDE](#arduino-ide)
* [Requirements](#requirements)
* [Application Example](#application-example)
* [Password Protection](#password-protection)
* [Troubleshooting](#troubleshooting)
* [Web Browser](#web-browser)
* [Requirements](#requirements-1)
* [Implementation Overview](#implementation-overview)
* [Application Example](#application-example-1)
* [HTTP Server](#http-server)
* [Requirements](#requirements-2)
* [Arduino code](#arduino-code)
* [Simple updater](#simple-updater)
* [Advanced updater](#advanced-updater)
* [Server request handling](#server-request-handling)
* [Simple updater](#simple-updater-1)
* [Advanced updater](#advanced-updater-1)
* [Stream Interface](#stream-interface)
* [Updater class](#updater-class)
## Introduction
OTA (Over the Air) update is the process of loading the firmware to ESP module using Wi-Fi connection rather than a serial port. Such functionality became extremely useful in case of limited or no physical access to the module.
OTA may be done using:
* [Arduino IDE](#arduino-ide)
* [Web Browser](#web-browser)
* [HTTP Server](#http-server)
Arduino IDE option is intended primarily for software development phase. The two other options would be more useful after deployment, to provide module with application updates manually with a web browser, or automatically using a http server.
In any case, the first firmware upload has to be done over a serial port. If the OTA routines are correctly implemented in a sketch, then all subsequent uploads may be done over the air.
There is no imposed security on OTA process from being hacked. It is up to developer to ensure that updates are allowed only from legitimate / trusted sources. Once the update is complete, the module restarts, and the new code is executed. The developer should ensure that the application running on the module is shut down and restarted in a safe manner. Chapters below provide additional information regarding security and safety of OTA process.
### Security
Module has to be exposed wirelessly to get it updated with a new sketch. That poses chances of module being violently hacked and loaded with some other code. To reduce likelihood of being hacked consider protecting your uploads with a password, selecting certain OTA port, etc.
Check functionality provided with [ArduinoOTA](https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA) library that may improve security:
```cpp
void setPort(uint16_t port);
void setHostname(const char* hostname);
void setPassword(const char* password);
```
Certain protection functionality is already built in and do not require any additional coding by developer. [ArduinoOTA](https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA) and espota.py use [Digest-MD5](https://en.wikipedia.org/wiki/Digest_access_authentication) to authenticate upload. Integrity of transferred data is verified on ESP side using [MD5](https://en.wikipedia.org/wiki/MD5) checksum.
Make your own risk analysis and depending on application decide what library functions to implement. If required, consider implementation of other means of protection from being hacked, e.g. exposing module for uploads only according to specific schedule, trigger OTA only be user pressing dedicated “Update” button wired to ESP, etc.
### Safety
OTA process takes ESP’s resources and bandwidth during upload. Then module is restarted and a new sketch executed. Analyse and test how it affects functionality of existing and new sketch.
If ESP is placed in remote location and controlling some equipment, you should put additional attention what happens if operation of this equipment is suddenly interrupted by update process. Therefore, decide how to put this equipment into safe state before starting the update. For instance, your module may be controlling a garden watering system in a sequence. If this sequence is not properly shut down and a water valve left open, your garden may be flooded.
The following functions are provided with [ArduinoOTA](https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA) library and intended to handle functionality of your application during specific stages of OTA, or on an OTA error:
```cpp
void onStart(OTA_CALLBACK(fn));
void onEnd(OTA_CALLBACK(fn));
void onProgress(OTA_CALLBACK_PROGRESS(fn));
void onError(OTA_CALLBACK_ERROR (fn));
```
### Basic Requirements
Flash chip size should be able to hold the old sketch (currently running) and the new sketch (OTA) at the same time.
Keep in mind that the File system and EEPROM for example needs space too (one time) see [flash layout](../filesystem.md#flash-layout).
```cpp
ESP.getFreeSketchSpace();
```
can be used for checking the free space for the new sketch.
For overview of memory layout, where new sketch is stored and how it is copied during OTA process, see [Update process - memory view](#update-process---memory-view).
The following chapters provide more details and specific methods of doing OTA.
## Arduino IDE
Uploading modules wirelessly from Arduino IDE is intended for the following typical scenarios:
- during firmware development as a quicker alternative to loading over a serial,
- for updating small quantity of modules,
- only if modules are available on the same network as the computer with Arduino IDE.
### Requirements
- The ESP and the computer must be connected to the same network.
### Application Example
Instructions below show configuration of OTA on NodeMCU 1.0 (ESP-12E Module) board. You can use any other board assuming that it meets [requirements](#basic-requirements) described above. This instruction is valid for all operating systems supported by Arduino IDE. Screen captures have been made on Windows 7 and you may see small differences (like name of serial port), if you are using Linux and MacOS.
1. Before you begin, please make sure that you have the following s/w installed:
- Arduino IDE 1.6.7 or newer - https://www.arduino.cc/en/Main/Software
- esp8266/Arduino platform package 2.0.0 or newer - for instructions follow https://github.com/esp8266/Arduino#installing-with-boards-manager
- Python 2.7 (do not install Python 3.5 that is not supported) - https://www.python.org/
**Note:** Windows users should select “Add python.exe to Path” (see below – this option is not selected by default).
![alt text](a-ota-python-configuration.png "Python installation set up")
2. Now prepare the sketch and configuration for the upload over a serial port.
- Start Arduino IDE and load sketch BasicOTA.ino available under File > Examples > ArduinoOTA
![alt text](a-ota-sketch-selection.png "Selection of example OTA sketch")
- Update SSID and password in the sketch, so the module can join your Wi-Fi network
![alt text](a-ota-ssid-pass-entry.png "SSID and password entry")
- Configure upload parameters as below (you may need to adjust configuration if you are using a different module):
![alt text](a-ota-serial-upload-configuration.png "Configuration of serial upload")
**Note:** Depending on version of platform package and board you have, you may see `Upload Using:` in the menu above. This option is inactive and it does not matter what you select. It has been left for compatibility with older implementation of OTA and finally removed in platform package version 2.2.0.
3. Upload the sketch (Ctrl+U). Once done, open Serial Monitor (Ctrl+Shift+M) and check if module has joined your Wi-Fi network:
![alt text](a-ota-upload-complete-and-joined-wifi.png "Check if module joined network")
**Note:** ESP module should be reset after serial upload. Otherwise subsequent steps will not work. Reset may be done automatically for you after opening serial monitor as visible on the screenshot above. It depends on how you have DTR and RTS wired from USB-Serial converter to the ESP. If reset is not done automatically, then do it by pressing reset button or manually cycling the power. For more details why this should be done please refer to [FAQ](../faq#i-have-observed-a-case-when-esprestart-doesnt-work-what-is-the-reason-for-that) regarding `ESP.restart()`.
4. Only if module is connected to network, after a couple of seconds, the esp8266-ota port will show up in Arduino IDE. Select port with IP address shown in the Serial Monitor window in previous step:
![alt text](a-ota-ota-port-selection.png "Selection of OTA port")
**Note:** If OTA port does not show up, exit Arduino IDE, open it again and check if port is there. If it does not help, check your firewall and router settings. OTA port is advertised using mDNS service. To check if port is visible by your PC, you can use application like Bonjour Browser.
5. Now get ready for your first OTA upload by selecting the OTA port:
![alt text](a-ota-ota-upload-configuration.png "Configuration of OTA upload")
**Note:** The menu entry `Upload Speed:` does not matter at this point as it concerns the serial port. Just left it unchanged.
6. If you have successfully completed all the above steps, you can upload (Ctrl+U) the same (or any other) sketch over OTA:
![alt text](a-ota-ota-upload-complete.png "OTA upload complete")
**Note:** To be able to upload your sketch over and over again using OTA, you need to embed OTA routines inside. Please use BasicOTA.ino as an example.
#### Password Protection
Protecting your OTA uploads with password is really straightforward. All you need to do, is to include the following statement in your code:
```cpp
ArduinoOTA.setPassword((const char *)"123");
```
Where `123` is a sample password that you should replace with your own.
Before implementing it in your sketch, it is a good idea to check how it works using *BasicOTA.ino* sketch available under *File > Examples > ArduinoOTA*. Go ahead, open *BasicOTA.ino*, uncomment the above statement that is already there, and upload the sketch. To make troubleshooting easier, do not modify example sketch besides what is absolutely required. This is including original simple `123` OTA password. Then attempt to upload sketch again (using OTA). After compilation is complete, once upload is about to begin, you should see prompt for password as follows:
![alt text](a-ota-upload-password-prompt.png "Password prompt for OTA upload")
Enter the password and upload should be initiated as usual with the only difference being `Authenticating...OK` message visible in upload log.
![alt text](a-ota-upload-password-authenticating-ok.png "Authenticating...OK during OTA upload")
You will not be prompted for a reentering the same password next time. Arduino IDE will remember it for you. You will see prompt for password only after reopening IDE, or if you change it in your sketch, upload the sketch and then try to upload it again.
Please note, it is possible to reveal password entered previously in Arduino IDE, if IDE has not been closed since last upload. This can be done by enabling *Show verbose output during: upload* in *File > Preferences* and attempting to upload the module.
![alt text](a-ota-upload-password-passing-upload-ok.png "Verbose upload output with password passing in plain text")
The picture above shows that the password is visible in log, as it is passed to *espota.py* upload script.
Another example below shows situation when password is changed between uploads.
![alt text](a-ota-upload-password-passing-again-upload-ok.png "Verbose output when OTA password has been changed between uploads")
When uploading, Arduino IDE used previously entered password, so the upload failed and that has been clearly reported by IDE. Only then IDE prompted for a new password. That was entered correctly and second attempt to upload has been successful.
#### Troubleshooting
If OTA update fails, first step is to check for error messages that may be shown in upload window of Arduino IDE. If this is not providing any useful hints, try to upload again while checking what is shown by ESP on serial port. Serial Monitor from IDE will not be useful in that case. When attempting to open it, you will likely see the following:
![alt text](a-ota-network-terminal.png "Arduino IDE network terminal window")
This window is for Arduino Yún and not yet implemented for esp8266/Arduino. It shows up because IDE is attempting to open Serial Monitor using network port you have selected for OTA upload.
Instead you need an external serial monitor. If you are a Windows user check out [Termite](http://www.compuphase.com/software_termite.htm). This is handy, slick and simple RS232 terminal that does not impose RTS or DTR flow control. Such flow control may cause issues if you are using respective lines to toggle GPIO0 and RESET pins on ESP for upload.
Select COM port and baud rate on external terminal program as if you were using Arduino Serial Monitor. Please see typical settings for [Termite](http://www.compuphase.com/software_termite.htm) below:
![alt text](termite-configuration.png "Termite settings")
Then run OTA from IDE and look what is displayed on terminal. Successful [ArduinoOTA](#arduinoota) process using BasicOTA.ino sketch looks like below (IP address depends on your network configuration):
![alt text](a-ota-external-serial-terminal-output.png "OTA upload successful - output on an external serial terminal")
If upload fails you will likely see errors caught by the uploader, exception and the stack trace, or both.
Instead of the log as on the above screen you may see the following:
![alt text](a-ota-external-serial-terminal-output-failed.png "OTA upload failed - output on an external serial terminal")
If this is the case, then most likely ESP module has not been reset after initial upload using serial port.
The most common causes of OTA failure are as follows:
* not enough physical memory on the chip (e.g. ESP01 with 512K flash memory is not enough for OTA),
* too much memory declared for SPIFFS so new sketch will not fit between existing sketch and SPIFFS – see [Update process - memory view](#update-process---memory-view),
* too little memory declared in Arduino IDE for your selected board (i.e. less than physical size),
* not resetting the ESP module after initial upload using serial port.
For more details regarding flash memory layout please check [File system](https://github.com/esp8266/Arduino/blob/master/doc/filesystem.md).
For overview where new sketch is stored, how it is copied and how memory is organized for the purpose of OTA see [Update process - memory view](#update-process---memory-view).
## Web Browser
Updates described in this chapter are done with a web browser that can be useful in the following typical scenarios:
- after application deployment if loading directly from Arduino IDE is inconvenient or not possible,
- after deployment if user is unable to expose module for OTA from external update server,
- to provide updates after deployment to small quantity of modules when setting an update server is not practicable.
### Requirements
- The ESP and the computer must be connected to the same network.
### Implementation Overview
Updates with a web browser are implemented using `ESP8266HTTPUpdateServer` class together with `ESP8266WebServer` and `ESP8266mDNS` classes. The following code is required to get it work:
setup()
```cpp
MDNS.begin(host);
httpUpdater.setup(&httpServer);
httpServer.begin();
MDNS.addService("http", "tcp", 80);
```
loop()
```cpp
httpServer.handleClient();
```
### Application Example
The sample implementation provided below has been done using:
- example sketch WebUpdater.ino available in `ESP8266HTTPUpdateServer` library,
- NodeMCU 1.0 (ESP-12E Module).
You can use another module if it meets previously described [requirements](#basic-requirements).
1. Before you begin, please make sure that you have the following software installed:
- Arduino IDE and 2.0.0-rc1 (of Nov 17, 2015) version of platform package as described under https://github.com/esp8266/Arduino#installing-with-boards-manager
- Host software depending on O/S you use:
1. Avahi http://avahi.org/ for Linux
2. Bonjour http://www.apple.com/support/bonjour/ for Windows
3. Mac OSX and iOS - support is already built in / no any extra s/w is required
2. Prepare the sketch and configuration for initial upload with a serial port.
- Start Arduino IDE and load sketch WebUpdater.ino available under File > Examples > ESP8266HTTPUpdateServer.
- Update SSID and password in the sketch, so the module can join your Wi-Fi network.
- Open File > Preferences, look for “Show verbose output during:” and check out “compilation” option.
![alt text](ota-web-show-verbose-compilation.png "Preferences - enabling verbose output during compilation")
**Note:** This setting will be required in step 5 below. You can uncheck this setting afterwards.
3. Upload sketch (Ctrl+U). Once done, open Serial Monitor (Ctrl+Shift+M) and check if you see the following message displayed, that contains url for OTA update.
![alt text](ota-web-serial-monitor-ready.png "Serial Monitor - after first load using serial")
**Note:** Such message will be shown only after module successfully joins network and is ready for an OTA upload. Please remember about resetting the module once after serial upload as discussed in chapter [Arduino IDE](#arduino-ide), step 3.
4. Now open web browser and enter the url provided on Serial Monitor, i.e. `http://esp8266-webupdate.local/update`. Once entered, browser should display a form like below that has been served by your module. The form invites you to choose a file for update.
![alt text](ota-web-browser-form.png "OTA update form in web browser")
**Note:** If entering `http://esp8266-webupdate.local/update` does not work, try replacing `esp8266-webupdate` with module’s IP address. For example, if your module IP is `192.168.1.100` then url should be `http://192.168.1.100/update`. This workaround is useful in case the host software installed in step 1 does not work. If still nothing works and there are no clues on the Serial Monitor, try to diagnose issue by opening provided url in Google Chrome, pressing F12 and checking contents of “Console” and “Network” tabs. Chrome provides some advanced logging on these tabs.
5. To obtain the file, navigate to directory used by Arduino IDE to store results of compilation. You can check the path to this file in compilation log shown in IDE debug window as marked below.
![alt text](ota-web-path-to-binary.png "Compilation complete - path to binary file")
6. Now press “Choose File” in web browser, go to directory identified in step 5 above, find the file “WebUpdater.cpp.bin” and upload it. If upload is successful, you will see “OK” on web browser like below.
![alt text](ota-web-browser-form-ok.png "OTA update complete")
Module will reboot that should be visible on Serial Monitor:
![alt text](ota-web-serial-monitor-reboot.png "Serial Monitor - after OTA update")
Just after reboot you should see exactly the same message `HTTPUpdateServer ready! Open http:// esp8266-webupdate.local /update in your browser` like in step 3. This is because module has been loaded again with the same code – first using serial port, and then using OTA.
Once you are comfortable with this procedure, go ahead and modify WebUpdater.ino sketch to print some additional messages, compile it, locate new binary file and upload it using web browser to see entered changes on a Serial Monitor.
You can also add OTA routines to your own sketch following guidelines in [Implementation Overview](#implementation-overview) above. If this is done correctly, you should be always able to upload new sketch over the previous one using a web browser.
In case OTA update fails dead after entering modifications in your sketch, you can always recover module by loading it over a serial port. Then diagnose the issue with sketch using Serial Monitor. Once the issue is fixed try OTA again.
## HTTP Server
```ESPhttpUpdate``` class can check for updates and download a binary file from HTTP web server.
It is possible to download updates from every IP or domain address on the network or Internet.
#### Requirements
- web server
#### Arduino code
##### Simple updater
Simple updater downloads the file every time the function is called.
```cpp
ESPhttpUpdate.update("192.168.0.2", 80, "/arduino.bin");
```
##### Advanced updater
Its possible to point update function to a script at the server.
If version string argument is given, it will be sent to the server.
Server side script can use this to check if update should be performed.
Server side script can respond as follows:
- response code 200, and send the firmware image,
- or response code 304 to notify ESP that no update is required.
```cpp
t_httpUpdate_return ret = ESPhttpUpdate.update("192.168.0.2", 80, "/esp/update/arduino.php", "optional current version string here");
switch(ret) {
case HTTP_UPDATE_FAILED:
Serial.println("[update] Update failed.");
break;
case HTTP_UPDATE_NO_UPDATES:
Serial.println("[update] Update no Update.");
break;
case HTTP_UPDATE_OK:
Serial.println("[update] Update ok."); // may not called we reboot the ESP
break;
}
```
#### Server request handling
##### Simple updater
For the simple updater the server only needs to deliver the binary file for update.
##### Advanced updater
For advanced update management a script needs to run at the server side, for example a PHP script.
At every update request the ESP sends some information in HTTP headers to the server.
Example header data:
```
[HTTP_USER_AGENT] => ESP8266-http-Update
[HTTP_X_ESP8266_STA_MAC] => 18:FE:AA:AA:AA:AA
[HTTP_X_ESP8266_AP_MAC] => 1A:FE:AA:AA:AA:AA
[HTTP_X_ESP8266_FREE_SPACE] => 671744
[HTTP_X_ESP8266_SKETCH_SIZE] => 373940
[HTTP_X_ESP8266_SKETCH_MD5] => a56f8ef78a0bebd812f62067daf1408a
[HTTP_X_ESP8266_CHIP_SIZE] => 4194304
[HTTP_X_ESP8266_SDK_VERSION] => 1.3.0
[HTTP_X_ESP8266_VERSION] => DOOR-7-g14f53a19
```
With this information the script now can check if an update is needed. It is also possible to deliver different binaries based on the MAC address for example.
Script example:
```php
<?PHP
header('Content-type: text/plain; charset=utf8', true);
function check_header($name, $value = false) {
if(!isset($_SERVER[$name])) {
return false;
}
if($value && $_SERVER[$name] != $value) {
return false;
}
return true;
}
function sendFile($path) {
header($_SERVER["SERVER_PROTOCOL"].' 200 OK', true, 200);
header('Content-Type: application/octet-stream', true);
header('Content-Disposition: attachment; filename='.basename($path));
header('Content-Length: '.filesize($path), true);
header('x-MD5: '.md5_file($path), true);
readfile($path);
}
if(!check_header('HTTP_USER_AGENT', 'ESP8266-http-Update')) {
header($_SERVER["SERVER_PROTOCOL"].' 403 Forbidden', true, 403);
echo "only for ESP8266 updater!\n";
exit();
}
if(
!check_header('HTTP_X_ESP8266_STA_MAC') ||
!check_header('HTTP_X_ESP8266_AP_MAC') ||
!check_header('HTTP_X_ESP8266_FREE_SPACE') ||
!check_header('HTTP_X_ESP8266_SKETCH_SIZE') ||
!check_header('HTTP_X_ESP8266_SKETCH_MD5') ||
!check_header('HTTP_X_ESP8266_CHIP_SIZE') ||
!check_header('HTTP_X_ESP8266_SDK_VERSION')
) {
header($_SERVER["SERVER_PROTOCOL"].' 403 Forbidden', true, 403);
echo "only for ESP8266 updater! (header)\n";
exit();
}
$db = array(
"18:FE:AA:AA:AA:AA" => "DOOR-7-g14f53a19",
"18:FE:AA:AA:AA:BB" => "TEMP-1.0.0"
);
if(!isset($db[$_SERVER['HTTP_X_ESP8266_STA_MAC']])) {
header($_SERVER["SERVER_PROTOCOL"].' 500 ESP MAC not configured for updates', true, 500);
}
$localBinary = "./bin/".$db[$_SERVER['HTTP_X_ESP8266_STA_MAC']].".bin";
// Check if version has been set and does not match, if not, check if
// MD5 hash between local binary and ESP8266 binary do not match if not.
// then no update has been found.
if((!check_header('HTTP_X_ESP8266_SDK_VERSION') && $db[$_SERVER['HTTP_X_ESP8266_STA_MAC']] != $_SERVER['HTTP_X_ESP8266_VERSION'])
|| $_SERVER["HTTP_X_ESP8266_SKETCH_MD5"] != md5_file($localBinary)) {
sendFile($localBinary);
} else {
header($_SERVER["SERVER_PROTOCOL"].' 304 Not Modified', true, 304);
}
header($_SERVER["SERVER_PROTOCOL"].' 500 no version for ESP MAC', true, 500);
```
## Stream Interface
TODO describe Stream Interface
The Stream Interface is the base for all other update modes like OTA, http Server / client.
## Updater class
Updater is in the Core and deals with writing the firmware to the flash,
checking its integrity and telling the bootloader to load the new firmware on the next boot.
### Update process - memory view
- The new sketch will be stored in the space between the old sketch and the spiff.
- on the next reboot the "eboot" bootloader check for commands.
- the new sketch is now copied "over" the old one.
- the new sketch is started.
![alt text](update_memory_copy.png "Memory layout for OTA updates")

541
doc/ota_updates/readme.rst Normal file
View File

@ -0,0 +1,541 @@
OTA Updates
===========
Introduction
------------
OTA (Over the Air) update is the process of loading the firmware to ESP module using Wi-Fi connection rather than a serial port. Such functionality became extremely useful in case of limited or no physical access to the module.
OTA may be done using:
- `Arduino IDE <#arduino-ide>`__
- `Web Browser <#web-browser>`__
- `HTTP Server <#http-server>`__
Arduino IDE option is intended primarily for software development phase. The two other options would be more useful after deployment, to provide module with application updates manually with a web browser, or automatically using a http server.
In any case, the first firmware upload has to be done over a serial port. If the OTA routines are correctly implemented in a sketch, then all subsequent uploads may be done over the air.
There is no imposed security on OTA process from being hacked. It is up to developer to ensure that updates are allowed only from legitimate / trusted sources. Once the update is complete, the module restarts, and the new code is executed. The developer should ensure that the application running on the module is shut down and restarted in a safe manner. Chapters below provide additional information regarding security and safety of OTA process.
Security
~~~~~~~~
Module has to be exposed wirelessly to get it updated with a new sketch. That poses chances of module being violently hacked and loaded with some other code. To reduce likelihood of being hacked consider protecting your uploads with a password, selecting certain OTA port, etc.
Check functionality provided with `ArduinoOTA <https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA>`__ library that may improve security:
.. code:: cpp
void setPort(uint16_t port);
void setHostname(const char* hostname);
void setPassword(const char* password);
Certain protection functionality is already built in and do not require any additional coding by developer. `ArduinoOTA <https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA>`__ and espota.py use `Digest-MD5 <https://en.wikipedia.org/wiki/Digest_access_authentication>`__ to authenticate upload. Integrity of transferred data is verified on ESP side using `MD5 <https://en.wikipedia.org/wiki/MD5>`__ checksum.
Make your own risk analysis and depending on application decide what library functions to implement. If required, consider implementation of other means of protection from being hacked, e.g. exposing module for uploads only according to specific schedule, trigger OTA only be user pressing dedicated “Update” button wired to ESP, etc.
Safety
~~~~~~
OTA process takes ESP’s resources and bandwidth during upload. Then module is restarted and a new sketch executed. Analyse and test how it affects functionality of existing and new sketch.
If ESP is placed in remote location and controlling some equipment, you should put additional attention what happens if operation of this equipment is suddenly interrupted by update process. Therefore, decide how to put this equipment into safe state before starting the update. For instance, your module may be controlling a garden watering system in a sequence. If this sequence is not properly shut down and a water valve left open, your garden may be flooded.
The following functions are provided with `ArduinoOTA <https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA>`__ library and intended to handle functionality of your application during specific stages of OTA, or on an OTA error:
.. code:: cpp
void onStart(OTA_CALLBACK(fn));
void onEnd(OTA_CALLBACK(fn));
void onProgress(OTA_CALLBACK_PROGRESS(fn));
void onError(OTA_CALLBACK_ERROR (fn));
Basic Requirements
~~~~~~~~~~~~~~~~~~
Flash chip size should be able to hold the old sketch (currently running) and the new sketch (OTA) at the same time.
Keep in mind that the File system and EEPROM for example needs space too (one time) see `flash layout <../filesystem.md#flash-layout>`__.
.. code:: cpp
ESP.getFreeSketchSpace();
can be used for checking the free space for the new sketch.
For overview of memory layout, where new sketch is stored and how it is copied during OTA process, see `Update process - memory view <#update-process---memory-view>`__.
The following chapters provide more details and specific methods of doing OTA.
Arduino IDE
-----------
Uploading modules wirelessly from Arduino IDE is intended for the following typical scenarios: - during firmware development as a quicker alternative to loading over a serial, - for updating small quantity of modules, - only if modules are available on the same network as the computer with Arduino IDE.
Requirements
~~~~~~~~~~~~
- The ESP and the computer must be connected to the same network.
Application Example
~~~~~~~~~~~~~~~~~~~
Instructions below show configuration of OTA on NodeMCU 1.0 (ESP-12E Module) board. You can use any other board assuming that it meets `requirements <#basic-requirements>`__ described above. This instruction is valid for all operating systems supported by Arduino IDE. Screen captures have been made on Windows 7 and you may see small differences (like name of serial port), if you are using Linux and MacOS.
1. Before you begin, please make sure that you have the following s/w
installed:
- Arduino IDE 1.6.7 or newer -
https://www.arduino.cc/en/Main/Software
- esp8266/Arduino platform package 2.0.0 or newer - for instructions
follow
https://github.com/esp8266/Arduino#installing-with-boards-manager
- Python 2.7 (do not install Python 3.5 that is not supported) -
https://www.python.org/
**Note:** Windows users should select “Add python.exe to Path”
(see below – this option is not selected by default).
.. figure:: a-ota-python-configuration.png
:alt: Python installation set up
2. Now prepare the sketch and configuration for the upload over a serial
port.
- Start Arduino IDE and load sketch BasicOTA.ino available under
File > Examples > ArduinoOTA |ota sketch selection|
- Update SSID and password in the sketch, so the module can join
your Wi-Fi network |ota ssid pass entry|
- Configure upload parameters as below (you may need to adjust
configuration if you are using a different module): |ota serial upload config|
**Note:** Depending on version of platform package and board you
have, you may see ``Upload Using:`` in the menu above. This option
is inactive and it does not matter what you select. It has been
left for compatibility with older implementation of OTA and
finally removed in platform package version 2.2.0.
3. Upload the sketch (Ctrl+U). Once done, open Serial Monitor
(Ctrl+Shift+M) and check if module has joined your Wi-Fi network:
.. figure:: a-ota-upload-complete-and-joined-wifi.png
:alt: Check if module joined network
**Note:** ESP module should be reset after serial upload. Otherwise subsequent steps will not work. Reset may be done automatically for you after opening serial monitor as visible on the screenshot above. It depends on how you have DTR and RTS wired from USB-Serial converter to the ESP. If reset is not done automatically, then do it by pressing reset button or manually cycling the power. For more details why this should be done please refer to `FAQ <../faq#i-have-observed-a-case-when-esprestart-doesnt-work-what-is-the-reason-for-that>`__ regarding ``ESP.restart()``.
4. Only if module is connected to network, after a couple of seconds,
the esp8266-ota port will show up in Arduino IDE. Select port with IP
address shown in the Serial Monitor window in previous step:
.. figure:: a-ota-ota-port-selection.png
:alt: Selection of OTA port
**Note:** If OTA port does not show up, exit Arduino IDE, open it
again and check if port is there. If it does not help, check your
firewall and router settings. OTA port is advertised using mDNS
service. To check if port is visible by your PC, you can use
application like Bonjour Browser.
5. Now get ready for your first OTA upload by selecting the OTA port:
.. figure:: a-ota-ota-upload-configuration.png
:alt: Configuration of OTA upload
**Note:** The menu entry ``Upload Speed:`` does not matter at this
point as it concerns the serial port. Just left it unchanged.
6. If you have successfully completed all the above steps, you can
upload (Ctrl+U) the same (or any other) sketch over OTA:
.. figure:: a-ota-ota-upload-complete.png
:alt: OTA upload complete
**Note:** To be able to upload your sketch over and over again using OTA, you need to embed OTA routines inside. Please use BasicOTA.ino as an example.
Password Protection
^^^^^^^^^^^^^^^^^^^
Protecting your OTA uploads with password is really straightforward. All you need to do, is to include the following statement in your code:
.. code:: cpp
ArduinoOTA.setPassword((const char *)"123");
Where ``123`` is a sample password that you should replace with your own.
Before implementing it in your sketch, it is a good idea to check how it works using *BasicOTA.ino* sketch available under *File > Examples > ArduinoOTA*. Go ahead, open *BasicOTA.ino*, uncomment the above statement that is already there, and upload the sketch. To make troubleshooting easier, do not modify example sketch besides what is absolutely required. This is including original simple ``123`` OTA password. Then attempt to upload sketch again (using OTA). After compilation is complete, once upload is about to begin, you should see prompt for password as follows:
.. figure:: a-ota-upload-password-prompt.png
:alt: Password prompt for OTA upload
Enter the password and upload should be initiated as usual with the only difference being ``Authenticating...OK`` message visible in upload log.
.. figure:: a-ota-upload-password-authenticating-ok.png
:alt: Authenticating...OK during OTA upload
You will not be prompted for a reentering the same password next time. Arduino IDE will remember it for you. You will see prompt for password only after reopening IDE, or if you change it in your sketch, upload the sketch and then try to upload it again.
Please note, it is possible to reveal password entered previously in Arduino IDE, if IDE has not been closed since last upload. This can be done by enabling *Show verbose output during: upload* in *File > Preferences* and attempting to upload the module.
.. figure:: a-ota-upload-password-passing-upload-ok.png
:alt: Verbose upload output with password passing in plain text
The picture above shows that the password is visible in log, as it is passed to *espota.py* upload script.
Another example below shows situation when password is changed between uploads.
.. figure:: a-ota-upload-password-passing-again-upload-ok.png
:alt: Verbose output when OTA password has been changed between uploads
When uploading, Arduino IDE used previously entered password, so the upload failed and that has been clearly reported by IDE. Only then IDE prompted for a new password. That was entered correctly and second attempt to upload has been successful.
Troubleshooting
^^^^^^^^^^^^^^^
If OTA update fails, first step is to check for error messages that may be shown in upload window of Arduino IDE. If this is not providing any useful hints, try to upload again while checking what is shown by ESP on serial port. Serial Monitor from IDE will not be useful in that case. When attempting to open it, you will likely see the following:
.. figure:: a-ota-network-terminal.png
:alt: Arduino IDE network terminal window
This window is for Arduino Yún and not yet implemented for esp8266/Arduino. It shows up because IDE is attempting to open Serial Monitor using network port you have selected for OTA upload.
Instead you need an external serial monitor. If you are a Windows user check out `Termite <http://www.compuphase.com/software_termite.htm>`__. This is handy, slick and simple RS232 terminal that does not impose RTS or DTR flow control. Such flow control may cause issues if you are using respective lines to toggle GPIO0 and RESET pins on ESP for upload.
Select COM port and baud rate on external terminal program as if you were using Arduino Serial Monitor. Please see typical settings for `Termite <http://www.compuphase.com/software_termite.htm>`__ below:
.. figure:: termite-configuration.png
:alt: Termite settings
Then run OTA from IDE and look what is displayed on terminal. Successful `ArduinoOTA <#arduinoota>`__ process using BasicOTA.ino sketch looks like below (IP address depends on your network configuration):
.. figure:: a-ota-external-serial-terminal-output.png
:alt: OTA upload successful - output on an external serial terminal
If upload fails you will likely see errors caught by the uploader, exception and the stack trace, or both.
Instead of the log as on the above screen you may see the following:
.. figure:: a-ota-external-serial-terminal-output-failed.png
:alt: OTA upload failed - output on an external serial terminal
If this is the case, then most likely ESP module has not been reset after initial upload using serial port.
The most common causes of OTA failure are as follows: \* not enough physical memory on the chip (e.g. ESP01 with 512K flash memory is not enough for OTA), \* too much memory declared for SPIFFS so new sketch will not fit between existing sketch and SPIFFS – see `Update process - memory view <#update-process---memory-view>`__, \* too little memory declared in Arduino IDE for your selected board (i.e. less than physical size), \* not resetting the ESP module after initial upload using serial port.
For more details regarding flash memory layout please check `File system <https://github.com/esp8266/Arduino/blob/master/doc/filesystem.md>`__. For overview where new sketch is stored, how it is copied and how memory is organized for the purpose of OTA see `Update process - memory view <#update-process---memory-view>`__.
Web Browser
-----------
Updates described in this chapter are done with a web browser that can be useful in the following typical scenarios:
- after application deployment if loading directly from Arduino IDE is
inconvenient or not possible,
- after deployment if user is unable to expose module for OTA from
external update server,
- to provide updates after deployment to small quantity of modules when
setting an update server is not practicable.
Requirements
~~~~~~~~~~~~
- The ESP and the computer must be connected to the same network.
Implementation Overview
~~~~~~~~~~~~~~~~~~~~~~~
Updates with a web browser are implemented using ``ESP8266HTTPUpdateServer`` class together with ``ESP8266WebServer`` and ``ESP8266mDNS`` classes. The following code is required to get it work:
setup()
.. code:: cpp
MDNS.begin(host);
httpUpdater.setup(&httpServer);
httpServer.begin();
MDNS.addService("http", "tcp", 80);
loop()
.. code:: cpp
httpServer.handleClient();
Application Example
~~~~~~~~~~~~~~~~~~~
The sample implementation provided below has been done using:
- example sketch WebUpdater.ino available in
``ESP8266HTTPUpdateServer`` library,
- NodeMCU 1.0 (ESP-12E Module).
You can use another module if it meets previously described `requirements <#basic-requirements>`__.
1. Before you begin, please make sure that you have the following
software installed:
- Arduino IDE and 2.0.0-rc1 (of Nov 17, 2015) version of platform
package as described under
https://github.com/esp8266/Arduino#installing-with-boards-manager
- Host software depending on O/S you use:
1. Avahi http://avahi.org/ for Linux
2. Bonjour http://www.apple.com/support/bonjour/ for Windows
3. Mac OSX and iOS - support is already built in / no any extra
s/w is required
2. Prepare the sketch and configuration for initial upload with a serial
port.
- Start Arduino IDE and load sketch WebUpdater.ino available under
File > Examples > ESP8266HTTPUpdateServer.
- Update SSID and password in the sketch, so the module can join
your Wi-Fi network.
- Open File > Preferences, look for “Show verbose output during:”
and check out “compilation” option.
.. figure:: ota-web-show-verbose-compilation.png
:alt: Preferences - enabling verbose output during compilation
**Note:** This setting will be required in step 5 below. You can
uncheck this setting afterwards.
3. Upload sketch (Ctrl+U). Once done, open Serial Monitor (Ctrl+Shift+M)
and check if you see the following message displayed, that contains
url for OTA update.
.. figure:: ota-web-serial-monitor-ready.png
:alt: Serial Monitor - after first load using serial
**Note:** Such message will be shown only after module successfully
joins network and is ready for an OTA upload. Please remember about
resetting the module once after serial upload as discussed in chapter
`Arduino IDE <#arduino-ide>`__, step 3.
4. Now open web browser and enter the url provided on Serial Monitor,
i.e. ``http://esp8266-webupdate.local/update``. Once entered, browser
should display a form like below that has been served by your module.
The form invites you to choose a file for update.
.. figure:: ota-web-browser-form.png
:alt: OTA update form in web browser
**Note:** If entering ``http://esp8266-webupdate.local/update`` does
not work, try replacing ``esp8266-webupdate`` with module’s IP
address. For example, if your module IP is ``192.168.1.100`` then url
should be ``http://192.168.1.100/update``. This workaround is useful
in case the host software installed in step 1 does not work. If still
nothing works and there are no clues on the Serial Monitor, try to
diagnose issue by opening provided url in Google Chrome, pressing F12
and checking contents of “Console” and “Network” tabs. Chrome
provides some advanced logging on these tabs.
5. To obtain the file, navigate to directory used by Arduino IDE to
store results of compilation. You can check the path to this file in
compilation log shown in IDE debug window as marked below.
.. figure:: ota-web-path-to-binary.png
:alt: Compilation complete - path to binary file
6. Now press “Choose File” in web browser, go to directory identified in
step 5 above, find the file “WebUpdater.cpp.bin” and upload it. If
upload is successful, you will see “OK” on web browser like below.
.. figure:: ota-web-browser-form-ok.png
:alt: OTA update complete
Module will reboot that should be visible on Serial Monitor:
.. figure:: ota-web-serial-monitor-reboot.png
:alt: Serial Monitor - after OTA update
Just after reboot you should see exactly the same message
``HTTPUpdateServer ready! Open http:// esp8266-webupdate.local /update in your browser``
like in step 3. This is because module has been loaded again with the
same code – first using serial port, and then using OTA.
Once you are comfortable with this procedure, go ahead and modify WebUpdater.ino sketch to print some additional messages, compile it, locate new binary file and upload it using web browser to see entered changes on a Serial Monitor.
You can also add OTA routines to your own sketch following guidelines in `Implementation Overview <#implementation-overview>`__ above. If this is done correctly, you should be always able to upload new sketch over the previous one using a web browser.
In case OTA update fails dead after entering modifications in your sketch, you can always recover module by loading it over a serial port. Then diagnose the issue with sketch using Serial Monitor. Once the issue is fixed try OTA again.
HTTP Server
-----------
``ESPhttpUpdate`` class can check for updates and download a binary file from HTTP web server. It is possible to download updates from every IP or domain address on the network or Internet.
Requirements
~~~~~~~~~~~~
- web server
Arduino code
~~~~~~~~~~~~
Simple updater
^^^^^^^^^^^^^^
Simple updater downloads the file every time the function is called.
.. code:: cpp
ESPhttpUpdate.update("192.168.0.2", 80, "/arduino.bin");
Advanced updater
^^^^^^^^^^^^^^^^
Its possible to point update function to a script at the server. If version string argument is given, it will be sent to the server. Server side script can use this to check if update should be performed.
Server side script can respond as follows: - response code 200, and send the firmware image, - or response code 304 to notify ESP that no update is required.
.. code:: cpp
t_httpUpdate_return ret = ESPhttpUpdate.update("192.168.0.2", 80, "/esp/update/arduino.php", "optional current version string here");
switch(ret) {
case HTTP_UPDATE_FAILED:
Serial.println("[update] Update failed.");
break;
case HTTP_UPDATE_NO_UPDATES:
Serial.println("[update] Update no Update.");
break;
case HTTP_UPDATE_OK:
Serial.println("[update] Update ok."); // may not called we reboot the ESP
break;
}
Server request handling
~~~~~~~~~~~~~~~~~~~~~~~
Simple updater
^^^^^^^^^^^^^^
For the simple updater the server only needs to deliver the binary file for update.
Advanced updater
^^^^^^^^^^^^^^^^
For advanced update management a script needs to run at the server side, for example a PHP script. At every update request the ESP sends some information in HTTP headers to the server.
Example header data:
::
[HTTP_USER_AGENT] => ESP8266-http-Update
[HTTP_X_ESP8266_STA_MAC] => 18:FE:AA:AA:AA:AA
[HTTP_X_ESP8266_AP_MAC] => 1A:FE:AA:AA:AA:AA
[HTTP_X_ESP8266_FREE_SPACE] => 671744
[HTTP_X_ESP8266_SKETCH_SIZE] => 373940
[HTTP_X_ESP8266_SKETCH_MD5] => a56f8ef78a0bebd812f62067daf1408a
[HTTP_X_ESP8266_CHIP_SIZE] => 4194304
[HTTP_X_ESP8266_SDK_VERSION] => 1.3.0
[HTTP_X_ESP8266_VERSION] => DOOR-7-g14f53a19
With this information the script now can check if an update is needed. It is also possible to deliver different binaries based on the MAC address for example.
Script example:
.. code:: php
<?PHP
header('Content-type: text/plain; charset=utf8', true);
function check_header($name, $value = false) {
if(!isset($_SERVER[$name])) {
return false;
}
if($value && $_SERVER[$name] != $value) {
return false;
}
return true;
}
function sendFile($path) {
header($_SERVER["SERVER_PROTOCOL"].' 200 OK', true, 200);
header('Content-Type: application/octet-stream', true);
header('Content-Disposition: attachment; filename='.basename($path));
header('Content-Length: '.filesize($path), true);
header('x-MD5: '.md5_file($path), true);
readfile($path);
}
if(!check_header('HTTP_USER_AGENT', 'ESP8266-http-Update')) {
header($_SERVER["SERVER_PROTOCOL"].' 403 Forbidden', true, 403);
echo "only for ESP8266 updater!\n";
exit();
}
if(
!check_header('HTTP_X_ESP8266_STA_MAC') ||
!check_header('HTTP_X_ESP8266_AP_MAC') ||
!check_header('HTTP_X_ESP8266_FREE_SPACE') ||
!check_header('HTTP_X_ESP8266_SKETCH_SIZE') ||
!check_header('HTTP_X_ESP8266_SKETCH_MD5') ||
!check_header('HTTP_X_ESP8266_CHIP_SIZE') ||
!check_header('HTTP_X_ESP8266_SDK_VERSION')
) {
header($_SERVER["SERVER_PROTOCOL"].' 403 Forbidden', true, 403);
echo "only for ESP8266 updater! (header)\n";
exit();
}
$db = array(
"18:FE:AA:AA:AA:AA" => "DOOR-7-g14f53a19",
"18:FE:AA:AA:AA:BB" => "TEMP-1.0.0"
);
if(!isset($db[$_SERVER['HTTP_X_ESP8266_STA_MAC']])) {
header($_SERVER["SERVER_PROTOCOL"].' 500 ESP MAC not configured for updates', true, 500);
}
$localBinary = "./bin/".$db[$_SERVER['HTTP_X_ESP8266_STA_MAC']].".bin";
// Check if version has been set and does not match, if not, check if
// MD5 hash between local binary and ESP8266 binary do not match if not.
// then no update has been found.
if((!check_header('HTTP_X_ESP8266_SDK_VERSION') && $db[$_SERVER['HTTP_X_ESP8266_STA_MAC']] != $_SERVER['HTTP_X_ESP8266_VERSION'])
|| $_SERVER["HTTP_X_ESP8266_SKETCH_MD5"] != md5_file($localBinary)) {
sendFile($localBinary);
} else {
header($_SERVER["SERVER_PROTOCOL"].' 304 Not Modified', true, 304);
}
header($_SERVER["SERVER_PROTOCOL"].' 500 no version for ESP MAC', true, 500);
Stream Interface
----------------
TODO describe Stream Interface
The Stream Interface is the base for all other update modes like OTA, http Server / client.
Updater class
-------------
Updater is in the Core and deals with writing the firmware to the flash, checking its integrity and telling the bootloader to load the new firmware on the next boot.
Update process - memory view
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The new sketch will be stored in the space between the old sketch and
the spiff.
- on the next reboot the "eboot" bootloader check for commands.
- the new sketch is now copied "over" the old one.
- the new sketch is started.
.. figure:: update_memory_copy.png
:alt: Memory layout for OTA updates
.. |ota sketch selection| image:: a-ota-sketch-selection.png
.. |ota ssid pass entry| image:: a-ota-ssid-pass-entry.png
.. |ota serial upload config| image:: a-ota-serial-upload-configuration.png

130
doc/reference.md
View File

@ -1,130 +0,0 @@
---
title: Reference
---
## Table of Contents
* [Table of Contents](#table-of-contents)
* [Digital IO](#digital-io)
* [Analog input](#analog-input)
* [Analog output](#analog-output)
* [Timing and delays](#timing-and-delays)
* [Serial](#serial)
* [Progmem](#progmem)
## Digital IO
Pin numbers in Arduino correspond directly to the ESP8266 GPIO pin numbers. `pinMode`, `digitalRead`, and `digitalWrite` functions work as usual, so to read GPIO2, call `digitalRead(2)`.
Digital pins 0—15 can be `INPUT`, `OUTPUT`, or `INPUT_PULLUP`.
Pin 16 can be `INPUT`, `OUTPUT` or `INPUT_PULLDOWN_16`. At startup, pins are configured as `INPUT`.
Pins may also serve other functions, like Serial, I2C, SPI. These functions are normally activated by the corresponding library. The diagram below shows pin mapping for the popular ESP-12 module.
![Pin Functions](esp12.png)
Digital pins 6—11 are not shown on this diagram because they are used to connect flash memory chip on most modules. Trying to use these pins as IOs will likely cause the program to crash.
Note that some boards and modules (ESP-12ED, NodeMCU 1.0) also break out pins 9 and 11. These may be used as IO if flash chip works in DIO mode (as opposed to QIO, which is the default one).
Pin interrupts are supported through `attachInterrupt`, `detachInterrupt` functions.
Interrupts may be attached to any GPIO pin, except GPIO16. Standard Arduino interrupt
types are supported: `CHANGE`, `RISING`, `FALLING`.
## Analog input
ESP8266 has a single ADC channel available to users. It may be used either to read voltage at ADC pin, or to read module supply voltage (VCC).
To read external voltage applied to ADC pin, use `analogRead(A0)`. Input voltage range is 0 — 1.0V.
To read VCC voltage, use `ESP.getVcc()` and ADC pin must be kept unconnected. Additionally, the following line has to be added to the sketch:
```c++
ADC_MODE(ADC_VCC);
```
This line has to appear outside of any functions, for instance right after the `#include ` lines of your sketch.
## Analog output
`analogWrite(pin, value)` enables software PWM on the given pin. PWM may be used on pins 0 to 16.
Call `analogWrite(pin, 0)` to disable PWM on the pin. `value` may be in range from 0 to `PWMRANGE`, which is equal to 1023 by default. PWM range may be changed by calling `analogWriteRange(new_range)`.
PWM frequency is 1kHz by default. Call `analogWriteFreq(new_frequency)` to change the frequency.
## Timing and delays
`millis()` and `micros()` return the number of milliseconds and microseconds elapsed after reset, respectively.
`delay(ms)` pauses the sketch for a given number of milliseconds and allows WiFi and TCP/IP tasks to run.
`delayMicroseconds(us)` pauses for a given number of microseconds.
Remember that there is a lot of code that needs to run on the chip besides the sketch
when WiFi is connected. WiFi and TCP/IP libraries get a chance to handle any pending
events each time the `loop()` function completes, OR when `delay` is called.
If you have a loop somewhere in your sketch that takes a lot of time (>50ms) without
calling `delay`, you might consider adding a call to `delay` function to keep the WiFi
stack running smoothly.
There is also a `yield()` function which is equivalent to `delay(0)`. The `delayMicroseconds`
function, on the other hand, does not yield to other tasks, so using it for delays
more than 20 milliseconds is not recommended.
## Serial
`Serial` object works much the same way as on a regular Arduino. Apart from hardware FIFO (128 bytes for TX and RX) HardwareSerial has additional 256-byte TX and RX buffers. Both transmit and receive is interrupt-driven. Write and read functions only block the sketch execution when the respective FIFO/buffers are full/empty.
`Serial` uses UART0, which is mapped to pins GPIO1 (TX) and GPIO3 (RX). Serial may be remapped to GPIO15 (TX) and GPIO13 (RX) by calling `Serial.swap()` after `Serial.begin`. Calling `swap` again maps UART0 back to GPIO1 and GPIO3.
`Serial1` uses UART1, TX pin is GPIO2. UART1 can not be used to receive data because normally it's RX pin is occupied for flash chip connection. To use `Serial1`, call `Serial1.begin(baudrate)`.
If `Serial1` is not used and `Serial` is not swapped - TX for UART0 can be mapped to GPIO2 instead by calling `Serial.set_tx(2)` after `Serial.begin` or directly with `Serial.begin(baud, config, mode, 2)`.
By default the diagnostic output from WiFi libraries is disabled when you call `Serial.begin`. To enable debug output again, call `Serial.setDebugOutput(true)`. To redirect debug output to `Serial1` instead, call `Serial1.setDebugOutput(true)`.
You also need to use `Serial.setDebugOutput(true)` to enable output from `printf()` function.
Both `Serial` and `Serial1` objects support 5, 6, 7, 8 data bits, odd (O), even (E), and no (N) parity, and 1 or 2 stop bits. To set the desired mode, call `Serial.begin(baudrate, SERIAL_8N1)`, `Serial.begin(baudrate, SERIAL_6E2)`, etc.
A new method has been implemented on both `Serial` and `Serial1` to get current baud rate setting. To get the current baud rate, call `Serial.baudRate()`, `Serial1.baudRate()`. Return a `int` of current speed. For example
```cpp
// Set Baud rate to 57600
Serial.begin(57600);
// Get current baud rate
int br = Serial.baudRate();
// Will print "Serial is 57600 bps"
Serial.printf("Serial is %d bps", br);
```
I've done this also for official ESP8266 [Software Serial](https://github.com/esp8266/Arduino/blob/master/doc/libraries.md#softwareserial) library, see this [pull request](https://github.com/plerup/espsoftwareserial/pull/22).
Note that this implementation is **only for ESP8266 based boards**, and will not works with other Arduino boards.
## Progmem
The Program memory features work much the same way as on a regular Arduino; placing read only data and strings in read only memory and freeing heap for your application.
The important difference is that on the ESP8266 the literal strings are not pooled. This means that the same literal string defined inside a `F("")` and/or `PSTR("")` will take up space for each instance in the code. So you will need to manage the duplicate strings yourself.
There is one additional helper macro to make it easier to pass ```const PROGMEM``` strings to methods that take a ```__FlashStringHelper``` called ```FPSTR()```. The use of this will help make it easier to pool strings.
Not pooling strings...
```c++
String response1;
response1 += F("http:");
...
String response2;
response2 += F("http:");
```
using FPSTR would become...
```c++
const char HTTP[] PROGMEM = "http:";
...
{
String response1;
response1 += FPSTR(HTTP);
...
String response2;
response2 += FPSTR(HTTP);
}
```

188
doc/reference.rst Normal file
View File

@ -0,0 +1,188 @@
Reference
=========
Digital IO
----------
Pin numbers in Arduino correspond directly to the ESP8266 GPIO pin
numbers. ``pinMode``, ``digitalRead``, and ``digitalWrite`` functions
work as usual, so to read GPIO2, call ``digitalRead(2)``.
Digital pins 0—15 can be ``INPUT``, ``OUTPUT``, or ``INPUT_PULLUP``. Pin
16 can be ``INPUT``, ``OUTPUT`` or ``INPUT_PULLDOWN_16``. At startup,
pins are configured as ``INPUT``.
Pins may also serve other functions, like Serial, I2C, SPI. These
functions are normally activated by the corresponding library. The
diagram below shows pin mapping for the popular ESP-12 module.
.. figure:: esp12.png
:alt: Pin Functions
Pin Functions
Digital pins 6—11 are not shown on this diagram because they are used to
connect flash memory chip on most modules. Trying to use these pins as
IOs will likely cause the program to crash.
Note that some boards and modules (ESP-12ED, NodeMCU 1.0) also break out
pins 9 and 11. These may be used as IO if flash chip works in DIO mode
(as opposed to QIO, which is the default one).
Pin interrupts are supported through ``attachInterrupt``,
``detachInterrupt`` functions. Interrupts may be attached to any GPIO
pin, except GPIO16. Standard Arduino interrupt types are supported:
``CHANGE``, ``RISING``, ``FALLING``.
Analog input
------------
ESP8266 has a single ADC channel available to users. It may be used
either to read voltage at ADC pin, or to read module supply voltage
(VCC).
To read external voltage applied to ADC pin, use ``analogRead(A0)``.
Input voltage range is 0 — 1.0V.
To read VCC voltage, use ``ESP.getVcc()`` and ADC pin must be kept
unconnected. Additionally, the following line has to be added to the
sketch:
.. code:: cpp
ADC_MODE(ADC_VCC);
This line has to appear outside of any functions, for instance right
after the ``#include`` lines of your sketch.
Analog output
-------------
``analogWrite(pin, value)`` enables software PWM on the given pin. PWM
may be used on pins 0 to 16. Call ``analogWrite(pin, 0)`` to disable PWM
on the pin. ``value`` may be in range from 0 to ``PWMRANGE``, which is
equal to 1023 by default. PWM range may be changed by calling
``analogWriteRange(new_range)``.
PWM frequency is 1kHz by default. Call
``analogWriteFreq(new_frequency)`` to change the frequency.
Timing and delays
-----------------
``millis()`` and ``micros()`` return the number of milliseconds and
microseconds elapsed after reset, respectively.
``delay(ms)`` pauses the sketch for a given number of milliseconds and
allows WiFi and TCP/IP tasks to run. ``delayMicroseconds(us)`` pauses
for a given number of microseconds.
Remember that there is a lot of code that needs to run on the chip
besides the sketch when WiFi is connected. WiFi and TCP/IP libraries get
a chance to handle any pending events each time the ``loop()`` function
completes, OR when ``delay`` is called. If you have a loop somewhere in
your sketch that takes a lot of time (>50ms) without calling ``delay``,
you might consider adding a call to ``delay`` function to keep the WiFi
stack running smoothly.
There is also a ``yield()`` function which is equivalent to
``delay(0)``. The ``delayMicroseconds`` function, on the other hand,
does not yield to other tasks, so using it for delays more than 20
milliseconds is not recommended.
Serial
------
``Serial`` object works much the same way as on a regular Arduino. Apart
from hardware FIFO (128 bytes for TX and RX) HardwareSerial has
additional 256-byte TX and RX buffers. Both transmit and receive is
interrupt-driven. Write and read functions only block the sketch
execution when the respective FIFO/buffers are full/empty.
``Serial`` uses UART0, which is mapped to pins GPIO1 (TX) and GPIO3
(RX). Serial may be remapped to GPIO15 (TX) and GPIO13 (RX) by calling
``Serial.swap()`` after ``Serial.begin``. Calling ``swap`` again maps
UART0 back to GPIO1 and GPIO3.
``Serial1`` uses UART1, TX pin is GPIO2. UART1 can not be used to
receive data because normally it's RX pin is occupied for flash chip
connection. To use ``Serial1``, call ``Serial1.begin(baudrate)``.
If ``Serial1`` is not used and ``Serial`` is not swapped - TX for UART0
can be mapped to GPIO2 instead by calling ``Serial.set_tx(2)`` after
``Serial.begin`` or directly with
``Serial.begin(baud, config, mode, 2)``.
By default the diagnostic output from WiFi libraries is disabled when
you call ``Serial.begin``. To enable debug output again, call
``Serial.setDebugOutput(true)``. To redirect debug output to ``Serial1``
instead, call ``Serial1.setDebugOutput(true)``.
You also need to use ``Serial.setDebugOutput(true)`` to enable output
from ``printf()`` function.
Both ``Serial`` and ``Serial1`` objects support 5, 6, 7, 8 data bits,
odd (O), even (E), and no (N) parity, and 1 or 2 stop bits. To set the
desired mode, call ``Serial.begin(baudrate, SERIAL_8N1)``,
``Serial.begin(baudrate, SERIAL_6E2)``, etc.
A new method has been implemented on both ``Serial`` and ``Serial1`` to
get current baud rate setting. To get the current baud rate, call
``Serial.baudRate()``, ``Serial1.baudRate()``. Return a ``int`` of
current speed. For example
.. code:: cpp
// Set Baud rate to 57600
Serial.begin(57600);
// Get current baud rate
int br = Serial.baudRate();
// Will print "Serial is 57600 bps"
Serial.printf("Serial is %d bps", br);
| I've done this also for official ESP8266 `Software
Serial <https://github.com/esp8266/Arduino/blob/master/doc/libraries.md#softwareserial>`__
library, see this `pull
request <https://github.com/plerup/espsoftwareserial/pull/22>`__.
| Note that this implementation is **only for ESP8266 based boards**,
and will not works with other Arduino boards.
Progmem
-------
The Program memory features work much the same way as on a regular
Arduino; placing read only data and strings in read only memory and
freeing heap for your application. The important difference is that on
the ESP8266 the literal strings are not pooled. This means that the same
literal string defined inside a ``F("")`` and/or ``PSTR("")`` will take
up space for each instance in the code. So you will need to manage the
duplicate strings yourself.
There is one additional helper macro to make it easier to pass
``const PROGMEM`` strings to methods that take a ``__FlashStringHelper``
called ``FPSTR()``. The use of this will help make it easier to pool
strings. Not pooling strings...
.. code:: cpp
String response1;
response1 += F("http:");
...
String response2;
response2 += F("http:");
using FPSTR would become...
.. code:: cpp
const char HTTP[] PROGMEM = "http:";
...
{
String response1;
response1 += FPSTR(HTTP);
...
String response2;
response2 += FPSTR(HTTP);
}

5
doc/requirements.txt Normal file
View File

@ -0,0 +1,5 @@
# Requirements file for pip
# list of Python packages used in documentation build
sphinx
sphinx-rtd-theme
breathe

57
libraries/ESP8266AVRISP/README.md
View File

@ -1,57 +0,0 @@
# AVR In-System Programming over WiFi for ESP8266
This library allows an ESP8266 module with the HSPI port available to become
an AVR In-System Programmer.
## Hardware
The ESP8266 module connects to the AVR target chip via the standard 6-pin
AVR "Recommended In-System Programming Interface Connector Layout" as seen
in [AVR910](http://www.atmel.com/images/doc0943.pdf) among other places.
If the AVR target is powered by a different Vcc than what powers your ESP8266
chip, you **must provide voltage level shifting** or some other form of buffers.
Exposing the pins of ESP8266 to anything larger than 3.6V will damage it.
Connections are as follows:
ESP8266 | AVR / SPI
--------|------------
GPIO12 | MISO
GPIO13 | MOSI
GPIO14 | SCK
any* | RESET
For RESET use a GPIO other than 0, 2 and 15 (bootselect pins), and apply an
external pullup/down so that the target is normally running.
## Usage
See the included example. In short:
```arduino
// Create the programmer object
ESP8266AVRISP avrprog(PORT, RESET_PIN)
// ... with custom SPI frequency
ESP8266AVRISP avrprog(PORT, RESET_PIN, 4e6)
// Check current connection state, but don't perform any actions
AVRISPState_t state = avrprog.update();
// Serve the pending connection, execute STK500 commands
AVRISPState_t state = avrprog.serve();
```
### License and Authors
This library started off from the source of ArduinoISP "sketch" included with
the Arduino IDE:
ArduinoISP version 04m3
Copyright (c) 2008-2011 Randall Bohn
If you require a license, see
http://www.opensource.org/licenses/bsd-license.php
Support for TCP on ESP8266
Copyright (c) Kiril Zyapkov <kiril@robotev.com>.

70
libraries/ESP8266AVRISP/README.rst Normal file
View File

@ -0,0 +1,70 @@
AVR In-System Programming over WiFi for ESP8266
===============================================
This library allows an ESP8266 module with the HSPI port available to
become an AVR In-System Programmer.
Hardware
--------
The ESP8266 module connects to the AVR target chip via the standard
6-pin AVR "Recommended In-System Programming Interface Connector Layout"
as seen in `AVR910 <http://www.atmel.com/images/doc0943.pdf>`__ among
other places.
If the AVR target is powered by a different Vcc than what powers your
ESP8266 chip, you **must provide voltage level shifting** or some other
form of buffers. Exposing the pins of ESP8266 to anything larger than
3.6V will damage it.
Connections are as follows:
+-----------+-------------+
| ESP8266 | AVR / SPI |
+===========+=============+
| GPIO12 | MISO |
+-----------+-------------+
| GPIO13 | MOSI |
+-----------+-------------+
| GPIO14 | SCK |
+-----------+-------------+
| any\* | RESET |
+-----------+-------------+
For RESET use a GPIO other than 0, 2 and 15 (bootselect pins), and apply
an external pullup/down so that the target is normally running.
Usage
-----
See the included example. In short:
.. code:: arduino
// Create the programmer object
ESP8266AVRISP avrprog(PORT, RESET_PIN)
// ... with custom SPI frequency
ESP8266AVRISP avrprog(PORT, RESET_PIN, 4e6)
// Check current connection state, but don't perform any actions
AVRISPState_t state = avrprog.update();
// Serve the pending connection, execute STK500 commands
AVRISPState_t state = avrprog.serve();
License and Authors
~~~~~~~~~~~~~~~~~~~
This library started off from the source of ArduinoISP "sketch" included
with the Arduino IDE:
::
ArduinoISP version 04m3
Copyright (c) 2008-2011 Randall Bohn
If you require a license, see
http://www.opensource.org/licenses/bsd-license.php
Support for TCP on ESP8266
Copyright (c) Kiril Zyapkov <kiril@robotev.com>.

22
libraries/ESP8266SSDP/README.md
View File

@ -1,22 +0,0 @@
ESP8266 Simple Service Discovery
Copyright (c) 2015 Hristo Gochkov
Original (Arduino) version by Filippo Sallemi, July 23, 2014.
Can be found at: https://github.com/nomadnt/uSSDP
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

22
libraries/ESP8266SSDP/README.rst Normal file
View File

@ -0,0 +1,22 @@
ESP8266 Simple Service Discovery Copyright (c) 2015 Hristo Gochkov
Original (Arduino) version by Filippo Sallemi, July 23, 2014. Can be
found at: https://github.com/nomadnt/uSSDP
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

52
libraries/ESP8266mDNS/README.md
View File

@ -1,52 +0,0 @@
ESP8266 Multicast DNS
====================
A port of CC3000 Multicast DNS library (version 1.1)
This is a simple implementation of multicast DNS query support for an Arduino
running on ESP8266 chip. Only support for resolving address queries is currently
implemented.
Requirements
------------
- ESP8266WiFi library
- MDNS support in your operating system/client machines:
- For Mac OSX support is built in through Bonjour already.
- For Linux, install [Avahi](http://avahi.org/).
- For Windows, install [Bonjour](http://www.apple.com/support/bonjour/).
Usage
-----
1. Download this repository as a zip (button on the right) and follow [these instructions to install into Arduino](http://arduino.cc/en/Guide/Libraries).
2. Include the ESP8266mDNS library in the sketch.
3. Call MDNS.begin method in the sketch's setup and provide a domain name (without
the '.local' suffix, i.e. just provide 'foo' to resolve 'foo.local'). Optionally provide
the IP address to advertise and time to live (in seconds) for the DNS record -- the default is 1 hour.
4. To advertise DNS-SD services, call MDNS.addService(service, proto, port), where service and proto
are strings with service and protocol name (e.g. "http", "tcp"), and port is an integer port number
for this service (e.g. 80).
See the included MDNS + HTTP server sketch for a full example.
License
-------
Copyright (c) 2013 Tony DiCola (tony@tonydicola.com)
ESP8266 port (c) 2015 Ivan Grokhotkov (ivan@esp8266.com)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

61
libraries/ESP8266mDNS/README.rst Normal file
View File

@ -0,0 +1,61 @@
ESP8266 Multicast DNS
=====================
A port of CC3000 Multicast DNS library (version 1.1)
This is a simple implementation of multicast DNS query support for an
Arduino running on ESP8266 chip. Only support for resolving address
queries is currently implemented.
Requirements
------------
- ESP8266WiFi library
- MDNS support in your operating system/client machines:
- For Mac OSX support is built in through Bonjour already.
- For Linux, install `Avahi <http://avahi.org/>`__.
- For Windows, install
`Bonjour <http://www.apple.com/support/bonjour/>`__.
Usage
-----
1. Download this repository as a zip (button on the right) and follow
`these instructions to install into
Arduino <http://arduino.cc/en/Guide/Libraries>`__.
2. Include the ESP8266mDNS library in the sketch.
3. Call MDNS.begin method in the sketch's setup and provide a domain
name (without the '.local' suffix, i.e. just provide 'foo' to resolve
'foo.local'). Optionally provide the IP address to advertise and time
to live (in seconds) for the DNS record -- the default is 1 hour.
4. To advertise DNS-SD services, call MDNS.addService(service, proto,
port), where service and proto are strings with service and protocol
name (e.g. "http", "tcp"), and port is an integer port number for
this service (e.g. 80).
See the included MDNS + HTTP server sketch for a full example.
License
-------
Copyright (c) 2013 Tony DiCola (tony@tonydicola.com) ESP8266 port (c)
2015 Ivan Grokhotkov (ivan@esp8266.com)
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

34
libraries/GDBStub/README.md
View File

@ -1,34 +0,0 @@
## Using GDB stub
- Add `#include <GDBStub.h>` to the sketch
- Upload the sketch
- Redirect serial port to TCP port:
```
tcp_serial_redirect.py -p /dev/tty.SLAB_USBtoUART -b 115200 --spy -P 9980 --rts=0 --dtr=0
```
Change port and baud rate as necessary. This command requires python and pyserial.
- Observe serial output:
```
nc localhost 9980
```
- Once crash happens, close nc and start gdb:
```
xtensa-lx106-elf-gdb /path/to/Sketch.cpp.elf -ex "target remote :9980"
```
Or, using the provided gdbcmds file:
```
xtensa-lx106-elf-gdb /path/to/Sketch.cpp.elf -x gdbcmds
```
- Use gdb to inspect program state at the point of an exception.
## Tips and tricks
- To halt the target when software WDT fires, add
```
((int*)0) = 0;
```
at the top of `__wrap_system_restart_local` in core_esp8266_postmortem.c.
## License
Espressif MIT License. See License file.

49
libraries/GDBStub/README.rst Normal file
View File

@ -0,0 +1,49 @@
Using GDB stub
--------------
- Add ``#include <GDBStub.h>`` to the sketch
- Upload the sketch
- Redirect serial port to TCP port:
::
tcp_serial_redirect.py -p /dev/tty.SLAB_USBtoUART -b 115200 --spy -P 9980 --rts=0 --dtr=0
Change port and baud rate as necessary. This command requires python
and pyserial.
- Observe serial output:
::
nc localhost 9980
- Once crash happens, close nc and start gdb:
::
xtensa-lx106-elf-gdb /path/to/Sketch.cpp.elf -ex "target remote :9980"
Or, using the provided gdbcmds file:
::
xtensa-lx106-elf-gdb /path/to/Sketch.cpp.elf -x gdbcmds
- Use gdb to inspect program state at the point of an exception.
Tips and tricks
---------------
- To halt the target when software WDT fires, add
::
((int*)0) = 0;
at the top of ``__wrap_system_restart_local`` in
core\_esp8266\_postmortem.c.
License
-------
Espressif MIT License. See License file.