Merge branch 'master' of https://github.com/esp8266/Arduino

Author: earlephilhower

README.md

@@ -51,19 +51,19 @@ python get.py
 
 ### Using PlatformIO
 
-[PlatformIO](http://platformio.org) is an open source ecosystem for IoT
+[PlatformIO](http://platformio.org?utm_source=github&utm_medium=arduino-esp8266) is an open source ecosystem for IoT
 development with cross platform build system, library manager and full support
 for Espressif (ESP8266) development. It works on the popular host OS: macOS, Windows,
 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 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
-- [Project Examples](http://docs.platformio.org/page/platforms/espressif.html#examples)
+- [What is PlatformIO?](http://docs.platformio.org/en/latest/what-is-platformio.html?utm_source=github&utm_medium=arduino-esp8266)
+- [PlatformIO IDE](http://platformio.org/platformio-ide?utm_source=github&utm_medium=arduino-esp8266)
+- [PlatformIO Core](http://docs.platformio.org/en/latest/core.html?utm_source=github&utm_medium=arduino-esp8266) (command line tool)
+- [Advanced usage](http://docs.platformio.org/en/latest/platforms/espressif8266.html?utm_source=github&utm_medium=arduino-esp8266) -
+  custom settings, uploading to SPIFFS, Over-the-Air (OTA), staging version
+- [Integration with Cloud and Standalone IDEs](http://docs.platformio.org/en/latest/ide.html?utm_source=github&utm_medium=arduino-esp8266) -
+  Cloud9, Codeanywhere, Eclipse Che (Codenvy), Atom, CLion, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, VIM, Visual Studio, and VSCode
+- [Project Examples](http://docs.platformio.org/en/latest/platforms/espressif8266.html?utm_source=github&utm_medium=arduino-esp8266#examples)
 
 ### Building with make
 

boards.txt

@@ -107,13 +107,22 @@ void EspClass::wdtFeed(void)
 
 extern "C" void esp_yield();
 
-void EspClass::deepSleep(uint32_t time_us, WakeMode mode)
+void EspClass::deepSleep(uint64_t time_us, WakeMode mode)
 {
     system_deep_sleep_set_option(static_cast<int>(mode));
     system_deep_sleep(time_us);
     esp_yield();
 }
 
+//this calculation was taken verbatim from the SDK api reference for SDK 2.1.0.
+//Note: system_rtc_clock_cali_proc() returns a uint32_t, even though system_deep_sleep() takes a uint64_t.
+uint64_t EspClass::deepSleepMax()
+{
+  //cali*(2^31-1)/(2^12)
+  return (uint64_t)system_rtc_clock_cali_proc()*(0x80000000-1)/(0x1000);
+
+}
+
 bool EspClass::rtcUserMemoryRead(uint32_t offset, uint32_t *data, size_t size)
 {
     if (size + offset > 512) {

cores/esp8266/Esp.cpp

@@ -92,7 +92,8 @@ class EspClass {
         void wdtDisable();
         void wdtFeed();
 
-        void deepSleep(uint32_t time_us, RFMode mode = RF_DEFAULT);
+        void deepSleep(uint64_t time_us, RFMode mode = RF_DEFAULT);
+        uint64_t deepSleepMax();
 
         bool rtcUserMemoryRead(uint32_t offset, uint32_t *data, size_t size);
         bool rtcUserMemoryWrite(uint32_t offset, uint32_t *data, size_t size);

cores/esp8266/Esp.h

@@ -212,15 +212,43 @@ static uint32_t _i2s_sample_rate;
 void ICACHE_FLASH_ATTR i2s_set_rate(uint32_t rate){ //Rate in HZ
   if(rate == _i2s_sample_rate) return;
   _i2s_sample_rate = rate;
-  uint32_t i2s_clock_div = (I2SBASEFREQ/(_i2s_sample_rate*32)) & I2SCDM;
-  uint8_t i2s_bck_div = (I2SBASEFREQ/(_i2s_sample_rate*i2s_clock_div*2)) & I2SBDM;
+
+  uint32_t scaled_base_freq = I2SBASEFREQ/32;
+  float delta_best = scaled_base_freq;
+
+  uint8_t sbd_div_best=1;
+  uint8_t scd_div_best=1;
+  for (uint8_t i=1; i<64; i++){
+    for (uint8_t j=i; j<64; j++){
+      float new_delta = fabs(((float)scaled_base_freq/i/j) - rate);
+      if (new_delta < delta_best){
+      	delta_best = new_delta;
+        sbd_div_best = i;
+        scd_div_best = j;
+      }
+    }
+  }
+
   //os_printf("Rate %u Div %u Bck %u Frq %u\n", _i2s_sample_rate, i2s_clock_div, i2s_bck_div, I2SBASEFREQ/(i2s_clock_div*i2s_bck_div*2));
 
   //!trans master, !bits mod, rece slave mod, rece msb shift, right first, msb right
   I2SC &= ~(I2STSM | (I2SBMM << I2SBM) | (I2SBDM << I2SBD) | (I2SCDM << I2SCD));
-  I2SC |= I2SRF | I2SMR | I2SRSM | I2SRMS | ((i2s_bck_div-1) << I2SBD) | ((i2s_clock_div-1) << I2SCD);
+  I2SC |= I2SRF | I2SMR | I2SRSM | I2SRMS | ((sbd_div_best) << I2SBD) | ((scd_div_best) << I2SCD);
+}
+
+void ICACHE_FLASH_ATTR i2s_set_dividers(uint8_t div1, uint8_t div2){
+  div1 &= I2SBDM;
+  div2 &= I2SCDM;
+
+  I2SC &= ~(I2STSM | (I2SBMM << I2SBM) | (I2SBDM << I2SBD) | (I2SCDM << I2SCD));
+  I2SC |= I2SRF | I2SMR | I2SRSM | I2SRMS | (div1 << I2SBD) | (div2 << I2SCD);
 }
 
+float ICACHE_FLASH_ATTR i2s_get_real_rate(){
+  return (float)I2SBASEFREQ/32/((I2SC>>I2SBD) & I2SBDM)/((I2SC >> I2SCD) & I2SCDM);
+}
+
+
 void ICACHE_FLASH_ATTR i2s_begin(){
   _i2s_sample_rate = 0;
   i2s_slc_begin();

cores/esp8266/core_esp8266_i2s.c

@@ -754,7 +754,7 @@ extern uint8_t esp8266_gpioToFn[16];
 #define i2c_bbpll_en_audio_clock_out_msb  7
 #define i2c_bbpll_en_audio_clock_out_lsb  7
 #define I2S_CLK_ENABLE()                  i2c_writeReg_Mask_def(i2c_bbpll, i2c_bbpll_en_audio_clock_out, 1)
-#define I2SBASEFREQ                       (12000000L)
+#define I2SBASEFREQ                       (160000000L)
 
 #define I2STXF  ESP8266_REG(0xe00) //I2STXFIFO (32bit)
 #define I2SRXF  ESP8266_REG(0xe04) //I2SRXFIFO (32bit)

cores/esp8266/esp8266_peri.h

@@ -43,6 +43,8 @@ extern "C" {
 void i2s_begin();
 void i2s_end();
 void i2s_set_rate(uint32_t rate);//Sample Rate in Hz (ex 44100, 48000)
+void i2s_set_dividers(uint8_t div1, uint8_t div2);//Direct control over output rate
+float i2s_get_real_rate();//The actual Sample Rate on output
 bool i2s_write_sample(uint32_t sample);//32bit sample with channels being upper and lower 16 bits (blocking when DMA is full)
 bool i2s_write_sample_nb(uint32_t sample);//same as above but does not block when DMA is full and returns false instead
 bool i2s_write_lr(int16_t left, int16_t right);//combines both channels and calls i2s_write_sample with the result
@@ -54,4 +56,4 @@ int16_t i2s_available();// returns the number of samples than can be written bef
 }
 #endif
 
-#endif
+#endif

cores/esp8266/i2s.h

@@ -329,7 +329,7 @@ class SPIFFSFileImpl : public FileImpl
         if (mode == SeekEnd) {
             offset = -offset;
         }
-        auto rc = SPIFFS_lseek(_fs->getFs(), _fd, pos, (int) mode);
+        auto rc = SPIFFS_lseek(_fs->getFs(), _fd, offset, (int) mode);
         if (rc < 0) {
             DEBUGV("SPIFFS_lseek rc=%d\r\n", rc);
             return false;

cores/esp8266/spiffs_api.h

@@ -1685,7 +1685,9 @@ void *umm_calloc( size_t num, size_t item_size ) {
 
   size += POISON_SIZE(size);
   ret = _umm_malloc(size);
-  memset(ret, 0x00, size);
+  if (ret) {
+    memset(ret, 0x00, size);
+  }
 
   ret = GET_POISONED(ret, size);
 

cores/esp8266/umm_malloc/umm_malloc.c

@@ -59,4 +59,4 @@ Other Function Calls
 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.
+:arrow\_right: <client-examples.rst>`__ dedicated specifically to the Client Class.

doc/esp8266wifi/client-class.rst

@@ -28,7 +28,7 @@ This time we are going to concentrate just on retrieving a web page contents sen
 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.
+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.rst#quick-start>`__. Please refer to it for details.
 
 Select a Server
 ~~~~~~~~~~~~~~~
@@ -257,4 +257,4 @@ For more client examples please check
 
 - `WiFiClient.ino <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiClient/WiFiClient.ino>`__ - this sketch sends data via HTTP GET requests to data.sparkfun.com service.
 
-For the list of functions provided to manage clients, please refer to the `Client Class :arrow\_right: <client-class.md>`__ documentation.
+For the list of functions provided to manage clients, please refer to the `Client Class :arrow\_right: <client-class.rst>`__ documentation.

doc/esp8266wifi/client-examples.rst

@@ -98,4 +98,4 @@ Other Function Calls
 
 Documentation for the above functions is not yet prepared.
 
-For code samples please refer to separate section with `examples <client-secure-examples.md>`__ dedicated specifically to the Client Secure Class.
+For code samples please refer to separate section with `examples <client-secure-examples.rst>`__ dedicated specifically to the Client Secure Class.

doc/esp8266wifi/client-secure-class.rst

@@ -3,7 +3,7 @@
 Client Secure
 -------------
 
-The client secure is a `client <#client>`__ but secure. Application example below will be easier to follow if you check similar and simpler `example <client-examples.md>`__ for the "ordinary" client. That being said we will concentrate on discussing the code that is specific to the client secure.
+The client secure is a `client <#client>`__ but secure. Application example below will be easier to follow if you check similar and simpler `example <client-examples.rst>`__ for the "ordinary" client. That being said we will concentrate on discussing the code that is specific to the client secure.
 
 Table of Contents
 -----------------
@@ -71,7 +71,7 @@ We can obtain the ``fingerprint`` for specific ``host`` using a web browser. For
 
    alt text
 
-Remaining steps look almost identical as for the `non-secure client example <client-examples.md>`__.
+Remaining steps look almost identical as for the `non-secure client example <client-examples.rst>`__.
 
 Connect to the Server
 ~~~~~~~~~~~~~~~~~~~~~
@@ -106,7 +106,7 @@ If this check fails, it is up to you to decide if to proceed further or abort co
 GET Response from the Server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In the next steps we should execute GET command. This is done is similar way as discussed in `non-secure client example <client-examples.md>`__.
+In the next steps we should execute GET command. This is done is similar way as discussed in `non-secure client example <client-examples.rst>`__.
 
 .. code:: cpp
 

doc/esp8266wifi/client-secure-examples.rst

@@ -27,7 +27,7 @@ WiFiEventHandler
     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.md>`__ dedicated specifically to the Generic Class..
+To see a sample application with ``WiFiEventHandler``, please check separate section with `examples :arrow\_right: <generic-examples.rst>`__ dedicated specifically to the Generic Class..
 
 persistent
 ~~~~~~~~~~

doc/esp8266wifi/generic-class.rst

@@ -3,7 +3,7 @@
 Generic
 -------
 
-In the first `example <readme.md#quick-start>`__ of the ESP8266WiFi library documentation we have discussed how to check when module connects to the Wi-Fi network. We were waiting until connection is established. If network is not available, the module could wait like that for ever doing nothing else. Another `example <scan-examples.md#async-scan>`__ on the Wi-Fi asynchronous scan mode demonstrated how to wait for scan result and do in parallel something else - blink a LED not disturbing the blink pattern. Let's apply similar functionality when connecting the module to an access point.
+In the first `example <readme.rst#quick-start>`__ of the ESP8266WiFi library documentation we have discussed how to check when module connects to the Wi-Fi network. We were waiting until connection is established. If network is not available, the module could wait like that for ever doing nothing else. Another `example <scan-examples.rst#async-scan>`__ on the Wi-Fi asynchronous scan mode demonstrated how to wait for scan result and do in parallel something else - blink a LED not disturbing the blink pattern. Let's apply similar functionality when connecting the module to an access point.
 
 Table of Contents
 -----------------
@@ -29,7 +29,7 @@ We would like to write a code that will inform us that connection to Wi-Fi netwo
 Event Driven Methods
 ~~~~~~~~~~~~~~~~~~~~
 
-The list of all such methods is provided in `Generic Class <generic-class.md>`__ documentation.
+The list of all such methods is provided in `Generic Class <generic-class.rst>`__ documentation.
 
 We would like to use two of them: \* ``onStationModeGotIP`` called when station is assigned IP address. This assignment may be done by DHCP client or by executing ``WiFi.config(...)``. \* ``onStationModeDisconnected`` called when station is disconnected from Wi-Fi network. The reason of disconnection does not matter. Event will be triggered both if disconnection is done from the code by executing ``WiFi.disconnect()``, because the Wi-Fi signal is weak, or because the access point is switched off.
 
@@ -122,4 +122,4 @@ Conclusion
 
 Check out events from generic class. They will help you to write more compact code. Use them to practice splitting your code into separate tasks that are executed asynchronously.
 
-For review of functions included in generic class, please refer to the `Generic Class <generic-class.md>`__ documentation.
+For review of functions included in generic class, please refer to the `Generic Class <generic-class.rst>`__ documentation.

doc/esp8266wifi/generic-examples.rst

@@ -302,7 +302,7 @@ The same sketch without ``Serial.setDebugOutput(true)`` will print out only the
 Enable Debugging in IDE
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Arduino IDE provides convenient method to `enable debugging <https://github.com/esp8266/Arduino/blob/master/doc/Troubleshooting/debugging.md>`__ for specific libraries.
+Arduino IDE provides convenient method to `enable debugging <https://github.com/esp8266/Arduino/blob/master/doc/Troubleshooting/debugging.rst>`__ for specific libraries.
 
 What's Inside?
 --------------

doc/esp8266wifi/readme.rst

@@ -235,4 +235,4 @@ The ``networkItem`` is a zero based index of network discovered during scan. All
     5: , Ch:11 (-77dBm)  hidden
     6: UPC Wi-Free, Ch:11 (-79dBm)
 
-For code samples please refer to separate section with `examples <scan-examples.md>`__ dedicated specifically to the Scan Class.
+For code samples please refer to separate section with `examples <scan-examples.rst>`__ dedicated specifically to the Scan Class.

doc/esp8266wifi/scan-class.rst

@@ -240,4 +240,4 @@ Conclusion
 
 The scan class API provides comprehensive set of methods to do scanning in both synchronous as well as in asynchronous mode. Therefore we can easy implement code that is doing scanning in background without disturbing other processes running on ESP8266 module.
 
-For the list of functions provided to manage scan mode please refer to the `Scan Class <scan-class.md>`__ documentation.
+For the list of functions provided to manage scan mode please refer to the `Scan Class <scan-class.rst>`__ documentation.

doc/esp8266wifi/scan-examples.rst

@@ -3,7 +3,7 @@
 Station
 -------
 
-Example of connecting to an access point has been shown in chapter `Quick Start <readme.md#quick-start>`__. In case connection is lost, ESP8266 will automatically reconnect to the last used access point, once it is again available.
+Example of connecting to an access point has been shown in chapter `Quick Start <readme.rst#quick-start>`__. In case connection is lost, ESP8266 will automatically reconnect to the last used access point, once it is again available.
 
 Can we provide more robust connection to Wi-Fi than that?
 
@@ -19,7 +19,7 @@ Table of Contents
 Introduction
 ~~~~~~~~~~~~
 
-Following the example in\ `Quick Start <readme.md#quick-start>`__, we would like to go one step further and made ESP connect to next available access point if current connection is lost. This functionality is provided with 'ESP8266WiFiMulti' class and demonstrated in sketch below.
+Following the example in\ `Quick Start <readme.rst#quick-start>`__, we would like to go one step further and made ESP connect to next available access point if current connection is lost. This functionality is provided with 'ESP8266WiFiMulti' class and demonstrated in sketch below.
 
 .. code:: cpp
 
@@ -100,7 +100,7 @@ Function ``monitorWiFi()`` is in place to show when connection is lost by displa
 Can we Make it Simpler?
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Please note that you may simplify this sketch by removing function ``monitorWiFi()`` and putting inside ``loop()`` only ``wifiMulti.run()``. ESP will still reconnect between configured access points if required. Now you won't be able to see it on serial monitor unless you add ``Serial.setDebugOutput(true)`` as described in point `Enable Wi-Fi Diagnostic <readme.md#enable-wi-fi-diagnostic>`__.
+Please note that you may simplify this sketch by removing function ``monitorWiFi()`` and putting inside ``loop()`` only ``wifiMulti.run()``. ESP will still reconnect between configured access points if required. Now you won't be able to see it on serial monitor unless you add ``Serial.setDebugOutput(true)`` as described in point `Enable Wi-Fi Diagnostic <readme.rst#enable-wi-fi-diagnostic>`__.
 
 Updated sketch for such scenario will look as follows:
 

doc/esp8266wifi/station-examples.rst

@@ -41,7 +41,7 @@ Once we have libraries in place we need to create a ``WiFiUDP`` object. Then we
 Wi-Fi Connection
 ~~~~~~~~~~~~~~~~
 
-At the beginning of ``setup()`` let's implement typical code to connect to an access point. This has been discussed in `Quick Start <readme.md#quick-start>`__. Please refer to it if required.
+At the beginning of ``setup()`` let's implement typical code to connect to an access point. This has been discussed in `Quick Start <readme.rst#quick-start>`__. Please refer to it if required.
 
 UDP Setup
 ~~~~~~~~~

doc/esp8266wifi/udp-examples.rst

@@ -42,7 +42,7 @@ following three things right: 1. Module is provided with enough power,
 resistors, 3. Module is put into boot loader mode.
 
 For specific details please refer to section on `Generic ESP8266
-modules <../boards.md#generic-esp8266-modules>`__. Example modules
+modules <../boards.rst#generic-esp8266-modules>`__. Example modules
 without USB to serial converter on board are shown below.
 
 .. figure:: pictures/a01-example-boards-without-usb.png
@@ -128,7 +128,7 @@ follows:
 ``ets Jan  8 2013,rst cause:2, boot mode:(1,7)``
 
 If you see similar message but different values then decode them using
-`Boot Messages and Modes <../boards.md#boot-messages-and-modes>`__. The
+`Boot Messages and Modes <../boards.rst#boot-messages-and-modes>`__. The
 key information is contained in first digit / three right-most bits of
 the boot mode message as shown below.
 
@@ -140,9 +140,9 @@ the boot mode message as shown below.
 For instance message ``boot mode (3,3)`` indicates that pins GPIO2 and
 GPIO0 are set HIGH and GPIO15 is set LOW. This is configuration for
 `normal
-operation <../boards.md#minimal-hardware-setup-for-running-only>`__ of
+operation <../boards.rst#minimal-hardware-setup-for-running-only>`__ of
 module (to execute application from flash), not for `boot
-loading <../boards.md#minimal-hardware-setup-for-bootloading-only>`__
+loading <../boards.rst#minimal-hardware-setup-for-bootloading-only>`__
 (flash programming).
 
     Note: Without having this step right you will not be able to upload
@@ -391,4 +391,4 @@ Test stand used for checking of ck reset method is shown above.
 
 No any ESP module has been harmed during preparation of this FAQ item.
 
-`FAQ list :back: <readme.md>`__
+`FAQ list :back: <readme.rst>`__