Merge branch 'master' into pgmspace_to_libc

Author: earlephilhower

boards.txt

@@ -0,0 +1,48 @@
+/*
+ Esp.cpp - ESP8266-specific APIs
+ Copyright (c) 2015 Ivan Grokhotkov. 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
+ version 2.1 of the License, or (at your option) any later version.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
+#include "umm_malloc/umm_malloc.h"
+#include "umm_malloc/umm_malloc_cfg.h"
+#include "coredecls.h"
+#include "Esp.h"
+
+void EspClass::getHeapStats(uint32_t* hfree, uint16_t* hmax, uint8_t* hfrag)
+{
+    // L2 / Euclidian norm of free block sizes.
+    // Having getFreeHeap()=sum(hole-size), fragmentation is given by
+    // 100 * (1 - sqrt(sum(hole-size²)) / sum(hole-size))
+
+    umm_info(NULL, 0);
+    uint8_t block_size = umm_block_size();
+    uint32_t fh = ummHeapInfo.freeBlocks * block_size;
+    if (hfree)
+        *hfree = fh;
+    if (hmax)
+        *hmax = ummHeapInfo.maxFreeContiguousBlocks * block_size;
+    if (hfrag)
+        *hfrag = 100 - (sqrt32(ummHeapInfo.freeSize2) * 100) / fh;
+}
+
+uint8_t EspClass::getHeapFragmentation()
+{
+    uint8_t hfrag;
+    getHeapStats(nullptr, nullptr, &hfrag);
+    return hfrag;
+}

cores/esp8266/Esp-frag.cpp

@@ -24,6 +24,7 @@
 #include <memory>
 #include "interrupts.h"
 #include "MD5Builder.h"
+#include "umm_malloc/umm_malloc.h"
 
 extern "C" {
 #include "user_interface.h"
@@ -171,6 +172,11 @@ uint32_t EspClass::getFreeHeap(void)
     return system_get_free_heap_size();
 }
 
+uint16_t EspClass::getMaxFreeBlockSize(void)
+{
+    return umm_max_block_size();
+}
+
 uint32_t EspClass::getChipId(void)
 {
     return system_get_chip_id();

cores/esp8266/Esp.cpp

@@ -103,10 +103,13 @@ class EspClass {
         void restart();
 
         uint16_t getVcc();
-        uint32_t getFreeHeap();
-
         uint32_t getChipId();
 
+        uint32_t getFreeHeap();
+        uint16_t getMaxFreeBlockSize();
+        uint8_t getHeapFragmentation(); // in %
+        void getHeapStats(uint32_t* free = nullptr, uint16_t* max = nullptr, uint8_t* frag = nullptr);
+
         const char * getSdkVersion();
         String getCoreVersion();
         String getFullVersion();

cores/esp8266/Esp.h

@@ -8,6 +8,7 @@ extern "C" {
 
 // TODO: put declarations here, get rid of -Wno-implicit-function-declaration
 
+#include <stdint.h>
 #include <cont.h> // g_pcont declaration
 
 extern bool timeshift64_is_set;
@@ -18,6 +19,8 @@ void tune_timeshift64 (uint64_t now_us);
 void settimeofday_cb (void (*cb)(void));
 void disable_extra4k_at_link_time (void) __attribute__((noinline));
 
+uint32_t sqrt32 (uint32_t n);
+
 #ifdef __cplusplus
 }
 #endif

cores/esp8266/coredecls.h

@@ -0,0 +1,56 @@
+
+#include <coredecls.h>
+#include <stdint.h>
+
+uint32_t sqrt32 (uint32_t n)
+{
+    // http://www.codecodex.com/wiki/Calculate_an_integer_square_root#C
+    // Another very fast algorithm donated by Tristan.Muntsinger@gmail.com
+    // (note: tested across the full 32 bits range, see comment below)
+
+    // 15 iterations (c=1<<15)
+
+    unsigned int c = 0x8000;
+    unsigned int g = 0x8000;
+
+    for(;;)
+    {
+        if (g*g > n)
+            g ^= c;
+        c >>= 1;
+        if (!c)
+            return g;
+        g |= c;
+    }
+}
+
+/*
+ * tested with:
+ *
+
+#include <stdio.h>
+#include <stdint.h>
+#include <math.h>
+
+int main (void)
+{
+    for (uint32_t i = 0; ++i; )
+    {
+        uint32_t sr = sqrt32(i);
+        uint32_t ifsr = sqrt(i);
+
+        if (ifsr != sr)
+            printf("%d: i%d f%d\n", i, sr, ifsr);
+
+        if (!(i & 0xffffff))
+        {
+            printf("%i%% (0x%08x)\r", ((i >> 16) * 100) >> 16, i);
+            fflush(stdout);
+        }
+    }
+
+    printf("\n");
+}
+
+ *
+ */

