[BREAKING] Disable WiFi at boot by default (#7902)

* Disable WiFi at boot by default

* +define WIFI_IS_OFF_AT_BOOT

* remove now useless example

* mv enableWiFiAtBootTime() to core_esp8266_features.h

* sync with master

* per @earlephilhower review: a file was missing

* doc

* WiFi persistence is now false by default

* fix doc

* ditto

* doc: remove sphinx warnings (fix links and formatting)

* fix link name

* fix doc

* legacy: restore persistence

* undeprecate preinit()

* move force modem up to when mode has changed (per @mcspr review)

* do not wake up from sleep when mode if OFF

* fix doc per review

doc/esp8266wifi/generic-class.rst

@@ -42,6 +42,33 @@ persistent
 
     WiFi.persistent(persistent)
 
+Starting from version 3 of this core, **persistence is disabled by default
+and WiFi does not start automatically at boot** (see PR `#7902 <https://github.com/esp8266/Arduino/pull/7902>`__).
+
+Previously, SDK was automatically starting WiFi at boot.  This was probably
+intended for the Espressif AT FW which is interactive and preserves WiFi
+state accross reboots.  This behavior is generally irrelevant with the
+Arduino API because sketches start with ``WiFi.begin()`` or
+``WiFi.softAP()``.
+
+This change is harmless with standard sketches: Calls to ``WiFi.mode()`` do
+enable radio as usual.  It also smooths current spikes at boot and decreases
+DHCP stress.
+
+Legacy behavior can be restored by calling ``enableWiFiAtBootTime()`` from
+anywhere in the code (it is a weak void function intended to play with the
+linker).
+
+.. code:: cpp
+
+    void setup () {
+    #ifdef WIFI_IS_OFF_AT_BOOT
+        enableWiFiAtBootTime(); // can be called from anywhere with the same effect
+    #endif
+        ....
+    }
+
+When legacy behavior is restored thanks to this call,
 ESP8266 is able to reconnect to the last used WiFi 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>`__).

doc/esp8266wifi/readme.rst

@@ -164,6 +164,7 @@ WiFi Multi
 Example:
 
 .. code:: cpp
+
     #include <ESP8266WiFiMulti.h>
 
     ESP8266WiFiMulti wifiMulti;

doc/faq/a01-espcomm_sync-failed.rst

@@ -41,9 +41,8 @@ following three things right: 1. Module is provided with enough power,
 2. GPIO0, GPIO15 and CH\_PD are connected using pull up / pull down
 resistors, 3. Module is put into boot loader mode.
 
-For specific details please refer to section on `Generic ESP8266
-modules <../boards.rst#generic-esp8266-modules>`__. Example modules
-without USB to serial converter on board are shown below.
+For specific details please refer to section on `Generic ESP8266 module <../boards.rst#generic-esp8266-module>`__.
+Example modules without USB to serial converter on board are shown below.
 
 .. figure:: pictures/a01-example-boards-without-usb.png
    :alt: Example ESP8266 modules without USB to serial converter

doc/faq/a04-board-generic-is-unknown.rst

@@ -48,7 +48,7 @@ follows:
     Error compiling for board Generic ESP8266 Module.
 
 Below is an example messages for
-`WeMos <../boards.rst#wemos-d1-r2-mini>`__:
+`WeMos <../boards.rst#lolin-wemos-d1-r2-mini>`__:
 
 ::
 

doc/faq/readme.rst

@@ -177,3 +177,12 @@ will need to implement an additional (short) deep sleep using
 ``WAKE_RF_DEFAULT``.
 
 Ref.  `#3072 <https://github.com/esp8266/Arduino/issues/3072>`__
+
+My WiFi was previously automatically connected right after booting, but isn't anymore
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This was WiFi persistence.  Starting from version 3 of this core, WiFi is
+indeed off at boot and is powered on only when starting to be used with the
+regular API.
+
+Read more at `former WiFi persistent mode <../esp8266wifi/generic-class.rst#persistent>`__.

doc/filesystem.rst

@@ -474,8 +474,8 @@ Performs the same operation as ``info`` but allows for reporting greater than
 4GB for filesystem size/used/etc.  Should be used with the SD and SDFS
 filesystems since most SD cards today are greater than 4GB in size.
 
-setTimeCallback(time_t (*cb)(void))
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+setTimeCallback(time_t (\*cb)(void))
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code:: cpp
 
@@ -574,8 +574,8 @@ rewind
 
 Resets the internal pointer to the start of the directory.
 
-setTimeCallback(time_t (*cb)(void))
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+setTimeCallback(time_t (\*cb)(void))
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Sets the time callback for any files accessed from this Dir object via openNextFile.
 Note that the SD and SDFS filesystems only support a filesystem-wide callback and
@@ -693,7 +693,7 @@ Close the file. No other operations should be performed on *File* object
 after ``close`` function was called.
 
 openNextFile  (compatibiity method, not recommended for new code)
-~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code:: cpp
 
@@ -705,7 +705,7 @@ Opens the next file in the directory pointed to by the File.  Only valid
 when ``File.isDirectory() == true``.
 
 rewindDirectory  (compatibiity method, not recommended for new code)
-~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code:: cpp
 
@@ -718,8 +718,8 @@ rewindDirectory  (compatibiity method, not recommended for new code)
 Resets the ``openNextFile`` pointer to the top of the directory.  Only
 valid when ``File.isDirectory() == true``.
 
-setTimeCallback(time_t (*cb)(void))
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+setTimeCallback(time_t (\*cb)(void))
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Sets the time callback for this specific file.  Note that the SD and
 SDFS filesystems only support a filesystem-wide callback and calls to

doc/libraries.rst

@@ -87,7 +87,7 @@ Some ESP-specific APIs related to deep sleep, RTC and flash memories are availab
 
 ``ESP.getHeapFragmentation()`` returns the fragmentation metric (0% is clean, more than ~50% is not harmless)
 
-``ESP.getMaxFreeBlockSize()`` returns the largest contiguous free RAM block in the heap, useful for checking heap fragmentation.  **NOTE:** Maximum ``malloc()``able block will be smaller due to memory manager overheads.
+``ESP.getMaxFreeBlockSize()`` returns the largest contiguous free RAM block in the heap, useful for checking heap fragmentation.  **NOTE:** Maximum ``malloc()`` -able block will be smaller due to memory manager overheads.
 
 ``ESP.getChipId()`` returns the ESP8266 chip ID as a 32-bit integer.
 

doc/mmu.rst

@@ -233,5 +233,3 @@ address range of IRAM or DRAM.
     uint8_t mmu_set_uint8(void *p8, const uint8_t val);
     uint16_t mmu_set_uint16(uint16_t *p16, const uint16_t val);
     int16_t mmu_set_int16(int16_t *p16, const int16_t val);
-
-::

doc/ota_updates/readme.rst

@@ -161,7 +161,7 @@ If signing is desired, sign the gzip compressed file *after* compression.
 Updating apps in the field to support compression
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you have applications deployed in the field and wish to update them to support compressed OTA uploads, you will need to first recompile the application, then _upload the uncompressed `.bin` file once_.  Attempting to upload a `gzip` compressed binary to a legacy app will result in the Updater rejecting the upload as it does not understand the `gzip` format.  After this initial upload, which will include the new bootloader and `Updater` class with compression support, compressed updates can then be used.
+If you have applications deployed in the field and wish to update them to support compressed OTA uploads, you will need to first recompile the application, then _upload the uncompressed `.bin` file once.  Attempting to upload a `gzip` compressed binary to a legacy app will result in the Updater rejecting the upload as it does not understand the `gzip` format.  After this initial upload, which will include the new bootloader and `Updater` class with compression support, compressed updates can then be used.
 
 
 Safety