From 283eb97cd3f6dac691e8350a612021f1e1ccd8e3 Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Sun, 19 Feb 2017 16:55:37 +0800 Subject: [PATCH] docs: convert to .rst and add readthedocs --- .travis.yml | 22 +- doc/.gitignore | 1 + doc/Makefile | 20 + doc/Troubleshooting/debugging.md | 102 --- doc/Troubleshooting/debugging.rst | 107 +++ doc/Troubleshooting/stack_dump.md | 66 -- doc/Troubleshooting/stack_dump.rst | 65 ++ doc/_static/.keep | 0 doc/boards.md | 319 --------- doc/boards.rst | 376 ++++++++++ doc/changes.md | 364 ---------- doc/changes.rst | 293 ++++++++ doc/conf.py | 169 +++++ doc/eclipse/eclipse.md | 38 -- doc/eclipse/eclipse.rst | 53 ++ doc/esp8266wifi/client-class.md | 65 -- doc/esp8266wifi/client-class.rst | 62 ++ doc/esp8266wifi/client-examples.md | 256 ------- doc/esp8266wifi/client-examples.rst | 260 +++++++ doc/esp8266wifi/client-secure-class.md | 81 --- doc/esp8266wifi/client-secure-class.rst | 78 +++ doc/esp8266wifi/client-secure-examples.md | 172 ----- doc/esp8266wifi/client-secure-examples.rst | 181 +++++ doc/esp8266wifi/generic-class.md | 85 --- doc/esp8266wifi/generic-class.rst | 82 +++ doc/esp8266wifi/generic-examples.md | 138 ---- doc/esp8266wifi/generic-examples.rst | 125 ++++ doc/esp8266wifi/readme.md | 318 --------- doc/esp8266wifi/readme.rst | 332 +++++++++ doc/esp8266wifi/scan-class.md | 267 -------- doc/esp8266wifi/scan-class.rst | 238 +++++++ doc/esp8266wifi/scan-examples.md | 261 ------- doc/esp8266wifi/scan-examples.rst | 243 +++++++ doc/esp8266wifi/server-class.md | 54 -- doc/esp8266wifi/server-class.rst | 49 ++ doc/esp8266wifi/server-examples.md | 253 ------- doc/esp8266wifi/server-examples.rst | 255 +++++++ doc/esp8266wifi/soft-access-point-class.md | 211 ------ doc/esp8266wifi/soft-access-point-class.rst | 227 +++++++ doc/esp8266wifi/soft-access-point-examples.md | 134 ---- .../soft-access-point-examples.rst | 125 ++++ doc/esp8266wifi/station-class.md | 600 ---------------- doc/esp8266wifi/station-class.rst | 642 ++++++++++++++++++ doc/esp8266wifi/station-examples.md | 205 ------ doc/esp8266wifi/station-examples.rst | 205 ++++++ doc/esp8266wifi/udp-class.md | 41 -- doc/esp8266wifi/udp-class.rst | 36 + doc/esp8266wifi/udp-examples.md | 198 ------ doc/esp8266wifi/udp-examples.rst | 194 ++++++ doc/exception_causes.md | 38 -- doc/exception_causes.rst | 124 ++++ doc/faq/a01-espcomm_sync-failed.md | 284 -------- doc/faq/a01-espcomm_sync-failed.rst | 394 +++++++++++ doc/faq/a02-my-esp-crashes.md | 169 ----- doc/faq/a02-my-esp-crashes.rst | 292 ++++++++ doc/faq/a03-library-does-not-work.md | 85 --- doc/faq/a03-library-does-not-work.rst | 112 +++ doc/faq/a04-board-generic-is-unknown.md | 99 --- doc/faq/a04-board-generic-is-unknown.rst | 151 ++++ doc/faq/readme.md | 50 -- doc/faq/readme.rst | 90 +++ doc/filesystem.md | 308 --------- doc/filesystem.rst | 365 ++++++++++ doc/index.rst | 22 + doc/installing.md | 80 --- doc/installing.rst | 101 +++ doc/libraries.md | 193 ------ doc/libraries.rst | 176 +++++ doc/ota_updates/readme.md | 483 ------------- doc/ota_updates/readme.rst | 541 +++++++++++++++ doc/reference.md | 130 ---- doc/reference.rst | 188 +++++ doc/requirements.txt | 5 + libraries/ESP8266AVRISP/README.md | 57 -- libraries/ESP8266AVRISP/README.rst | 70 ++ libraries/ESP8266SSDP/README.md | 22 - libraries/ESP8266SSDP/README.rst | 22 + libraries/ESP8266mDNS/README.md | 52 -- libraries/ESP8266mDNS/README.rst | 61 ++ libraries/GDBStub/README.md | 34 - libraries/GDBStub/README.rst | 49 ++ 81 files changed, 7191 insertions(+), 6324 deletions(-) create mode 100644 doc/.gitignore create mode 100644 doc/Makefile delete mode 100644 doc/Troubleshooting/debugging.md create mode 100644 doc/Troubleshooting/debugging.rst delete mode 100644 doc/Troubleshooting/stack_dump.md create mode 100644 doc/Troubleshooting/stack_dump.rst create mode 100644 doc/_static/.keep delete mode 100644 doc/boards.md create mode 100644 doc/boards.rst delete mode 100644 doc/changes.md create mode 100644 doc/changes.rst create mode 100644 doc/conf.py delete mode 100644 doc/eclipse/eclipse.md create mode 100644 doc/eclipse/eclipse.rst delete mode 100644 doc/esp8266wifi/client-class.md create mode 100644 doc/esp8266wifi/client-class.rst delete mode 100644 doc/esp8266wifi/client-examples.md create mode 100644 doc/esp8266wifi/client-examples.rst delete mode 100644 doc/esp8266wifi/client-secure-class.md create mode 100644 doc/esp8266wifi/client-secure-class.rst delete mode 100644 doc/esp8266wifi/client-secure-examples.md create mode 100644 doc/esp8266wifi/client-secure-examples.rst delete mode 100644 doc/esp8266wifi/generic-class.md create mode 100644 doc/esp8266wifi/generic-class.rst delete mode 100644 doc/esp8266wifi/generic-examples.md create mode 100644 doc/esp8266wifi/generic-examples.rst delete mode 100644 doc/esp8266wifi/readme.md create mode 100644 doc/esp8266wifi/readme.rst delete mode 100644 doc/esp8266wifi/scan-class.md create mode 100644 doc/esp8266wifi/scan-class.rst delete mode 100644 doc/esp8266wifi/scan-examples.md create mode 100644 doc/esp8266wifi/scan-examples.rst delete mode 100644 doc/esp8266wifi/server-class.md create mode 100644 doc/esp8266wifi/server-class.rst delete mode 100644 doc/esp8266wifi/server-examples.md create mode 100644 doc/esp8266wifi/server-examples.rst delete mode 100644 doc/esp8266wifi/soft-access-point-class.md create mode 100644 doc/esp8266wifi/soft-access-point-class.rst delete mode 100644 doc/esp8266wifi/soft-access-point-examples.md create mode 100644 doc/esp8266wifi/soft-access-point-examples.rst delete mode 100644 doc/esp8266wifi/station-class.md create mode 100644 doc/esp8266wifi/station-class.rst delete mode 100644 doc/esp8266wifi/station-examples.md create mode 100644 doc/esp8266wifi/station-examples.rst delete mode 100644 doc/esp8266wifi/udp-class.md create mode 100644 doc/esp8266wifi/udp-class.rst delete mode 100644 doc/esp8266wifi/udp-examples.md create mode 100644 doc/esp8266wifi/udp-examples.rst delete mode 100644 doc/exception_causes.md create mode 100644 doc/exception_causes.rst delete mode 100644 doc/faq/a01-espcomm_sync-failed.md create mode 100644 doc/faq/a01-espcomm_sync-failed.rst delete mode 100644 doc/faq/a02-my-esp-crashes.md create mode 100644 doc/faq/a02-my-esp-crashes.rst delete mode 100644 doc/faq/a03-library-does-not-work.md create mode 100644 doc/faq/a03-library-does-not-work.rst delete mode 100644 doc/faq/a04-board-generic-is-unknown.md create mode 100644 doc/faq/a04-board-generic-is-unknown.rst delete mode 100644 doc/faq/readme.md create mode 100644 doc/faq/readme.rst delete mode 100644 doc/filesystem.md create mode 100644 doc/filesystem.rst create mode 100644 doc/index.rst delete mode 100644 doc/installing.md create mode 100644 doc/installing.rst delete mode 100644 doc/libraries.md create mode 100644 doc/libraries.rst delete mode 100644 doc/ota_updates/readme.md create mode 100644 doc/ota_updates/readme.rst delete mode 100644 doc/reference.md create mode 100644 doc/reference.rst create mode 100644 doc/requirements.txt delete mode 100644 libraries/ESP8266AVRISP/README.md create mode 100644 libraries/ESP8266AVRISP/README.rst delete mode 100644 libraries/ESP8266SSDP/README.md create mode 100644 libraries/ESP8266SSDP/README.rst delete mode 100644 libraries/ESP8266mDNS/README.md create mode 100644 libraries/ESP8266mDNS/README.rst delete mode 100644 libraries/GDBStub/README.md create mode 100644 libraries/GDBStub/README.rst diff --git a/.travis.yml b/.travis.yml index 05fb744fe..911993d86 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,23 +3,25 @@ language: bash os: - linux -addons: - apt: - sources: - - ubuntu-toolchain-r-test - packages: - - g++-4.8 +dist: trusty + +install: + - pip install --user -r doc/requirements.txt script: - 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" - pushd $TRAVIS_BUILD_DIR/tests/host - make - make clean-objects + - popd - echo -e "travis_fold:end:host_tests" - 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 - tar xf arduino.tar.xz - mv arduino-nightly $HOME/arduino_ide @@ -42,10 +44,6 @@ script: - cat size.log - 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: email: on_success: change diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 000000000..e35d8850c --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +_build diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 000000000..36b492348 --- /dev/null +++ b/doc/Makefile @@ -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) \ No newline at end of file diff --git a/doc/Troubleshooting/debugging.md b/doc/Troubleshooting/debugging.md deleted file mode 100644 index 47a3cbebb..000000000 --- a/doc/Troubleshooting/debugging.md +++ /dev/null @@ -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); -} -``` - diff --git a/doc/Troubleshooting/debugging.rst b/doc/Troubleshooting/debugging.rst new file mode 100644 index 000000000..970cb0e7b --- /dev/null +++ b/doc/Troubleshooting/debugging.rst @@ -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 `__ + +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 + diff --git a/doc/Troubleshooting/stack_dump.md b/doc/Troubleshooting/stack_dump.md deleted file mode 100644 index 49c544940..000000000 --- a/doc/Troubleshooting/stack_dump.md +++ /dev/null @@ -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>>> + 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 + <<` +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 `__ tool. + +.. figure:: ESP_Exception_Decoderp.png + :alt: ESP Exception Decoder + + ESP Exception Decoder diff --git a/doc/_static/.keep b/doc/_static/.keep new file mode 100644 index 000000000..e69de29bb diff --git a/doc/boards.md b/doc/boards.md deleted file mode 100644 index 177a1111d..000000000 --- a/doc/boards.md +++ /dev/null @@ -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 ](#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 - - - diff --git a/doc/boards.rst b/doc/boards.rst new file mode 100644 index 000000000..ec085057b --- /dev/null +++ b/doc/boards.rst @@ -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 `__ + +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 `__ + +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 `__. + +`This guide `__ 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 `__. + +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 `__ entries, `github `__ and `community `__ 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 `__. + +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 `__) 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 diff --git a/doc/changes.md b/doc/changes.md deleted file mode 100644 index df07d5a95..000000000 --- a/doc/changes.md +++ /dev/null @@ -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. diff --git a/doc/changes.rst b/doc/changes.rst new file mode 100644 index 000000000..767f33a2a --- /dev/null +++ b/doc/changes.rst @@ -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. diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 000000000..2c0f130ca --- /dev/null +++ b/doc/conf.py @@ -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()] + + diff --git a/doc/eclipse/eclipse.md b/doc/eclipse/eclipse.md deleted file mode 100644 index 348d1cf19..000000000 --- a/doc/eclipse/eclipse.md +++ /dev/null @@ -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 - - \ No newline at end of file diff --git a/doc/eclipse/eclipse.rst b/doc/eclipse/eclipse.rst new file mode 100644 index 000000000..f8ee6e8d8 --- /dev/null +++ b/doc/eclipse/eclipse.rst @@ -0,0 +1,53 @@ +Using Eclipse with Arduino ESP8266 +================================== + +What to Download +~~~~~~~~~~~~~~~~ + +- `arduino IDE `__ +- `Eclipse IDE for C/C++ + Developers `__ +- `Java `__ + +Setup Arduino +~~~~~~~~~~~~~ + +See the +`Readme `__ + +Setup Eclipse +~~~~~~~~~~~~~ + +- `step 1 `__ +- `step 2 `__ +- 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 diff --git a/doc/esp8266wifi/client-class.md b/doc/esp8266wifi/client-class.md deleted file mode 100644 index 48c685a40..000000000 --- a/doc/esp8266wifi/client-class.md +++ /dev/null @@ -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. diff --git a/doc/esp8266wifi/client-class.rst b/doc/esp8266wifi/client-class.rst new file mode 100644 index 000000000..4b98034ce --- /dev/null +++ b/doc/esp8266wifi/client-class.rst @@ -0,0 +1,62 @@ +:orphan: + +Client Class +------------ + +Methods documented for `Client `__ in `Arduino `__ + +1. `WiFiClient() `__ +2. `connected() `__ +3. `connect() `__ +4. `write() `__ +5. `print() `__ +6. `println() `__ +7. `available() `__ +8. `read() `__ +9. `flush() `__ +10. `stop() `__ + +Methods and properties described further down are specific to ESP8266. They are not covered in `Arduino WiFi library `__ 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 `__. + +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: `__ dedicated specifically to the Client Class. diff --git a/doc/esp8266wifi/client-examples.md b/doc/esp8266wifi/client-examples.md deleted file mode 100644 index a38ff37af..000000000 --- a/doc/esp8266wifi/client-examples.md +++ /dev/null @@ -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 - -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. - -``` - - - - Example Domain - - - - -