From fb7b2180914d9619b551f0ab1b9530b08de45f6a Mon Sep 17 00:00:00 2001 From: krzychb Date: Tue, 17 Jan 2017 18:53:29 +0100 Subject: [PATCH 1/6] Fixed broken links --- docs/api/bluetooth/esp_gap_ble.rst | 2 +- docs/api/peripherals/sigmadelta.rst | 2 +- docs/api/peripherals/spi_master.rst | 2 +- docs/api/protocols/mdns.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api/bluetooth/esp_gap_ble.rst b/docs/api/bluetooth/esp_gap_ble.rst index 088ab27dba..40ccdba50f 100644 --- a/docs/api/bluetooth/esp_gap_ble.rst +++ b/docs/api/bluetooth/esp_gap_ble.rst @@ -27,7 +27,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `bt/bluedroid/api/include/esp_gap_ble_api.h `_ + * `bt/bluedroid/api/include/esp_gap_ble_api.h `_ Macros diff --git a/docs/api/peripherals/sigmadelta.rst b/docs/api/peripherals/sigmadelta.rst index b03f049421..56e4d77e72 100644 --- a/docs/api/peripherals/sigmadelta.rst +++ b/docs/api/peripherals/sigmadelta.rst @@ -10,7 +10,7 @@ This driver configures the channels of the sigma-delta module. Application Example ------------------- -Sigma-delta Modulation example: `examples/14_sigmadelta `_. +Sigma-delta Modulation example: `examples/peripherals/sigmadelta `_. API Reference ------------- diff --git a/docs/api/peripherals/spi_master.rst b/docs/api/peripherals/spi_master.rst index 5b57d85f42..012d1832ce 100644 --- a/docs/api/peripherals/spi_master.rst +++ b/docs/api/peripherals/spi_master.rst @@ -111,7 +111,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `drivers/include/drivers/spi_master.h `_ + * `driver/include/driver/spi_master.h `_ Macros ^^^^^^ diff --git a/docs/api/protocols/mdns.rst b/docs/api/protocols/mdns.rst index d674e25a08..6214883965 100644 --- a/docs/api/protocols/mdns.rst +++ b/docs/api/protocols/mdns.rst @@ -163,7 +163,7 @@ Example of using the methods above: Application Example ------------------- -mDNS server/scanner example: `examples/protocols/mdsn `_. +mDNS server/scanner example: `examples/protocols/mdns `_. API Reference ------------- From 5ae9647667619e862fd9969f44edd1cefd52e3b6 Mon Sep 17 00:00:00 2001 From: krzychb Date: Tue, 17 Jan 2017 19:12:48 +0100 Subject: [PATCH 2/6] Added links to examples in API documentation --- docs/api/peripherals/spi_master.rst | 5 +++++ docs/api/peripherals/uart.rst | 8 +++----- docs/api/system/deep_sleep.rst | 5 +++++ docs/api/system/log.rst | 8 +++++--- docs/api/system/ota.rst | 5 +++++ docs/api/wifi/esp_wifi.rst | 8 +++----- 6 files changed, 26 insertions(+), 13 deletions(-) diff --git a/docs/api/peripherals/spi_master.rst b/docs/api/peripherals/spi_master.rst index 012d1832ce..9e5c0eb636 100644 --- a/docs/api/peripherals/spi_master.rst +++ b/docs/api/peripherals/spi_master.rst @@ -105,6 +105,11 @@ on the transmission. For received data, use ``rx_data`` and set ``SPI_USE_RXDATA 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 `_. + API Reference ------------- diff --git a/docs/api/peripherals/uart.rst b/docs/api/peripherals/uart.rst index 8684b2afa3..b00b4e0648 100644 --- a/docs/api/peripherals/uart.rst +++ b/docs/api/peripherals/uart.rst @@ -6,18 +6,16 @@ Overview `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 `_. API Reference ------------- -`Instructions`_ - -.. _Instructions: ../template.html - Header Files ^^^^^^^^^^^^ diff --git a/docs/api/system/deep_sleep.rst b/docs/api/system/deep_sleep.rst index 9e6642fd90..393d5f025e 100644 --- a/docs/api/system/deep_sleep.rst +++ b/docs/api/system/deep_sleep.rst @@ -87,3 +87,8 @@ The following function can be used to enter deep sleep once wakeup sources are c .. doxygenfunction:: esp_deep_sleep_start +Application Example +------------------- + +Implementation of basic functionality of deep sleep is shown in `protocols/sntp `_ example, where ESP module is periodically waken up to retrive time from NTP server. + diff --git a/docs/api/system/log.rst b/docs/api/system/log.rst index d812740bb2..24d3bef80a 100644 --- a/docs/api/system/log.rst +++ b/docs/api/system/log.rst @@ -3,9 +3,11 @@ 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 `_ folder of `espressif/esp-idf `_ repository, that among others, contains the following examples: + +* `system/ota `_ +* `storage/sd_card `_ +* `protocols/https_request `_ API Reference ------------- diff --git a/docs/api/system/ota.rst b/docs/api/system/ota.rst index a4984620f6..ce2fdba635 100644 --- a/docs/api/system/ota.rst +++ b/docs/api/system/ota.rst @@ -1,6 +1,11 @@ OTA === +Application Example +------------------- + +Demonstration of OTA (over the air) firmware update workflow: `examples/system/ota `_. + API Reference ------------- diff --git a/docs/api/wifi/esp_wifi.rst b/docs/api/wifi/esp_wifi.rst index 1fe832a2c5..247ddf7522 100644 --- a/docs/api/wifi/esp_wifi.rst +++ b/docs/api/wifi/esp_wifi.rst @@ -6,18 +6,16 @@ Overview `Instructions`_ +.. _Instructions: ../template.html + Application Example ------------------- -`Instructions`_ +Simple code showing how to connect ESP32 module to an Access Point: `esp-idf-template `_. API Reference ------------- -`Instructions`_ - -.. _Instructions: ../template.html - Header Files ^^^^^^^^^^^^ From 03c14809f96d43352e76c4e3282b8ed6bd70b412 Mon Sep 17 00:00:00 2001 From: krzychb Date: Tue, 17 Jan 2017 20:03:26 +0100 Subject: [PATCH 3/6] Updated links to point directly to example folder, fixed names --- docs/api/bluetooth/controller_vhci.rst | 10 ++++------ docs/api/bluetooth/esp_blufi.rst | 6 +++--- docs/api/bluetooth/esp_gap_ble.rst | 16 ++++++---------- docs/api/bluetooth/esp_gattc.rst | 12 +++++------- docs/api/bluetooth/esp_gatts.rst | 13 +++++-------- docs/api/storage/nvs_flash.rst | 6 +++--- 6 files changed, 26 insertions(+), 37 deletions(-) diff --git a/docs/api/bluetooth/controller_vhci.rst b/docs/api/bluetooth/controller_vhci.rst index 3868d9cec7..dfad1af25e 100644 --- a/docs/api/bluetooth/controller_vhci.rst +++ b/docs/api/bluetooth/controller_vhci.rst @@ -6,19 +6,17 @@ Overview `Instructions`_ +.. _Instructions: ../template.html + Application Example ------------------- -Check `/examples `_ folder of `espressif/esp-idf `_ repository, that contains the following example: +Check `/examples/bluetooth `_ folder of `espressif/esp-idf `_ repository, that contains the following example: -`bluetooth/ble_adv `_ +`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 ------------- diff --git a/docs/api/bluetooth/esp_blufi.rst b/docs/api/bluetooth/esp_blufi.rst index a281c3d3d6..442e54f5ca 100644 --- a/docs/api/bluetooth/esp_blufi.rst +++ b/docs/api/bluetooth/esp_blufi.rst @@ -11,11 +11,11 @@ Use should concern these things: Application Example ------------------- -Check `/examples `_ folder of `espressif/esp-idf `_ repository, that contains the following example: +Check `/examples/bluetooth `_ folder of `espressif/esp-idf `_ repository, that contains the following example: -`bluetooth/blufi `_ +`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 diff --git a/docs/api/bluetooth/esp_gap_ble.rst b/docs/api/bluetooth/esp_gap_ble.rst index 40ccdba50f..f53b8d56ad 100644 --- a/docs/api/bluetooth/esp_gap_ble.rst +++ b/docs/api/bluetooth/esp_gap_ble.rst @@ -1,25 +1,21 @@ GAP API -======== +======= Overview -------- `Instructions`_ +.. _Instructions: ../template.html + Application Example ------------------- -Check `/examples `_ folder of `espressif/esp-idf `_ repository, that contains the following example: +Check `/examples/bluetooth `_ folder of `espressif/esp-idf `_ repository, that contains the following examples: -`14_gatts_demo `_ -`15_gattc_demo `_ - -The two demos use different gap api, such like advertising, scan, set device name and others. - -`Instructions`_ - -.. _Instructions: ../template.html +`gatt_server `_, `gatt_client `_ + The two demos use different gap api, such like advertising, scan, set device name and others. API Reference ------------- diff --git a/docs/api/bluetooth/esp_gattc.rst b/docs/api/bluetooth/esp_gattc.rst index eada883fd7..adfc225dfa 100644 --- a/docs/api/bluetooth/esp_gattc.rst +++ b/docs/api/bluetooth/esp_gattc.rst @@ -6,18 +6,16 @@ Overview `Instructions`_ +.. _Instructions: ../template.html + Application Example ------------------- -Check `/examples `_ folder of `espressif/esp-idf `_ repository, that contains the following example: +Check `/examples/bluetooth `_ folder of `espressif/esp-idf `_ repository, that contains the following example: -`15_gattc_demo `_ +`gatt_client `_ -This is a gatt client demo. This demo can scan devices, connect to the gatt server and discover the service. - -`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 diff --git a/docs/api/bluetooth/esp_gatts.rst b/docs/api/bluetooth/esp_gatts.rst index 877840402c..4753490d4d 100644 --- a/docs/api/bluetooth/esp_gatts.rst +++ b/docs/api/bluetooth/esp_gatts.rst @@ -6,19 +6,16 @@ Overview `Instructions`_ +.. _Instructions: ../template.html + Application Example ------------------- -Check `/examples `_ folder of `espressif/esp-idf `_ repository, that contains the following example: +Check `/examples/bluetooth `_ folder of `espressif/esp-idf `_ repository, that contains the following example: -`14_gatts_demo `_ - -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. - -`Instructions`_ - -.. _Instructions: ../template.html +`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 ------------- diff --git a/docs/api/storage/nvs_flash.rst b/docs/api/storage/nvs_flash.rst index 00094d8697..9e97c3a811 100644 --- a/docs/api/storage/nvs_flash.rst +++ b/docs/api/storage/nvs_flash.rst @@ -3,9 +3,9 @@ Application Example ------------------- -Two examples are provided in ESP-IDF examples directory: +Two examples are provided in ESP-IDF `examples/storage `_ directory: -`storage/nvs_rw_value `_ +`nvs_rw_value `_ Demonstrates how to read and write a single integer value using NVS. @@ -13,7 +13,7 @@ Two examples are provided in ESP-IDF examples directory: 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 `_ +`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. From 46d8ece20e5e48fd0f0abeccd62fc62284f92d35 Mon Sep 17 00:00:00 2001 From: krzychb Date: Tue, 17 Jan 2017 20:37:27 +0100 Subject: [PATCH 4/6] Docs folder info, ref. https://github.com/espressif/esp-idf/issues/243; Doc title fix --- docs/README.md | 11 +++++++++++ docs/conf.py | 4 ++-- 2 files changed, 13 insertions(+), 2 deletions(-) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..475ce0973e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,11 @@ +# Documentation Source Folder + +This folder contains source files of [ESP-IDF documentation](http://esp-idf.readthedocs.io/). + +The sources do not render well in GitHub and some information is not visible at all. + +Use actual documentation generated instantly on each commit: + +* Main server: http://esp-idf.readthedocs.io/ or http://esp-idf.rtfd.io/ +* Mirror: https://dl.espressif.com/doc/esp-idf/latest/ + diff --git a/docs/conf.py b/docs/conf.py index 551cd86dd0..d38d3dee9d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -65,8 +65,8 @@ source_suffix = '.rst' 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 From 66647bb5bd4b5475ad2372216378f186aac43718 Mon Sep 17 00:00:00 2001 From: krzychb Date: Tue, 17 Jan 2017 21:12:54 +0100 Subject: [PATCH 5/6] Typo corrections --- docs/api/wifi/esp_smartconfig.rst | 2 +- docs/{build_system.rst => build-system.rst} | 6 +++--- docs/index.rst | 2 +- docs/security/flash-encryption.rst | 4 +++- examples/storage/sd_card/README.md | 3 ++- 5 files changed, 10 insertions(+), 7 deletions(-) rename docs/{build_system.rst => build-system.rst} (98%) diff --git a/docs/api/wifi/esp_smartconfig.rst b/docs/api/wifi/esp_smartconfig.rst index 262218aa8b..11a6bccbfa 100644 --- a/docs/api/wifi/esp_smartconfig.rst +++ b/docs/api/wifi/esp_smartconfig.rst @@ -1,5 +1,5 @@ Smart Config -=== +============ API Reference ------------- diff --git a/docs/build_system.rst b/docs/build-system.rst similarity index 98% rename from docs/build_system.rst rename to docs/build-system.rst index d4353287b9..8f43b21176 100644 --- a/docs/build_system.rst +++ b/docs/build-system.rst @@ -131,7 +131,7 @@ Component Makefiles 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -464,7 +464,7 @@ The file's contents will be added to the .rodata section in flash, and are avail 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 `_ - the certificate file contents are loaded from the text .pem file at compile time. Fully Overriding The Component Makefile @@ -485,7 +485,7 @@ is set then the component can instruct the linker to link other binaries instead .. _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 diff --git a/docs/index.rst b/docs/index.rst index d1072b6511..b934472b59 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,7 +28,7 @@ Contents: :maxdepth: 1 General Notes - Build System + Build System Debugging ESP32 Core Dump Partition Tables diff --git a/docs/security/flash-encryption.rst b/docs/security/flash-encryption.rst index 298a0a75bf..8c6bd4c857 100644 --- a/docs/security/flash-encryption.rst +++ b/docs/security/flash-encryption.rst @@ -291,11 +291,13 @@ Flash Encryption Algorithm - 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. diff --git a/examples/storage/sd_card/README.md b/examples/storage/sd_card/README.md index bfc6a39fe9..b125716eae 100644 --- a/examples/storage/sd_card/README.md +++ b/examples/storage/sd_card/README.md @@ -32,7 +32,8 @@ N/C | WP | 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 From 8aa5082baae0db503b1bfb6876b63a03e5d458fc Mon Sep 17 00:00:00 2001 From: krzychb Date: Tue, 17 Jan 2017 21:20:24 +0100 Subject: [PATCH 6/6] Fixed memory leak in example, ref. https://github.com/espressif/esp-idf/issues/209 --- examples/storage/nvs_rw_blob/main/nvs_rw_blob.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/storage/nvs_rw_blob/main/nvs_rw_blob.c b/examples/storage/nvs_rw_blob/main/nvs_rw_blob.c index 0d4b7db4ee..c0a865eb6a 100644 --- a/examples/storage/nvs_rw_blob/main/nvs_rw_blob.c +++ b/examples/storage/nvs_rw_blob/main/nvs_rw_blob.c @@ -87,10 +87,10 @@ esp_err_t save_run_time(void) 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;