Getting started guides

This commit is contained in:
krzychb 2017-03-27 00:01:52 +02:00
parent 6f0a9f76cd
commit 1a19747678
130 changed files with 1371 additions and 608 deletions

View File

@ -43,5 +43,13 @@ Legal Part
Before a contribution can be accepted, you will need to sign our :doc:`contributor-agreement`. You will be prompted for this automatically as part of the Pull Request process.
Related Documents
-----------------
.. toctree::
:maxdepth: 1
style-guide
documenting-code
../api-reference/template
contributor-agreement

View File

@ -85,7 +85,7 @@ make -j5 flash monitor
Once you've compiled your project, the "build" directory will contain a binary file with a name like "my_app.bin". This is an ESP32 image binary that can be loaded by the bootloader.
A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to offset 0x4000 in the flash.
A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to offset 0x8000 in the flash.
Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.

View File

@ -356,7 +356,7 @@ esp_err_t gpio_wakeup_disable(gpio_num_t gpio_num);
* @param handle Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.
*
* \verbatim embed:rst:leading-asterisk
* To disable or remove the ISR, pass the returned handle to the :doc:`interrupt allocation functions </api/system/intr_alloc>`.
* To disable or remove the ISR, pass the returned handle to the :doc:`interrupt allocation functions </api-reference/system/intr_alloc>`.
* \endverbatim
*
* @return

View File

@ -5,7 +5,7 @@ Overview
--------
The spi_flash component contains APIs related to reading, writing, erasing,
memory mapping data in the external SPI flash. It also has higher-level
APIs which work with partitions defined in the :doc:`partition table </partition-tables>`.
APIs which work with partitions defined in the :doc:`partition table </api-guides/partition-tables>`.
Note that all the functionality is limited to the "main" SPI flash chip,
the same SPI flash chip from which program runs. For ``spi_flash_*`` functions,
@ -67,7 +67,7 @@ IRAM-Safe Interrupt Handlers
If you have an interrupt handler that you want to execute even when a flash
operation is in progress (for example, for low latency operations), set the
``ESP_INTR_FLAG_IRAM`` flag when the :doc:`interrupt handler is registered
</api/system/intr_alloc>`.
</api-reference/system/intr_alloc>`.
You must ensure all data and functions accessed by these interrupt handlers are
located in IRAM or DRAM. This includes any functions that the handler calls.
@ -104,7 +104,7 @@ Partition table APIs
ESP-IDF projects use a partition table to maintain information about various regions of
SPI flash memory (bootloader, various application binaries, data, filesystems).
More information about partition tables can be found :doc:`here </partition-tables>`.
More information about partition tables can be found :doc:`here </api-guides/partition-tables>`.
This component provides APIs to enumerate partitions found in the partition table
and perform operations on them. These functions are declared in ``esp_partition.h``:

View File

@ -12,7 +12,7 @@ memory without user interaction.
The wear_levelling component contains APIs related to reading, writing, erasing,
memory mapping data in the external SPI flash through the partition component. It
also has higher-level APIs which work with FAT filesystem defined in
the :doc:`FAT filesystem </api/storage/fatfs>`.
the :doc:`FAT filesystem </api-reference/storage/fatfs>`.
The wear levelling component does not cache data in RAM. Write and erase functions
modify flash directly, and flash contents is consistent when the function returns.

BIN
docs/_static/about-doc.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 67 KiB

BIN
docs/_static/api-guides.gif vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.2 KiB

BIN
docs/_static/api-reference.gif vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.0 KiB

BIN
docs/_static/contribute.gif vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.3 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 67 KiB

After

Width:  |  Height:  |  Size: 76 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 277 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 27 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 40 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 27 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 189 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 384 KiB

BIN
docs/_static/get-started.gif vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.8 KiB

BIN
docs/_static/hw-reference.gif vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.0 KiB

BIN
docs/_static/linux-logo.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 24 KiB

BIN
docs/_static/macos-logo.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 23 KiB

BIN
docs/_static/msys2-terminal-window.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 13 KiB

BIN
docs/_static/project-configuration.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 43 KiB

BIN
docs/_static/putty-settings-linux.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 62 KiB

BIN
docs/_static/putty-settings-windows.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 17 KiB

BIN
docs/_static/resources.gif vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.4 KiB

BIN
docs/_static/what-you-need.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 108 KiB

BIN
docs/_static/windows-logo.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 3.4 KiB

BIN
docs/_static/wrover-jp1-both.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 75 KiB

BIN
docs/_static/wrover-jp1-sd_io2.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 74 KiB

BIN
docs/_static/wrover-jp11-tx-rx.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 69 KiB

BIN
docs/_static/wrover-jp14.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 82 KiB

BIN
docs/_static/wrover-jp7-ext_5v.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 75 KiB

BIN
docs/_static/wrover-jp7-usb_5v.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 75 KiB

BIN
docs/_static/wrover-jp8.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 82 KiB

16
docs/about.rst Normal file
View File

@ -0,0 +1,16 @@
About
=====
This is documentation of `ESP-IDF <https://github.com/espressif/esp-idf>`_, the framework to develop applications for `ESP32 <https://espressif.com/en/products/hardware/esp32/overview>`_ chip by `Espressif <https://espressif.com>`_.
The ESP32 is 2.4 GHz Wi-Fi and Bluetooth combo, 32 bit dual core chip with 600 DMIPS processing power.
.. figure:: _static/about-doc.png
:align: center
:alt: Espressif IoT Integrated Development Framework
:figclass: align-center
Espressif IoT Integrated Development Framework
The ESP-IDF, Espressif IoT Integrated Development Framework, provides toolchain, API, components and workflows to develop applications for ESP32 using Windows, Linux and Mac OS operating systems.

