--- /dev/null
+# Documentation Source Folder\r
+\r
+This folder contains source files of [ESP-IDF documentation](http://esp-idf.readthedocs.io/).\r
+\r
+The sources do not render well in GitHub and some information is not visible at all.\r
+\r
+Use actual documentation generated instantly on each commit:\r
+\r
+* Main server: http://esp-idf.readthedocs.io/ or http://esp-idf.rtfd.io/\r
+* Mirror: https://dl.espressif.com/doc/esp-idf/latest/\r
+\r
`Instructions`_
+.. _Instructions: ../template.html
+
Application Example
-------------------
-Check `/examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf/>`_ repository, that contains the following example:
+Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf/>`_ repository, that contains the following example:
-`bluetooth/ble_adv <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/ble_adv/main/app_bt.c>`_
+`ble_adv <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/ble_adv>`_
This is a BLE advertising demo with virtual HCI interface. Send Reset/ADV_PARAM/ADV_DATA/ADV_ENABLE HCI command for BLE advertising.
-`Instructions`_
-
-.. _Instructions: ../template.html
-
API Reference
-------------
Application Example
-------------------
-Check `/examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf/>`_ repository, that contains the following example:
+Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that contains the following example:
-`bluetooth/blufi <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/blufi/main/>`_
+`blufi <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/blufi>`_
-This is a BLUFI demo. This demo can set ESP32's wifi to softap/station/softap&station mode and config wifi connections.
+ This is a BLUFI demo. This demo can set ESP32's wifi to softap/station/softap&station mode and config wifi connections.
API Reference
GAP API
-========
+=======
Overview
--------
`Instructions`_
+.. _Instructions: ../template.html
+
Application Example
-------------------
-Check `/examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf/>`_ repository, that contains the following example:
-
-`14_gatts_demo <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_server/main/gatts_demo.c>`_
-`15_gattc_demo <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_client/main/gattc_demo.c>`_
-
-The two demos use different gap api, such like advertising, scan, set device name and others.
+Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that contains the following examples:
-`Instructions`_
-
-.. _Instructions: ../template.html
+`gatt_server <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_server>`_, `gatt_client <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_client>`_
+ The two demos use different gap api, such like advertising, scan, set device name and others.
API Reference
-------------
Header Files
^^^^^^^^^^^^
- * `bt/bluedroid/api/include/esp_gap_ble_api.h <https://github.com/espressif/esp-idf/blob/master/components/bt/bluedroid/api/include/esp_gap_ble.h>`_
+ * `bt/bluedroid/api/include/esp_gap_ble_api.h <https://github.com/espressif/esp-idf/blob/master/components/bt/bluedroid/api/include/esp_gap_ble_api.h>`_
Macros
`Instructions`_
+.. _Instructions: ../template.html
+
Application Example
-------------------
-Check `/examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf/>`_ repository, that contains the following example:
-
-`15_gattc_demo <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_client/main/gattc_demo.c>`_
+Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that contains the following example:
-This is a gatt client demo. This demo can scan devices, connect to the gatt server and discover the service.
+`gatt_client <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_client>`_
-`Instructions`_
-
-.. _Instructions: ../template.html
+ This is a gatt client demo. This demo can scan devices, connect to the gatt server and discover the service.
API Reference
`Instructions`_
+.. _Instructions: ../template.html
+
Application Example
-------------------
-Check `/examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf/>`_ repository, that contains the following example:
-
-`14_gatts_demo <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_server/main/gatts_demo.c>`_
-
-This is a gatt server demo. Use gatt api to create a gatt server with send advertising. This gatt server can be connected and the service can be discovery.
+Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that contains the following example:
-`Instructions`_
-
-.. _Instructions: ../template.html
+`gatt_server <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_server>`_
+ This is a gatt server demo. Use gatt api to create a gatt server with send advertising. This gatt server can be connected and the service can be discovery.
API Reference
-------------
Application Example
-------------------
-Sigma-delta Modulation example: `examples/14_sigmadelta <https://github.com/espressif/esp-idf/tree/master/examples/14_sigmadelta>`_.
+Sigma-delta Modulation example: `examples/peripherals/sigmadelta <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/sigmadelta>`_.
API Reference
-------------
not touch the ``tx_buffer`` or ``rx_buffer`` members, because they use the same memory locations
as ``tx_data`` and ``rx_data``.
+Application Example
+-------------------
+
+Display graphics on the ILI9341-based 320x240 LCD: `examples/peripherals/spi_master <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/spi_master>`_.
+
API Reference
-------------
Header Files
^^^^^^^^^^^^
- * `drivers/include/drivers/spi_master.h <https://github.com/espressif/esp-idf/blob/master/components/drivers/include/drivers/spi_master.h>`_
+ * `driver/include/driver/spi_master.h <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/spi_master.h>`_
Macros
^^^^^^
`Instructions`_
+.. _Instructions: ../template.html
+
Application Example
-------------------
-`Instructions`_
+Configure uart settings and install uart driver to read/write using UART0 and UART1 interfaces: `examples/peripherals/uart <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/uart>`_.
API Reference
-------------
-`Instructions`_
-
-.. _Instructions: ../template.html
-
Header Files
^^^^^^^^^^^^
Application Example
-------------------
-mDNS server/scanner example: `examples/protocols/mdsn <https://github.com/espressif/esp-idf/tree/master/examples/protocols/mdsn>`_.
+mDNS server/scanner example: `examples/protocols/mdns <https://github.com/espressif/esp-idf/tree/master/examples/protocols/mdns>`_.
API Reference
-------------
Application Example
-------------------
-Two examples are provided in ESP-IDF examples directory:
+Two examples are provided in ESP-IDF `examples/storage <https://github.com/espressif/esp-idf/tree/master/examples/storage>`_ directory:
-`storage/nvs_rw_value <https://github.com/espressif/esp-idf/blob/master/examples/storage/nvs_rw_value/main/nvs_rw_value.c>`_
+`nvs_rw_value <https://github.com/espressif/esp-idf/blob/master/examples/storage/nvs_rw_value>`_
Demonstrates how to read and write a single integer value using NVS.
Example also shows how to check if read / write operation was successful, or certain value is not initialized in NVS. Diagnostic is provided in plain text to help track program flow and capture any issues on the way.
-`storage/nvs_rw_blob <https://github.com/espressif/esp-idf/blob/master/examples/storage/nvs_rw_blob/main/nvs_rw_blob.c>`_
+`nvs_rw_blob <https://github.com/espressif/esp-idf/blob/master/examples/storage/nvs_rw_blob>`_
Demonstrates how to read and write a single integer value and a blob (binary large object) using NVS to preserve them between ESP32 module restarts.
.. doxygenfunction:: esp_deep_sleep_start
+Application Example
+-------------------
+
+Implementation of basic functionality of deep sleep is shown in `protocols/sntp <https://github.com/espressif/esp-idf/tree/master/examples/protocols/sntp>`_ example, where ESP module is periodically waken up to retrive time from NTP server.
+
Application Example
-------------------
-`Instructions`_
-
-.. _Instructions: ../template.html
+Log library is commonly used by most of esp-idf components and examples. For demonstration of log functionality check `examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that among others, contains the following examples:
+
+* `system/ota <https://github.com/espressif/esp-idf/tree/master/examples/system/ota>`_
+* `storage/sd_card <https://github.com/espressif/esp-idf/tree/master/examples/storage/sd_card>`_
+* `protocols/https_request <https://github.com/espressif/esp-idf/tree/master/examples/protocols/https_request>`_
API Reference
-------------
OTA
===
+Application Example
+-------------------
+
+Demonstration of OTA (over the air) firmware update workflow: `examples/system/ota <https://github.com/espressif/esp-idf/tree/master/examples/system/ota>`_.
+
API Reference
-------------
Smart Config
-===
+============
API Reference
-------------
`Instructions`_
+.. _Instructions: ../template.html
+
Application Example
-------------------
-`Instructions`_
+Simple code showing how to connect ESP32 module to an Access Point: `esp-idf-template <https://github.com/espressif/esp-idf-template>`_.
API Reference
-------------
-`Instructions`_
-
-.. _Instructions: ../template.html
-
Header Files
^^^^^^^^^^^^
Each project contains one or more components, which can either be part of esp-idf or added from other component directories.
-A component is any sub-directory that contains a `component.mk` file.[#f1]_.
+A component is any sub-directory that contains a `component.mk` file [#f1]_.
Minimal Component Makefile
^^^^^^^^^^^^^^^^^^^^^^^^^^
The names are generated from the full name of the file, as given in COMPONENT_EMBED_FILES. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files.
-For an example of using this technique, see examples/protocols/https_request - the certificate file contents are loaded from the text .pem file at compile time.
+For an example of using this technique, see `examples/protocols/https_request <https://github.com/espressif/esp-idf/tree/master/examples/protocols/https_request>`_ - the certificate file contents are loaded from the text .pem file at compile time.
Fully Overriding The Component Makefile
.. _esp-idf-template: https://github.com/espressif/esp-idf-template
.. _GNU Make Manual: https://www.gnu.org/software/make/manual/make.html
-.. _[_f1]: Actually, some components in esp-idf are "pure configuration" components that don't have a component.mk file, only a Makefile.projbuild and/or Kconfig.projbuild file. However, these components are unusual and most components have a component.mk file.
+.. [#f1] Actually, some components in esp-idf are "pure configuration" components that don't have a component.mk file, only a Makefile.projbuild and/or Kconfig.projbuild file. However, these components are unusual and most components have a component.mk file.
Custom sdkconfig defaults
master_doc = 'index'
# General information about the project.
-project = u'ESP32 Programming Guide'
-copyright = u'2016, Espressif'
+project = u'ESP-IDF Programming Guide'
+copyright = u'2016 - 2017, Espressif'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
:maxdepth: 1
General Notes <general-notes>
- Build System <build_system>
+ Build System <build-system>
Debugging <openocd>
ESP32 Core Dump <core_dump>
Partition Tables <partition-tables>
- Each 32 byte block is encrypted with a unique key which is derived from this main flash encryption key XORed with the offset of this block in the flash (a "key tweak").
- The specific tweak depends on the setting of ``FLASH_CRYPT_CONFIG`` efuse. This is a 4 bit efuse, where each bit enables XORing of a particular range of the key bits:
+
- Bit 1, bits 0-66 of the key are XORed.
- Bit 2, bits 67-131 of the key are XORed.
- Bit 3, bits 132-194 of the key are XORed.
- Bit 4, bits 195-256 of the key are XORed.
-It is recommended that ``FLASH_CRYPT_CONFIG`` is always left to set the default value `0xF`, so that all key bits are XORed with the block offset. See `Setting FLASH_CRYPT_CONFIG` for details.
+
+ It is recommended that ``FLASH_CRYPT_CONFIG`` is always left to set the default value `0xF`, so that all key bits are XORed with the block offset. See `Setting FLASH_CRYPT_CONFIG` for details.
- The high 19 bits of the block offset (bit 5 to bit 23) are XORed with the main flash encryption key. This range is chosen for two reasons: the maximum flash size is 16MB (24 bits), and each block is 32 bytes so the least significant 5 bits are always zero.
required_size += sizeof(uint32_t);
run_time[required_size / sizeof(uint32_t) - 1] = xTaskGetTickCount() * portTICK_PERIOD_MS;
err = nvs_set_blob(my_handle, "run_time", run_time, required_size);
- if (err != ESP_OK) return err;
-
free(run_time);
+ if (err != ESP_OK) return err;
+
// Commit
err = nvs_commit(my_handle);
if (err != ESP_OK) return err;
This example doesn't utilize card detect (CD) and write protect (WP) signals from SD card slot.
### Note about GPIO2
-GPIO2 pin is used as a bootstrapping pin, and should be low to enter UART download mode. One way to do this is to connect GPIO0 and GPIO2 using a jumper, and then the auto-reset circuit on most development boards will pull GPIO2 low along with GPIO2, when entering download mode.
+
+GPIO2 pin is used as a bootstrapping pin, and should be low to enter UART download mode. One way to do this is to connect GPIO0 and GPIO2 using a jumper, and then the auto-reset circuit on most development boards will pull GPIO2 low along with GPIO0, when entering download mode.
### Note about GPIO12