cores/esp8266/sqrt32.c

@@ -1024,6 +1024,10 @@ void ICACHE_FLASH_ATTR *umm_info( void *ptr, int force ) {
     if( UMM_NBLOCK(blockNo) & UMM_FREELIST_MASK ) {
       ++ummHeapInfo.freeEntries;
       ummHeapInfo.freeBlocks += curBlocks;
+      ummHeapInfo.freeSize2 += (unsigned int)curBlocks
+                             * (unsigned int)sizeof(umm_block)
+                             * (unsigned int)curBlocks
+                             * (unsigned int)sizeof(umm_block);
 
       if (ummHeapInfo.maxFreeContiguousBlocks < curBlocks) {
         ummHeapInfo.maxFreeContiguousBlocks = curBlocks;
@@ -1761,4 +1765,13 @@ size_t ICACHE_FLASH_ATTR umm_free_heap_size( void ) {
   return (size_t)ummHeapInfo.freeBlocks * sizeof(umm_block);
 }
 
+size_t ICACHE_FLASH_ATTR umm_max_block_size( void ) {
+  umm_info(NULL, 0);
+  return ummHeapInfo.maxFreeContiguousBlocks * sizeof(umm_block);
+}
+
+size_t ICACHE_FLASH_ATTR umm_block_size( void ) {
+  return sizeof(umm_block);
+}
+
 /* ------------------------------------------------------------------------ */

cores/esp8266/umm_malloc/umm_malloc.c

@@ -26,6 +26,8 @@ typedef struct UMM_HEAP_INFO_t {
   unsigned short int freeBlocks;
 
   unsigned short int maxFreeContiguousBlocks;
+
+  unsigned int freeSize2;
 }
 UMM_HEAP_INFO;
 
@@ -41,6 +43,8 @@ void *umm_realloc( void *ptr, size_t size );
 void umm_free( void *ptr );
 
 size_t umm_free_heap_size( void );
+size_t umm_max_block_size( void );
+size_t umm_block_size( void );
 
 #ifdef __cplusplus
 }

cores/esp8266/umm_malloc/umm_malloc.h

@@ -10,7 +10,7 @@ onEvent
 
 .. code:: cpp
 
-    void  onEvent (WiFiEventCb cb, WiFiEvent_t event=WIFI_EVENT_ANY) __attribute__((deprecated)) 
+    void  onEvent (WiFiEventCb cb, WiFiEvent_t event=WIFI_EVENT_ANY) __attribute__((deprecated))
 
 To see how to use ``onEvent`` please check example sketch `WiFiClientEvents.ino <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiClientEvents/WiFiClientEvents.ino>`__ available inside examples folder of the ESP8266WiFi library.
 
@@ -19,13 +19,13 @@ WiFiEventHandler
 
 .. code:: cpp
 
-    WiFiEventHandler  onStationModeConnected (std::function< void(const WiFiEventStationModeConnected &)>) 
-    WiFiEventHandler  onStationModeDisconnected (std::function< void(const WiFiEventStationModeDisconnected &)>) 
-    WiFiEventHandler  onStationModeAuthModeChanged (std::function< void(const WiFiEventStationModeAuthModeChanged &)>) 
-    WiFiEventHandler  onStationModeGotIP (std::function< void(const WiFiEventStationModeGotIP &)>) 
-    WiFiEventHandler  onStationModeDHCPTimeout (std::function< void(void)>) 
-    WiFiEventHandler  onSoftAPModeStationConnected (std::function< void(const WiFiEventSoftAPModeStationConnected &)>) 
-    WiFiEventHandler  onSoftAPModeStationDisconnected (std::function< void(const WiFiEventSoftAPModeStationDisconnected &)>) 
+    WiFiEventHandler  onStationModeConnected (std::function< void(const WiFiEventStationModeConnected &)>)
+    WiFiEventHandler  onStationModeDisconnected (std::function< void(const WiFiEventStationModeDisconnected &)>)
+    WiFiEventHandler  onStationModeAuthModeChanged (std::function< void(const WiFiEventStationModeAuthModeChanged &)>)
+    WiFiEventHandler  onStationModeGotIP (std::function< void(const WiFiEventStationModeGotIP &)>)
+    WiFiEventHandler  onStationModeDHCPTimeout (std::function< void(void)>)
+    WiFiEventHandler  onSoftAPModeStationConnected (std::function< void(const WiFiEventSoftAPModeStationConnected &)>)
+    WiFiEventHandler  onSoftAPModeStationDisconnected (std::function< void(const WiFiEventSoftAPModeStationDisconnected &)>)
 
 To see a sample application with ``WiFiEventHandler``, please check separate section with `examples :arrow\_right: <generic-examples.rst>`__ dedicated specifically to the Generic Class..
 
@@ -34,25 +34,21 @@ persistent
 
 .. code:: cpp
 
-    WiFi.persistent (persistent) 
+    WiFi.persistent(persistent)
 
-Module is able to reconnect to last used Wi-Fi network on power up or reset basing on settings stored in specific sectors of flash memory. By default these settings are written to flash each time they are used in functions like ``WiFi.begin(ssid, password)``. This happens no matter if SSID or password has been actually changed.
+ESP8266 is able to reconnect to the last used Wi-Fi network or establishes the same Access Point upon power up or reset.
+By default, these settings are written to specific sectors of flash memory every time they are changed in ``WiFi.begin(ssid, passphrase)`` or ``WiFi.softAP(ssid, passphrase, channel)``, and when ``WiFi.disconnect`` or ``WiFi.softAPdisconnect`` is invoked.
+Frequently calling these functions could cause wear on the flash memory (see issue `#1054 <https://github.com/esp8266/Arduino/issues/1054>`__).
 
-This might result in some wear of flash memory depending on how often such functions are called.
-
-Setting ``persistent`` to ``false`` will get SSID / password written to flash only if currently used values do not match what is already stored in flash.
-
-Please note that functions ``WiFi.disconnect`` or ``WiFi.softAPdisconnect`` reset currently used SSID / password. If ``persistent`` is set to ``false``, then using these functions will not affect SSID / password stored in flash.
-
-To learn more about this functionality, and why it has been introduced, check issue report `#1054 <https://github.com/esp8266/Arduino/issues/1054>`__.
+Once ``WiFi.persistent(false)`` is called, ``WiFi.begin``, ``WiFi.disconnect``, ``WiFi.softAP``, or ``WiFi.softAPdisconnect`` only changes the current in-memory Wi-Fi settings, and does not affect the Wi-Fi settings stored in flash memory.
 
 mode
 ~~~~
 
 .. code:: cpp
 
-    WiFi.mode(m) 
-    WiFi.getMode() 
+    WiFi.mode(m)
+    WiFi.getMode()
 
 -  ``WiFi.mode(m)``: set mode to ``WIFI_AP``, ``WIFI_STA``,
    ``WIFI_AP_STA`` or ``WIFI_OFF``
@@ -64,17 +60,17 @@ Other Function Calls
 
 .. code:: cpp
 
-    int32_t  channel (void) 
-    bool  setSleepMode (WiFiSleepType_t type) 
-    WiFiSleepType_t  getSleepMode () 
-    bool  setPhyMode (WiFiPhyMode_t mode) 
-    WiFiPhyMode_t  getPhyMode () 
-    void  setOutputPower (float dBm) 
-    WiFiMode_t  getMode () 
-    bool  enableSTA (bool enable) 
-    bool  enableAP (bool enable) 
-    bool  forceSleepBegin (uint32 sleepUs=0) 
-    bool  forceSleepWake () 
+    int32_t  channel (void)
+    bool  setSleepMode (WiFiSleepType_t type)
+    WiFiSleepType_t  getSleepMode ()
+    bool  setPhyMode (WiFiPhyMode_t mode)
+    WiFiPhyMode_t  getPhyMode ()
+    void  setOutputPower (float dBm)
+    WiFiMode_t  getMode ()
+    bool  enableSTA (bool enable)
+    bool  enableAP (bool enable)
+    bool  forceSleepBegin (uint32 sleepUs=0)
+    bool  forceSleepWake ()
     int  hostByName (const char *aHostname, IPAddress &aResult)
 
 Documentation for the above functions is not yet prepared.

doc/esp8266wifi/generic-class.rst

@@ -125,7 +125,7 @@ Soft Access Point
 ~~~~~~~~~~~~~~~~~
 
 An `access point (AP) <https://en.wikipedia.org/wiki/Wireless_access_point>`__ is a device that provides access to Wi-Fi network to other devices (stations)
-and connects them further to a wired network. ESP8266 can provide similar functionality except it does not have interface to a wired network. Such mode of operation is called soft access point (soft-AP). The maximum number of stations connected to the soft-AP is five.
+and connects them further to a wired network. ESP8266 can provide similar functionality except it does not have interface to a wired network. Such mode of operation is called soft access point (soft-AP). The maximum number of stations that can simultaneously be connected to the soft-AP can be set `from 1 to 8 <https://bbs.espressif.com/viewtopic.php?f=46&t=481&p=1832&hilit=max_connection#p1832>`__, but defaults to 4.
 
 .. figure:: pictures/esp8266-soft-access-point.png
    :alt: ESP8266 operating in the Soft Access Point mode

doc/esp8266wifi/readme.rst

@@ -44,15 +44,24 @@ To set up password protected network, or to configure additional network paramet
 
 .. code:: cpp
 
-    WiFi.softAP(ssid, password, channel, hidden)
+    WiFi.softAP(ssid, password, channel, hidden, max_connection)
 
-The first parameter of this function is required, remaining three are optional.
+The first parameter of this function is required, remaining four are optional.
 
-Meaning of all parameters is as follows: - ``ssid`` - character string containing network SSID (max. 63 characters) \* ``password`` - optional character string with a password. For WPA2-PSK network it should be at least 8 character long. If not specified, the access point will be open for anybody to connect. \* ``channel`` - optional parameter to set Wi-Fi channel, from 1 to 13. Default channel = 1. \* ``hidden`` - optional parameter, if set to ``true`` will hide SSID
+Meaning of all parameters is as follows:
+
+- ``ssid`` - character string containing network SSID (max. 63 characters) 
+- ``password`` - optional character string with a password. For WPA2-PSK network it should be at least 8 character long. If not specified, the access point will be open for anybody to connect. 
+- ``channel`` - optional parameter to set Wi-Fi channel, from 1 to 13. Default channel = 1. 
+- ``hidden`` - optional parameter, if set to ``true`` will hide SSID. 
+- ``max_connection`` - optional parameter to set max simultaneous connected stations, `from 1 to 8 <https://bbs.espressif.com/viewtopic.php?f=46&t=481&p=1832&hilit=max_connection#p1832>`__. Defaults to 4. Once the max number has been reached, any other station that wants to connect will be forced to wait until an already connected station disconnects.
 
 Function will return ``true`` or ``false`` depending on result of setting the soft-AP.
 
-Notes: \* The network established by softAP will have default IP address of 192.168.4.1. This address may be changed using ``softAPConfig`` (see below). \* Even though ESP8266 can operate in soft-AP + station mode, it actually has only one hardware channel. Therefore in soft-AP + station mode, the soft-AP channel will default to the number used by station. For more information how this may affect operation of stations connected to ESP8266's soft-AP, please check `this FAQ entry <http://bbs.espressif.com/viewtopic.php?f=10&t=324>`__ on Espressif forum.
+Notes:
+
+- The network established by softAP will have default IP address of 192.168.4.1. This address may be changed using ``softAPConfig`` (see below). 
+- Even though ESP8266 can operate in soft-AP + station mode, it actually has only one hardware channel. Therefore in soft-AP + station mode, the soft-AP channel will default to the number used by station. For more information how this may affect operation of stations connected to ESP8266's soft-AP, please check `this FAQ entry <http://bbs.espressif.com/viewtopic.php?f=10&t=324>`__ on Espressif forum.
 
 softAPConfig
 ^^^^^^^^^^^^
@@ -63,10 +72,11 @@ Configure the soft access point's network interface.
 
     softAPConfig (local_ip, gateway, subnet) 
 
-| All parameters are the type of ``IPAddress`` and defined as follows:
-  \* ``local_ip`` - IP address of the soft access point \* ``gateway`` -
-  gateway IP address
-| \* ``subnet`` - subnet mask
+All parameters are the type of ``IPAddress`` and defined as follows:
+
+- ``local_ip`` - IP address of the soft access point 
+- ``gateway`` - gateway IP address
+- ``subnet`` - subnet mask
 
 Function will return ``true`` or ``false`` depending on result of changing the configuration.
 
@@ -131,7 +141,7 @@ Get the count of the stations that are connected to the soft-AP interface.
 
     Stations connected to soft-AP = 2
 
-Note: the maximum number of stations that may be connected to ESP8266 soft-AP is five.
+Note: the maximum number of stations that may be connected to ESP8266 soft-AP is 4 by default. This can be changed from 1 to 8 via the ``max_connection`` argument of the softAP method.
 
 softAPdisconnect
 ^^^^^^^^^^^^^^^^

doc/esp8266wifi/soft-access-point-class.rst

@@ -291,9 +291,12 @@ Memory, memory, memory
    rely on exceptions for error handling, which is not available for the ESP, and in any
    case there is no access to the underlying code.
 
-   Instrumenting the code with the OOM debug option and calls to ``ESP.getFreeHeap()`` will
-   help the process of finding leaks. Now is time to re-read about the
-   `exception decoder <#exception-decoder>`__.
+   Instrumenting the code with the OOM debug option and calls to
+   ``ESP.getFreeHeap()`` / ``ESP.getHeapFragmentation()`` /
+   ``ESP.getMaxFreeBlockSize()`` will help the process of finding memory issues.
+
+   Now is time to re-read about the `exception decoder
+   <#exception-decoder>`__.
 
 
 *Some techniques for reducing memory usage*

doc/faq/a02-my-esp-crashes.rst

@@ -34,7 +34,9 @@ It needs to be run from the root directory,
     C:\...> python tools\boards.txt.py
 
 Running without parameters will show the command line help.  They are
-generally self-explanatory.
+generally self-explanatory.  Running with the parameters will show no output but will generate a new boards.txt file (and a backup boards.txt.orig).
+
+The core root directory varies depending on your development environment.  In Windows, core root is found under your home directory; for Arduino it is in AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.4.2\ for PlatformIO it is in .platformio\packages\framework-arduinoespressif8266.
 
 
 What can I do with it ?

doc/faq/a05-board-generator.rst

@@ -65,6 +65,8 @@ required to enable it:
 
 `Read more <a05-board-generator.rst>`__.
 
+For platformIO (and maybe other build environments), you will also need to add the build flag: -D NO_EXTRA_4K_HEAP
+
 This manual selection is not needed starting from 2.5.0 (and in git
 version).  WPS is always available, and not using it will give an extra
 ~4.5KB compared to releases until 2.4.1 included.