7a43092df0
* WIP: Initial overlay of upstream version of umm_malloc over our current version w/o any edits. Using files from: https://github.com/rhempel/umm_malloc/tree/master/src https://github.com/rhempel/c-helper-macros/tree/develop The following file remanents from our old version were removed: umm_malloc.cpp, umm_performance.h, umm_performance.cpp, and umm_stats.h This is intended to be a "compare to" for changes made to upstream version. * WIP: upstream version of umm_malloc customized for Arduino ESP8266 Core See comments at the top of umm_malloc.cpp for a summary of changes so far. Added support for integrity check and poison check to refactored heap.cpp. * Resoved Travis CI - issue * Corrected #ifdef's for UMM_STATS/UMM_STATS_FULL * Corrected UMM_REALLOC_DEFRAG option to be more like the original umm_realloc. Updated some comments and changed method of defining _rom_putc1. * Updated UMM_POISON_CHECK_LITE - Expanded the poison check on the current allocation to include its nearest allocated neighbors in the heap. That is to say, if the nearest neighbor is free, then the next one over is checked. And this is done in both directions. umm_malloc() will also checks the neighbors of the selected allocation before use. Merged umm_malloc.c into umm_malloc.cpp. Added additional stats for debug build. On going comment cleanup. Removed #if 0 block from isr_safe_printf. Corrected mistyped UMM_POISON_CHECK UMM_CHECK_POISON. Corrected other conditional build issues. * Updated printing in heap.cpp to behave the way os_printf did. Updated printing in heap.cpp to behave the way os_printf would have with regards to system_set_os_print. ie. setDebugOutput enable/disables printing Expanded #ifdef fenceing of .c files to prevent Arduino IDE from building them outside of the .cpp file they are included in. Corrected more conditional building issues. Remaining concern - umm_info(0, true) printing - does it need an ISR safe method, all printing is done from within a critical sectionn with rsil(15)? Or should be have the print option disabled for non-debug builds. ie. Debug port: "Disabled" * Merged latest, 2019-09-07, from upstream umm_malloc * R.Hempel 2019-09-07 - Separate the malloc() and free() functionality into * wrappers that use critical section protection macros * and static core functions that assume they are * running in a protected con text. Thanks @devyte * Resolved issue where OOM selected w/ Debug port: "Disabled" caused hang. With OOM selected w/ Debug port: "Disabled" you can now use Serial.setDebugOutput(true); to enable OOM message displaying. This is the behavior previously available with os_printf. commit rev 1 * Fixed realloc OOM bug introduced due to confusing code, added comment for future. umm_info(NULL, true) is now treated as a debug option that is enabled by Arduino IDE->tools `Debug port: "Serial"`, etc. It now prints when DEBUG_ESP_PORT or UMM_INFO_PRINT are defined. Cleanup comments and some conditionals. * Updated to track PRs for various print definitions. Cleaned up comments * Added missing "#ifdef __cplusplus" * Reorganize local enhancements More comment cleanups Added Status TODOs marks for upstream * Print notice message for the need of -DUMM_INFO_PRINT * This updates the heap management library, umm_malloc, to the current upstream version at https://github.com/rhempel/umm_malloc. Some reorganizing and new code was needed to use the new version. This is a list of note worthy changes: UMM_POISON - now has a lite option as well as the previous intensive check option. The code for running the full poison test at the call of the various alloc functions was removed in the upstream version. In this port the missing code was added to heap.cpp and umm_local.cpp. * UMM_POISON - appears to have been partially changed to UMM_POISON_CHECK, I treat it as depricated and used UMM_POISON_CHECK, when needed. However, the Arduino Core's references to UMM_POISON were replaced with UMM_POISON_CHECK_LITE. * UMM_POISON_CHECK_LITE - Less intense, it just checks poison on active neighboring allocations. * UMM_POISON_CHECK - Full heap intensive check of poison UMM_INFO_PRINT - This new define makes building UMM_INFO with printing capability, optional. When umm_info(NULL, true) is used to print a debug view of heap information to the debug port, it has to walk the heap and print out information, while in a critical section. This requires that the print function be able to print w/o doing malloc calls and from an IRQ disabled context. It also requires more IRAM to handle printing. Without this define `umm_info(NULL, true)` will not print. * UMM_INFO_PRINT is enabled as part of selecting `Debug port: "Serial" or * "Serial1"`. To make available all the time use '-D UMM_INFO_PRINT`. A cautionary note, on the use of UMM_INTEGRITY_CHECK, UMM_POISON_CHECK, and UMM_INFO_PRINT. All of these run with IRQs disabled, for periods that can go into 100's of us. With umm_info(NULL, true) that may go into seconds, depending on the serial interface speed and the number of memory allocations present. Use UMM_INTEGRITY_CHECK, UMM_POISON_CHECK, and UMM_INFO_PRINT sparingly. If you want to see numbers for the disabled time, explore using UMM_CRITICAL_METRICS in umm_malloc_cfg.h. * This updates the heap management library, umm_malloc, to the current upstream version at https://github.com/rhempel/umm_malloc. Some reorganizing and new code was needed to use the new version. This is a list of note worthy changes: UMM_POISON - now has a lite option as well as the previous intensive check option. The code for running the full poison test at the call of the various alloc functions was removed in the upstream version. In this port the missing code was added to heap.cpp and umm_local.cpp. * UMM_POISON - appears to have been partially changed to UMM_POISON_CHECK, I treat it as depricated and used UMM_POISON_CHECK, when needed. However, the Arduino Core's references to UMM_POISON were replaced with UMM_POISON_CHECK_LITE. * UMM_POISON_CHECK_LITE - Less intense, it just checks poison on active neighboring allocations. * UMM_POISON_CHECK - Full heap intensive check of poison UMM_INFO_PRINT - This new define makes building UMM_INFO with printing capability, optional. When umm_info(NULL, true) is used to print a debug view of heap information to the debug port, it has to walk the heap and print out information, while in a critical section. This requires that the print function be able to print w/o doing malloc calls and from an IRQ disabled context. It also requires more IRAM to handle printing. Without this define `umm_info(NULL, true)` will not print. * UMM_INFO_PRINT is enabled as part of selecting `Debug port: "Serial" or * "Serial1"`. To make available all the time use '-D UMM_INFO_PRINT`. A cautionary note, on the use of UMM_INTEGRITY_CHECK, UMM_POISON_CHECK, and UMM_INFO_PRINT. All of these run with IRQs disabled, for periods that can go into 100's of us. With umm_info(NULL, true) that may go into seconds, depending on the serial interface speed and the number of memory allocations present. Use UMM_INTEGRITY_CHECK, UMM_POISON_CHECK, and UMM_INFO_PRINT sparingly. If you want to see numbers for the disabled time, explore using UMM_CRITICAL_METRICS in umm_malloc_cfg.h. * Updated upstream TODO * Changes on printing to comply with new understanding of SPI bus availability from an ISR vs forground with INTLEVEL 15. * Removed no longer needed files. * OOM build option now saves file and line number for post mortem reporting. * Missed change. * Consolated upstream integration comments into Notes.h. This helps keep these comments separated from the upstream code and to avoid getting lost. I'll expand this as I think of and remember more. * Comment updates. * Notes update. * Changes to heap.cpp - Refactored macro PTR_CHECK__LOG_LAST_FAIL. Replaced macros __umm_... with uppercase versions. Corrected misplaced POISON_CHECK__PANIC_FL macro in realloc. Added debug free options for OOM and Poison to umm_malloc_cfg.h Updated Notes.h. Lines that start with "//C" are meant to flag reviewer's attention. * Corrected Full Poison Check's placement and documented the thinking behind its placement and Integrity Checks placement with relation to the *alloc function. Just so I don't forget again :/ * Fixed typos
Arduino core for ESP8266 WiFi chip
Quick links
Arduino on ESP8266
This project brings support for the ESP8266 chip to the Arduino environment. It lets you write sketches, using familiar Arduino functions and libraries, and run them directly on ESP8266, with no external microcontroller required.
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, and work with SD cards, servos, SPI and I2C peripherals.
Contents
- Installing options:
- Documentation
- Issues and support
- Contributing
- License and credits
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 the current upstream Arduino IDE at the 1.8.7 level or later. The current version is on the Arduino website.
- Start Arduino and open the Preferences window.
- Enter
https://arduino.esp8266.com/stable/package_esp8266com_index.jsoninto the 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).
Latest release 
Boards manager link: https://arduino.esp8266.com/stable/package_esp8266com_index.json
Documentation: https://arduino-esp8266.readthedocs.io/en/2.5.2/
Using git version
Also known as latest git or master branch.
- Install the current upstream Arduino IDE at the 1.8 level or later. The current version is on the Arduino website.
- Follow the instructions in the documentation.
Using PlatformIO
PlatformIO is an open source ecosystem for IoT development with a cross-platform build system, a library manager, and full support for Espressif (ESP8266) development. It works on the following popular host operating systems: macOS, Windows, Linux 32/64, and Linux ARM (like Raspberry Pi, BeagleBone, CubieBoard).
- What is PlatformIO?
- PlatformIO IDE
- PlatformIO Core (command line tool)
- Advanced usage - custom settings, uploading to SPIFFS, Over-the-Air (OTA), staging version
- Integration with Cloud and Standalone IDEs - Cloud9, Codeanywhere, Eclipse Che (Codenvy), Atom, CLion, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, VIM, Visual Studio, and VSCode
- Project Examples
Building with make
makeEspArduino is a generic makefile for any ESP8266 Arduino project. Using make instead of the Arduino IDE makes it easier to do automated and production builds.
Documentation
Documentation for latest development version: https://arduino-esp8266.readthedocs.io/en/latest/
Issues and support
ESP8266 Community Forum is a well-established community for questions and answers about Arduino for ESP8266. If you need help, have a "How do I..." type question, have a problem with a 3rd party library not hosted in this repo, or just want to discuss how to approach a problem, please ask there.
If you find the forum useful, please consider supporting it with a donation.
If you encounter an issue which you think is a bug in the ESP8266 Arduino Core or the associated libraries, or if you want to propose an enhancement, you are welcome to submit it here on Github: https://github.com/esp8266/Arduino/issues.
Please provide as much context as possible, as well as the information requested in the issue template:
- 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
- when encountering an issue that happens at run time, attach the serial output. Wrap it into a code block, just like the code.
- for issues that 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 choice, flash size)
- etc
Contributing
For minor fixes of code and documentation, please go ahead and submit a pull request. A gentle introduction to the process can be found here.
Check out the list of issues that are easy to fix — easy issues pending. 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 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.
License and credits
Arduino IDE is developed and maintained by the Arduino team. The IDE is licensed under GPL.
ESP8266 core includes an xtensa gcc toolchain, which is also under GPL.
Esptool written by Christian Klippel is licensed under GPLv2, currently maintained by Ivan Grokhotkov: https://github.com/igrr/esptool-ck.
Espressif SDK included in this build is under Espressif MIT License.
ESP8266 core files are licensed under LGPL.
SPI Flash File System (SPIFFS) written by Peter Andersson is used in this project. It is distributed under the MIT license.
umm_malloc memory management library written by Ralph Hempel is used in this project. It is distributed under the MIT license.
SoftwareSerial library and examples written by Peter Lerup. Distributed under LGPL 2.1.
axTLS library written by Cameron Rich, built from https://github.com/igrr/axtls-8266, is used in this project. It is distributed under BSD license.
BearSSL library written by Thomas Pornin, built from https://github.com/earlephilhower/bearssl-esp8266, is used in this project. It is distributed under the MIT License.
LittleFS library written by ARM Limited and released under the BSD 3-clause license.