17
docs/api-guides/index.rst Normal file
View File

@ -0,0 +1,17 @@
API Guides
**********
.. toctree::
:maxdepth: 1
General Notes <general-notes>
Build System <build-system>
Debugging <openocd>
ESP32 Core Dump <core_dump>
Partition Tables <partition-tables>
Flash Encryption <../security/flash-encryption>
Secure Boot <../security/secure-boot>
Deep Sleep Wake Stubs <deep-sleep-stub>
ULP Coprocessor <ulp>
Unit Testing <unit-tests>

View File

@ -95,7 +95,7 @@ When type is "app", the subtype field can be specified as factory (0), ota_0 (0x
- OTA never updates the factory partition.
- If you want to conserve flash usage in an OTA project, you can remove the factory partition and use ota_0 instead.
- ota_0 (0x10) ... ota_15 (0x1F) are the OTA app slots. Refer to the :doc:`OTA documentation <api/system/ota>` for more details, which then use the OTA data partition to configure which app slot the bootloader should boot. If using OTA, an application should have at least two OTA application slots (ota_0 & ota_1). Refer to the :doc:`OTA documentation <api/system/ota>` for more details.
- ota_0 (0x10) ... ota_15 (0x1F) are the OTA app slots. Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details, which then use the OTA data partition to configure which app slot the bootloader should boot. If using OTA, an application should have at least two OTA application slots (ota_0 & ota_1). Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details.
- test (0x2) is a reserved subtype for factory test procedures. It is not currently supported by the esp-idf bootloader.
Data Subtypes
@ -108,10 +108,10 @@ When type is "data", the subtype field can be specified as ota (0), phy (1), nvs
- In the default configuration, the phy partition is not used and PHY initialisation data is compiled into the app itself. As such, this partition can be removed from the partition table to save space.
- To load PHY data from this partition, run ``make menuconfig`` and enable "Component Config" -> "PHY" -> "Use a partition to store PHY init data". You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically.
- nvs (2) is for the :doc:`Non-Volatile Storage (NVS) API <api/storage/nvs_flash>`.
- nvs (2) is for the :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>`.
- NVS is used to store per-device PHY calibration data (different to initialisation data).
- NVS is used to store WiFi data if the :doc:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <api/wifi/esp_wifi>` initialisation function is used.
- NVS is used to store WiFi data if the :doc:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <../api-reference/wifi/esp_wifi>` initialisation function is used.
- The NVS API can also be used for other application data.
- It is strongly recommended that you include an NVS partition of at least 0x3000 bytes in your project.
- If using NVS API to store a lot of data, increase the NVS partition size from the default 0x6000 bytes.

View File

@ -1,5 +1,5 @@
ULP coprocessor instruction set
+++++++++++++++++++++++++++++++
===============================
This document provides details about the instructions used by ESP32 ULP coprocessor assembler.
@ -242,7 +242,7 @@ Similar considerations apply to ``LD`` and ``ST`` instructions. Consider the fol
**RSH** - Logical Shift Right
----------------------------
-----------------------------
**Syntax**
**RSH** *Rdst, Rsrc1, Rsrc2*

View File

@ -0,0 +1 @@
.. include:: ../../components/ulp/README.rst

View File

@ -0,0 +1,14 @@
*************
API Reference
*************
.. toctree::
:maxdepth: 2
Wi-Fi <wifi/index>
Bluetooth <bluetooth/index>
Ethernet <ethernet/index>
Peripherals <peripherals/index>
System <system/index>
Storage <storage/index>
Protocols <protocols/index>

View File

@ -9,7 +9,7 @@ The ESP32 chip features 40 physical GPIO pads. Some GPIO pads cannot be used or
- Note that GPIO6-11 are usually used for SPI flash.
- GPIO34-39 can only be set as input mode and do not have software pullup or pulldown functions.
There is also separate "RTC GPIO" support, which functions when GPIOs are routed to the "RTC" low-power and analog subsystem. These pin functions can be used when in deep sleep, when the :doc:`Ultra Low Power co-processor </ulp>` is running, or when analog functions such as ADC/DAC/etc are in use.
There is also separate "RTC GPIO" support, which functions when GPIOs are routed to the "RTC" low-power and analog subsystem. These pin functions can be used when in deep sleep, when the :doc:`Ultra Low Power co-processor <../../api-guides/ulp>` is running, or when analog functions such as ADC/DAC/etc are in use.
Application Example
-------------------

View File

@ -3,8 +3,8 @@
See also
--------
- :doc:`Partition Table documentation </partition-tables>`
- :doc:`Over The Air Update (OTA) API </api/system/ota>` provides high-level API for updating app firmware stored in flash.
- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
- :doc:`Over The Air Update (OTA) API <../system/ota>` provides high-level API for updating app firmware stored in flash.
- :doc:`Non-Volatile Storage (NVS) API <nvs_flash>` provides a structured API for storing small items of data in SPI flash.
API Reference

View File

@ -3,8 +3,8 @@
See also
--------
- :doc:`FAT Filesystem </partition-tables>`
- :doc:`Partition Table documentation </partition-tables>`
- :doc:`FAT Filesystem <../../api-guides/partition-tables>`
- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
Application Example
@ -14,7 +14,7 @@ An example which combines wear levelling driver with FATFS library is provided i
wear levelling driver, mounts FATFS partition, and writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
High level API Reference
-------------
------------------------
Header Files
^^^^^^^^^^^^
@ -30,7 +30,7 @@ Functions
.. doxygenfunction:: esp_vfs_fat_spiflash_unmount
Mid level API Reference
-------------
-----------------------
Header Files
^^^^^^^^^^^^

View File

@ -7,7 +7,7 @@ OTA Process Overview
The OTA update mechanism allows a device to update itself based on data received while the normal firmware is running
(for example, over WiFi or Bluetooth.)
OTA requires configuring the :doc:`Partition Table </partition-tables>` of the device with at least two "OTA app slot"
OTA requires configuring the :doc:`Partition Table <../../api-guides/partition-tables>` of the device with at least two "OTA app slot"
partitions (ie `ota_0` and `ota_1`) and an "OTA Data Partition".
The OTA operation functions write a new app firmware image to whichever OTA app slot is not currently being used for
@ -19,7 +19,7 @@ next boot.
OTA Data Partition
^^^^^^^^^^^^^^^^^^
An OTA data partition (type ``data``, subtype ``ota``) must be included in the :doc:`Partition Table </partition-tables>`
An OTA data partition (type ``data``, subtype ``ota``) must be included in the :doc:`Partition Table <../../api-guides/partition-tables>`
of any project which uses the OTA functions.
For factory boot settings, the OTA data partition should contain no data (all bytes erased to 0xFF). In this case the
@ -35,8 +35,8 @@ counter field is used to determine which sector was written more recently.
See also
--------
* :doc:`Partition Table documentation </partition-tables>`
* :doc:`Lower-Level SPI Flash/Partition API </api/storage/spi_flash>`
* :doc:`Partition Table documentation <../../api-guides/partition-tables>`
* :doc:`Lower-Level SPI Flash/Partition API <../storage/spi_flash>`
Application Example
-------------------

View File

@ -1,5 +1,5 @@
Template
========
API Documentation Template
==========================
.. note::
@ -69,7 +69,7 @@ API Reference
See `Breathe documentation <https://breathe.readthedocs.io/en/latest/directives.html>`_ for additional information.
4. Once done remove superfluous headers.
5. When changes are committed and documentation is build, check how this section rendered. :doc:`Correct annotations <../documenting-code>` in respective header files, if required.
5. When changes are committed and documentation is build, check how this section rendered. :doc:`Correct annotations <../contribute/documenting-code>` in respective header files, if required.
Header Files
^^^^^^^^^^^^

Some files were not shown because too many files have changed in this diff Show More