diff --git a/.travis.yml b/.travis.yml index 05fb744fe3..bf280321fd 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,50 +1,29 @@ sudo: false language: bash -os: - - linux +os: linux +dist: trusty -addons: - apt: - sources: - - ubuntu-toolchain-r-test - packages: - - g++-4.8 +env: + - BUILD_TYPE=build + +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:host_tests" - - pushd $TRAVIS_BUILD_DIR/tests/host - - make - - make clean-objects - - 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 - - cd $HOME/arduino_ide/hardware - - mkdir esp8266com - - cd esp8266com - - ln -s $TRAVIS_BUILD_DIR esp8266 - - cd esp8266/tools - - python get.py - - export PATH="$HOME/arduino_ide:$TRAVIS_BUILD_DIR/tools/xtensa-lx106-elf/bin:$PATH" - - which arduino - - cd $TRAVIS_BUILD_DIR - - source tests/common.sh - - install_libraries - - echo -e "travis_fold:end:sketch_test_env_prepare" - - echo -e "travis_fold:start:sketch_test" - - build_sketches $HOME/arduino_ide $TRAVIS_BUILD_DIR/libraries "-l $HOME/Arduino/libraries" - - echo -e "travis_fold:end:sketch_test" - - echo -e "travis_fold:start:size_report" - - cat size.log - - echo -e "travis_fold:end:size_report" + - $TRAVIS_BUILD_DIR/tests/common.sh -after_success: - - pushd $TRAVIS_BUILD_DIR/tests/host - - bash <(curl -s https://codecov.io/bash) -X gcov +deploy: + provider: releases + prerelease: true + api_key: + secure: A4FBmqyhlzy33oPeZVolg2Q/A3ZcJ3WnRQqQJ3NAPy+qGM5xcboOYtwcLL9vKaHZGfUB7lUP9QVZFGou1Wrmo9DnPvAoe3+XvCaDRGzVMxeIpu7UStbBD4Knbh98tlbMvZCXYRlT4VcusI9bMLK6UWw4sMdPislBh2FEfglTiag= + file_glob: true + file: + - package/versions/$TRAVIS_TAG/esp8266-$TRAVIS_TAG.zip + - package/versions/$TRAVIS_TAG/package_esp8266com_index.json + on: + repo: esp8266/Arduino + tags: true notifications: email: diff --git a/README.md b/README.md index 6348e073a2..48f53fb2ad 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,6 @@ This project brings support for ESP8266 chip to the Arduino environment. It lets ESP8266 Arduino core comes with libraries to communicate over WiFi using TCP and UDP, set up HTTP, mDNS, SSDP, and DNS servers, do OTA updates, use a file system in flash memory, work with SD cards, servos, SPI and I2C peripherals. -A large community is well established for questions and answers about Arduino for ESP8266 [ESP8266 Community Forum](http://www.esp8266.com/u/arduinoanswers) - # Contents - Installing options: - [Using Boards Manager](#installing-with-boards-manager) @@ -18,35 +16,24 @@ A large community is well established for questions and answers about Arduino fo - [Contributing](#contributing) - [License and credits](#license-and-credits) -### Installing with Boards Manager ### +### Installing with Boards Manager Starting with 1.6.4, Arduino allows installation of third-party platform packages using Boards Manager. We have packages available for Windows, Mac OS, and Linux (32 and 64 bit). -- Install Arduino 1.6.8 from the [Arduino website](http://www.arduino.cc/en/main/software). +- Install Arduino 1.8.2 from the [Arduino website](http://www.arduino.cc/en/main/software). - 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 install *esp8266* platform (and don't forget to select your ESP8266 board from Tools > Board menu after installation). -The best place to ask questions related to this core is ESP8266 community forum: http://www.esp8266.com/arduino. -If you find this forum or the ESP8266 Boards Manager package useful, please consider supporting it with a donation.
-[![Donate](https://img.shields.io/badge/paypal-donate-yellow.svg)](https://www.paypal.com/webscr?cmd=_s-xclick&hosted_button_id=4M56YCWV6PX66) - -#### Available versions - -##### Stable version ![](http://arduino.esp8266.com/stable/badge.svg) +#### Latest release [![Latest release](https://img.shields.io/github/release/esp8266/Arduino.svg)](https://github.com/esp8266/Arduino/releases/latest/) Boards manager link: `http://arduino.esp8266.com/stable/package_esp8266com_index.json` Documentation: [http://esp8266.github.io/Arduino/versions/2.3.0/](http://esp8266.github.io/Arduino/versions/2.3.0/) -##### Staging version ![](http://arduino.esp8266.com/staging/badge.svg) -Boards manager link: `http://arduino.esp8266.com/staging/package_esp8266com_index.json` - -Documentation: [http://esp8266.github.io/Arduino/versions/2.3.0-rc2/](http://esp8266.github.io/Arduino/versions/2.3.0-rc2/) - ### Using git version -[![Linux build status](https://travis-ci.org/esp8266/Arduino.svg)](https://travis-ci.org/esp8266/Arduino) [![codecov.io](https://codecov.io/github/esp8266/Arduino/coverage.svg?branch=master)](https://codecov.io/github/esp8266/Arduino?branch=master) +[![Linux build status](https://travis-ci.org/esp8266/Arduino.svg)](https://travis-ci.org/esp8266/Arduino) -- Install Arduino 1.6.8 +- Install Arduino 1.8.2 from the [Arduino website](http://www.arduino.cc/en/main/software). - Go to Arduino directory - Clone this repository into hardware/esp8266com/esp8266 directory (or clone it elsewhere and create a symlink) ```bash @@ -72,7 +59,7 @@ Linux 32/64, Linux ARM (like Raspberry Pi, BeagleBone, CubieBoard). - [What is PlatformIO?](http://docs.platformio.org/page/what-is-platformio.html) - [PlatformIO IDE](http://platformio.org/platformio-ide) - Quick Start with [PlatformIO IDE](http://docs.platformio.org/page/ide/atom.html#quick-start) or [PlatformIO Core](http://docs.platformio.org/page/core.html) -- [Advanced using](http://docs.platformio.org/page/platforms/espressif.html) - +- [Advanced usage](http://docs.platformio.org/page/platforms/espressif.html) - custom settings, uploading to SPIFFS, Over-the-Air (OTA) or using stage version - [Integration with Cloud and Standalone IDEs](http://docs.platformio.org/page/ide.html) - Cloud9, Codeanywhere, Eclipse Che (Codenvy), Atom, CLion, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, VIM and Visual Studio @@ -85,30 +72,33 @@ Using make instead of the Arduino IDE makes it easier to do automated and produc ### Documentation -Documentation for latest development version: - -- [Reference](doc/reference.md) -- [Libraries](doc/libraries.md) -- [File system](doc/filesystem.md) -- [OTA update](doc/ota_updates/readme.md) -- [Supported boards](doc/boards.md) -- [FAQ / Trubleshooting](doc/faq/readme.md) -- [Change log](doc/changes.md) +Documentation for latest development version: https://arduino-esp8266.readthedocs.io/en/latest/ ### Issues and support ### -If you encounter an issue, you are welcome to submit it here on Github: https://github.com/esp8266/Arduino/issues. -Please provide as much context as possible: version which you are using (you can check it in Boards Manager), your sketch code, serial output, board model, IDE settings (board selection, flash size, etc). +[ESP8266 Community Forum](http://www.esp8266.com/u/arduinoanswers) is a well established community for questions and answers about Arduino for ESP8266. + +If you find this forum useful, please consider supporting it with a donation.
+[![Donate](https://img.shields.io/badge/paypal-donate-yellow.svg)](https://www.paypal.com/webscr?cmd=_s-xclick&hosted_button_id=4M56YCWV6PX66) + +If you encounter an issue which you think is a bug in the ESP8266 Arduino Core or the associated libraries, you are welcome to submit it here on Github: https://github.com/esp8266/Arduino/issues. + +Please provide as much context as possible: -If you can not find the answers above, you can also try [ESP8266 Community Forum](http://www.esp8266.com/arduino) +- ESP8266 Arduino core version which you are using (you can check it in Boards Manager) +- your sketch code; please wrap it into a code block, see [Github markdown manual](https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code) +- when encountering an issue which happens at run time, attach serial output. Wrap it into a code block, just like the code. +- for issues which happen at compile time, enable verbose compiler output in the IDE preferences, and attach that output (also inside a code block) +- ESP8266 development board model +- IDE settings (board choich, flash size) ### Contributing -For minor fixes of code and documentation, go ahead and submit a pull request. +For minor fixes of code and documentation, please go ahead and submit a pull request. -Check out the list of issues which are easy to fix — [easy issues for 2.2.0](https://github.com/esp8266/Arduino/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.2.0+label%3A%22level%3A+easy%22). Working on them is a great way to move the project forward. +Check out the list of issues which are easy to fix — [easy issues for 2.4.0](https://github.com/esp8266/Arduino/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.4.0+label%3A%22level%3A+easy%22). Working on them is a great way to move the project forward. -Larger changes (rewriting parts of existing code from scratch, adding new functions to the core, adding new libraries) should generally be discussed [in the chat](https://gitter.im/esp8266/Arduino) first. +Larger changes (rewriting parts of existing code from scratch, adding new functions to the core, adding new libraries) should generally be discussed by opening an issue first. Feature branches with lots of small commits (especially titled "oops", "fix typo", "forgot to add file", etc.) should be squashed before opening a pull request. At the same time, please refrain from putting multiple unrelated changes into a single pull request. diff --git a/boards.txt b/boards.txt index 818b26ce25..890a8bc0fb 100644 --- a/boards.txt +++ b/boards.txt @@ -1,5 +1,7 @@ +menu.BoardModel=Model menu.UploadSpeed=Upload Speed menu.CpuFrequency=CPU Frequency +menu.CrystalFreq=Crystal Frequency menu.FlashSize=Flash Size menu.FlashMode=Flash Mode menu.FlashFreq=Flash Frequency @@ -36,6 +38,10 @@ generic.menu.CpuFrequency.80.build.f_cpu=80000000L generic.menu.CpuFrequency.160=160 MHz generic.menu.CpuFrequency.160.build.f_cpu=160000000L +generic.menu.CrystalFreq.26=26 MHz +generic.menu.CrystalFreq.40=40 MHz +generic.menu.CrystalFreq.40.build.extra_flags=-DF_CRYSTAL=40000000 + generic.menu.FlashFreq.40=40MHz generic.menu.FlashFreq.40.build.flash_freq=40 generic.menu.FlashFreq.80=80MHz @@ -146,6 +152,11 @@ generic.menu.FlashSize.1M64.build.spiffs_end=0xFB000 generic.menu.FlashSize.1M64.build.spiffs_blocksize=4096 generic.menu.FlashSize.1M64.upload.maximum_size=958448 +generic.menu.FlashSize.1M0=1M (no SPIFFS) +generic.menu.FlashSize.1M0.build.flash_size=1M +generic.menu.FlashSize.1M0.build.flash_ld=eagle.flash.1m0.ld +generic.menu.FlashSize.1M0.upload.maximum_size=1023984 + generic.menu.FlashSize.2M=2M (1M SPIFFS) generic.menu.FlashSize.2M.build.flash_size=2M generic.menu.FlashSize.2M.build.flash_ld=eagle.flash.2m.ld @@ -1892,3 +1903,121 @@ coredev.menu.DebugLevel.OTA2____=OTA + Updater coredev.menu.DebugLevel.OTA2____.build.debug_level=-DDEBUG_ESP_OTA -DDEBUG_ESP_UPDATER coredev.menu.DebugLevel.all_____=All coredev.menu.DebugLevel.all_____.build.debug_level=-DDEBUG_ESP_CORE -DDEBUG_ESP_SSL -DDEBUG_ESP_WIFI -DDEBUG_ESP_HTTP_CLIENT -DDEBUG_ESP_HTTP_UPDATE -DDEBUG_ESP_HTTP_SERVER -DDEBUG_ESP_UPDATER -DDEBUG_ESP_OTA -DDEBUG_TLS_MEM + +############ Arduino boards with Esp8266 ############ + +arduino-esp8266.name=Arduino + +arduino-esp8266.upload.tool=esptool +arduino-esp8266.upload.speed=9600 +arduino-esp8266.upload.resetmethod=ck +arduino-esp8266.upload.maximum_size=1044464 +arduino-esp8266.upload.maximum_data_size=81920 +arduino-esp8266.upload.wait_for_upload_port=true +arduino-esp8266.serial.disableDTR=true +arduino-esp8266.serial.disableRTS=true + +arduino-esp8266.build.mcu=esp8266 +arduino-esp8266.build.f_cpu=80000000L +#arduino-esp8266.build.f_crystal=40000000 +arduino-esp8266.build.core=esp8266 +arduino-esp8266.build.flash_mode=qio +arduino-esp8266.build.flash_size=4M +arduino-esp8266.build.flash_freq=40 +arduino-esp8266.build.debug_port= +arduino-esp8266.build.debug_level= +arduino-esp8266.build.board=ESP8266_ARDUINO + +arduino-esp8266.menu.BoardModel.starottodeved=Star OTTO +arduino-esp8266.menu.BoardModel.starottodeved.build.board=ESP8266_ARDUINO_STAR_OTTO +arduino-esp8266.menu.BoardModel.starottodeved.build.variant=arduino_uart +arduino-esp8266.menu.BoardModel.starottodeved.build.extra_flags=-DF_CRYSTAL=40000000 + +arduino-esp8266.menu.BoardModel.primo=Primo +arduino-esp8266.menu.BoardModel.primo.build.board=ESP8266_ARDUINO_PRIMO +arduino-esp8266.menu.BoardModel.primo.build.variant=arduino_spi +arduino-esp8266.menu.BoardModel.primo.build.extra_flags=-DF_CRYSTAL=40000000 + +arduino-esp8266.menu.BoardModel.unowifideved=Uno WiFi +arduino-esp8266.menu.BoardModel.unowifideved.build.board=ESP8266_ARDUINO_UNOWIFI +arduino-esp8266.menu.BoardModel.unowifideved.build.variant=arduino_uart +arduino-esp8266.menu.BoardModel.unowifideved.build.extra_flags=-DF_CRYSTAL=40000000 + +arduino-esp8266.menu.UploadSpeed.9600=9600 +arduino-esp8266.menu.UploadSpeed.9600.upload.speed=9600 +arduino-esp8266.menu.UploadSpeed.19200=19200 +arduino-esp8266.menu.UploadSpeed.19200.upload.speed=19200 +arduino-esp8266.menu.UploadSpeed.57600=57600 +arduino-esp8266.menu.UploadSpeed.57600.upload.speed=57600 +arduino-esp8266.menu.UploadSpeed.115200=115200 +arduino-esp8266.menu.UploadSpeed.115200.upload.speed=115200 +arduino-esp8266.menu.UploadSpeed.230400=230400 +arduino-esp8266.menu.UploadSpeed.230400.upload.speed=230400 +arduino-esp8266.menu.UploadSpeed.460800=460800 +arduino-esp8266.menu.UploadSpeed.460800.upload.speed=460800 + +arduino-esp8266.menu.FlashSize.4M1M=4M (1M SPIFFS) +arduino-esp8266.menu.FlashSize.4M1M.build.flash_size=4M +arduino-esp8266.menu.FlashSize.4M1M.build.flash_ld=eagle.flash.4m1m.ld +arduino-esp8266.menu.FlashSize.4M1M.build.spiffs_start=0x300000 +arduino-esp8266.menu.FlashSize.4M1M.build.spiffs_end=0x3FB000 +arduino-esp8266.menu.FlashSize.4M1M.build.spiffs_blocksize=8192 +arduino-esp8266.menu.FlashSize.4M1M.build.spiffs_pagesize=256 + +arduino-esp8266.menu.FlashSize.4M3M=4M (3M SPIFFS) +arduino-esp8266.menu.FlashSize.4M3M.build.flash_size=4M +arduino-esp8266.menu.FlashSize.4M3M.build.flash_ld=eagle.flash.4m.ld +arduino-esp8266.menu.FlashSize.4M3M.build.spiffs_start=0x100000 +arduino-esp8266.menu.FlashSize.4M3M.build.spiffs_end=0x3FB000 +arduino-esp8266.menu.FlashSize.4M3M.build.spiffs_blocksize=8192 +arduino-esp8266.menu.FlashSize.4M3M.build.spiffs_pagesize=256 + +############################################################## + +gen4iod.name=4D Systems gen4 IoD Range + +gen4iod.upload.tool=esptool +gen4iod.upload.speed=921600 +gen4iod.upload.resetmethod=nodemcu +gen4iod.upload.maximum_size=434160 +gen4iod.upload.maximum_data_size=81920 +gen4iod.upload.wait_for_upload_port=true +gen4iod.serial.disableDTR=true +gen4iod.serial.disableRTS=true + +gen4iod.build.mcu=esp8266 +gen4iod.build.f_cpu=160000000L +gen4iod.build.board=GEN4_IOD +gen4iod.build.core=esp8266 +gen4iod.build.variant=generic +gen4iod.build.flash_mode=qio +# flash chip: AT25SF041 (512 kbyte, 4Mbit) +gen4iod.build.flash_size=512K +gen4iod.build.flash_ld=eagle.flash.512k0.ld +gen4iod.build.flash_freq=80 +gen4iod.build.debug_port= +gen4iod.build.debug_level= + +gen4iod.menu.CpuFrequency.160=160 MHz +gen4iod.menu.CpuFrequency.160.build.f_cpu=160000000L +gen4iod.menu.CpuFrequency.80=80 MHz +gen4iod.menu.CpuFrequency.80.build.f_cpu=80000000L + +gen4iod.menu.UploadSpeed.115200=115200 +gen4iod.menu.UploadSpeed.115200.upload.speed=115200 +gen4iod.menu.UploadSpeed.9600=9600 +gen4iod.menu.UploadSpeed.9600.upload.speed=9600 +gen4iod.menu.UploadSpeed.57600=57600 +gen4iod.menu.UploadSpeed.57600.upload.speed=57600 +gen4iod.menu.UploadSpeed.256000.windows=256000 +gen4iod.menu.UploadSpeed.256000.upload.speed=256000 +gen4iod.menu.UploadSpeed.230400.linux=230400 +gen4iod.menu.UploadSpeed.230400.macosx=230400 +gen4iod.menu.UploadSpeed.230400.upload.speed=230400 +gen4iod.menu.UploadSpeed.460800.linux=460800 +gen4iod.menu.UploadSpeed.460800.macosx=460800 +gen4iod.menu.UploadSpeed.460800.upload.speed=460800 +gen4iod.menu.UploadSpeed.512000.windows=512000 +gen4iod.menu.UploadSpeed.512000.upload.speed=512000 +gen4iod.menu.UploadSpeed.921600=921600 +gen4iod.menu.UploadSpeed.921600.upload.speed=921600 diff --git a/cores/esp8266/MD5Builder.cpp b/cores/esp8266/MD5Builder.cpp index ac4fa29ee2..b32693ed73 100644 --- a/cores/esp8266/MD5Builder.cpp +++ b/cores/esp8266/MD5Builder.cpp @@ -1,26 +1,22 @@ #include #include -uint8_t hex_char_to_byte(uint8_t c) -{ +uint8_t hex_char_to_byte(uint8_t c){ return (c >= 'a' && c <= 'f') ? (c - ((uint8_t)'a' - 0xa)) : (c >= 'A' && c <= 'F') ? (c - ((uint8_t)'A' - 0xA)) : (c >= '0' && c<= '9') ? (c - (uint8_t)'0') : 0; } -void MD5Builder::begin(void) -{ +void MD5Builder::begin(void){ memset(_buf, 0x00, 16); MD5Init(&_ctx); } -void MD5Builder::add(uint8_t * data, uint16_t len) -{ +void MD5Builder::add(const uint8_t * data, const uint16_t len){ MD5Update(&_ctx, data, len); } -void MD5Builder::addHexString(const char * data) -{ +void MD5Builder::addHexString(const char * data){ uint16_t i, len = strlen(data); uint8_t * tmp = (uint8_t*)malloc(len/2); if(tmp == NULL) { @@ -35,8 +31,7 @@ void MD5Builder::addHexString(const char * data) free(tmp); } -bool MD5Builder::addStream(Stream & stream, const size_t maxLen) -{ +bool MD5Builder::addStream(Stream & stream, const size_t maxLen){ const int buf_size = 512; int maxLengthLeft = maxLen; uint8_t * buf = (uint8_t*) malloc(buf_size); @@ -76,25 +71,21 @@ bool MD5Builder::addStream(Stream & stream, const size_t maxLen) return true; } -void MD5Builder::calculate(void) -{ +void MD5Builder::calculate(void){ MD5Final(_buf, &_ctx); } -void MD5Builder::getBytes(uint8_t * output) -{ +void MD5Builder::getBytes(uint8_t * output){ memcpy(output, _buf, 16); } -void MD5Builder::getChars(char * output) -{ +void MD5Builder::getChars(char * output){ for(uint8_t i = 0; i < 16; i++) { sprintf(output + (i * 2), "%02x", _buf[i]); } } -String MD5Builder::toString(void) -{ +String MD5Builder::toString(void){ char out[33]; getChars(out); return String(out); diff --git a/cores/esp8266/MD5Builder.h b/cores/esp8266/MD5Builder.h index d4e336fca9..0a2f22b43b 100644 --- a/cores/esp8266/MD5Builder.h +++ b/cores/esp8266/MD5Builder.h @@ -1,9 +1,9 @@ -/* +/* md5.h - exposed md5 ROM functions for esp8266 Copyright (c) 2015 Hristo Gochkov. All rights reserved. This file is part of the esp8266 core for Arduino environment. - + This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either @@ -31,13 +31,13 @@ class MD5Builder { uint8_t _buf[16]; public: void begin(void); - void add(uint8_t * data, uint16_t len); - void add(const char * data){ add((uint8_t*)data, strlen(data)); } + void add(const uint8_t * data, const uint16_t len); + void add(const char * data){ add((const uint8_t*)data, strlen(data)); } void add(char * data){ add((const char*)data); } - void add(String data){ add(data.c_str()); } + void add(const String data){ add(data.c_str()); } void addHexString(const char * data); void addHexString(char * data){ addHexString((const char*)data); } - void addHexString(String data){ addHexString(data.c_str()); } + void addHexString(const String data){ addHexString(data.c_str()); } bool addStream(Stream & stream, const size_t maxLen); void calculate(void); void getBytes(uint8_t * output); diff --git a/cores/esp8266/Updater.cpp b/cores/esp8266/Updater.cpp index 258d899c3a..90b9c13acf 100644 --- a/cores/esp8266/Updater.cpp +++ b/cores/esp8266/Updater.cpp @@ -2,6 +2,7 @@ #include "Arduino.h" #include "eboot_command.h" #include "interrupts.h" +#include "esp8266_peri.h" //#define DEBUG_UPDATER Serial @@ -39,14 +40,28 @@ void UpdaterClass::_reset() { bool UpdaterClass::begin(size_t size, int command) { if(_size > 0){ #ifdef DEBUG_UPDATER - DEBUG_UPDATER.println("[begin] already running"); + DEBUG_UPDATER.println(F("[begin] already running")); #endif return false; } + /* Check boot mode; if boot mode is 1 (UART download mode), + we will not be able to reset into normal mode once update is done. + Fail early to avoid frustration. + https://github.com/esp8266/Arduino/issues/1017#issuecomment-200605576 + */ + int boot_mode = (GPI >> 16) & 0xf; + if (boot_mode == 1) { + _error = UPDATE_ERROR_BOOTSTRAP; +#ifdef DEBUG_UPDATER + printError(DEBUG_UPDATER); +#endif + return false; + } + #ifdef DEBUG_UPDATER if (command == U_SPIFFS) { - DEBUG_UPDATER.println("[begin] Update SPIFFS."); + DEBUG_UPDATER.println(F("[begin] Update SPIFFS.")); } #endif @@ -103,7 +118,7 @@ bool UpdaterClass::begin(size_t size, int command) { else { // unknown command #ifdef DEBUG_UPDATER - DEBUG_UPDATER.println("[begin] Unknown update command."); + DEBUG_UPDATER.println(F("[begin] Unknown update command.")); #endif return false; } @@ -112,7 +127,12 @@ bool UpdaterClass::begin(size_t size, int command) { _startAddress = updateStartAddress; _currentAddress = _startAddress; _size = size; - _buffer = new uint8_t[FLASH_SECTOR_SIZE]; + if (ESP.getFreeHeap() > 2 * FLASH_SECTOR_SIZE) { + _bufferSize = FLASH_SECTOR_SIZE; + } else { + _bufferSize = 256; + } + _buffer = new uint8_t[_bufferSize]; _command = command; #ifdef DEBUG_UPDATER @@ -137,7 +157,7 @@ bool UpdaterClass::setMD5(const char * expected_md5){ bool UpdaterClass::end(bool evenIfRemaining){ if(_size == 0){ #ifdef DEBUG_UPDATER - DEBUG_UPDATER.println("no update"); + DEBUG_UPDATER.println(F("no update")); #endif return false; } @@ -203,13 +223,16 @@ bool UpdaterClass::end(bool evenIfRemaining){ bool UpdaterClass::_writeBuffer(){ - if(!_async) yield(); - bool result = ESP.flashEraseSector(_currentAddress/FLASH_SECTOR_SIZE); - if(!_async) yield(); + bool result = true; + if (_currentAddress % FLASH_SECTOR_SIZE == 0) { + if(!_async) yield(); + result = ESP.flashEraseSector(_currentAddress/FLASH_SECTOR_SIZE); + } + if (result) { - result = ESP.flashWrite(_currentAddress, (uint32_t*) _buffer, _bufferLen); + if(!_async) yield(); + result = ESP.flashWrite(_currentAddress, (uint32_t*) _buffer, _bufferLen); } - if(!_async) yield(); if (!result) { _error = UPDATE_ERROR_WRITE; @@ -238,8 +261,8 @@ size_t UpdaterClass::write(uint8_t *data, size_t len) { size_t left = len; - while((_bufferLen + left) > FLASH_SECTOR_SIZE) { - size_t toBuff = FLASH_SECTOR_SIZE - _bufferLen; + while((_bufferLen + left) > _bufferSize) { + size_t toBuff = _bufferSize - _bufferLen; memcpy(_buffer + _bufferLen, data + (len - left), toBuff); _bufferLen += toBuff; if(!_writeBuffer()){ @@ -325,10 +348,10 @@ size_t UpdaterClass::writeStream(Stream &data) { } while(remaining()) { - toRead = data.readBytes(_buffer + _bufferLen, (FLASH_SECTOR_SIZE - _bufferLen)); + toRead = data.readBytes(_buffer + _bufferLen, (_bufferSize - _bufferLen)); if(toRead == 0) { //Timeout delay(100); - toRead = data.readBytes(_buffer + _bufferLen, (FLASH_SECTOR_SIZE - _bufferLen)); + toRead = data.readBytes(_buffer + _bufferLen, (_bufferSize - _bufferLen)); if(toRead == 0) { //Timeout _error = UPDATE_ERROR_STREAM; _currentAddress = (_startAddress + _size); @@ -340,7 +363,7 @@ size_t UpdaterClass::writeStream(Stream &data) { } } _bufferLen += toRead; - if((_bufferLen == remaining() || _bufferLen == FLASH_SECTOR_SIZE) && !_writeBuffer()) + if((_bufferLen == remaining() || _bufferLen == _bufferSize) && !_writeBuffer()) return written; written += toRead; yield(); @@ -349,31 +372,33 @@ size_t UpdaterClass::writeStream(Stream &data) { } void UpdaterClass::printError(Stream &out){ - out.printf("ERROR[%u]: ", _error); + out.printf_P(PSTR("ERROR[%u]: "), _error); if(_error == UPDATE_ERROR_OK){ - out.println("No Error"); + out.println(F("No Error")); } else if(_error == UPDATE_ERROR_WRITE){ - out.println("Flash Write Failed"); + out.println(F("Flash Write Failed")); } else if(_error == UPDATE_ERROR_ERASE){ - out.println("Flash Erase Failed"); + out.println(F("Flash Erase Failed")); } else if(_error == UPDATE_ERROR_READ){ - out.println("Flash Read Failed"); + out.println(F("Flash Read Failed")); } else if(_error == UPDATE_ERROR_SPACE){ - out.println("Not Enough Space"); + out.println(F("Not Enough Space")); } else if(_error == UPDATE_ERROR_SIZE){ - out.println("Bad Size Given"); + out.println(F("Bad Size Given")); } else if(_error == UPDATE_ERROR_STREAM){ - out.println("Stream Read Timeout"); + out.println(F("Stream Read Timeout")); } else if(_error == UPDATE_ERROR_MD5){ - out.println("MD5 Check Failed"); + out.println(F("MD5 Check Failed")); } else if(_error == UPDATE_ERROR_FLASH_CONFIG){ - out.printf("Flash config wrong real: %d IDE: %d\n", ESP.getFlashChipRealSize(), ESP.getFlashChipSize()); + out.printf_P(PSTR("Flash config wrong real: %d IDE: %d\n"), ESP.getFlashChipRealSize(), ESP.getFlashChipSize()); } else if(_error == UPDATE_ERROR_NEW_FLASH_CONFIG){ - out.printf("new Flash config wrong real: %d\n", ESP.getFlashChipRealSize()); + out.printf_P(PSTR("new Flash config wrong real: %d\n"), ESP.getFlashChipRealSize()); } else if(_error == UPDATE_ERROR_MAGIC_BYTE){ - out.println("Magic byte is wrong, not 0xE9"); + out.println(F("Magic byte is wrong, not 0xE9")); + } else if (_error == UPDATE_ERROR_BOOTSTRAP){ + out.println(F("Invalid bootstrapping state, reset ESP8266 before updating")); } else { - out.println("UNKNOWN"); + out.println(F("UNKNOWN")); } } diff --git a/cores/esp8266/Updater.h b/cores/esp8266/Updater.h index 046ff1667b..0f98cafd42 100644 --- a/cores/esp8266/Updater.h +++ b/cores/esp8266/Updater.h @@ -16,7 +16,7 @@ #define UPDATE_ERROR_FLASH_CONFIG (8) #define UPDATE_ERROR_NEW_FLASH_CONFIG (9) #define UPDATE_ERROR_MAGIC_BYTE (10) - +#define UPDATE_ERROR_BOOTSTRAP (11) #define U_FLASH 0 #define U_SPIFFS 100 @@ -116,8 +116,8 @@ class UpdaterClass { if(_bufferLen + available > remaining()){ available = remaining() - _bufferLen; } - if(_bufferLen + available > FLASH_SECTOR_SIZE) { - size_t toBuff = FLASH_SECTOR_SIZE - _bufferLen; + if(_bufferLen + available > _bufferSize) { + size_t toBuff = _bufferSize - _bufferLen; data.read(_buffer + _bufferLen, toBuff); _bufferLen += toBuff; if(!_writeBuffer()) @@ -151,7 +151,8 @@ class UpdaterClass { bool _async; uint8_t _error; uint8_t *_buffer; - size_t _bufferLen; + size_t _bufferLen; // amount of data written into _buffer + size_t _bufferSize; // total size of _buffer size_t _size; uint32_t _startAddress; uint32_t _currentAddress; diff --git a/cores/esp8266/base64.cpp b/cores/esp8266/base64.cpp old mode 100644 new mode 100755 index 11deb0af04..a1e6261890 --- a/cores/esp8266/base64.cpp +++ b/cores/esp8266/base64.cpp @@ -35,13 +35,20 @@ extern "C" { * @param length size_t * @return String */ -String base64::encode(uint8_t * data, size_t length) { +String base64::encode(uint8_t * data, size_t length, bool doNewLines) { // base64 needs more size then the source data size_t size = ((length * 1.6f) + 1); char * buffer = (char *) malloc(size); if(buffer) { base64_encodestate _state; - base64_init_encodestate(&_state); + if(doNewLines) + { + base64_init_encodestate(&_state); + } + else + { + base64_init_encodestate_nonewlines(&_state); + } int len = base64_encode_block((const char *) &data[0], length, &buffer[0], &_state); len = base64_encode_blockend((buffer + len), &_state); @@ -57,7 +64,7 @@ String base64::encode(uint8_t * data, size_t length) { * @param text String * @return String */ -String base64::encode(String text) { - return base64::encode((uint8_t *) text.c_str(), text.length()); +String base64::encode(String text, bool doNewLines) { + return base64::encode((uint8_t *) text.c_str(), text.length(), doNewLines); } diff --git a/cores/esp8266/base64.h b/cores/esp8266/base64.h old mode 100644 new mode 100755 index 39be2d397c..67140123ed --- a/cores/esp8266/base64.h +++ b/cores/esp8266/base64.h @@ -27,8 +27,11 @@ class base64 { public: - static String encode(uint8_t * data, size_t length); - static String encode(String text); + // NOTE: The default behaviour of backend (lib64) + // is to add a newline every 72 (encoded) characters output. + // This may 'break' longer uris and json variables + static String encode(uint8_t * data, size_t length, bool doNewLines = true); + static String encode(String text, bool doNewLines = true); private: }; diff --git a/cores/esp8266/core_esp8266_i2s.c b/cores/esp8266/core_esp8266_i2s.c index 3a7ca505ed..a154ac85d5 100644 --- a/cores/esp8266/core_esp8266_i2s.c +++ b/cores/esp8266/core_esp8266_i2s.c @@ -146,6 +146,10 @@ void ICACHE_FLASH_ATTR i2s_slc_end(){ SLCIE = 0; SLCTXL &= ~(SLCTXLAM << SLCTXLA); // clear TX descriptor address SLCRXL &= ~(SLCRXLAM << SLCRXLA); // clear RX descriptor address + + for (int x = 0; xstep = step_A; state_in->result = 0; state_in->stepcount = 0; + state_in->stepsnewline = CHARS_PER_LINE; +} + + +void base64_init_encodestate_nonewlines(base64_encodestate* state_in){ + base64_init_encodestate(state_in); + state_in->stepsnewline = -1; } char base64_encode_value(char value_in){ @@ -65,7 +72,7 @@ int base64_encode_block(const char* plaintext_in, int length_in, char* code_out, *codechar++ = base64_encode_value(result); ++(state_in->stepcount); - if (state_in->stepcount == CHARS_PER_LINE/4){ + if ((state_in->stepcount == CHARS_PER_LINE/4) && (state_in->stepsnewline > 0)){ *codechar++ = '\n'; state_in->stepcount = 0; } diff --git a/cores/esp8266/libb64/cencode.h b/cores/esp8266/libb64/cencode.h index 058cc5d1a6..7890e7a4a6 100755 --- a/cores/esp8266/libb64/cencode.h +++ b/cores/esp8266/libb64/cencode.h @@ -22,9 +22,11 @@ typedef struct { base64_encodestep step; char result; int stepcount; + int stepsnewline; } base64_encodestate; void base64_init_encodestate(base64_encodestate* state_in); +void base64_init_encodestate_nonewlines(base64_encodestate* state_in); char base64_encode_value(char value_in); diff --git a/cores/esp8266/md5.h b/cores/esp8266/md5.h index b3f1f54533..4efcaa9553 100644 --- a/cores/esp8266/md5.h +++ b/cores/esp8266/md5.h @@ -1,11 +1,11 @@ -/* +/* md5.h - exposed md5 ROM functions for esp8266 Copyright (c) 2015 Hristo Gochkov. All rights reserved. This file is part of the esp8266 core for Arduino environment. - + original C source from https://github.com/morrissinger/ESP8266-Websocket/raw/master/MD5.h - + This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either @@ -34,7 +34,7 @@ typedef struct { } md5_context_t; extern void MD5Init (md5_context_t *); -extern void MD5Update (md5_context_t *, uint8_t *, uint16_t); +extern void MD5Update (md5_context_t *, const uint8_t *, const uint16_t); extern void MD5Final (uint8_t [16], md5_context_t *); #ifdef __cplusplus diff --git a/cores/esp8266/pgmspace.h b/cores/esp8266/pgmspace.h index 6f04b10229..a785e26391 100644 --- a/cores/esp8266/pgmspace.h +++ b/cores/esp8266/pgmspace.h @@ -87,23 +87,35 @@ int vsnprintf_P(char *str, size_t strSize, PGM_P formatP, va_list ap) __attribut // w1, w0 #ifdef __ets__ -#define pgm_read_byte(addr) \ -(__extension__({ \ - PGM_P __local = (PGM_P)(addr); /* isolate varible for macro expansion */ \ - ptrdiff_t __offset = ((uint32_t)__local & 0x00000003); /* byte aligned mask */ \ - const uint32_t* __addr32 = (const uint32_t*)((const uint8_t*)(__local)-__offset); \ - uint8_t __result = ((*__addr32) >> (__offset * 8)); \ - __result; \ -})) - -#define pgm_read_word(addr) \ -(__extension__({ \ - PGM_P __local = (PGM_P)(addr); /* isolate varible for macro expansion */ \ - ptrdiff_t __offset = ((uint32_t)__local & 0x00000002); /* word aligned mask */ \ - const uint32_t* __addr32 = (const uint32_t*)((const uint8_t*)(__local) - __offset); \ - uint16_t __result = ((*__addr32) >> (__offset * 8)); \ - __result; \ -})) + +#define pgm_read_with_offset(addr, res) \ + asm("extui %0, %1, 0, 2\n" /* Extract offset within word (in bytes) */ \ + "sub %1, %1, %0\n" /* Subtract offset from addr, yielding an aligned address */ \ + "l32i.n %1, %1, 0x0\n" /* Load word from aligned address */ \ + "slli %0, %0, 3\n" /* Mulitiply offset by 8, yielding an offset in bits */ \ + "ssr %0\n" /* Prepare to shift by offset (in bits) */ \ + "srl %0, %1\n" /* Shift right; now the requested byte is the first one */ \ + :"=r"(res), "=r"(addr) \ + :"1"(addr) \ + :); + +static inline uint8_t pgm_read_byte_inlined(const void* addr) { + register uint32_t res; + pgm_read_with_offset(addr, res); + return (uint8_t) res; /* This masks the lower byte from the returned word */ +} + +/* Although this says "word", it's actually 16 bit, i.e. half word on Xtensa */ +static inline uint16_t pgm_read_word_inlined(const void* addr) { + register uint32_t res; + pgm_read_with_offset(addr, res); + return (uint16_t) res; /* This masks the lower half-word from the returned word */ +} + +// Make sure, that libraries checking existence of this macro are not failing +#define pgm_read_byte(addr) pgm_read_byte_inlined(addr) +#define pgm_read_word(addr) pgm_read_word_inlined(addr) + #else //__ets__ #define pgm_read_byte(addr) (*reinterpret_cast(addr)) #define pgm_read_word(addr) (*reinterpret_cast(addr)) diff --git a/cores/esp8266/spiffs_hal.cpp b/cores/esp8266/spiffs_hal.cpp index 7f3245c0d0..2d66bd54df 100644 --- a/cores/esp8266/spiffs_hal.cpp +++ b/cores/esp8266/spiffs_hal.cpp @@ -60,7 +60,7 @@ int32_t spiffs_hal_read(uint32_t addr, uint32_t size, uint8_t *dst) { __LINE__, addr, size, alignedBegin, alignedEnd); return SPIFFS_ERR_INTERNAL; } - memcpy(dst, &tmp + 4 - nb, nb); + memcpy(dst, ((uint8_t*) &tmp) + 4 - nb, nb); } if (alignedEnd != alignedBegin) { diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000000..e35d8850c9 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +_build diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000000..36b4923488 --- /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/PROGMEM.rst b/doc/PROGMEM.rst new file mode 100644 index 0000000000..e1803475e6 --- /dev/null +++ b/doc/PROGMEM.rst @@ -0,0 +1,253 @@ +Guide to PROGMEM on ESP8266 and Arduino IDE +=========================================== + +Intro +----- + +PROGMEM is a Arduino AVR feature that has been ported to ESP8266 to +ensure compatability with existing Arduino libraries, as well as, saving +RAM. On the esp8266 declaring a string such as ``const char * xyz = +"this is a string"`` will place this string in RAM, not flash. It is +possible to place a String into flash, and then load it into RAM when +it is needed. On an 8bit AVR this process is very simple. On the 32bit +ESP8266 there are conditions that must be met to read back from flash. + +On the ESP8266 PROGMEM is a macro: + +.. code:: cpp + + #define PROGMEM ICACHE_RODATA_ATTR + +``ICACHE_RODATA_ATTR`` is defined by: + +.. code:: cpp + + #define ICACHE_RODATA_ATTR __attribute__((section(".irom.text"))) + +Which places the variable in the .irom.text section ie flash. Placing strings in +flash requires using any of the methods above. + +| ### Declare a global string to be stored in flash. + +.. code:: cpp + + static const char xyz[] PROGMEM = "This is a string stored in flash"; + +Declare a flash string within code block. +----------------------------------------- + +For this you can use the PSTR macro. Which are all defined in +`pgmspace.h `__ + +.. code:: cpp + + #define PGM_P const char * + #define PGM_VOID_P const void * + #define PSTR(s) (__extension__({static const char __c[] PROGMEM = (s); &__c[0];})) + +In practice: + +.. code:: cpp + + void myfunction(void) { + PGM_P xyz = PSTR("Store this string in flash"); + const char * abc = PSTR("Also Store this string in flash"); + } + +The two examples above will store these strings in flash. To retrieve +and manipulate flash strings they must be read from flash in 4byte words. +In the Arduino IDE for esp8266 there are several functions that can help +retrieve strings from flash that have been stored using PROGMEM. Both of +the examples above return ``const char *``. However use of these pointers, +without correct 32bit alignment you will cause a segmentation fault and +the ESP8266 will crash. You must read from the flash 32 bit aligned. + +Functions to read back from PROGMEM +----------------------------------- + +Which are all defined in +`pgmspace.h `__ + +.. code:: cpp + + int memcmp_P(const void* buf1, PGM_VOID_P buf2P, size_t size); + void* memccpy_P(void* dest, PGM_VOID_P src, int c, size_t count); + void* memmem_P(const void* buf, size_t bufSize, PGM_VOID_P findP, size_t findPSize); + void* memcpy_P(void* dest, PGM_VOID_P src, size_t count); + char* strncpy_P(char* dest, PGM_P src, size_t size); + char* strcpy_P(dest, src) + char* strncat_P(char* dest, PGM_P src, size_t size); + char* strcat_P(dest, src) + int strncmp_P(const char* str1, PGM_P str2P, size_t size); + int strcmp_P(str1, str2P) + int strncasecmp_P(const char* str1, PGM_P str2P, size_t size); + int strcasecmp_P(str1, str2P) + size_t strnlen_P(PGM_P s, size_t size); + size_t strlen_P(strP) + char* strstr_P(const char* haystack, PGM_P needle); + int printf_P(PGM_P formatP, ...); + int sprintf_P(char *str, PGM_P formatP, ...); + int snprintf_P(char *str, size_t strSize, PGM_P formatP, ...); + int vsnprintf_P(char *str, size_t strSize, PGM_P formatP, va_list ap); + +There are a lot of functions there but in reality they are ``_P`` +versions of standard c functions that are adapted to read from the +esp8266 32bit aligned flash. All of them take a ``PGM_P`` which is +essentially a ``const char *``. Under the hood these functions all use, a +process to ensure that 4 bytes are read, and the request byte is returned. + +This works well when you have designed a function as above that is +specialised for dealing with PROGMEM pointers but there is no type +checking except against ``const char *``. This means that it is totally +legitimate, as far as the compiler is concerned, for you to pass it any +``const char *`` string, which is obviously not true and will lead to +undefined behaviour. This makes it impossible to create any overloaded +functions that can use flash strings when they are defined as ``PGM_P``. +If you try you will get an ambiguous overload error as ``PGM_P`` == +``const char *``. + +Enter the \_\_FlashStringHelper... This is a wrapper class that allows flash +strings to be used as a class, this means that type checking and function +overloading can be used with flash strings. Most people will be familiar with +the ``F()`` macro and possibly the FPSTR() macro. These are defined in `WString.h `__: + +.. code:: cpp + + #define FPSTR(pstr_pointer) (reinterpret_cast(pstr_pointer)) + #define F(string_literal) (FPSTR(PSTR(string_literal))) + +So ``FSPTR()`` takes a PROGMEM pointer to a string and casts it to this +``__FlashStringHelper`` class. Thus if you have defined a string as +above ``xyz`` you can use ``FPSTR()`` to convert it to +``__FlashStringHelper`` for passing into functions that take it. + +.. code:: cpp + + static const char xyz[] PROGMEM = "This is a string stored in flash"; + Serial.println(FPSTR(xyz)); + +The ``F()`` combines both of these methods to create an easy and quick +way to store an inline string in flash, and return the type +``__FlashStringHelper``. For example: + +.. code:: cpp + + Serial.println(F("This is a string stored in flash")); + +Although these two functions provide a similar function, they serve +different roles. ``FPSTR()`` allows you to define a global flash string +and then use it in any function that takes ``__FlashStringHelper``. +``F()`` allows you to define these flash strings in place, but you can't +use them anywhere else. The consequence of this is sharing common +strings is possible using ``FPSTR()`` but not ``F()``. +``__FlashStringHelper`` is what the String class uses to overload its +constructor: + +.. code:: cpp + + String(const char *cstr = ""); // constructor from const char * + String(const String &str); // copy constructor + String(const __FlashStringHelper *str); // constructor for flash strings + +This allows you to write: + +.. code:: cpp + + String mystring(F("This string is stored in flash")); + +How do I write a function to use \_\_FlashStringHelper? Simples: cast the pointer back to a PGM\_P and use the ``_P`` functions shown above. This an example implementation for String for the concat function. + +.. code:: cpp + + unsigned char String::concat(const __FlashStringHelper * str) { + if (!str) return 0; // return if the pointer is void + int length = strlen_P((PGM_P)str); // cast it to PGM_P, which is basically const char *, and measure it using the _P version of strlen. + if (length == 0) return 1; + unsigned int newlen = len + length; + if (!reserve(newlen)) return 0; // create a buffer of the correct length + strcpy_P(buffer + len, (PGM_P)str); //copy the string in using strcpy_P + len = newlen; + return 1; + } + +How do I declare a global flash string and use it? +-------------------------------------------------- + +.. code:: cpp + + static const char xyz[] PROGMEM = "This is a string stored in flash. Len = %u"; + + void setup() { + Serial.begin(115200); Serial.println(); + Serial.println( FPSTR(xyz) ); // just prints the string, must convert it to FlashStringHelper first using FPSTR(). + Serial.printf_P( xyz, strlen_P(xyz)); // use printf with PROGMEM string + } + +How do I use inline flash strings? +---------------------------------- + +.. code:: cpp + + void setup() { + Serial.begin(115200); Serial.println(); + Serial.println( F("This is an inline string")); // + Serial.printf_P( PSTR("This is an inline string using printf %s"), "hello"); + } + +How do I declare and use data in PROGMEM? +----------------------------------------- + +.. code:: cpp + + const size_t len_xyz = 30; + const uint8_t xyz[] PROGMEM = { + 0x53, 0x61, 0x79, 0x20, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x20, + 0x74, 0x6f, 0x20, 0x4d, 0x79, 0x20, 0x4c, 0x69, 0x74, 0x74, + 0x6c, 0x65, 0x20, 0x46, 0x72, 0x69, 0x65, 0x6e, 0x64, 0x00}; + + void setup() { + Serial.begin(115200); Serial.println(); + uint8_t * buf = new uint8_t[len_xyz]; + if (buf) { + memcpy_P(buf, xyz, len_xyz); + Serial.write(buf, len_xyz); // output the buffer. + } + } + +How do I declare some data in PROGMEM, and retrieve one byte from it. +--------------------------------------------------------------------- + +Declare the data as done previously, then use ``pgm_read_byte`` to get +the value back. + +.. code:: cpp + + const size_t len_xyz = 30; + const uint8_t xyz[] PROGMEM = { + 0x53, 0x61, 0x79, 0x20, 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x20, + 0x74, 0x6f, 0x20, 0x4d, 0x79, 0x20, 0x4c, 0x69, 0x74, 0x74, + 0x6c, 0x65, 0x20, 0x46, 0x72, 0x69, 0x65, 0x6e, 0x64, 0x00 + }; + + void setup() { + Serial.begin(115200); Serial.println(); + for (int i = 0; i < len_xyz; i++) { + uint8_t byteval = pgm_read_byte(xyz + i); + Serial.write(byteval); // output the buffer. + } + } + +In summary +---------- + +It is easy to store strings in flash using ``PROGMEM`` and ``PSTR`` but +you have to create functions that specifically use the pointers they +generate as they are basically ``const char *``. On the other hand +``FPSTR`` and ``F()`` give you a class that you can do implicit +conversions from, very useful when overloading functions, and doing +implicit type conversions. It is worth adding that if you wish to store +an ``int``, ``float`` or pointer these can be stored and read back +directly as they are 4 bytes in size and therefor will be always +aligned! + +Hope this helps. diff --git a/doc/Troubleshooting/debugging.md b/doc/Troubleshooting/debugging.md deleted file mode 100644 index 47a3cbebb4..0000000000 --- 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 0000000000..970cb0e7b6 --- /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 49c544940e..0000000000 --- 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 0000000000..e69de29bb2 diff --git a/doc/boards.md b/doc/boards.md deleted file mode 100644 index f500263b0d..0000000000 --- a/doc/boards.md +++ /dev/null @@ -1,308 +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) - -## 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) - - - - diff --git a/doc/boards.rst b/doc/boards.rst new file mode 100644 index 0000000000..ec085057bc --- /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 df07d5a95e..0000000000 --- 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 0000000000..767f33a2a8 --- /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 0000000000..2c0f130ca1 --- /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 348d1cf19e..0000000000 --- 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 0000000000..f8ee6e8d89 --- /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 8be1d4720e..0000000000 --- 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 -clinet.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 0000000000..4b98034ce2 --- /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 a38ff37af3..0000000000 --- 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 - - - - -