diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index df4070504..19dde17a9 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -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 \ No newline at end of file diff --git a/README.md b/README.md index 7d8934f6c..a616b7364 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/components/driver/include/driver/gpio.h b/components/driver/include/driver/gpio.h index f044964da..6c79f7b8b 100644 --- a/components/driver/include/driver/gpio.h +++ b/components/driver/include/driver/gpio.h @@ -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 `. + * To disable or remove the ISR, pass the returned handle to the :doc:`interrupt allocation functions `. * \endverbatim * * @return diff --git a/components/spi_flash/README.rst b/components/spi_flash/README.rst index da953f0cf..6de4e9281 100644 --- a/components/spi_flash/README.rst +++ b/components/spi_flash/README.rst @@ -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 `. +APIs which work with partitions defined in the :doc:`partition table `. 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 -`. +`. 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 `. +More information about partition tables can be found :doc:`here `. 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``: diff --git a/components/wear_levelling/README.rst b/components/wear_levelling/README.rst index a51185ea3..ebe298355 100644 --- a/components/wear_levelling/README.rst +++ b/components/wear_levelling/README.rst @@ -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 `. +the :doc:`FAT filesystem `. 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. diff --git a/docs/_static/about-doc.png b/docs/_static/about-doc.png new file mode 100644 index 000000000..4af663dbf Binary files /dev/null and b/docs/_static/about-doc.png differ diff --git a/docs/_static/api-guides.gif b/docs/_static/api-guides.gif new file mode 100644 index 000000000..bc9dd36db Binary files /dev/null and b/docs/_static/api-guides.gif differ diff --git a/docs/_static/api-reference.gif b/docs/_static/api-reference.gif new file mode 100644 index 000000000..7fd81755b Binary files /dev/null and b/docs/_static/api-reference.gif differ diff --git a/docs/_static/contribute.gif b/docs/_static/contribute.gif new file mode 100644 index 000000000..48a450890 Binary files /dev/null and b/docs/_static/contribute.gif differ diff --git a/docs/_static/doc-code-void-function.png b/docs/_static/doc-code-void-function.png index 36eeced6b..f6aa4af1d 100644 Binary files a/docs/_static/doc-code-void-function.png and b/docs/_static/doc-code-void-function.png differ diff --git a/docs/_static/esp32-devkitc-functional-overview.png b/docs/_static/esp32-devkitc-functional-overview.png new file mode 100644 index 000000000..73ce5820c Binary files /dev/null and b/docs/_static/esp32-devkitc-functional-overview.png differ diff --git a/docs/_static/esp32-devkitc-in-device-manager.png b/docs/_static/esp32-devkitc-in-device-manager.png new file mode 100644 index 000000000..640fc8e3b Binary files /dev/null and b/docs/_static/esp32-devkitc-in-device-manager.png differ diff --git a/docs/_static/esp32-wrover-kit-block-diagram.png b/docs/_static/esp32-wrover-kit-block-diagram.png new file mode 100644 index 000000000..65adba51b Binary files /dev/null and b/docs/_static/esp32-wrover-kit-block-diagram.png differ diff --git a/docs/_static/esp32-wrover-kit-in-device-manager.png b/docs/_static/esp32-wrover-kit-in-device-manager.png new file mode 100644 index 000000000..e953e1352 Binary files /dev/null and b/docs/_static/esp32-wrover-kit-in-device-manager.png differ diff --git a/docs/_static/esp32-wrover-kit-layout-back.png b/docs/_static/esp32-wrover-kit-layout-back.png new file mode 100644 index 000000000..84dab7a46 Binary files /dev/null and b/docs/_static/esp32-wrover-kit-layout-back.png differ diff --git a/docs/_static/esp32-wrover-kit-layout-front.png b/docs/_static/esp32-wrover-kit-layout-front.png new file mode 100644 index 000000000..d7806ad14 Binary files /dev/null and b/docs/_static/esp32-wrover-kit-layout-front.png differ diff --git a/docs/_static/get-started.gif b/docs/_static/get-started.gif new file mode 100644 index 000000000..7a7a8023b Binary files /dev/null and b/docs/_static/get-started.gif differ diff --git a/docs/_static/hw-reference.gif b/docs/_static/hw-reference.gif new file mode 100644 index 000000000..0b969c209 Binary files /dev/null and b/docs/_static/hw-reference.gif differ diff --git a/docs/_static/linux-logo.png b/docs/_static/linux-logo.png new file mode 100644 index 000000000..1112db655 Binary files /dev/null and b/docs/_static/linux-logo.png differ diff --git a/docs/_static/macos-logo.png b/docs/_static/macos-logo.png new file mode 100644 index 000000000..289d1f601 Binary files /dev/null and b/docs/_static/macos-logo.png differ diff --git a/docs/_static/msys2-terminal-window.png b/docs/_static/msys2-terminal-window.png new file mode 100644 index 000000000..a748ae8f9 Binary files /dev/null and b/docs/_static/msys2-terminal-window.png differ diff --git a/docs/_static/project-configuration.png b/docs/_static/project-configuration.png new file mode 100644 index 000000000..e724556c6 Binary files /dev/null and b/docs/_static/project-configuration.png differ diff --git a/docs/_static/putty-settings-linux.png b/docs/_static/putty-settings-linux.png new file mode 100644 index 000000000..7b04f9227 Binary files /dev/null and b/docs/_static/putty-settings-linux.png differ diff --git a/docs/_static/putty-settings-windows.png b/docs/_static/putty-settings-windows.png new file mode 100644 index 000000000..d08d6ab15 Binary files /dev/null and b/docs/_static/putty-settings-windows.png differ diff --git a/docs/_static/resources.gif b/docs/_static/resources.gif new file mode 100644 index 000000000..cde4bd809 Binary files /dev/null and b/docs/_static/resources.gif differ diff --git a/docs/_static/what-you-need.png b/docs/_static/what-you-need.png new file mode 100644 index 000000000..328c277c6 Binary files /dev/null and b/docs/_static/what-you-need.png differ diff --git a/docs/_static/windows-logo.png b/docs/_static/windows-logo.png new file mode 100644 index 000000000..122f53a2c Binary files /dev/null and b/docs/_static/windows-logo.png differ diff --git a/docs/_static/wrover-jp1-both.png b/docs/_static/wrover-jp1-both.png new file mode 100644 index 000000000..29a44c9f3 Binary files /dev/null and b/docs/_static/wrover-jp1-both.png differ diff --git a/docs/_static/wrover-jp1-sd_io2.png b/docs/_static/wrover-jp1-sd_io2.png new file mode 100644 index 000000000..be341f7c8 Binary files /dev/null and b/docs/_static/wrover-jp1-sd_io2.png differ diff --git a/docs/_static/wrover-jp11-tx-rx.png b/docs/_static/wrover-jp11-tx-rx.png new file mode 100644 index 000000000..340278f6c Binary files /dev/null and b/docs/_static/wrover-jp11-tx-rx.png differ diff --git a/docs/_static/wrover-jp14.png b/docs/_static/wrover-jp14.png new file mode 100644 index 000000000..eaf266f46 Binary files /dev/null and b/docs/_static/wrover-jp14.png differ diff --git a/docs/_static/wrover-jp7-ext_5v.png b/docs/_static/wrover-jp7-ext_5v.png new file mode 100644 index 000000000..86fc2f65d Binary files /dev/null and b/docs/_static/wrover-jp7-ext_5v.png differ diff --git a/docs/_static/wrover-jp7-usb_5v.png b/docs/_static/wrover-jp7-usb_5v.png new file mode 100644 index 000000000..bd71636af Binary files /dev/null and b/docs/_static/wrover-jp7-usb_5v.png differ diff --git a/docs/_static/wrover-jp8.png b/docs/_static/wrover-jp8.png new file mode 100644 index 000000000..fb64e8c27 Binary files /dev/null and b/docs/_static/wrover-jp8.png differ diff --git a/docs/about.rst b/docs/about.rst new file mode 100644 index 000000000..235161892 --- /dev/null +++ b/docs/about.rst @@ -0,0 +1,16 @@ +About +===== + +This is documentation of `ESP-IDF `_, the framework to develop applications for `ESP32 `_ chip by `Espressif `_. + +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. + diff --git a/docs/build-system.rst b/docs/api-guides/build-system.rst similarity index 100% rename from docs/build-system.rst rename to docs/api-guides/build-system.rst diff --git a/docs/core_dump.rst b/docs/api-guides/core_dump.rst similarity index 100% rename from docs/core_dump.rst rename to docs/api-guides/core_dump.rst diff --git a/docs/deep-sleep-stub.rst b/docs/api-guides/deep-sleep-stub.rst similarity index 100% rename from docs/deep-sleep-stub.rst rename to docs/api-guides/deep-sleep-stub.rst diff --git a/docs/esp32.cfg b/docs/api-guides/esp32.cfg similarity index 100% rename from docs/esp32.cfg rename to docs/api-guides/esp32.cfg diff --git a/docs/general-notes.rst b/docs/api-guides/general-notes.rst similarity index 100% rename from docs/general-notes.rst rename to docs/api-guides/general-notes.rst diff --git a/docs/api-guides/index.rst b/docs/api-guides/index.rst new file mode 100644 index 000000000..f0b02d1e8 --- /dev/null +++ b/docs/api-guides/index.rst @@ -0,0 +1,17 @@ +API Guides +********** + +.. toctree:: + :maxdepth: 1 + + General Notes + Build System + Debugging + ESP32 Core Dump + Partition Tables + Flash Encryption <../security/flash-encryption> + Secure Boot <../security/secure-boot> + Deep Sleep Wake Stubs + ULP Coprocessor + Unit Testing + diff --git a/docs/openocd.rst b/docs/api-guides/openocd.rst similarity index 100% rename from docs/openocd.rst rename to docs/api-guides/openocd.rst diff --git a/docs/partition-tables.rst b/docs/api-guides/partition-tables.rst similarity index 93% rename from docs/partition-tables.rst rename to docs/api-guides/partition-tables.rst index afe880a2b..7d5512294 100644 --- a/docs/partition-tables.rst +++ b/docs/api-guides/partition-tables.rst @@ -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 ` 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 ` 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 `. +- 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) ` 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. diff --git a/docs/ulp.rst b/docs/api-guides/ulp.rst similarity index 100% rename from docs/ulp.rst rename to docs/api-guides/ulp.rst diff --git a/docs/ulp_instruction_set.rst b/docs/api-guides/ulp_instruction_set.rst similarity index 96% rename from docs/ulp_instruction_set.rst rename to docs/api-guides/ulp_instruction_set.rst index 5a104a7e9..fdabb7f6b 100755 --- a/docs/ulp_instruction_set.rst +++ b/docs/api-guides/ulp_instruction_set.rst @@ -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* diff --git a/docs/api-guides/ulp_macros.rst b/docs/api-guides/ulp_macros.rst new file mode 100644 index 000000000..0a0c5df69 --- /dev/null +++ b/docs/api-guides/ulp_macros.rst @@ -0,0 +1 @@ +.. include:: ../../components/ulp/README.rst \ No newline at end of file diff --git a/docs/unit-tests.rst b/docs/api-guides/unit-tests.rst similarity index 100% rename from docs/unit-tests.rst rename to docs/api-guides/unit-tests.rst diff --git a/docs/api/bluetooth/bt_common.rst b/docs/api-reference/bluetooth/bt_common.rst similarity index 100% rename from docs/api/bluetooth/bt_common.rst rename to docs/api-reference/bluetooth/bt_common.rst diff --git a/docs/api/bluetooth/bt_le.rst b/docs/api-reference/bluetooth/bt_le.rst similarity index 100% rename from docs/api/bluetooth/bt_le.rst rename to docs/api-reference/bluetooth/bt_le.rst diff --git a/docs/api/bluetooth/classic_bt.rst b/docs/api-reference/bluetooth/classic_bt.rst similarity index 100% rename from docs/api/bluetooth/classic_bt.rst rename to docs/api-reference/bluetooth/classic_bt.rst diff --git a/docs/api/bluetooth/controller_vhci.rst b/docs/api-reference/bluetooth/controller_vhci.rst similarity index 100% rename from docs/api/bluetooth/controller_vhci.rst rename to docs/api-reference/bluetooth/controller_vhci.rst diff --git a/docs/api/bluetooth/esp_a2dp.rst b/docs/api-reference/bluetooth/esp_a2dp.rst similarity index 100% rename from docs/api/bluetooth/esp_a2dp.rst rename to docs/api-reference/bluetooth/esp_a2dp.rst diff --git a/docs/api/bluetooth/esp_avrc.rst b/docs/api-reference/bluetooth/esp_avrc.rst similarity index 100% rename from docs/api/bluetooth/esp_avrc.rst rename to docs/api-reference/bluetooth/esp_avrc.rst diff --git a/docs/api/bluetooth/esp_blufi.rst b/docs/api-reference/bluetooth/esp_blufi.rst similarity index 100% rename from docs/api/bluetooth/esp_blufi.rst rename to docs/api-reference/bluetooth/esp_blufi.rst diff --git a/docs/api/bluetooth/esp_bt_defs.rst b/docs/api-reference/bluetooth/esp_bt_defs.rst similarity index 100% rename from docs/api/bluetooth/esp_bt_defs.rst rename to docs/api-reference/bluetooth/esp_bt_defs.rst diff --git a/docs/api/bluetooth/esp_bt_device.rst b/docs/api-reference/bluetooth/esp_bt_device.rst similarity index 100% rename from docs/api/bluetooth/esp_bt_device.rst rename to docs/api-reference/bluetooth/esp_bt_device.rst diff --git a/docs/api/bluetooth/esp_bt_main.rst b/docs/api-reference/bluetooth/esp_bt_main.rst similarity index 100% rename from docs/api/bluetooth/esp_bt_main.rst rename to docs/api-reference/bluetooth/esp_bt_main.rst diff --git a/docs/api/bluetooth/esp_gap_ble.rst b/docs/api-reference/bluetooth/esp_gap_ble.rst similarity index 100% rename from docs/api/bluetooth/esp_gap_ble.rst rename to docs/api-reference/bluetooth/esp_gap_ble.rst diff --git a/docs/api/bluetooth/esp_gap_bt.rst b/docs/api-reference/bluetooth/esp_gap_bt.rst similarity index 100% rename from docs/api/bluetooth/esp_gap_bt.rst rename to docs/api-reference/bluetooth/esp_gap_bt.rst diff --git a/docs/api/bluetooth/esp_gatt_defs.rst b/docs/api-reference/bluetooth/esp_gatt_defs.rst similarity index 100% rename from docs/api/bluetooth/esp_gatt_defs.rst rename to docs/api-reference/bluetooth/esp_gatt_defs.rst diff --git a/docs/api/bluetooth/esp_gattc.rst b/docs/api-reference/bluetooth/esp_gattc.rst similarity index 100% rename from docs/api/bluetooth/esp_gattc.rst rename to docs/api-reference/bluetooth/esp_gattc.rst diff --git a/docs/api/bluetooth/esp_gatts.rst b/docs/api-reference/bluetooth/esp_gatts.rst similarity index 100% rename from docs/api/bluetooth/esp_gatts.rst rename to docs/api-reference/bluetooth/esp_gatts.rst diff --git a/docs/api/bluetooth/index.rst b/docs/api-reference/bluetooth/index.rst similarity index 100% rename from docs/api/bluetooth/index.rst rename to docs/api-reference/bluetooth/index.rst diff --git a/docs/api/ethernet/esp_eth.rst b/docs/api-reference/ethernet/esp_eth.rst similarity index 100% rename from docs/api/ethernet/esp_eth.rst rename to docs/api-reference/ethernet/esp_eth.rst diff --git a/docs/api/ethernet/index.rst b/docs/api-reference/ethernet/index.rst similarity index 100% rename from docs/api/ethernet/index.rst rename to docs/api-reference/ethernet/index.rst diff --git a/docs/api-reference/index.rst b/docs/api-reference/index.rst new file mode 100644 index 000000000..28bb8b250 --- /dev/null +++ b/docs/api-reference/index.rst @@ -0,0 +1,14 @@ +************* +API Reference +************* + +.. toctree:: + :maxdepth: 2 + + Wi-Fi + Bluetooth + Ethernet + Peripherals + System + Storage + Protocols diff --git a/docs/api/peripherals/adc.rst b/docs/api-reference/peripherals/adc.rst similarity index 100% rename from docs/api/peripherals/adc.rst rename to docs/api-reference/peripherals/adc.rst diff --git a/docs/api/peripherals/dac.rst b/docs/api-reference/peripherals/dac.rst similarity index 100% rename from docs/api/peripherals/dac.rst rename to docs/api-reference/peripherals/dac.rst diff --git a/docs/api/peripherals/gpio.rst b/docs/api-reference/peripherals/gpio.rst similarity index 95% rename from docs/api/peripherals/gpio.rst rename to docs/api-reference/peripherals/gpio.rst index a4f2ea81d..16d012084 100644 --- a/docs/api/peripherals/gpio.rst +++ b/docs/api-reference/peripherals/gpio.rst @@ -4,12 +4,12 @@ GPIO & RTC GPIO Overview -------- -The ESP32 chip features 40 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual ). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal. +The ESP32 chip features 40 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal. - 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 ` 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 ------------------- diff --git a/docs/api/peripherals/i2c.rst b/docs/api-reference/peripherals/i2c.rst similarity index 100% rename from docs/api/peripherals/i2c.rst rename to docs/api-reference/peripherals/i2c.rst diff --git a/docs/api/peripherals/i2s.rst b/docs/api-reference/peripherals/i2s.rst similarity index 100% rename from docs/api/peripherals/i2s.rst rename to docs/api-reference/peripherals/i2s.rst diff --git a/docs/api/peripherals/index.rst b/docs/api-reference/peripherals/index.rst similarity index 100% rename from docs/api/peripherals/index.rst rename to docs/api-reference/peripherals/index.rst diff --git a/docs/api/peripherals/ledc.rst b/docs/api-reference/peripherals/ledc.rst similarity index 100% rename from docs/api/peripherals/ledc.rst rename to docs/api-reference/peripherals/ledc.rst diff --git a/docs/api/peripherals/pcnt.rst b/docs/api-reference/peripherals/pcnt.rst similarity index 100% rename from docs/api/peripherals/pcnt.rst rename to docs/api-reference/peripherals/pcnt.rst diff --git a/docs/api/peripherals/rmt.rst b/docs/api-reference/peripherals/rmt.rst similarity index 100% rename from docs/api/peripherals/rmt.rst rename to docs/api-reference/peripherals/rmt.rst diff --git a/docs/api/peripherals/sigmadelta.rst b/docs/api-reference/peripherals/sigmadelta.rst similarity index 100% rename from docs/api/peripherals/sigmadelta.rst rename to docs/api-reference/peripherals/sigmadelta.rst diff --git a/docs/api/peripherals/spi_master.rst b/docs/api-reference/peripherals/spi_master.rst similarity index 100% rename from docs/api/peripherals/spi_master.rst rename to docs/api-reference/peripherals/spi_master.rst diff --git a/docs/api/peripherals/spi_slave.rst b/docs/api-reference/peripherals/spi_slave.rst similarity index 100% rename from docs/api/peripherals/spi_slave.rst rename to docs/api-reference/peripherals/spi_slave.rst diff --git a/docs/api/peripherals/timer.rst b/docs/api-reference/peripherals/timer.rst similarity index 100% rename from docs/api/peripherals/timer.rst rename to docs/api-reference/peripherals/timer.rst diff --git a/docs/api/peripherals/uart.rst b/docs/api-reference/peripherals/uart.rst similarity index 100% rename from docs/api/peripherals/uart.rst rename to docs/api-reference/peripherals/uart.rst diff --git a/docs/api/protocols/index.rst b/docs/api-reference/protocols/index.rst similarity index 100% rename from docs/api/protocols/index.rst rename to docs/api-reference/protocols/index.rst diff --git a/docs/api/protocols/mdns.rst b/docs/api-reference/protocols/mdns.rst similarity index 100% rename from docs/api/protocols/mdns.rst rename to docs/api-reference/protocols/mdns.rst diff --git a/docs/api/storage/fatfs.rst b/docs/api-reference/storage/fatfs.rst similarity index 100% rename from docs/api/storage/fatfs.rst rename to docs/api-reference/storage/fatfs.rst diff --git a/docs/api/storage/index.rst b/docs/api-reference/storage/index.rst similarity index 100% rename from docs/api/storage/index.rst rename to docs/api-reference/storage/index.rst diff --git a/docs/api/storage/nvs_flash.rst b/docs/api-reference/storage/nvs_flash.rst similarity index 100% rename from docs/api/storage/nvs_flash.rst rename to docs/api-reference/storage/nvs_flash.rst diff --git a/docs/api/storage/sdmmc.rst b/docs/api-reference/storage/sdmmc.rst similarity index 100% rename from docs/api/storage/sdmmc.rst rename to docs/api-reference/storage/sdmmc.rst diff --git a/docs/api/storage/spi_flash.rst b/docs/api-reference/storage/spi_flash.rst similarity index 95% rename from docs/api/storage/spi_flash.rst rename to docs/api-reference/storage/spi_flash.rst index c42aedb4b..c43af4d8c 100644 --- a/docs/api/storage/spi_flash.rst +++ b/docs/api-reference/storage/spi_flash.rst @@ -3,8 +3,8 @@ See also -------- -- :doc:`Partition Table documentation ` -- :doc:`Over The Air Update (OTA) API ` 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 ` provides a structured API for storing small items of data in SPI flash. API Reference diff --git a/docs/api/storage/vfs.rst b/docs/api-reference/storage/vfs.rst similarity index 100% rename from docs/api/storage/vfs.rst rename to docs/api-reference/storage/vfs.rst diff --git a/docs/api/storage/wear-levelling.rst b/docs/api-reference/storage/wear-levelling.rst similarity index 82% rename from docs/api/storage/wear-levelling.rst rename to docs/api-reference/storage/wear-levelling.rst index 71bb3d4b6..0766087df 100644 --- a/docs/api/storage/wear-levelling.rst +++ b/docs/api-reference/storage/wear-levelling.rst @@ -3,8 +3,8 @@ See also -------- -- :doc:`FAT Filesystem ` -- :doc:`Partition Table documentation ` +- :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 ^^^^^^^^^^^^ diff --git a/docs/api/system/deep_sleep.rst b/docs/api-reference/system/deep_sleep.rst similarity index 100% rename from docs/api/system/deep_sleep.rst rename to docs/api-reference/system/deep_sleep.rst diff --git a/docs/api/system/index.rst b/docs/api-reference/system/index.rst similarity index 100% rename from docs/api/system/index.rst rename to docs/api-reference/system/index.rst diff --git a/docs/api/system/intr_alloc.rst b/docs/api-reference/system/intr_alloc.rst similarity index 100% rename from docs/api/system/intr_alloc.rst rename to docs/api-reference/system/intr_alloc.rst diff --git a/docs/api/system/log.rst b/docs/api-reference/system/log.rst similarity index 100% rename from docs/api/system/log.rst rename to docs/api-reference/system/log.rst diff --git a/docs/api/system/mem_alloc.rst b/docs/api-reference/system/mem_alloc.rst similarity index 100% rename from docs/api/system/mem_alloc.rst rename to docs/api-reference/system/mem_alloc.rst diff --git a/docs/api/system/ota.rst b/docs/api-reference/system/ota.rst similarity index 87% rename from docs/api/system/ota.rst rename to docs/api-reference/system/ota.rst index eaabeae3a..0ecb01d4e 100644 --- a/docs/api/system/ota.rst +++ b/docs/api-reference/system/ota.rst @@ -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 ` 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 ` +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 ` -* :doc:`Lower-Level SPI Flash/Partition API ` +* :doc:`Partition Table documentation <../../api-guides/partition-tables>` +* :doc:`Lower-Level SPI Flash/Partition API <../storage/spi_flash>` Application Example ------------------- diff --git a/docs/api/system/wdts.rst b/docs/api-reference/system/wdts.rst similarity index 100% rename from docs/api/system/wdts.rst rename to docs/api-reference/system/wdts.rst diff --git a/docs/api/template.rst b/docs/api-reference/template.rst similarity index 93% rename from docs/api/template.rst rename to docs/api-reference/template.rst index 3cc8713ba..931ead75e 100644 --- a/docs/api/template.rst +++ b/docs/api-reference/template.rst @@ -1,5 +1,5 @@ -Template -======== +API Documentation Template +========================== .. note:: @@ -7,7 +7,7 @@ Template 1. Use this file as a template to document API. 2. Change the file name to the name of the header file that represents documented API. - 3. Include respective files with descriptions from the API folder using ``..include::`` + 3. Include respective files with descriptions from the API folder using ``..include::`` * README.rst * example.rst @@ -69,7 +69,7 @@ API Reference See `Breathe documentation `_ 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 ^^^^^^^^^^^^ diff --git a/docs/api/wifi/esp_smartconfig.rst b/docs/api-reference/wifi/esp_smartconfig.rst similarity index 100% rename from docs/api/wifi/esp_smartconfig.rst rename to docs/api-reference/wifi/esp_smartconfig.rst diff --git a/docs/api/wifi/esp_wifi.rst b/docs/api-reference/wifi/esp_wifi.rst similarity index 100% rename from docs/api/wifi/esp_wifi.rst rename to docs/api-reference/wifi/esp_wifi.rst diff --git a/docs/api/wifi/index.rst b/docs/api-reference/wifi/index.rst similarity index 100% rename from docs/api/wifi/index.rst rename to docs/api-reference/wifi/index.rst diff --git a/docs/contributor-agreement.rst b/docs/contribute/contributor-agreement.rst similarity index 100% rename from docs/contributor-agreement.rst rename to docs/contribute/contributor-agreement.rst diff --git a/docs/documenting-code.rst b/docs/contribute/documenting-code.rst similarity index 59% rename from docs/documenting-code.rst rename to docs/contribute/documenting-code.rst index a201dafb8..8df56e643 100644 --- a/docs/documenting-code.rst +++ b/docs/contribute/documenting-code.rst @@ -3,27 +3,27 @@ Documenting Code The purpose of this description is to provide quick summary on documentation style used in `espressif/esp-idf`_ repository and how to add new documentation. + Introduction ------------ -When documenting code for this repository, please follow `Doxygen style `_. You are doing it by inserting special commands, for instance ``@param``, into standard comments blocks, for example: +When documenting code for this repository, please follow `Doxygen style `_. You are doing it by inserting special commands, for instance ``@param``, into standard comments blocks, for example: :: -:: - - /** - * @param ratio this is oxygen to air ratio - */ + /** + * @param ratio this is oxygen to air ratio + */ Doxygen is phrasing the code, extracting the commands together with subsequent text, and building documentation out of it. Typical comment block, that contains documentation of a function, looks like below. -.. image:: _static/doc-code-documentation-inline.png - :align: center - :alt: Sample inline code documentation +.. image:: ../_static/doc-code-documentation-inline.png + :align: center + :alt: Sample inline code documentation Doxygen supports couple of formatting styles. It also gives you great flexibility on level of details to include in documentation. To get familiar with available features, please check data reach and very well organized `Doxygen Manual `_. + Why we need it? --------------- @@ -31,9 +31,10 @@ The ultimate goal is to ensure that all the code is consistently documented, so With these tools the above piece of code renders like below: -.. image:: _static/doc-code-documentation-rendered.png - :align: center - :alt: Sample inline code after rendering +.. image:: ../_static/doc-code-documentation-rendered.png + :align: center + :alt: Sample inline code after rendering + Go for it! ---------- @@ -46,26 +47,23 @@ When writing code for this repository, please follow guidelines below. 3. Do not add a data type before parameter or any other characters besides spaces. All spaces and line breaks are compressed into a single space. If you like to break a line, then break it twice. - .. image:: _static/doc-code-function.png - :align: center - :alt: Sample function documented inline and after rendering + .. image:: ../_static/doc-code-function.png + :align: center + :alt: Sample function documented inline and after rendering 4. If function has void input or does not return any value, then skip ``@param`` or ``@return`` - .. image:: _static/doc-code-void-function.png - :align: center - :alt: Sample void function documented inline and after rendering + .. image:: ../_static/doc-code-void-function.png + :align: center + :alt: Sample void function documented inline and after rendering 5. When documenting a ``define`` as well as members of a ``struct`` or ``enum``, place specific comment like below after each member. - .. image:: _static/doc-code-member.png - :align: center - :alt: Sample of member documentation inline and after rendering + .. image:: ../_static/doc-code-member.png + :align: center + :alt: Sample of member documentation inline and after rendering - -6. To provide well formatted lists, break the line after command (like ``@return`` in example below). - - :: +6. To provide well formatted lists, break the line after command (like ``@return`` in example below). :: * * @return @@ -78,14 +76,13 @@ When writing code for this repository, please follow guidelines below. 7. Overview of functionality of documented header file, or group of files that make a library, should be placed in the same directory in a separate ``README.rst`` file. If directory contains header files for different APIs, then the file name should be ``apiname-readme.rst``. + Go one extra mile ----------------- There is couple of tips, how you can make your documentation even better and more useful to the reader. -1. Add code snippets to illustrate implementation. To do so, enclose snippet using ``@code{c}`` and ``@endcode`` commands. - - :: +1. Add code snippets to illustrate implementation. To do so, enclose snippet using ``@code{c}`` and ``@endcode`` commands. :: * * @code{c} @@ -98,11 +95,9 @@ There is couple of tips, how you can make your documentation even better and mor * @endcode * - The code snippet should be enclosed in a comment block of the function that it illustrates. + The code snippet should be enclosed in a comment block of the function that it illustrates. -2. To highlight some important information use command ``@attention`` or ``@note``. - - :: +2. To highlight some important information use command ``@attention`` or ``@note``. :: * * @attention @@ -112,9 +107,7 @@ There is couple of tips, how you can make your documentation even better and mor Above example also shows how to use a numbered list. -3. Use markdown to make your documentation even more readable. You will add headers, links, tables and more. - - :: +3. Use markdown to make your documentation even more readable. You will add headers, links, tables and more. :: * * [ESP32 Technical Reference](http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf) @@ -122,24 +115,52 @@ There is couple of tips, how you can make your documentation even better and mor .. note:: - Code snippets, notes, links, etc. will not make it to the documentation, if not enclosed in a comment block associated with one of documented objects. + Code snippets, notes, links, etc. will not make it to the documentation, if not enclosed in a comment block associated with one of documented objects. + +4. Prepare one or more complete code examples together with description. Place description in a separate file ``README.md`` in specific folder of :idf:`examples` directory. + + +Linking Examples +---------------- + +When linking to examples on GitHub do not use absolute / hadcoded URLs. Instead, use docutils custom roles that will generate links for you. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links do not get broken when files in master branch are moved around or deleted. + +The following roles are provided: + +- ``:idf:`path``` - points to directory inside ESP-IDF +- ``:idf_blob:`path``` - points to file inside ESP-IDF +- ``:idf_raw:`path``` - points to raw view of the file inside ESP-IDF +- ``:component:`path``` - points to directory inside ESP-IDF components dir +- ``:component_blob:`path``` - points to file inside ESP-IDF components dir +- ``:component_raw:`path``` - points to raw view of the file inside ESP-IDF components dir +- ``:example:`path``` - points to directory inside ESP-IDF examples dir +- ``:example_blob:`path``` - points to file inside ESP-IDF examples dir +- ``:example_raw:`path``` - points to raw view of the file inside ESP-IDF examples dir + +A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: ``cd docs`` and then ``make gh-linkcheck``. -5. Prepare one or more complete code examples together with description. Place them in a separate file ``example.rst`` in the same directory as the API header files. If directory contains header files for different APIs, then the file name should be ``apiname-example.rst``. Put it all together ------------------- -Once all the above steps are complete, follow instruction in :doc:`api/template` and create a single file, that will merge all individual pieces of prepared documentation. Finally add a link to this file to respective ``.. toctree::`` in ``index.rst`` file located in ``/docs`` folder. +Once documentation is ready, follow instruction in :doc:`../api-reference/template` and create a single file, that will merge all individual pieces of prepared documentation. Finally add a link to this file to respective ``.. toctree::`` in ``index.rst`` file located in ``/docs`` folder or subfolders. + OK, but I am new to Sphinx! --------------------------- 1. No worries. All the software you need is well documented. It is also open source and free. Start by checking `Sphinx `_ documentation. If you are not clear how to write using rst markup language, see `reStructuredText Primer `_. + 2. Check the source files of this documentation to understand what is behind of what you see now on the screen. Sources are maintained on GitHub in `espressif/esp-idf`_ repository in :idf:`docs` folder. You can go directly to the source file of this page by scrolling up and clicking the link in the top right corner. When on GitHub, see what's really inside, open source files by clicking ``Raw`` button. + 3. You will likely want to see how documentation builds and looks like before posting it on the GitHub. There are two options to do so: - * Install `Sphinx `_, `Breathe `_ and `Doxygen `_ to build it locally. You would need a Linux machine for that. - * Set up an account on `Read the Docs `_ and build documentation in the cloud. Read the Docs provides document building and hosting for free and their service works really quick and great. + * Install `Sphinx `_, `Breathe `_ and `Doxygen `_ to build it locally. You would need a Linux machine for that. + + * Set up an account on `Read the Docs `_ and build documentation in the cloud. Read the Docs provides document building and hosting for free and their service works really quick and great. + +4. To preview documentation before building use `Sublime Text `_ editor together with `OmniMarkupPreviewer `_ plugin. + Wrap up ------- diff --git a/docs/contribute/index.rst b/docs/contribute/index.rst new file mode 100644 index 000000000..ac7b6bcf3 --- /dev/null +++ b/docs/contribute/index.rst @@ -0,0 +1 @@ +.. include:: ../../CONTRIBUTING.rst diff --git a/docs/style-guide.rst b/docs/contribute/style-guide.rst similarity index 100% rename from docs/style-guide.rst rename to docs/contribute/style-guide.rst diff --git a/docs/contributing.rst b/docs/contributing.rst deleted file mode 100644 index 3bdd7dc21..000000000 --- a/docs/contributing.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../CONTRIBUTING.rst \ No newline at end of file diff --git a/docs/get-started/add-idf_path-to-profile.rst b/docs/get-started/add-idf_path-to-profile.rst new file mode 100644 index 000000000..51c044496 --- /dev/null +++ b/docs/get-started/add-idf_path-to-profile.rst @@ -0,0 +1,59 @@ +Add IDF_PATH to User Profile +============================ + +To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below. + + +.. _add-idf_path-to-profile-windows: + +Windows +------- + +The user profile scripts are contained in ``C:/msys32/etc/profile.d/`` directory. They are executed every time you open an MSYS2 window. + +#. Create a new script file in ``C:/msys32/etc/profile.d/`` directory. Name it ``export_idf_path.sh``. + +#. Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like ``C:\msys32\home\Krzysztof\esp\esp-idf`` + +#. Add the ``export`` command to the script file, e.g.:: + + export IDF_PATH="C:/msys32/home/Krzysztof/esp/esp-idf" + + Remember to replace back-slashes with forward-slashes in the original Windows path. + +#. Save the script file. + +#. Close MSYS2 window and open it again. Check if ``IDF_PATH`` is set, by typing:: + + printenv IDF_PATH + + The path previusly entered in the script file should be printed out. + +If you do not like to have ``IDF_PATH`` set up permanently in user profile, you should enter it manually on opening of an MSYS2 window:: + + export IDF_PATH="C:/msys32/home/Krzysztof/esp/esp-idf" + +If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`. + + +.. _add-idf_path-to-profile-linux-macos: + +Linux and MacOS +--------------- + +Set up ``IDF_PATH`` by adding the following line to ``~/.bash`` file: :: + + export IDF_PATH=~/esp/esp-idf + +Log off and log in back to make this change effective. + +If you do not like to have ``IDF_PATH`` set up permanently, you should enter it manually in terminal window on each restart or logout. + +Run the following command to check if ``IDF_PATH`` is set:: + + printenv IDF_PATH + +The path previously entered in ``~/.bash`` file (or set manually) should be printed out. + + +If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`. diff --git a/docs/eclipse-setup-windows.rst b/docs/get-started/eclipse-setup-windows.rst similarity index 92% rename from docs/eclipse-setup-windows.rst rename to docs/get-started/eclipse-setup-windows.rst index aeb011c0c..f8bec31e6 100644 --- a/docs/eclipse-setup-windows.rst +++ b/docs/get-started/eclipse-setup-windows.rst @@ -1,3 +1,4 @@ +********************** Eclipse IDE on Windows ********************** @@ -51,7 +52,7 @@ Project Properties * Edit the PATH environment variable. Delete the existing value and replace it with ``C:\msys32\usr\bin;C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin`` (If you installed msys32 to a different directory then you'll need to change these paths to match). -* Click on "C/C++ General" -> "Preprocessor Include Paths, Macros,etc." property page: +* Click on "C/C++ General" -> "Preprocessor Include Paths, Macros, etc." property page: * Click the "Providers" tab @@ -70,8 +71,8 @@ Technical Details **Of interest to Windows gurus or very curious parties, only.** -Explanations of the technical reasons for some of these steps. You don't need to know this in order to use esp-idf with Eclipse on Windows, but it may be helpful background knowledge if you plan to do dig into the Eclipse support: +Explanations of the technical reasons for some of these steps. You don't need to know this to use esp-idf with Eclipse on Windows, but it may be helpful background knowledge if you plan to do dig into the Eclipse support: * The xtensa-esp32-elf-gcc cross-compiler is *not* a Cygwin toolchain, even though we tell Eclipse that it is one. This is because msys2 uses Cygwin and supports Cygwin paths (of the type ``/c/blah`` instead of ``c:/blah`` or ``c:\\blah``). In particular, xtensa-esp32-elf-gcc reports to the Eclipse "built-in compiler settings" function that its built-in include directories are all under ``/usr/``, which is a Unix/Cygwin-style path that Eclipse otherwise can't resolve. By telling Eclipse the compiler is Cygwin, it resolves these paths internally using the ``cygpath`` utility. -* The same problem occurs when parsing make output from esp-idf. Eclipse parses this output to find header directories, but it can't resolve include directories of the form ``/c/blah`` without using ``cygpath``. There is a heuristic that Eclipse Build Output Parser uses to determine whether it should call ``cygpath``, but for currently unknown reasons the esp-idf configuration doesn't trigger it. For this reason the ``eclipse_make.py`` wrapper script is used to call ``make`` and then use ``cygpath`` to process the output for Eclipse. +* The same problem occurs when parsing make output from esp-idf. Eclipse parses this output to find header directories, but it can't resolve include directories of the form ``/c/blah`` without using ``cygpath``. There is a heuristic that Eclipse Build Output Parser uses to determine whether it should call ``cygpath``, but for currently unknown reasons the esp-idf configuration doesn't trigger it. For this reason, the ``eclipse_make.py`` wrapper script is used to call ``make`` and then use ``cygpath`` to process the output for Eclipse. diff --git a/docs/eclipse-setup.rst b/docs/get-started/eclipse-setup.rst similarity index 94% rename from docs/eclipse-setup.rst rename to docs/get-started/eclipse-setup.rst index aa53d171e..d95dee8be 100644 --- a/docs/eclipse-setup.rst +++ b/docs/get-started/eclipse-setup.rst @@ -1,3 +1,4 @@ +******************************** Build and Flash with Eclipse IDE ******************************** @@ -76,7 +77,7 @@ Before your project is first built, Eclipse may show a lot of errors and warning * Back in Eclipse, choose Project -> Build to build your project. -**TIP**: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before chosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths. +**TIP**: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before choosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths. Flash from Eclipse ------------------ @@ -95,5 +96,14 @@ Note that you will need to use "make menuconfig" to set the serial port and othe Follow the same steps to add ``bootloader`` and ``partition_table`` targets, if necessary. +Related Documents +----------------- + +.. toctree:: + :maxdepth: 1 + + eclipse-setup-windows + + .. _eclipse.org: http://www.eclipse.org/ diff --git a/docs/get-started/establish-serial-connection.rst b/docs/get-started/establish-serial-connection.rst new file mode 100644 index 000000000..b7bc026fc --- /dev/null +++ b/docs/get-started/establish-serial-connection.rst @@ -0,0 +1,108 @@ +Establish Serial Connection with ESP32 +====================================== + +This section provides guidance how to establish serial connection between ESP32 and PC. + + +Connect ESP32 to PC +-------------------- + +Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and install them. + +Below are the links to drivers for ESP32 boards produced by Espressif: + +* ESP32 Core Board - `CP210x USB to UART Bridge VCP Drivers `_ + +* ESP32 WROVER KIT and ESP32 Demo Board - `FTDI Virtual COM Port Drivers `_ + + +Check port on Windows +--------------------- + +Check the list of identified COM ports in the Windows Device Manager. Disconnect ESP32 and connect it back, to verify which port disappears from the list and then shows back again. + +Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT + +.. figure:: ../_static/esp32-devkitc-in-device-manager.png + :align: center + :alt: USB to UART bridge of ESP32-DevKitC in Windows Device Manager + :figclass: align-center + + USB to UART bridge of ESP32-DevKitC in Windows Device Manager + +.. figure:: ../_static/esp32-wrover-kit-in-device-manager.png + :align: center + :alt: Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager + :figclass: align-center + + Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager + + +Check port on Linux and MacOS +----------------------------- + +To check the device name for the serial port of your ESP32 board (or external converter dongle), run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need: + +Linux :: + + ls /dev/tty* + +MacOS :: + + ls /dev/tty.* + + +Verify serial connection +------------------------ + +Now verify is serial connection is operational. You can do it using a serial terminal program. In this example we will use `PuTTY SSH Client `_ that is avilable for both Windows and Linux. You can use other serial program and set communication parameters like below. + +Run terminal, set identified serial port, baud rate = 115200, data bits = 8, stop bits = 1, and parity = N. Below are example screen shoots of setting the port and such transmission parameters (in short described as 115200-8-1-N) on Windows and Linux. Remember to select exactly the same serial port you have identified in steps above. + +.. figure:: ../_static/putty-settings-windows.png + :align: center + :alt: Setting Serial Communication in PuTTY on Windows + :figclass: align-center + + Setting Serial Communication in PuTTY on Windows + +.. figure:: ../_static/putty-settings-linux.png + :align: center + :alt: Setting Serial Communication in PuTTY on Linux + :figclass: align-center + + Setting Serial Communication in PuTTY on Linux + + +Then open serial port in terminal and check, if you see any log printed out by ESP32. The log contents will depend on application loaded to ESP32. An example log by ESP32 is shown below. + +.. highlight:: none + +:: + + ets Jun 8 2016 00:22:57 + + rst:0x5 (DEEPSLEEP_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) + ets Jun 8 2016 00:22:57 + + rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) + configsip: 0, SPIWP:0x00 + clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 + mode:DIO, clock div:2 + load:0x3fff0008,len:8 + load:0x3fff0010,len:3464 + load:0x40078000,len:7828 + load:0x40080000,len:252 + entry 0x40080034 + I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader + I (45) boot: compile time 18:48:10 + + ... + +If you see some legible log, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32. + +.. note:: + + Close serial terminal after verification that communication is working. In next step we are going to use another application to upload ESP32. This application will not be able to access serial port while it is open in terminal. + +If you got here from section :ref:`get-started-connect` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure`. diff --git a/docs/get-started/get-started-devkitc.rst b/docs/get-started/get-started-devkitc.rst new file mode 100644 index 000000000..e27661051 --- /dev/null +++ b/docs/get-started/get-started-devkitc.rst @@ -0,0 +1,63 @@ +ESP32-DevKitC Getting Started Guide +=================================== + +This user guide shows how to get started with ESP32-DevKitC development board. + + +What You Need +------------- + +* 1 × ESP32-DevKitC board +* 1 × USB A / mini USB B cable +* 1 × PC loaded with Windows, Linux or Mac O/S + + +Overview +-------- + +ESP32-DevKitC is a small-sized ESP32-based development board produced by `Espressif `_. Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing. Developers can connect these pins to peripherals as needed. Standard headers also make development easy and convenient when using a breadboard. + + +Functional Description +---------------------- + +The following list and figure below describe key components, interfaces and controls of ESP32-DevKitC board. + +ESP-WROOM-32 + Standard `ESP-WROOM-32 `_ module soldered to the ESP32-DevKitC board. +EN + Reset button: pressing this button resets the system. +Boot + Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port. +USB + USB interface. It functions as the power supply for the board and the communication interface between PC and ESP-WROOM-32. +I/O + Most of the pins on the ESP-WROOM-32 are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM,ADC, DAC, I2C, I2S, SPI, etc. + +.. figure:: ../_static/esp32-devkitc-functional-overview.png + :align: center + :alt: ESP32-DevKitC board layout + :figclass: align-center + + ESP32-DevKitC board layout + + +Start Application Development +------------------------------ + +Before powering up the ESP32-DevKitC, please make sure that the board has been received in good condition with no obvious signs of damage. + +To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps: + +* :ref:`get-started-setup-toochain` in your PC to develop applications for ESP32 in C language +* :ref:`get-started-connect` the module to the PC and verify if it is accessible +* :ref:`get-started-build-flash` an example application to the ESP32 +* :ref:`get-started-build-monitor` instantly what the application is doing + + +Related Documents +----------------- + +* `ESP32-DevKitC schematic `_ (PDF) +* `ESP32 Datasheet `_ (PDF) +* `ESP-WROOM-32 Datasheet `_ (PDF) diff --git a/docs/get-started/get-started-wrover-kit.rst b/docs/get-started/get-started-wrover-kit.rst new file mode 100644 index 000000000..287a27a5a --- /dev/null +++ b/docs/get-started/get-started-wrover-kit.rst @@ -0,0 +1,196 @@ +ESP-WROVER-KIT Getting Started Guide +==================================== + +This user guide shows how to get started with ESP-WROVER-KIT development board. + + +What You Need +------------- + +* 1 × ESP-WROVER-KIT board +* 1 × USB A / mini USB B cable +* 1 × PC loaded with Windows, Linux or Mac O/S + + +The Board +--------- + +This section describes functionality of ESP-WROVER-KIT board and configuration options. If you like to start using it now, go directly to section :ref:`esp-wrover-start-developement` + + +Overview +^^^^^^^^ + +The ESP-WROVER-KIT is a development board produced by `Espressif `_ built around ESP32. This board is compatible with ESP32 modules, including the ESP-WROOM-32 and ESP32-WROVER. The ESP-WROVER-KIT features support for an LCD and MicroSD card. The I/O pins have been broken out from the ESP32 module for easy extension. The board carries an advanced multi-protocol USB bridge (the FTDI FT2232HL), enabling developers to use JTAG directly to debug the ESP32 through the USB interface. The development board makes secondary development easy and cost-effective. + +.. note:: + + ESP-WROVER-KIT integrates the ESP-WROOM-32 module by default. + + +Functionality Overview +^^^^^^^^^^^^^^^^^^^^^^ + +Block diagram below presents main components of ESP-WROVER-KIT and interconnections between components. + +.. figure:: ../_static/esp32-wrover-kit-block-diagram.png + :align: center + :alt: ESP-WROVER-KIT block diagram + :figclass: align-center + + ESP-WROVER-KIT block diagram + + +Functional Description +^^^^^^^^^^^^^^^^^^^^^^ + +The following list and figures below describe key components, interfaces and controls of ESP-WROVER-KIT board. + +32.768 kHz + An external precision 32.768 kHz crystal oscillator provides the chip with a clock of low-power consumption during the Deep-sleep mode. +ESP32 Module + ESP-WROVER-KIT is compatible with both ESP-WROOM-32 and ESP32-WROVER. The ESP32-WROVER module features all the functions of ESP-WROOM-32 and integrates an external 32-MBit PSRAM for flexible extended storage and data processing capabilities. + + .. note:: + + GPIO16 and GPIO17 are used as the CS and clock signal for PSRAM. To ensure reliable performance, the two GPIOs are not broken out. + +CTS/RTS + Serial port flow control signals: the pins are not connected to the circuitry by default. To enable them, respective pins of JP14 must be shorted with jumpers. +UART + Serial port: the serial TX/RX signals on FT2232HL and ESP32 are broken out to the two sides of JP11. By default, the two signals are connected with jumpers. To use the ESP32 module serial interface only, the jumpers may be removed and the module can be connected to another external serial device. +SPI + SPI interface: the SPI interface connects to an external flash (PSRAM). To interface another SPI device, an extra CS signal is needed. If an ESP32-WROVER is being used, please note that the electrical level on the flash and SRAM is 1.8V. +JTAG + JTAG interface: the JTAG signals on FT2232HL and ESP32 are broken out to the two sides of JP8. By default, the two signals are disconnected. To enable JTAG, shorting jumpers are required on the signals. +FT2232 + FT2232 chip is a multi-protocol USB-to-serial bridge. The FT2232 chip features USB-to-UART and USB-to-JTAG functionalities. Users can control and program the FT2232 chip through the USB interface to establish communication with ESP32. + + The embedded FT2232 chip is one of the distinguishing features of the ESPWROVER-KIT. It enhances users’ convenience in terms of application development and debugging. In addition, uses do not need to buy a JTAG debugger separately, which reduces the development cost. The schematics is provided in section :ref:`wrover-kit-related-documents`. +EN + Reset button: pressing this button resets the system. +Boot + Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port. +USB + USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32 module. +Power Select + Power supply selection interface: the ESP-WROVER-KIT can be powered through the USB interface or the 5V Input interface. The user can select the power supply with a jumper. More details can be found in section :ref:`esp-wrover-setup-options`, jumper header JP7. +Power Key + Power on/off button: toggling to the right powers the board on; toggling to the left powers the board off. +5V Input + The 5V power supply interface is used as a backup power supply in case of full-load operation. +LDO + NCP1117(1A). 5V-to-3.3V LDO. (There is an alternative pin-compatible LDO — LM317DCY, with an output current of up to 1.5A). NCP1117 can provide a maximum current of 1A. The LDO solutions are available with both fixed output voltage and variable output voltage. For details please refer to `ESP-WROVER-KIT schematic`_. +Camera + Camera interface: a standard OV7670 camera module is supported. +RGB + Red, green and blue (RGB) light emitting diodes (LEDs), which may be controlled by pulse width modulation (PWM). +I/O + All the pins on the ESP32 module are led out to the pin headers on the ESPWROVER-KIT. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc. + +Micro SD Card + Micro SD card slot for data storage: when ESP32 enters the download mode, GPIO2 cannot be held high. However, a pull-up resistor is required on GPIO2 to enable the Micro SD Card. By default, GPIO2 and the pull-up resistor R153 are disconnected. To enable the SD Card, use jumpers on JP1 as shown in section :ref:`esp-wrover-setup-options`. +LCD + ESP-WROVER-KIT supports mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`esp-wrover-board-back`. + +.. figure:: ../_static/esp32-wrover-kit-layout-front.png + :align: center + :alt: ESP-WROVER-KIT board layout - front + :figclass: align-center + + ESP-WROVER-KIT board layout - front + +.. _esp-wrover-board-back: + +.. figure:: ../_static/esp32-wrover-kit-layout-back.png + :align: center + :alt: ESP-WROVER-KIT board layout - back + :figclass: align-center + + ESP-WROVER-KIT board layout - back + + +.. _esp-wrover-setup-options: + +Setup Options +^^^^^^^^^^^^^ + +There are five jumper headers available to set up the board functionality. Typical options to select from are listed in table below. + ++--------+----------------------+-------------------------------------------------+ +| Header | Jumper Setting | Description of Functionality | ++--------+----------------------+-------------------------------------------------+ +| JP1 | |jp1-sd_io2| | Enable pull up for the Micro SD Card | ++--------+----------------------+-------------------------------------------------+ +| JP1 | |jp1-both| | Assert GPIO2 low during each download | +| | | (by jumping it to GPIO0) | ++--------+----------------------+-------------------------------------------------+ +| JP7 | |jp7-ext_5v| | Power ESP-WROVER-KIT board from an external | +| | | power supply | ++--------+----------------------+-------------------------------------------------+ +| JP7 | |jp7-usb_5v| | Power ESP-WROVER-KIT board from an USB port | ++--------+----------------------+-------------------------------------------------+ +| JP8 | |jp8| | Enable JTAG functionality | ++--------+----------------------+-------------------------------------------------+ +| JP11 | |jp11-rx-tx| | Enable UART communication | ++--------+----------------------+-------------------------------------------------+ +| JP14 | |jp14| | Enable RTS/CTS flow control for serial | +| | | communication | ++--------+----------------------+-------------------------------------------------+ + + +.. _esp-wrover-start-developement: + +Start Application Development +----------------------------- + +Before powering up the ESP-WROVER-KIT, please make sure that the board has been received in good condition with no obvious signs of damage. + + +Initial Setup +^^^^^^^^^^^^^ + +Select the source of power supply for the board by setting jumper JP7. The options are either USB port or an external power supply. For this application selection of USB port is sufficient. Enable UART communication by installing jumpers on JP11. Both selections are shown in table below. + ++----------------------+----------------------+ +| Power up | Enable UART | +| from USB port | communication | ++----------------------+----------------------+ +| |jp7-usb_5v| | |jp11-rx-tx| | ++----------------------+----------------------+ + +Do not install any other jumpers. + + +Now to Development +^^^^^^^^^^^^^^^^^^ + +To start development of applications for ESP32-DevKitC, proceed to section :doc:`index`, that will walk you through the following steps: + +* :ref:`get-started-setup-toochain` in your PC to develop applications for ESP32 in C language +* :ref:`get-started-connect` the module to the PC and verify if it is accessible +* :ref:`get-started-build-flash` an example application to the ESP32 +* :ref:`get-started-build-monitor` instantly what the application is doing + + +.. _wrover-kit-related-documents: + +Related Documents +----------------- + +* `ESP-WROVER-KIT schematic`_ (PDF) +* `ESP32 Datasheet `_ (PDF) +* `ESP-WROOM-32 Datasheet `_ (PDF) +* `JTAG Debugging for ESP32 `_ (PDF) + + + +.. |jp1-sd_io2| image:: ../_static/wrover-jp1-sd_io2.png +.. |jp1-both| image:: ../_static/wrover-jp1-both.png +.. |jp7-ext_5v| image:: ../_static/wrover-jp7-ext_5v.png +.. |jp7-usb_5v| image:: ../_static/wrover-jp7-usb_5v.png +.. |jp8| image:: ../_static/wrover-jp8.png +.. |jp11-rx-tx| image:: ../_static/wrover-jp11-tx-rx.png +.. |jp14| image:: ../_static/wrover-jp14.png + +.. _ESP-WROVER-KIT schematic: http://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf diff --git a/docs/idf-monitor.rst b/docs/get-started/idf-monitor.rst similarity index 99% rename from docs/idf-monitor.rst rename to docs/get-started/idf-monitor.rst index 61dfd0afd..469985bc0 100644 --- a/docs/idf-monitor.rst +++ b/docs/get-started/idf-monitor.rst @@ -1,3 +1,4 @@ +*********** IDF Monitor *********** @@ -17,6 +18,8 @@ Automatically Decoding Addresses Any time esp-idf prints a hexadecimal code address of the form ``0x4_______``, idf_monitor will use addr2line_ to look up the source code location and function name. +.. highlight:: none + When an esp-idf app crashes and panics a register dump and backtrace such as this is produced:: Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled. diff --git a/docs/get-started/index.rst b/docs/get-started/index.rst new file mode 100644 index 000000000..9eee8424d --- /dev/null +++ b/docs/get-started/index.rst @@ -0,0 +1,312 @@ +*********** +Get Started +*********** + +To develop applications for ESP32 you need: + +* **PC** loaded with either Windows, Linux or Mac operating system +* **Toolchain** to build the **Application** for ESP32 +* **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain** +* A text editor to write programs (**Projects**) in C, e.g. `Eclipse `_ +* **ESP32** board itself + +.. figure:: ../_static/what-you-need.png + :align: center + :alt: Development of applications for ESP32 + :figclass: align-center + + Development of applications for ESP32 + +Preparation of development environment consists of three steps: + +1. Setup of **Toolchain** +2. Getting of **ESP-IDF** from GitHub +3. Installation and configuration of **Eclipse** + +You may skip the last step, if you prefer to use different editor. + +Having environment set up, you are ready to start the most interesting part - the application development. This process may be summarized in four steps: + +1. Configuration of a **Project** and writing the code +2. Compilation of the **Project** and linking it to build an **Application** +3. Flashing (uploading) of the **Application** to **ESP32** +4. Monitoring / debugging of the **Application** + +See instructions below that will walk you through these steps. + + +Guides +====== + +If you have one of ESP32 development boards listed below, click on provided links to get you up and running. + +.. toctree:: + :maxdepth: 1 + + ESP32 DevKitC + ESP-WROVER-KIT + +If you have different board, move to sections below. + + +.. _get-started-setup-toochain: + +Setup Toolchain +=============== + +Depending on your experience and preferences, you may follow standard installation process or customize your environment. Instructions immediately below are for standard installation. To set up the system your own way go to section :ref:`get-started-customized-setup`. + + +.. _get-started-standard-setup: + +Standard Setup of Toolchain +--------------------------- + +The quickest way to start development with ESP32 is by installing prebuild toolchain. Pick up your O/S below and follow provided instructions. + + +.. toctree:: + :hidden: + + Windows + Linux + MacOS + ++-------------------+-------------------+-------------------+ +| |windows-logo| | |linux-logo| | |macos-logo| | ++-------------------+-------------------+-------------------+ +| `Windows`_ | `Linux`_ | `Mac OS`_ | ++-------------------+-------------------+-------------------+ + +.. |windows-logo| image:: ../_static/windows-logo.png + :target: ../get-started/windows-setup.html + +.. |linux-logo| image:: ../_static/linux-logo.png + :target: ../get-started/linux-setup.html + +.. |macos-logo| image:: ../_static/macos-logo.png + :target: ../get-started/macos-setup.html + +.. _Windows: ../get-started/windows-setup.html +.. _Linux: ../get-started/linux-setup.html +.. _Mac OS: ../get-started/macos-setup.html + +.. note:: + + We are using ``~/esp`` directory to install prebuild toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands. + +Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf`. + + +.. highlight:: bash + +.. _get-started-customized-setup: + +Customized Setup of Toolchain +----------------------------- + +Instead of downloading binary toolchain from Espressif website (:ref:`get-started-standard-setup` above) you may build the toolchain yourself. + +If you can't think of a reason why you need to build it yourself, then probably it's better to stick with the binary version. However, here are some of the reasons why you might want to compile it from source: + +- if you want to customize toolchain build configuration + +- if you want to use a different GCC version (such as 4.8.5) + +- if you want to hack gcc or newlib or libstdc++ + +- if you are curious and/or have time to spare + +- if you don't trust binaries downloaded from the Internet + +In any case, here are the instructions to compile the toolchain yourself. + +.. toctree:: + :maxdepth: 1 + + windows-setup-scratch + linux-setup-scratch + macos-setup-scratch + + +.. _get-started-get-esp-idf: + +Get ESP-IDF +=========== + +Once you have the toolchain (that contains programs to compile and build the application) installed, you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository `_. To get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command:: + + cd ~/esp + git clone --recursive https://github.com/espressif/esp-idf.git + +ESP-IDF will be downloaded into ``~/esp/esp-idf``. + +.. note:: + + Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules:: + + cd ~/esp/esp-idf + git submodule update --init + +.. note:: + + While cloning submodules on **Windows** platform, the ``git clone`` command may print some output starting ``': not a valid identifier...``. This is a `known issue `_ but the git clone still succeeds without any problems. + + +.. _get-started-setup-path: + +Setup Path to ESP-IDF +===================== + +The toolchain programs access ESP-IDF using ``IDF_PATH`` environment variable. This variable should be set up on your PC, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` in user profile. To do so, follow instructions specific to :ref:`Windows ` , :ref:`Linux and MacOS ` in section :doc:`add-idf_path-to-profile`. + + +.. _get-started-start-project: + +Start a Project +=============== + +Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. + +Copy :example:`get-started/hello_world` to ``~/esp`` directory:: + + cd ~/esp + cp -r $IDF_PATH/examples/get-started/hello_world . + +You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects. + +.. important:: + + The esp-idf build system does not support spaces in paths to esp-idf or to projects. + + +.. _get-started-connect: + +Connect +======= + +You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step. + + +.. _get-started-configure: + +Configure +========= + +Being in terminal window, go to directory of ``hello_world`` application by typing ``cd ~/esp/hello_world``. Then start project configuration utility ``menuconfig``:: + + cd ~/esp/hello_world + make menuconfig + +If previous steps have been done correctly, the following menu will be displayed: + +.. figure:: ../_static/project-configuration.png + :align: center + :alt: Project configuration - Home window + :figclass: align-center + + Project configuration - Home window + +In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit application by selecting ``< Exit >``. + +Here are couple of tips on navigation and use of ``menuconfig``: + +* Use up & down arrow keys to navigate the menu. +* Use Enter key to go into a submenu, Escape key to go out or to exit. +* Type ``?`` to see a help screen. Enter key exits the help screen. +* Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``" +* Pressing ``?`` while highlighting a configuration item displays help about that item. +* Type ``/`` to search the configuration items. + +.. note:: + + If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``. + + +.. _get-started-build-flash: + +Build and Flash +=============== + +Now you can build and flash the application. Run:: + + make flash + +This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your ESP32 board. + +.. highlight:: none + +:: + + esptool.py v2.0-beta2 + Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)... + esptool.py v2.0-beta2 + Connecting........___ + Uploading stub... + Running stub... + Stub running... + Changing baud rate to 921600 + Changed. + Attaching SPI flash... + Configuring flash size... + Auto-detected Flash size: 4MB + Flash params set to 0x0220 + Compressed 11616 bytes to 6695... + Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)... + Hash of data verified. + Compressed 408096 bytes to 171625... + Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)... + Hash of data verified. + Compressed 3072 bytes to 82... + Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)... + Hash of data verified. + + Leaving... + Hard resetting... + +If there are no issues, at the end of build process, you should see messages describing progress of loading process. Finally, the end module will be reset and "hello_world" application will start. + +If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide `. + +.. _get-started-build-monitor: + +Monitor +======= + +To see if "hello_world" application is indeed running, type ``make monitor``. This command is launching :doc:`IDF Monitor ` application:: + + $ make monitor + MONITOR + --- idf_monitor on /dev/ttyUSB0 115200 --- + --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- + ets Jun 8 2016 00:22:57 + + rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) + ets Jun 8 2016 00:22:57 + ... + +Several lines below, after start up and diagnostic log, you should see "Hello world!" printed out by the application. :: + + ... + Hello world! + Restarting in 10 seconds... + I (211) cpu_start: Starting scheduler on APP CPU. + Restarting in 9 seconds... + Restarting in 8 seconds... + Restarting in 7 seconds... + +To exit monitor use shortcut ``Ctrl+]``. To execute ``make flash`` and ``make monitor`` in one shoot type ``make flash monitor``. Check section :doc:`IDF Monitor ` for handy shortcuts and more details on using this application. + + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + add-idf_path-to-profile + establish-serial-connection + make-project + eclipse-setup + idf-monitor + diff --git a/docs/get-started/linux-setup-scratch.rst b/docs/get-started/linux-setup-scratch.rst new file mode 100644 index 000000000..a44e6521f --- /dev/null +++ b/docs/get-started/linux-setup-scratch.rst @@ -0,0 +1,66 @@ +********************************** +Setup Linux Toolchain from Scratch +********************************** + +The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`. + + +Install Prerequisites +===================== + +To compile with ESP-IDF you need to get the following packages: + +- Ubuntu and Debian:: + + sudo apt-get install git wget make libncurses-dev flex bison gperf python python-serial + +- Arch:: + + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial + + +Compile the Toolchain from Source +================================= + +- Install dependencies: + + - CentOS 7:: + + sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool + + - Ubuntu pre-16.04:: + + sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool + + - Ubuntu 16.04:: + + sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin + + - Debian:: + + TODO + + - Arch:: + + TODO + +Download ``crosstool-NG`` and build it:: + + cd ~/esp + git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git + cd crosstool-NG + ./bootstrap && ./configure --enable-local && make install + +Build the toolchain:: + + ./ct-ng xtensa-esp32-elf + ./ct-ng build + chmod -R u+w builds/xtensa-esp32-elf + +Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup ` to add the toolchain to your ``PATH``. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. diff --git a/docs/get-started/linux-setup.rst b/docs/get-started/linux-setup.rst new file mode 100644 index 000000000..db4182ac7 --- /dev/null +++ b/docs/get-started/linux-setup.rst @@ -0,0 +1,86 @@ +************************************* +Standard Setup of Toolchain for Linux +************************************* + + +Install Prerequisites +===================== + +To compile with ESP-IDF you need to get the following packages: + +- CentOS 7:: + + sudo yum install git wget make ncurses-devel flex bison gperf python pyserial + +- Ubuntu and Debian:: + + sudo apt-get install git wget make libncurses-dev flex bison gperf python python-serial + +- Arch:: + + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial + + +Toolchain Setup +=============== + +ESP32 toolchain for Linux is available for download from Espressif website: + +- for 64-bit Linux: + + https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-61-gab8375a-5.2.0.tar.gz + +- for 32-bit Linux: + + https://dl.espressif.com/dl/xtensa-esp32-elf-linux32-1.22.0-61-gab8375a-5.2.0.tar.gz + +Download this file, then extract it in ``~/esp`` directory:: + + mkdir -p ~/esp + cd ~/esp + tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-61-gab8375a-5.2.0.tar.gz + +.. _setup-linux-toolchain-add-it-to-path: + +The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory. + +To use it, you will need to update your ``PATH`` environment variable in ``~/.bash_profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.bash_profile`` file:: + + export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin + +Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.bash_profile`` file:: + + alias get_esp32="export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin" + +Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``. + + +Arch Linux Users +---------------- + +To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6. + +Backwards compatibility libraries are available in AUR_ for native and lib32 configurations: + +- https://aur.archlinux.org/packages/ncurses5-compat-libs/ +- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/ + +Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. + + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + linux-setup-scratch + + +.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository diff --git a/docs/get-started/macos-setup-scratch.rst b/docs/get-started/macos-setup-scratch.rst new file mode 100644 index 000000000..af36f1118 --- /dev/null +++ b/docs/get-started/macos-setup-scratch.rst @@ -0,0 +1,67 @@ +*************************************** +Setup Toolchain for Mac OS from Scratch +*************************************** + +Install Prerequisites +===================== + +- install pip:: + + sudo easy_install pip + +- install pyserial:: + + sudo pip install pyserial + + +Compile the Toolchain from Source +================================= + +- Install dependencies: + + - Install either MacPorts_ or homebrew_ package manager. MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools. + + .. _homebrew: http://brew.sh/ + .. _MacPorts: https://www.macports.org/install.php + + - with MacPorts:: + + sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake + + - with homebrew:: + + brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake + +Create a case-sensitive filesystem image:: + + hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+" + +Mount it:: + + hdiutil mount ~/esp/crosstool.dmg + +Create a symlink to your work directory:: + + cd ~/esp + ln -s /Volumes/ctng crosstool-NG + +Download ``crosstool-NG`` and build it:: + + cd ~/esp + git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git + cd crosstool-NG + ./bootstrap && ./configure --enable-local && make install + +Build the toolchain:: + + ./ct-ng xtensa-esp32-elf + ./ct-ng build + chmod -R u+w builds/xtensa-esp32-elf + +Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup ` to add the toolchain to your ``PATH``. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. diff --git a/docs/get-started/macos-setup.rst b/docs/get-started/macos-setup.rst new file mode 100644 index 000000000..328e4f225 --- /dev/null +++ b/docs/get-started/macos-setup.rst @@ -0,0 +1,57 @@ +************************************** +Standard Setup of Toolchain for Mac OS +************************************** + +Install Prerequisites +===================== + +- install pip:: + + sudo easy_install pip + +- install pyserial:: + + sudo pip install pyserial + + +Toolchain Setup +=============== + +ESP32 toolchain for macOS is available for download from Espressif website: + +https://dl.espressif.com/dl/xtensa-esp32-elf-osx-1.22.0-61-gab8375a-5.2.0.tar.gz + +Download this file, then extract it in ``~/esp`` directory:: + + mkdir -p ~/esp + cd ~/esp + tar -xzf ~/Downloads/xtensa-esp32-elf-osx-1.22.0-61-gab8375a-5.2.0.tar.gz + +.. _setup-macos-toolchain-add-it-to-path: + +The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory. + +To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file:: + + export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin + +Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file:: + + alias get_esp32="export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin" + +Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. + + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + macos-setup-scratch diff --git a/docs/make-project.rst b/docs/get-started/make-project.rst similarity index 59% rename from docs/make-project.rst rename to docs/get-started/make-project.rst index 0bfac801b..d85b2a91c 100644 --- a/docs/make-project.rst +++ b/docs/get-started/make-project.rst @@ -1,54 +1,64 @@ Build and Flash with Make ========================= + Finding a project ----------------- -As well as the `esp-idf-template `_ project mentioned in the setup guide, ESP-IDF comes with some example projects on github in the :idf:`examples` directory. +As well as the `esp-idf-template `_ project, ESP-IDF comes with some example projects on github in the :idf:`examples` directory. + +Once you've found the project you want to work with, change to its directory and you can configure and build it. -Once you've found the project you want to work with, change to its directory and you can configure and build it: Configuring your project ------------------------ -`make menuconfig` +:: + + make menuconfig + Compiling your project ---------------------- -`make all` +:: + + make all ... will compile app, bootloader and generate a partition table based on the config. + Flashing your project --------------------- -When `make all` finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this from make by running: +When ``make all`` finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this from make by running:: -`make flash` + make flash This will flash the entire project (app, bootloader and partition table) to a new chip. The settings for serial port flashing can be configured with `make menuconfig`. -You don't need to run `make all` before running `make flash`, `make flash` will automatically rebuild anything which needs it. +You don't need to run ``make all`` before running ``make flash``, ``make flash`` will automatically rebuild anything which needs it. + Compiling & Flashing Just the App --------------------------------- After the initial flash, you may just want to build and flash just your app, not the bootloader and partition table: -* `make app` - build just the app. -* `make app-flash` - flash just the app. +* ``make app`` - build just the app. +* ``make app-flash`` - flash just the app. -`make app-flash` will automatically rebuild the app if it needs it. +``make app-flash`` will automatically rebuild the app if it needs it. + +There's no downside to reflashing the bootloader and partition table each time, if they haven't changed. -(There's no downside to reflashing the bootloader and partition table each time, if they haven't changed.) The Partition Table ------------------- 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 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. @@ -59,5 +69,5 @@ The simplest way to use the partition table is to `make menuconfig` and choose o In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table. -For more details about :doc:`partition tables ` and how to create custom variations, view the :doc:`documentation `. +For more details about :doc:`partition tables <../api-guides/partition-tables>` and how to create custom variations, view the :doc:`documentation <../api-guides/partition-tables>`. diff --git a/docs/windows-setup-scratch.rst b/docs/get-started/windows-setup-scratch.rst similarity index 72% rename from docs/windows-setup-scratch.rst rename to docs/get-started/windows-setup-scratch.rst index 07cd51ecd..c58fda5cf 100644 --- a/docs/windows-setup-scratch.rst +++ b/docs/get-started/windows-setup-scratch.rst @@ -1,13 +1,15 @@ -Set up Windows Toolchain from Scratch -************************************* +************************************ +Setup Windows Toolchain from Scratch +************************************ -This is an **optional alternative to the normal Windows Guide**. +Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customize the install. The :doc:`pre-built environment `, addressed to less experienced users, has been prepared by following these steps. -:doc:`See the main Windows setup page for the quickest and simplest Windows setup guide `. +To quickly setup the toolchain in standard way, using prebuild environment, proceed to section :doc:`windows-setup`. -Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customise the install. The pre-built environment has been prepared by following these steps. -Configure toolchain & environment from scratch +.. _configure-windows-toolchain-from-scratch: + +Configure Toolchain & Environment from Scratch ============================================== This process involves installing MSYS2_, then installing the MSYS2_ and Python packages which ESP-IDF uses, and finally downloading and installing the Xtensa toolchain. @@ -38,7 +40,7 @@ MSYS2 Mirrors in China There are some (unofficial) MSYS2 mirrors inside China, which substantially improves download speeds inside China. -To add these mirrors, edit the following two MSYS2 mirrorlist files before running the setup script. The mirrorlist files can be found in the ``/etc/pacman.d`` directory (ie ``c:\msys2\etc\pacman.d``). +To add these mirrors, edit the following two MSYS2 mirrorlist files before running the setup script. The mirrorlist files can be found in the ``/etc/pacman.d`` directory (i.e. ``c:\msys2\etc\pacman.d``). Add these lines at the top of ``mirrorlist.mingw32``:: @@ -64,4 +66,27 @@ Or with credentials:: Add this line to ``/etc/profile`` in the MSYS directory in order to permanently enable the proxy when using MSYS. + +Alternative Setup: Just download a toolchain +============================================ + +If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here: + +https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-61-gab8375a-5.2.0.zip + +.. note:: + + If you followed instructions :ref:`configure-windows-toolchain-from-scratch`, you already have the toolchain and you won't need this download. + +.. important:: + + Just having this toolchain is *not enough* to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support). + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. + + .. _MSYS2: https://msys2.github.io/ diff --git a/docs/get-started/windows-setup.rst b/docs/get-started/windows-setup.rst new file mode 100644 index 000000000..4abd3272a --- /dev/null +++ b/docs/get-started/windows-setup.rst @@ -0,0 +1,51 @@ +*************************************** +Standard Setup of Toolchain for Windows +*************************************** + +Introduction +============ + +Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide this. You don't need to use this environment all the time (you can use :doc:`Eclipse ` or some other front-end), but it runs behind the scenes. + + +Toolchain Setup +=============== + +The quick setup is to download the Windows all-in-one toolchain & MSYS zip file from dl.espressif.com: + +https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20170330.zip + +Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``C:\``) and it will create an ``msys32`` directory with a pre-prepared environment. + + +Check it Out +============ + +Open an MSYS2 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. + +.. figure:: ../_static/msys2-terminal-window.png + :align: center + :alt: MSYS2 terminal window + :figclass: align-center + + MSYS2 terminal window + +Use this window in the following steps setting up development environment for ESP32. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. + + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + windows-setup-scratch + + +.. _MSYS2: https://msys2.github.io/ diff --git a/docs/hw-reference/index.rst b/docs/hw-reference/index.rst new file mode 100644 index 000000000..58edfa114 --- /dev/null +++ b/docs/hw-reference/index.rst @@ -0,0 +1,12 @@ +****************** +Hardware Reference +****************** + +.. toctree:: + + Technical Reference Manual (PDF) + Pin List and Functions (PDF) + Chip Pinout (PDF) + Silicon Errata (PDF) + Modules and Boards + diff --git a/docs/modules-and-boards.rst b/docs/hw-reference/modules-and-boards.rst similarity index 76% rename from docs/modules-and-boards.rst rename to docs/hw-reference/modules-and-boards.rst index 3f175c7f7..1574ef9cd 100644 --- a/docs/modules-and-boards.rst +++ b/docs/hw-reference/modules-and-boards.rst @@ -12,9 +12,10 @@ ESP-WROOM-32 The smallest module intended for installation in final products. Can be also used for evaluation after adding extra components like programming interface, boot strapping resistors and break out headers. .. image:: http://dl.espressif.com/dl/schematics/pictures/esp-wroom-32.jpg - :align: center - :width: 40% - :alt: ESP-WROOM-32 module (front and back) + :align: center + :width: 40% + :alt: ESP-WROOM-32 module (front and back) + * `Schematic `__ (PDF) * `Datasheet `__ (PDF) @@ -27,13 +28,13 @@ ESP32 Core Board V2 / ESP32 DevKitC Small and convenient development board with break out pin headers and minimum additional components. Includes USB to serial programming interface, that also provides power supply for the board. Has press buttons to reset the board and put it in upload mode. .. image:: http://dl.espressif.com/dl/schematics/pictures/esp32-core-board-v2.jpg - :align: center - :width: 50% - :alt: ESP32 Core Board V2 / ESP32 DevKitC board + :align: center + :width: 50% + :alt: ESP32 Core Board V2 / ESP32 DevKitC board * `Schematic `__ (PDF) * `ESP32 Development Board Reference Design `_ (ZIP) containing OrCAD schematic, PCB layout, gerbers and BOM -* `ESP32-DevKitC Getting Started Guide `_ (PDF) +* :doc:`../get-started/get-started-devkitc` * `CP210x USB to UART Bridge VCP Drivers `_ @@ -44,26 +45,26 @@ ESP32 Demo Board V2 One of first feature rich evaluation boards that contains several pin headers, dip switches, USB to serial programming interface, reset and boot mode press buttons, power switch, 10 touch pads and separate header to connect LCD screen. .. image:: http://dl.espressif.com/dl/schematics/pictures/esp32-demo-board-v2.jpg - :align: center - :alt: ESP32 Demo Board V2 board + :align: center + :alt: ESP32 Demo Board V2 board * `Schematic `__ (PDF) -* `FTDI Virtual COM Port Drivers`_ Note: Drivers install automatically on most of OS / there is no need to install them manually +* `FTDI Virtual COM Port Drivers`_ ESP32 WROVER KIT V1 / ESP32 DevKitJ V1 -------------------------------------- -Development board that has dual port USB to serial converter for programming and JTAG interface for debugging. Power supply is provided by USB interface or from standard 5 mm power supply jack. Power supply selection is done with a jumper and may be put on/off with a separate switch. Has SD card slot, 3.2” SPI LCD screen and dedicated header to connect a camera. Provides RGB diode for diagnostics. Also includes 32.768KHz XTAL for internal RTC to operate it in low power modes. +Development board that has dual port USB to serial converter for programming and JTAG interface for debugging. Power supply is provided by USB interface or from standard 5 mm power supply jack. Power supply selection is done with a jumper and may be put on/off with a separate switch. Has SD card slot, 3.2” SPI LCD screen and dedicated header to connect a camera. Provides RGB diode for diagnostics. Also, includes 32.768 kHz XTAL for internal RTC to operate it in low power modes. .. image:: http://dl.espressif.com/dl/schematics/pictures/esp32-devkitj-v1.jpg - :align: center - :width: 90% - :alt: ESP32 WROVER KIT V1 / ESP32 DevKitJ V1 board + :align: center + :width: 90% + :alt: ESP32 WROVER KIT V1 / ESP32 DevKitJ V1 board * `Schematic `__ (PDF) -* `FTDI Virtual COM Port Drivers`_ Note: Drivers install automatically on most of OS / there is no need to install them manually * `JTAG Debugging for ESP32`_ (PDF) +* `FTDI Virtual COM Port Drivers`_ ESP32 WROVER KIT V2 @@ -77,9 +78,9 @@ This is an updated version of ESP32 DevKitJ V1 described above with design impro :alt: ESP32 WROVER KIT V2 board * `Schematic `__ (PDF) -* `ESP-WROVER-KIT Getting Started Guide `_ (PDF) -* `FTDI Virtual COM Port Drivers`_ Note: Drivers install automatically on most of OS / there is no need to install them manually +* :doc:`../get-started/get-started-wrover-kit` * `JTAG Debugging for ESP32`_ (PDF) +* `FTDI Virtual COM Port Drivers`_ .. _JTAG Debugging for ESP32: https://github.com/espressif/esp-idf/ diff --git a/docs/index.rst b/docs/index.rst index f2324de1f..e4ee3fe4d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,83 +1,48 @@ ESP-IDF Programming Guide ========================= -This is the documentation for Espressif IoT Developement Framework (`esp-idf `_). ESP-IDF is the official development framework for the `ESP32 `_ chip. +This is the documentation for Espressif IoT Development Framework (`esp-idf `_). ESP-IDF is the official development framework for the `ESP32 `_ chip. + ++------------------+------------------+------------------+ +| |Get Started|_ | |API Reference|_ | |H/W Reference|_ | ++------------------+------------------+------------------+ +| `Get Started`_ | `API Reference`_ | `H/W Reference`_ | ++------------------+------------------+------------------+ +| |API Guides|_ | |Contribute|_ | |Resources|_ | ++------------------+------------------+------------------+ +| `API Guides`_ | `Contribute`_ | `Resources`_ | ++------------------+------------------+------------------+ -Contents: +.. |Get Started| image:: _static/get-started.gif +.. _Get Started: get-started/index.html + +.. |API Reference| image:: _static/api-reference.gif +.. _API Reference: api-reference/index.html + +.. |H/W Reference| image:: _static/hw-reference.gif +.. _H/W Reference: hw-reference/index.html + +.. |Api Guides| image:: _static/api-guides.gif +.. _Api Guides: api-guides/index.html + +.. |Contribute| image:: _static/contribute.gif +.. _Contribute: contribute/index.html + +.. |Resources| image:: _static/resources.gif +.. _Resources: resources.html + .. toctree:: - :caption: Setup Toolchain - :maxdepth: 1 + :hidden: - Windows - Linux - Mac OS - -.. Connect - TBA - -.. toctree:: - :caption: Build and Flash - :maxdepth: 1 - - Make - Eclipse IDE - IDF Monitor - -.. toctree:: - :caption: What Else? - :maxdepth: 1 - - General Notes - Build System - Debugging - ESP32 Core Dump - Partition Tables - Flash Encryption - Secure Boot - Deep Sleep Wake Stubs - ULP Coprocessor - Unit Testing - -.. toctree:: - :caption: API Reference - :maxdepth: 2 - - Wi-Fi - Bluetooth - Ethernet - Peripherals - System - Storage - Protocols - -.. toctree:: - :caption: Hardware Reference - - Technical Reference Manual (PDF) - Pin List and Functions (PDF) - Chip Pinout (PDF) - Silicon Errata (PDF) - Modules and Boards - -.. toctree:: - :caption: Contribute - :maxdepth: 1 - - Contributions Guide - Style Guide - Documenting Code - API Template - Contributor Agreement - -.. toctree:: - :caption: Legal - :maxdepth: 1 - - COPYRIGHT - - -Indices -======= + Get Started + API Reference + H/W Reference + API Guides + Contribute + Resources + Copyrights + About * :ref:`genindex` diff --git a/docs/linux-setup.rst b/docs/linux-setup.rst deleted file mode 100644 index 331741928..000000000 --- a/docs/linux-setup.rst +++ /dev/null @@ -1,187 +0,0 @@ -Set up of Toolchain for Linux -***************************** - -Step 0: Prerequisites -===================== - -Install some packages ---------------------- - -To compile with ESP-IDF you need to get the following packages: - -- CentOS 7:: - - sudo yum install git wget make ncurses-devel flex bison gperf python pyserial - -- Ubuntu and Debian:: - - sudo apt-get install git wget make libncurses-dev flex bison gperf python python-serial - -- Arch:: - - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial - -Step 1: Download binary toolchain for the ESP32 -================================================== - -ESP32 toolchain for Linux is available for download from Espressif website: - -- for 64-bit Linux:: - - https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-61-gab8375a-5.2.0.tar.gz - -- for 32-bit Linux:: - - https://dl.espressif.com/dl/xtensa-esp32-elf-linux32-1.22.0-61-gab8375a-5.2.0.tar.gz - -Download this file, then extract it to the location you prefer, for example:: - - mkdir -p ~/esp - cd ~/esp - tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-61-gab8375a-5.2.0.tar.gz - -The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory. - -To use it, you will need to update your ``PATH`` environment variable in ``~/.bash_profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.bash_profile`` file:: - - export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin - -Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.bash_profile`` file:: - - alias get_esp32="export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin" - -Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``. - -Arch Linux Users ----------------- - -To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6. Backwards compatibility libraries are available in AUR_ for native and lib32 configurations: -- https://aur.archlinux.org/packages/ncurses5-compat-libs/ -- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/ - -(Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.) - - -Alternative Step 1: Compile the toolchain from source using crosstool-NG -======================================================================== - -Instead of downloading binary toolchain from Espressif website (Step 1 above) you may build the toolchain yourself. - -If you can't think of a reason why you need to build it yourself, then probably it's better to stick with the binary version. However, here are some of the reasons why you might want to compile it from source: - -- if you want to customize toolchain build configuration - -- if you want to use a different GCC version (such as 4.8.5) - -- if you want to hack gcc or newlib or libstdc++ - -- if you are curious and/or have time to spare - -- if you don't trust binaries downloaded from the Internet - -In any case, here are the steps to compile the toolchain yourself. - -(Note: You will also need the prerequisite packages mentioned in step 0, above.) - -- Install dependencies: - - - CentOS 7:: - - sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool - - - Ubuntu pre-16.04:: - - sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool - - - Ubuntu 16.04:: - - sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin - - - Debian:: - - TODO - - - Arch:: - - TODO - -Download ``crosstool-NG`` and build it:: - - cd ~/esp - git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git - cd crosstool-NG - ./bootstrap && ./configure --enable-local && make install - -Build the toolchain:: - - ./ct-ng xtensa-esp32-elf - ./ct-ng build - chmod -R u+w builds/xtensa-esp32-elf - -Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow instructions given in the previous section to add the toolchain to your ``PATH``. - -Step 2: Getting ESP-IDF from github -=================================== - -Open terminal, navigate to the directory you want to clone ESP-IDF and clone it using ``git clone`` command:: - - cd ~/esp - git clone --recursive https://github.com/espressif/esp-idf.git - - -ESP-IDF will be downloaded into ``~/esp/esp-idf``. - -Note the ``--recursive`` option! If you have already cloned ESP-IDF without this option, run another command to get all the submodules:: - - cd ~/esp/esp-idf - git submodule update --init - -**IMPORTANT:** The esp-idf build system does not support spaces in paths to esp-idf or to projects. - -Step 3: Starting a project -========================== - -ESP-IDF by itself does not build a binary to run on the ESP32. The binary "app" comes from a project in a different directory. Multiple projects can share the same ESP-IDF directory. - -The easiest way to start a project is to download the template project from GitHub:: - - cd ~/esp - git clone https://github.com/espressif/esp-idf-template.git myapp - -This will download ``esp-idf-template`` project into ``~/esp/myapp`` directory. - -**IMPORTANT:** The esp-idf build system does not support spaces in paths to esp-idf or to projects. - -You can also find a range of example projects under the "examples" directory in IDF. These example project directories can be copied to outside IDF in order to begin your own projects. - -Step 4: Building and flashing the application -============================================= - -In terminal, go to the application directory which was obtained on the previous step:: - - cd ~/esp/myapp - -Type a command like this to set the path to ESP-IDF directory:: - - export IDF_PATH=~/esp/esp-idf - -At this point you may configure the serial port to be used for uploading. Run:: - - make menuconfig - -Then navigate to "Serial flasher config" submenu and change value of "Default serial port" to match the serial port you will use. Also take a moment to explore other options which are configurable in ``menuconfig``. - -Special note for Arch Linux users: navigate to "SDK tool configuration" and change the name of "Python 2 interpreter" from ``python`` to ``python2``. - -Now you can build and flash the application. Run:: - - make flash - -This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your development board. - -Further reading -=============== - -If you'd like to use the Eclipse IDE instead of running ``make``, check out the Eclipse setup guide in this directory. - -.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository diff --git a/docs/macos-setup.rst b/docs/macos-setup.rst deleted file mode 100644 index 33164f248..000000000 --- a/docs/macos-setup.rst +++ /dev/null @@ -1,166 +0,0 @@ -Set up of Toolchain for Mac OS -****************************** - -Step 0: Prerequisites -===================== - -- install pip:: - - sudo easy_install pip - -- install pyserial - - sudo pip install pyserial - -Step 1: Download binary toolchain for the ESP32 -================================================== - -ESP32 toolchain for macOS is available for download from Espressif website: - -https://dl.espressif.com/dl/xtensa-esp32-elf-osx-1.22.0-61-gab8375a-5.2.0.tar.gz - -Download this file, then extract it to the location you prefer, for example:: - - mkdir -p ~/esp - cd ~/esp - tar -xzf ~/Downloads/xtensa-esp32-elf-osx-1.22.0-61-gab8375a-5.2.0.tar.gz - -The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory. - -To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file:: - - export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin - -Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file:: - - alias get_esp32="export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin" - -Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``. - -Alternative Step 1: Compile the toolchain from source using crosstool-NG -======================================================================== - -Instead of downloading binary toolchain from Espressif website (Step 1 above) you may build the toolchain yourself. - -If you can't think of a reason why you need to build it yourself, then probably it's better to stick with the binary version. However, here are some of the reasons why you might want to compile it from source: - -- if you want to customize toolchain build configuration - -- if you want to use a different GCC version (such as 4.8.5) - -- if you want to hack gcc or newlib or libstdc++ - -- if you are curious and/or have time to spare - -- if you don't trust binaries downloaded from the Internet - -In any case, here are the steps to compile the toolchain yourself. - -- Install dependencies: - - - Install either MacPorts_ or homebrew_ package manager. MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools. - - .. _homebrew: http://brew.sh/ - .. _MacPorts: https://www.macports.org/install.php - - - with MacPorts:: - - sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake - - - with homebrew:: - - brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake - -Create a case-sensitive filesystem image:: - - hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+" - -Mount it:: - - hdiutil mount ~/esp/crosstool.dmg - -Create a symlink to your work directory:: - - cd ~/esp - ln -s /Volumes/ctng crosstool-NG - -Download ``crosstool-NG`` and build it:: - - cd ~/esp - git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git - cd crosstool-NG - ./bootstrap && ./configure --enable-local && make install - -Build the toolchain:: - - ./ct-ng xtensa-esp32-elf - ./ct-ng build - chmod -R u+w builds/xtensa-esp32-elf - -Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow instructions given in the previous section to add the toolchain to your ``PATH``. - -Step 2: Getting ESP-IDF from github -=================================== - -Open Terminal.app, navigate to the directory you want to clone ESP-IDF and clone it using ``git clone`` command:: - - cd ~/esp - git clone --recursive https://github.com/espressif/esp-idf.git - - -ESP-IDF will be downloaded into ``~/esp/esp-idf``. - -Note the ``--recursive`` option! If you have already cloned ESP-IDF without this option, run another command to get all the submodules:: - - cd ~/esp/esp-idf - git submodule update --init - - -Step 3: Starting a project -========================== - -ESP-IDF by itself does not build a binary to run on the ESP32. The binary "app" comes from a project in a different directory. Multiple projects can share the same ESP-IDF directory. - -The easiest way to start a project is to download the template project from GitHub:: - - cd ~/esp - git clone https://github.com/espressif/esp-idf-template.git myapp - -This will download ``esp-idf-template`` project into ``~/esp/myapp`` directory. - -**IMPORTANT:** The esp-idf build system does not support spaces in paths to esp-idf or to projects. - -You can also find a range of example projects under the "examples" directory in IDF. These example project directories can be copied to outside IDF in order to begin your own projects. - - -Step 4: Building and flashing the application -============================================= - -In Terminal.app, go to the application directory which was obtained on the previous step:: - - cd ~/esp/myapp - -Type a command like this to set the path to ESP-IDF directory:: - - export IDF_PATH=~/esp/esp-idf - -At this point you may configure the serial port to be used for uploading. Run:: - - make menuconfig - -Then navigate to "Serial flasher config" submenu and change value of "Default serial port" to match the serial port you will use. Also take a moment to explore other options which are configurable in ``menuconfig``. - -If you don't know device name for the serial port of your development board, run this command two times, first with the board unplugged, then with the board plugged in. The port which appears the second time is the one you need:: - - ls /dev/tty.* - -Now you can build and flash the application. Run:: - - make flash - -This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your development board. - -Further reading -=============== - -If you'd like to use the Eclipse IDE instead of running ``make``, check out the Eclipse setup guide in this directory. diff --git a/docs/resources.rst b/docs/resources.rst new file mode 100644 index 000000000..05092193d --- /dev/null +++ b/docs/resources.rst @@ -0,0 +1,15 @@ +********* +Resources +********* + +* The `esp32.com forum `_ is a place to ask questions and find community resources. + +* Check the `Issues `_ section on GitHub if you find a bug or have a feature request. Please check existing `Issues `_ before opening a new one. + +* If you're interested in contributing to ESP-IDF, please check the :doc:`contribute/index`. + +* To develop applications using Arduino platform, refer to `Arduino core for ESP32 WiFi chip `_. + +* For additional ESP32 product related information, please refer to `documentation `_ section of `Espressif `_ site. + +* Mirror of this documentation is available under: https://dl.espressif.com/doc/esp-idf/latest/. diff --git a/docs/security/flash-encryption.rst b/docs/security/flash-encryption.rst index f2f1339d9..fd9b620e1 100644 --- a/docs/security/flash-encryption.rst +++ b/docs/security/flash-encryption.rst @@ -282,7 +282,7 @@ Encrypted Partition Flag Some partitions are encrypted by default. Otherwise, it is possible to mark any partition as requiring encryption: -In the :doc:`partition table ` description CSV files, there is a field for flags. +In the :doc:`partition table <../api-guides/partition-tables>` description CSV files, there is a field for flags. Usually left blank, if you write "encrypted" in this field then the partition will be marked as encrypted in the partition table, and data written here will be treated as encrypted (same as an app partition):: diff --git a/docs/security/secure-boot.rst b/docs/security/secure-boot.rst index f90141a5e..126b8c9d6 100644 --- a/docs/security/secure-boot.rst +++ b/docs/security/secure-boot.rst @@ -5,7 +5,9 @@ Secure Boot is a feature for ensuring only your code can run on the chip. Data l Secure Boot is separate from the :doc:`Flash Encryption ` feature, and you can use secure boot without encrypting the flash contents. However we recommend using both features together for a secure environment. -**IMPORTANT: Enabling secure boot limits your options for further updates of your ESP32. Make sure to read this document throughly and understand the implications of enabling secure boot.** +.. important:: + + Enabling secure boot limits your options for further updates of your ESP32. Make sure to read this document throughly and understand the implications of enabling secure boot. Background ---------- @@ -14,7 +16,7 @@ Background - Efuses are used to store the secure bootloader key (in efuse block 2), and also a single Efuse bit (ABS_DONE_0) is burned (written to 1) to permanently enable secure boot on the chip. For more details about efuse, see the (forthcoming) chapter in the Technical Reference Manual. -- To understand the secure boot process, first familiarise yourself with the standard :doc:`ESP-IDF boot process <../general-notes>`. +- To understand the secure boot process, first familiarise yourself with the standard :doc:`ESP-IDF boot process <../api-guides/general-notes>`. - Both stages of the boot process (initial software bootloader load, and subsequent partition & app loading) are verified by the secure boot process, in a "chain of trust" relationship. diff --git a/docs/ulp_macros.rst b/docs/ulp_macros.rst deleted file mode 100644 index 2e3d2a07a..000000000 --- a/docs/ulp_macros.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../components/ulp/README.rst \ No newline at end of file diff --git a/docs/windows-setup.rst b/docs/windows-setup.rst deleted file mode 100644 index 828afbd9b..000000000 --- a/docs/windows-setup.rst +++ /dev/null @@ -1,69 +0,0 @@ -Set up of Toolchain for Windows -******************************* - -Step 1: Quick Steps -=================== - -Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide this. You don't need to use this environment all the time (you can use :doc:`Eclipse ` or some other front-end), but it runs behind the scenes. - -The quick setup is to download the Windows all-in-one toolchain & MSYS zip file from dl.espressif.com: - -https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20170330.zip - -Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``C:\``) and it will create an "msys32" directory with a pre-prepared environment. - -Alternative Step 1: Configure toolchain & environment from scratch -================================================================== - -Rather than use the pre-prepared environment, you can :doc:`alternatively follow this guide to set up the MSYS2 environment from scratch `. - -Another Alternative Step 1: Just download a toolchain -===================================================== - -If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here: - -https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-61-gab8375a-5.2.0.zip - -**If you followed one of the above options for Step 1, you already have the toolchain and you won't need this download.** - -**Important**: Just having this toolchain is *not enough* to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support). - -Step 2: Getting the esp-idf repository from github -================================================== - -Open an MSYS2 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. - -Change to the directory you want to clone the SDK into by typing a command like this one: ``cd "C:/path/to/dir"`` (note the forward-slashes in the path). Then type ``git clone --recursive https://github.com/espressif/esp-idf.git`` - -If you'd rather use a Windows UI tool to manage your git repositories, this is also possible. A wide range are available. - -*NOTE*: While cloning submodules, the ``git clone`` command may print some output starting ``': not a valid identifier...``. This is a `known issue`_ but the git clone still succeeds without any problems. - -Step 3: Starting a project -========================== - -ESP-IDF by itself does not build a binary to run on the ESP32. The binary "app" comes from a project in a different directory. Multiple projects can share the same ESP-IDF directory on your computer. - -The easiest way to start a project is to download the Getting Started project from github_. - -The process is the same as for checking out the ESP-IDF from github. Change to the parent directory and run ``git clone https://github.com/espressif/esp-idf-template.git``. - -**IMPORTANT:** The esp-idf build system does not support spaces in paths to esp-idf or to projects. - -You can also find a range of example projects under the "examples" directory in IDF. These example project directories can be copied to outside IDF in order to begin your own projects. - - -Step 4: Configuring the project -=============================== - -Open an MSYS2 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. - -Type a command like this to set the path to ESP-IDF directory: ``export IDF_PATH="C:/path/to/esp-idf"`` (note the forward-slashes not back-slashes for the path). If you don't want to run this command every time you open an MSYS2 window, create a new file in ``C:/msys32/etc/profile.d/`` and paste this line in - then it will be run each time you open an MYS2 terminal. - -Use ``cd`` to change to the project directory (not the ESP-IDF directory.) Type ``make menuconfig`` to configure your project, then ``make`` to build it, ``make clean`` to remove built files, and ``make flash`` to flash (use the menuconfig to set the serial port for flashing.) - -If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide `. - - -.. _github: https://github.com/espressif/esp-idf-template -.. _known issue: https://github.com/espressif/esp-idf/issues/11