espressif/ESP8266_RTOS_SDK
1
0
Fork 0
mirror of https://github.com/espressif/ESP8266_RTOS_SDK.git synced 2025-05-22 01:27:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(esp8266): Modify for ESP8266 platform

Browse Source
This commit is contained in:
Dong Heng
2018-11-13 14:48:21 +08:00
parent 0a0290c5ef
commit 3cc752b654
35 changed files with 343 additions and 626 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
docs/Doxyfile
View File

@ -13,7 +13,7 @@
# https://www.stack.nl/~dimitri/doxygen/manual/config.html
PROJECT_NAME = "ESP32 Programming Guide"
PROJECT_NAME = "ESP8266 Programming Guide"
## The 'INPUT' statement below is used as input by script 'gen-df-input.py'
## to automatically generate API reference list files heder_file.inc
@ -24,187 +24,36 @@ INPUT = \
##
## Wi-Fi - API Reference
##
../../components/esp32/include/esp_wifi.h \
../../components/esp32/include/esp_wifi_types.h \
../../components/esp32/include/esp_smartconfig.h \
../../components/esp32/include/esp_now.h \
## Mesh - API Reference
../../components/esp32/include/esp_mesh.h \
## Bluetooth - API Reference
## Controller && VHCI
../../components/bt/include/esp_bt.h \
## Bluetooth COMMON
## Issue with __attribute__
../../components/bt/bluedroid/api/include/api/esp_bt_defs.h \
../../components/bt/bluedroid/api/include/api/esp_bt_main.h \
../../components/bt/bluedroid/api/include/api/esp_bt_device.h \
## Bluetooth LE
../../components/bt/bluedroid/api/include/api/esp_gap_ble_api.h \
## Issue with __attribute__
../../components/bt/bluedroid/api/include/api/esp_gatt_defs.h \
../../components/bt/bluedroid/api/include/api/esp_gatts_api.h \
../../components/bt/bluedroid/api/include/api/esp_gattc_api.h \
../../components/bt/bluedroid/api/include/api/esp_blufi_api.h \
## Bluetooth Classic
../../components/bt/bluedroid/api/include/api/esp_gap_bt_api.h \
## Issue with __attribute__
../../components/bt/bluedroid/api/include/api/esp_a2dp_api.h \
../../components/bt/bluedroid/api/include/api/esp_avrc_api.h \
../../components/bt/bluedroid/api/include/api/esp_spp_api.h \
../../components/bt/bluedroid/api/include/api/esp_hf_defs.h \
../../components/bt/bluedroid/api/include/api/esp_hf_client_api.h \
../../components/esp8266/include/esp_wifi.h \
../../components/esp8266/include/esp_wifi_types.h \
../../components/esp8266/include/esp_smartconfig.h \
##
## Ethernet - API Reference
## TCP-IP - API Reference
##
../../components/ethernet/include/esp_eth.h \
../../components/ethernet/include/eth_phy/phy.h \
../../components/ethernet/include/eth_phy/phy_tlk110.h \
../../components/ethernet/include/eth_phy/phy_lan8720.h \
##
## Peripherals - API Reference
##
../../components/driver/include/driver/adc.h \
../../components/driver/include/driver/can.h \
../../components/driver/include/driver/dac.h \
../../components/driver/include/driver/gpio.h \
../../components/driver/include/driver/rtc_io.h \
../../components/driver/include/driver/i2c.h \
../../components/driver/include/driver/i2s.h \
../../components/driver/include/driver/ledc.h \
../../components/driver/include/driver/mcpwm.h \
../../components/driver/include/driver/pcnt.h \
../../components/driver/include/driver/rmt.h \
../../components/driver/include/driver/sigmadelta.h \
../../components/driver/include/driver/spi_common.h \
../../components/driver/include/driver/spi_master.h \
../../components/driver/include/driver/spi_slave.h \
../../components/driver/include/driver/timer.h \
../../components/driver/include/driver/touch_pad.h \
../../components/driver/include/driver/uart.h \
../../components/esp_adc_cal/include/esp_adc_cal.h \
../../components/soc/esp32/include/soc/adc_channel.h \
../../components/soc/esp32/include/soc/dac_channel.h \
../../components/soc/esp32/include/soc/touch_channel.h \
../../components/soc/esp32/include/soc/uart_channel.h \
../../components/soc/esp32/include/soc/rtc_gpio_channel.h \
##
## Protocols - API Reference
##
## ESP-TLS
../../components/esp-tls/esp_tls.h \
## MQTT
../../components/mqtt/esp-mqtt/include/mqtt_client.h \
## mDNS
../../components/mdns/include/mdns.h \
../../components/esp_http_client/include/esp_http_client.h \
../../components/esp_http_server/include/esp_http_server.h \
##
## Provisioning - API Reference
##
## Protocol Communication
../../components/protocomm/include/common/protocomm.h \
../../components/protocomm/include/security/protocomm_security.h \
../../components/protocomm/include/security/protocomm_security0.h \
../../components/protocomm/include/security/protocomm_security1.h \
../../components/protocomm/include/transports/protocomm_ble.h \
../../components/protocomm/include/transports/protocomm_console.h \
../../components/protocomm/include/transports/protocomm_httpd.h \
## WiFi Provisioning
../../components/wifi_provisioning/include/wifi_provisioning/wifi_config.h \
##
## Storage - API Reference
##
## SPI Flash and Partition APIs
../../components/spi_flash/include/esp_spi_flash.h \
../../components/spi_flash/include/esp_partition.h \
../../components/bootloader_support/include/esp_flash_encrypt.h \
## SPIFFS
../../components/spiffs/include/esp_spiffs.h \
## SD/MMC Card Host
../../components/sdmmc/include/sdmmc_cmd.h \
../../components/driver/include/driver/sdmmc_host.h \
../../components/driver/include/driver/sdmmc_types.h \
../../components/driver/include/driver/sdspi_host.h \
## SDIO slave
../../components/driver/include/driver/sdio_slave.h \
## Non-Volatile Storage
../../components/nvs_flash/include/nvs.h \
../../components/nvs_flash/include/nvs_flash.h \
## Virtual Filesystem
../../components/vfs/include/esp_vfs.h \
../../components/vfs/include/esp_vfs_dev.h \
## FAT Filesystem
## NOTE: for two lines below header_file.inc is not used
../../components/fatfs/src/esp_vfs_fat.h \
../../components/fatfs/src/diskio.h \
## Wear Levelling
../../components/wear_levelling/include/wear_levelling.h \
../../components/tcpip_adapter/include/tcpip_adapter.h \
##
## System - API Reference
##
## Memory Allocation #
## Watchdogs
../../components/esp8266/include/esp_task_wdt.h \
## Sleep
../../components/esp8266/include/esp_sleep.h \
## System
../../components/esp8266/include/esp_system.h \
## Memory Allocation
../../components/heap/include/esp_heap_caps.h \
../../components/heap/include/esp_heap_trace.h \
../../components/heap/include/esp_heap_caps_init.h \
../../components/heap/include/multi_heap.h \
## Himem
../../components/esp32/include/esp_himem.h \
## Interrupt Allocation
../../components/esp32/include/esp_intr_alloc.h \
## Watchdogs
## NOTE: for two lines below header_file.inc is not used
../../components/esp32/include/esp_int_wdt.h \
../../components/esp32/include/esp_task_wdt.h \
## Hooks
../../components/esp32/include/esp_freertos_hooks.h \
## Inter-Processor Call
../../components/esp32/include/esp_ipc.h \
## Over The Air Updates (OTA)
../../components/app_update/include/esp_ota_ops.h \
## ESP HTTPS OTA
../../components/esp_https_ota/include/esp_https_ota.h \
## Sleep
../../components/esp32/include/esp_sleep.h \
## Logging
../../components/log/include/esp_log.h \
## Base MAC address
## NOTE: for line below header_file.inc is not used
../../components/esp32/include/esp_system.h \
##
## ULP Coprocessor - API Guides
## Peripherals - API Reference
##
## NOTE: for line below header_file.inc is not used
../../components/ulp/include/esp32/ulp.h \
../../components/esp8266/include/driver/gpio.h \
../../components/esp8266/include/driver/i2c.h \
../../components/esp8266/include/driver/pwm.h \
../../components/esp8266/include/driver/uart.h
##
## Application Level Tracing - API Reference
##
../../components/app_trace/include/esp_app_trace.h \
### Power management
../../components/esp32/include/esp_pm.h \
../../components/esp32/include/esp32/pm.h \
### esp_timer, High Resolution Timer
../../components/esp32/include/esp_timer.h \
### esp_event, Event Loop Library
../../components/esp_event/include/esp_event.h \
../../components/esp_event/include/esp_event_base.h \
### ESP Pthread parameters
../../components/pthread/include/esp_pthread.h \
###
### FreeRTOS
###
../../components/freertos/include/freertos/task.h \
../../components/freertos/include/freertos/queue.h \
../../components/freertos/include/freertos/semphr.h \
../../components/freertos/include/freertos/timers.h \
../../components/freertos/include/freertos/event_groups.h \
### Ringbuffer
../../components/esp_ringbuf/include/freertos/ringbuf.h \
### Helper functions for error codes
../../components/esp32/include/esp_err.h \
### System APIs
../../components/esp32/include/esp_system.h \
### Modbus controller component header file
../../components/freemodbus/modbus_controller/mbcontroller.h
## Get warnings for functions that have no documentation for their parameters or return value
##

16
docs/conf_common.py
View File

@ -142,8 +142,8 @@ seqdiag_antialias = True
# Doxygen regenerates files in 'xml/' directory every time,
# but we copy files to 'xml_in/' only when they change, to speed up
# incremental builds.
breathe_projects = { "esp32-idf": "xml_in/" }
breathe_default_project = "esp32-idf"
breathe_projects = { "ESP8266_RTOS_SDK": "xml_in/" }
breathe_default_project = "ESP8266_RTOS_SDK"
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@ -316,8 +316,8 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'ReadtheDocsTemplate.tex', u'Read the Docs Template Documentation',
u'Read the Docs', 'manual'),
('index', 'ReadtheDocsTemplate.tex', u'ESP8266 RTOS SDK User Manual',
u'', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
@ -346,8 +346,8 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'readthedocstemplate', u'Read the Docs Template Documentation',
[u'Read the Docs'], 1)
('index', 'readthedocstemplate', u'ESP8266 RTOS SDK User Manual',
[u''], 1)
]
# If true, show URL addresses after external links.
@ -360,8 +360,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'ReadtheDocsTemplate', u'Read the Docs Template Documentation',
u'Read the Docs', 'ReadtheDocsTemplate', 'One line description of project.',
('index', 'ReadtheDocsTemplate', u'ESP8266 RTOS SDK User Manual',
u'', 'ReadtheDocsTemplate', 'One line description of project.',
'Miscellaneous'),
]

2
docs/docs_common.mk
View File

@ -17,7 +17,7 @@
SPHINXOPTS =
# note: this is changed from sphinx-build so it depends on default python interpreter, not on /bin/sphinx-build
# (which will be the most recently installed version of sphinx and may not match)
SPHINXBUILD = python -m sphinx
SPHINXBUILD = python3 -m sphinx
PAPER =
BUILDDIR = _build

63
docs/en/api-guides/build-system.rst
View File

@ -1,22 +1,23 @@
Build System
************
This document explains the Espressif IoT Development Framework build system and the
This document explains the Espressif IoT Development Framework (ESP-IDF) build system and the
concept of "components"
Read this document if you want to know how to organise a new ESP-IDF project.
Read this document if you want to know how to organise a new ESP8266\_RTOS\
-SDK (ESP-IDF Style) project.
We recommend using the project_template project at directory of examples/get-started as a starting point for your project.
Using the Build System
======================
The esp-idf README file contains a description of how to use the build system to build your project.
The ESP8266_RTOS_SDK README file contains a description of how to use the build system to build your project.
Overview
========
An ESP-IDF project can be seen as an amalgamation of a number of components.
An ESP8266_RTOS_SDK project can be seen as an amalgamation of a number of components.
For example, for a http request example that shows the current humidity, there could be:
- The SoC base libraries (libc, rom bindings etc)
@ -25,11 +26,11 @@ For example, for a http request example that shows the current humidity, there c
- The FreeRTOS operating system
- Main code tying it all together
ESP-IDF makes these components explicit and configurable. To do that,
ESP8266_RTOS_SDK makes these components explicit and configurable. To do that,
when a project is compiled, the build environment will look up all the
components in the SDK directories, the project directories and
(optionally) in additional custom component directories. It then
allows the user to configure the ESP-IDF project using a a text-based
allows the user to configure the ESP8266_RTOS_SDK project using a a text-based
menu system to customize each component. After the components in the
project are configured, the build process will compile the project.
@ -40,13 +41,13 @@ Concepts
- "Project configuration" is held in a single file called sdkconfig in the root directory of the project. This configuration file is modified via ``make menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration.
- An "app" is an executable which is built by esp-idf. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app).
- An "app" is an executable which is built by ESP8266_RTOS_SDK. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app).
- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by esp-idf itself, others may be sourced from other places.
- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by ESP8266_RTOS_SDK itself, others may be sourced from other places.
Some things are not part of the project:
- "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project.
- "ESP8266_RTOS_SDK" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``ESP8266_RTOS_SDK`` directory. This allows the IDF framework to be decoupled from your project.
- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH, or the path to the toolchain can be set as part of the compiler prefix in the project configuration.
@ -76,11 +77,11 @@ This example "myProject" contains the following elements:
- A top-level project Makefile. This Makefile set the ``PROJECT_NAME`` variable and (optionally) defines
other project-wide make variables. It includes the core ``$(IDF_PATH)/make/project.mk`` makefile which
implements the rest of the ESP-IDF build system.
implements the rest of the ESP8266_RTOS_SDK build system.
- "sdkconfig" project configuration file. This file is created/updated when "make menuconfig" runs, and holds configuration for all of the components in the project (including esp-idf itself). The "sdkconfig" file may or may not be added to the source control system of the project.
- "sdkconfig" project configuration file. This file is created/updated when "make menuconfig" runs, and holds configuration for all of the components in the project (including ESP8266_RTOS_SDK itself). The "sdkconfig" file may or may not be added to the source control system of the project.
- Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF.
- Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP8266_RTOS_SDK.
- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the Makefile variable ``COMPONENT_DIRS`` includes this component but you can modify this variable (or set ``EXTRA_COMPONENT_DIRS``) to look for components in other places.
@ -130,7 +131,7 @@ These variables should all be set before the line ``include $(IDF_PATH)/make/pro
Component Makefiles
-------------------
Each project contains one or more components, which can either be part of esp-idf or added from other component directories.
Each project contains one or more components, which can either be part of ESP8266_RTOS_SDK or added from other component directories.
A component is any directory that contains a ``component.mk`` file.
@ -144,11 +145,11 @@ Running the ``make list-components`` target dumps many of these variables and ca
Multiple components with the same name
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When esp-idf is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means the
When ESP8266_RTOS_SDK is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means the
idf components first, the project components second and optionally the components in ``EXTRA_COMPONENT_DIRS`` last. If two or more of these directories
contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding esp-idf components
with a modified version by simply copying the component from the esp-idf component directory to the project component tree and then modifying it there.
If used in this way, the esp-idf directory itself can remain untouched.
contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding ESP8266_RTOS_SDK components
with a modified version by simply copying the component from the ESP8266_RTOS_SDK component directory to the project component tree and then modifying it there.
If used in this way, the ESP8266_RTOS_SDK directory itself can remain untouched.
Minimal Component Makefile
^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -183,7 +184,7 @@ The following variables are set at the project level, but exported for use in th
- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``.
- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain.
- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain.
- ``IDF_VER``: ESP-IDF version, retrieved from either ``$(IDF_PATH)/version.txt`` file (if present) else using git command ``git describe``. Recommended format here is single liner that specifies major IDF release version, e.g. ``v2.0`` for a tagged release or ``v2.0-275-g0efaa4f`` for an arbitrary commit. Application can make use of this by calling :cpp:func:`esp_get_idf_version`.
- ``IDF_VER``: ESP8266_RTOS_SDK version, retrieved from either ``$(IDF_PATH)/version.txt`` file (if present) else using git command ``git describe``. Recommended format here is single liner that specifies major IDF release version, e.g. ``v2.0`` for a tagged release or ``v2.0-275-g0efaa4f`` for an arbitrary commit. Application can make use of this by calling :cpp:func:`esp_get_idf_version`.
If you modify any of these variables inside ``component.mk`` then this will not prevent other components from building but it may make your component hard to build and/or debug.
@ -211,7 +212,7 @@ The following variables can be set inside ``component.mk`` to control build sett
Typically used for linker script files and binary libraries. Most components do
not need to set this variable.
The following variable only works for components that are part of esp-idf itself:
The following variable only works for components that are part of ESP8266_RTOS_SDK itself:
- ``COMPONENT_SUBMODULES``: Optional list of git submodule paths
(relative to COMPONENT_PATH) used by the component. These will be
@ -286,17 +287,17 @@ configuration settings to add to the "make menuconfig" for this component.
These settings are found under the "Component Settings" menu when menuconfig is run.
To create a component KConfig file, it is easiest to start with one of the KConfig files distributed with esp-idf.
To create a component KConfig file, it is easiest to start with one of the KConfig files distributed with ESP8266_RTOS_SDK.
For an example, see `Adding conditional configuration`_.
Preprocessor Definitions
------------------------
ESP-IDF build systems adds the following C preprocessor definitions on the command line:
ESP8266_RTOS_SDK build systems adds the following C preprocessor definitions on the command line:
- ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF.
- ``IDF_VER`` — ESP-IDF version, see `Preset Component Variables`_ for more details.
- ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP8266_RTOS_SDK.
- ``IDF_VER`` — ESP8266_RTOS_SDK version, see `Preset Component Variables`_ for more details.
Build Process Internals
-----------------------
@ -326,7 +327,7 @@ Second Level: Component Makefiles
- If ``COMPONENT_OWNBUILDTARGET`` and ``COMPONENT_OWNCLEANTARGET`` are not defined, default build and clean targets are created for the component's source files and the prerequisite ``COMPONENT_LIBRARY`` static library file.
- The ``component_project_vars.mk`` file has its own target in ``component_wrapper.mk``, which is evaluated from ``project.mk`` if this file needs to be rebuilt due to changes in the component makefile or the project configuration.
To better understand the component make process, have a read through the ``component_wrapper.mk`` file and some of the ``component.mk`` files included with esp-idf.
To better understand the component make process, have a read through the ``component_wrapper.mk`` file and some of the ``component.mk`` files included with ESP8266_RTOS_SDK.
Running Make Non-Interactively
------------------------------
@ -336,13 +337,13 @@ When running ``make`` in a situation where you don't want interactive prompts (f
Setting ``BATCH_BUILD`` implies the following:
- Verbose output (same as ``V=1``, see below). If you don't want verbose output, also set ``V=0``.
- If the project configuration is missing new configuration items (from new components or esp-idf updates) then the project use the default values, instead of prompting the user for each item.
- If the project configuration is missing new configuration items (from new components or ESP8266_RTOS_SDK updates) then the project use the default values, instead of prompting the user for each item.
- If the build system needs to invoke ``menuconfig``, an error is printed and the build fails.
Debugging The Make Process
--------------------------
Some tips for debugging the esp-idf build system:
Some tips for debugging the ESP8266_RTOS_SDK build system:
- Appending ``V=1`` to the make arguments (or setting it as an environment variable) will cause make to echo all commands executed, and also each directory as it is entered for a sub-make.
- Running ``make -w`` will cause make to echo each directory as it is entered for a sub-make - same as ``V=1`` but without also echoing all commands.
@ -376,7 +377,7 @@ For example, if your component needs to add to CFLAGS for the entire
project (not just for its own source files) then you can set
``CFLAGS +=`` in Makefile.projbuild.
``Makefile.projbuild`` files are used heavily inside esp-idf, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".
``Makefile.projbuild`` files are used heavily inside ESP8266_RTOS_SDK, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".
Note that ``Makefile.projbuild`` isn't necessary for the most common component uses - such as adding include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the ``component.mk`` file itself. See `Optional Project-Wide Component Variables`_ for details.
@ -443,7 +444,7 @@ Adding conditional configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The configuration system can be used to conditionally compile some files
depending on the options selected in ``make menuconfig``. For this, ESP-IDF
depending on the options selected in ``make menuconfig``. For this, ESP8266_RTOS_SDK
has the compile_only_if and compile_only_if_not macros:
``Kconfig``::
@ -498,7 +499,7 @@ This can also be used to select or stub out an implementation, as such:
Note the use of the Make 'or' function to include the font file. Other substitution functions,
like 'and' and 'if' will also work here. Variables that do not come from menuconfig can also
be used: ESP-IDF uses the default Make policy of judging a variable which is empty or contains
be used: ESP8266_RTOS_SDK uses the default Make policy of judging a variable which is empty or contains
only whitespace to be false while a variable with any non-whitespace in it is true.
(Note: Older versions of this document advised conditionally adding object file names to
@ -575,7 +576,7 @@ Obviously, there are cases where all these recipes are insufficient for a
certain component, for example when the component is basically a wrapper
around another third-party component not originally intended to be
compiled under this build system. In that case, it's possible to forego
the esp-idf build system entirely by setting COMPONENT_OWNBUILDTARGET and
the ESP8266_RTOS_SDK build system entirely by setting COMPONENT_OWNBUILDTARGET and
possibly COMPONENT_OWNCLEANTARGET and defining your own targets named ``build`` and ``clean`` in ``component.mk``
target. The build target can do anything as long as it creates
$(COMPONENT_LIBRARY) for the project make process to link into the app binary.
@ -592,7 +593,7 @@ is overridden then the component can instruct the linker to link other binaries
Custom sdkconfig defaults
-------------------------
For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the esp-idf defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when running ``make defconfig``, or creating a new config from scratch.
For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the ESP8266_RTOS_SDK defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when running ``make defconfig``, or creating a new config from scratch.
To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable.

24
docs/en/api-guides/index.rst
View File

@ -4,29 +4,5 @@ API Guides
.. toctree::
:maxdepth: 1
General Notes <general-notes>
Build System <build-system>
Build System (CMake) <build-system-cmake>
Error Handling <error-handling>
Fatal Errors <fatal-errors>
Deep Sleep Wake Stubs <deep-sleep-stub>
ESP32 Core Dump <core_dump>
Flash Encryption <../security/flash-encryption>
FreeRTOS SMP Changes <freertos-smp>
Thread Local Storage <thread-local-storage>
High Level Interrupts <hlinterrupts>
JTAG Debugging <jtag-debugging/index>
Bootloader <bootloader>
Partition Tables <partition-tables>
Secure Boot <../security/secure-boot>
ULP Coprocessor <ulp>
ULP Coprocessor (CMake) <ulp-cmake>
Unit Testing <unit-tests>
Unit Testing (CMake) <unit-tests-cmake>
Application Level Tracing <app_trace>
Console Component <console>
ROM debug console <romconsole>
WiFi Driver <wifi>
ESP-MESH <mesh>
BluFi <blufi>
External SPI-connected RAM <external-ram>

8
docs/en/api-guides/partition-tables.rst
View File

@ -70,7 +70,7 @@ Name field can be any meaningful name. It is not significant to the ESP8266. Nam
Type field
~~~~~~~~~~
Partition type field can be specified as app (0) or data (1). Or it can be a number 0-254 (or as hex 0x00-0xFE). Types 0x00-0x3F are reserved for esp-idf core functions.
Partition type field can be specified as app (0) or data (1). Or it can be a number 0-254 (or as hex 0x00-0xFE). Types 0x00-0x3F are reserved for ESP8266_RTOS_SDK core functions.
If your application needs to store data, please add a custom partition type in the range 0x40-0xFE.
@ -81,7 +81,7 @@ Subtype
The 8-bit subtype field is specific to a given partition type.
esp-idf currently only specifies the meaning of the subtype field for "app" and "data" partition types.
ESP8266_RTOS_SDK currently only specifies the meaning of the subtype field for "app" and "data" partition types.
App Subtypes
~~~~~~~~~~~~
@ -101,7 +101,7 @@ When type is "data", the subtype field can be specified as ota (0), phy (1), nvs
- phy (1) is for storing PHY initialisation data. This allows PHY to be configured per-device, instead of in firmware.
- 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 **ESP_PHY_INIT_DATA_IN_PARTITION** option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically.
- To load PHY data from this partition, run ``make menuconfig`` and enable **ESP_PHY_INIT_DATA_IN_PARTITION** option. You will also need to flash your devices with phy init data as the ESP8266_RTOS_SDK build system does not do this automatically.
- nvs (2) is for the **Non-Volatile Storage (NVS) API**.
- NVS is used to store per-device PHY calibration data (different to initialisation data).
@ -110,7 +110,7 @@ When type is "data", the subtype field can be specified as ota (0), phy (1), nvs
- 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.
Other data subtypes are reserved for future esp-idf uses.
Other data subtypes are reserved for future ESP8266_RTOS_SDK uses.
Offset & Size
~~~~~~~~~~~~~

84
docs/en/api-guides/system-tasks.rst
View File

@ -1,84 +0,0 @@
System Tasks
************
This document explains the ESP8266 RTOS SDK internal system tasks.
Overview
========
The main tasks and their attributes are as following:
+-------------------------+----------------+----------------+
| Names | stack size | Priority |
+=========================+================+================+
| uiT | 3584(C) | 15 |
+-------------------------+----------------+----------------+
| IDLE | 768 | 0 |
+-------------------------+----------------+----------------+
| Tmr | 2048(C) | 2 |
+-------------------------+----------------+----------------+
| ppT | 2048(C) | 13 |
+-------------------------+----------------+----------------+
| pmT | 1024 | 11 |
+-------------------------+----------------+----------------+
| rtT | 2048 | 12 |
+-------------------------+----------------+----------------+
| tiT | 2048(C) | 8 |
+-------------------------+----------------+----------------+
| esp_event_loop_task | 2048(C) | 10 |
+-------------------------+----------------+----------------+
Note: (C) means it is configurable by "menuconfig".
Tasks Introduction
==================
uiT
---
This task initializes the system, including peripherals, file system, user entry function and so on.
This task will delete itself and free the resources after calling `app_main`.
IDLE
----
This task is freeRTOS internal idle callback task, it is created when starting the freeRTOS.
Its hook function is `vApplicationIdleHook`.
The system's function of `sleep` and function of feeding `task watch dog` are called in the `vApplicationIdleHook`.
Tmr
---
This task is the processor of freeRTOS internal software timer.
ppT
---
This task is to process Wi-Fi hardware driver and stack. It posts messages from the logic link layer to the upper layer TCP/IP stack after transforming them into ethernet packets.
pmT
---
The task is for system power management. It will check if the system can sleep right now, and if it is, it will start preparing for system sleep.
rtT
---
The task is the processor of high priority hardware timer. It mainly process Wi-Fi real time events.
It is suggested that functions based on this component should not be called in application, because it may block other low layer Wi-Fi functions.
tiT
---
The task is the main task of TCP-IP stack(LwIP) , it is to deal with TCP-IP packets.
esp_event_loop_task
-------------------
The task processes system events, for example, Wi-Fi and TCP-IP stack events.
Suggestions
===========
In general, the priority of user task should NOT be higher than the system real timer task's priority (12). So it is suggested that keep your user tasks' priorities less than 12.
If you want to speed up the TCP/UDP throughput, you can try to set the priority of send/receive task to be higher than the "rtT" task's priority (8).

12
docs/en/api-reference/index.rst
View File

@ -5,15 +5,7 @@ API Reference
.. toctree::
:maxdepth: 2
Wi-Fi <wifi/index>
Mesh <mesh/index>
Bluetooth <bluetooth/index>
Ethernet <ethernet/index>
Peripherals <peripherals/index>
Protocols <protocols/index>
Provisioning <provisioning/index>
Storage <storage/index>
Wi-Fi <wifi/index>
TCP-IP <tcpip/index>
System <system/index>
Configuration Options <kconfig>
Error Codes Reference <error-codes>

7
docs/en/api-reference/peripherals/gpio.rst Normal file
View File

@ -0,0 +1,7 @@
GPIO
====
API Reference
-------------
.. include:: /_build/inc/gpio.inc

7
docs/en/api-reference/peripherals/i2c.rst Normal file
View File

@ -0,0 +1,7 @@
I2C
===
API Reference
-------------
.. include:: /_build/inc/i2c.inc

13
docs/en/api-reference/peripherals/index.rst Normal file
View File

@ -0,0 +1,13 @@
Peripherals API
***************
.. toctree::
:maxdepth: 1
GPIO <gpio>
I2C <i2c>
PWM <pwm>
UART <uart>
Example code for this API section is provided in :example:`peripherals` directory of ESP-IDF examples.

7
docs/en/api-reference/peripherals/pwm.rst Normal file
View File

@ -0,0 +1,7 @@
PWM
====
API Reference
-------------
.. include:: /_build/inc/pwm.inc

7
docs/en/api-reference/peripherals/uart.rst Normal file
View File

@ -0,0 +1,7 @@
UART
====
API Reference
-------------
.. include:: /_build/inc/uart.inc

7
docs/en/api-reference/system/heap_debug.rst Normal file
View File

@ -0,0 +1,7 @@
Heap debug
==========
API Reference
-------------
.. include:: /_build/inc/esp_heap_trace.inc

12
docs/en/api-reference/system/index.rst Normal file
View File

@ -0,0 +1,12 @@
System API
**********
.. toctree::
:maxdepth: 1
Heap Memory Allocation <mem_alloc>
Heap Memory Debugging <heap_debug>
Watchdogs <wdts>
Logging <log>
Sleep Modes <sleep_modes>
Miscellaneous System APIs <system>

7
docs/en/api-reference/system/log.rst Normal file
View File

@ -0,0 +1,7 @@
Log
===
API Reference
-------------
.. include:: /_build/inc/esp_log.inc

8
docs/en/api-reference/system/mem_alloc.rst Normal file
View File

@ -0,0 +1,8 @@
Mem alloc
==========
API Reference
-------------
.. include:: /_build/inc/esp_heap_caps.inc
.. include:: /_build/inc/esp_heap_caps_init.inc

7
docs/en/api-reference/system/sleep_modes.rst Normal file
View File

@ -0,0 +1,7 @@
Sleep modes
===========
API Reference
-------------
.. include:: /_build/inc/esp_sleep.inc

7
docs/en/api-reference/system/system.rst Normal file
View File

@ -0,0 +1,7 @@
System
======
API Reference
-------------
.. include:: /_build/inc/esp_system.inc

7
docs/en/api-reference/system/wdts.rst Normal file
View File

@ -0,0 +1,7 @@
Watch dog task
==============
API Reference
-------------
.. include:: /_build/inc/esp_task_wdt.inc

7
docs/en/api-reference/tcpip/index.rst Normal file
View File

@ -0,0 +1,7 @@
TCP-IP API
**********
.. toctree::
:maxdepth: 1
TCP-IP Adapter <tcpip_adapter>

7
docs/en/api-reference/tcpip/tcpip_adapter.rst Normal file
View File

@ -0,0 +1,7 @@
TCPIP Adapter
=============
API Reference
-------------
.. include:: /_build/inc/tcpip_adapter.inc

14
docs/en/api-reference/wifi/esp_wifi.rst
View File

@ -4,11 +4,11 @@ Wi-Fi
Introduction
------------
The WiFi libraries provide support for configuring and monitoring the ESP32 WiFi networking functionality. This includes configuration for:
The WiFi libraries provide support for configuring and monitoring the ESP8266 WiFi networking functionality. This includes configuration for:
- Station mode (aka STA mode or WiFi client mode). ESP32 connects to an access point.
- AP mode (aka Soft-AP mode or Access Point mode). Stations connect to the ESP32.
- Combined AP-STA mode (ESP32 is concurrently an access point and a station connected to another access point).
- Station mode (aka STA mode or WiFi client mode). ESP8266 connects to an access point.
- AP mode (aka Soft-AP mode or Access Point mode). Stations connect to the ESP8266.
- Combined AP-STA mode (ESP8266 is concurrently an access point and a station connected to another access point).
- Various security modes for the above (WPA, WPA2, WEP, etc.)
- Scanning for access points (active & passive scanning).
@ -17,11 +17,9 @@ The WiFi libraries provide support for configuring and monitoring the ESP32 WiFi
Application Examples
--------------------
See :example:`wifi` directory of ESP-IDF examples that contains the following applications:
See :example:`wifi` directory of ESP8266_RTOS_SDK examples that contains the following applications:
* Simple application showing how to connect ESP32 module to an Access Point - `esp-idf-template <https://github.com/espressif/esp-idf-template>`_.
* Using power save mode of Wi-Fi - :example:`wifi/power_save`.
* Simple application showing how to connect ESP8266 module to an Access Point - `template <https://github.com/espressif/esp-idf-template>`_.
API Reference

3
docs/en/api-reference/wifi/index.rst
View File

@ -6,7 +6,6 @@ Wi-Fi API
Wi-Fi <esp_wifi>
Smart Config <esp_smartconfig>
ESPNOW <esp_now>
Example code for this API section is provided in :example:`wifi` directory of ESP-IDF examples.
Example code for this API section is provided in :example:`wifi` directory of SDK examples.

19
docs/en/get-started/eclipse-setup-windows.rst
View File

@ -1,7 +1,6 @@
**********************
Eclipse IDE on Windows
**********************
:link_to_translation:`zh_CN:[中文]`
Configuring Eclipse on Windows requires some different steps. The full configuration steps for Windows are shown below.
@ -22,13 +21,13 @@ Once your new Eclipse installation launches, follow these steps:
Import New Project
------------------
* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory.
* Eclipse makes use of the Makefile support in ESP8266_RTOS_SDK. This means you need to start by creating an ESP8266_RTOS_SDK project. You can use the idf-template project from github, or open one of the examples in the ESP8266_RTOS_SDK examples subdirectory.
* Once Eclipse is running, choose File -> Import...
* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next.
* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile).
* On the next page, enter "Existing Code Location" to be the directory of your ESP8266_RTOS_SDK project. Don't specify the path to the ESP8266_RTOS_SDK directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile).
* On the same page, under "Toolchain for Indexer Settings" uncheck "Show only available toolchains that support this platform".
@ -49,17 +48,17 @@ Project Properties
* Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``.
* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed. The IDF_PATH directory should be specified using forwards slashes not backslashes, ie *C:/Users/user-name/Development/esp-idf*.
* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP8266_RTOS_SDK is installed. The IDF_PATH directory should be specified using forwards slashes not backslashes, ie *C:/Users/user-name/Development/ESP8266_RTOS_SDK*.
* 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).
* 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-lx106-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 the "Providers" tab
* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Change "Command to get compiler specs" to ``xtensa-esp32-elf-gcc ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"``.
* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Change "Command to get compiler specs" to ``xtensa-lx106-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``.
* In the list of providers, click "CDT GCC Build Output Parser" and change the "Compiler command pattern" to ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)``
* In the list of providers, click "CDT GCC Build Output Parser" and change the "Compiler command pattern" to ``xtensa-lx106-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)``
Navigate to "C/C++ General" -> "Indexer" property page:
@ -83,8 +82,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 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 ESP8266_RTOS_SDK 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 Unix-style 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 xtensa-lx106-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 Unix-style paths (of the type ``/c/blah`` instead of ``c:/blah`` or ``c:\\blah``). In particular, xtensa-lx106-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 ESP8266_RTOS_SDK. 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 ESP8266_RTOS_SDK 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.

27
docs/en/get-started/eclipse-setup.rst
View File

@ -1,18 +1,17 @@
********************************
Build and Flash with Eclipse IDE
********************************
:link_to_translation:`zh_CN:[中文]`
.. _eclipse-install-steps:
Installing Eclipse IDE
======================
The Eclipse IDE gives you a graphical integrated development environment for writing, compiling and debugging ESP-IDF projects.
The Eclipse IDE gives you a graphical integrated development environment for writing, compiling and debugging ESP8266_RTOS_SDK projects.
* Start by installing the esp-idf for your platform (see files in this directory with steps for Windows, OS X, Linux).
* Start by installing the ESP8266_RTOS_SDK for your platform (see files in this directory with steps for Windows, OS X, Linux).
* We suggest building a project from the command line first, to get a feel for how that process works. You also need to use the command line to configure your esp-idf project (via ``make menuconfig``), this is not currently supported inside Eclipse.
* We suggest building a project from the command line first, to get a feel for how that process works. You also need to use the command line to configure your ESP8266_RTOS_SDK project (via ``make menuconfig``), this is not currently supported inside Eclipse.
* Download the Eclipse Installer for your platform from eclipse.org_.
@ -21,7 +20,7 @@ The Eclipse IDE gives you a graphical integrated development environment for wri
Windows Users
=============
Using ESP-IDF with Eclipse on Windows requires different configuration steps. :ref:`See the Eclipse IDE on Windows guide <eclipse-windows-setup>`.
Using ESP8266_RTOS_SDK with Eclipse on Windows requires different configuration steps. :ref:`See the Eclipse IDE on Windows guide <eclipse-windows-setup>`.
Setting up Eclipse
==================
@ -31,13 +30,13 @@ Once your new Eclipse installation launches, follow these steps:
Import New Project
------------------
* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory.
* Eclipse makes use of the Makefile support in ESP8266_RTOS_SDK. This means you need to start by creating an ESP8266_RTOS_SDK project. You can use the idf-template project from github, or open one of the examples in the ESP8266_RTOS_SDK examples subdirectory.
* Once Eclipse is running, choose File -> Import...
* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next.
* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile).
* On the next page, enter "Existing Code Location" to be the directory of your ESP8266_RTOS_SDK project. Don't specify the path to the ESP8266_RTOS_SDK directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile).
* On the same page, under "Toolchain for Indexer Settings" choose "Cross GCC". Then click Finish.
@ -49,9 +48,9 @@ Project Properties
* Click on the "Environment" properties page under "C/C++ Build". Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``.
* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed.
* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP8266_RTOS_SDK is installed.
* Edit the ``PATH`` environment variable. Keep the current value, and append the path to the Xtensa toolchain installed as part of IDF setup, if this is not already listed on the PATH. A typical path to the toolchain looks like ``/home/user-name/esp/xtensa-esp32-elf/bin``. Note that you need to add a colon ``:`` before the appended path.
* Edit the ``PATH`` environment variable. Keep the current value, and append the path to the Xtensa toolchain installed as part of ESP8266_RTOS_SDK setup, if this is not already listed on the PATH. A typical path to the toolchain looks like ``/home/user-name/esp/xtensa-lx106-elf/bin``. Note that you need to add a colon ``:`` before the appended path.
* On macOS, add a ``PYTHONPATH`` environment variable and set it to ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``. This is so that the system Python, which has pyserial installed as part of the setup steps, overrides any built-in Eclipse Python.
@ -59,9 +58,9 @@ Navigate to "C/C++ General" -> "Preprocessor Include Paths" property page:
* Click the "Providers" tab
* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Change "Command to get compiler specs" to ``xtensa-esp32-elf-gcc ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"``.
* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Change "Command to get compiler specs" to ``xtensa-lx106-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``.
* In the list of providers, click "CDT GCC Build Output Parser" and change the "Compiler command pattern" to ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)``
* In the list of providers, click "CDT GCC Build Output Parser" and change the "Compiler command pattern" to ``xtensa-lx106-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)``
Navigate to "C/C++ General" -> "Indexer" property page:
@ -78,13 +77,13 @@ Navigate to "C/C++ Build" -> "Behavior" property page:
Building in Eclipse
-------------------
Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the esp-idf build process. These errors and warnings will go away after you build the project.
Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the ESP8266_RTOS_SDK build process. These errors and warnings will go away after you build the project.
* Click OK to close the Properties dialog in Eclipse.
* Outside Eclipse, open a command line prompt. Navigate to your project directory, and run ``make menuconfig`` to configure your project's esp-idf settings. This step currently has to be run outside Eclipse.
* Outside Eclipse, open a command line prompt. Navigate to your project directory, and run ``make menuconfig`` to configure your project's ESP8266_RTOS_SDK settings. This step currently has to be run outside Eclipse.
*If you try to build without running a configuration step first, esp-idf will prompt for configuration on the command line - but Eclipse is not able to deal with this, so the build will hang or fail.*
*If you try to build without running a configuration step first, ESP8266_RTOS_SDKf will prompt for configuration on the command line - but Eclipse is not able to deal with this, so the build will hang or fail.*
* Back in Eclipse, choose Project -> Build to build your project.

166
docs/en/get-started/index.rst
View File

@ -1,42 +1,39 @@
***********
***********
Get Started
***********
:link_to_translation:`zh_CN:[中文]`
This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
.. include:: /_build/inc/version-note.inc
This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP8266EX. Through a simple example we would like to illustrate how to use ESP8266\_RTOS\_SDK (ESP-IDF Style), including the menu based configuration, compiling the ESP8266\_RTOS\_SDK and firmware download to ESP8266EX boards.
Introduction
============
ESP32 integrates Wi-Fi (2.4 GHz band) and Bluetooth 4.2 solutions on a single chip, along with dual high performance cores, Ultra Low Power co-processor and several peripherals. Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform to meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
The ESP8266EX microcontroller integrates a Tensilica L106 32-bit RISC processor, which achieves extra-low power consumption and reaches a maximum clock speed of 160 MHz. The Real-Time Operating System (RTOS) and Wi-Fi stack allow about 80% of the processing power to be available for user application programming and development.
Espressif provides the basic hardware and software resources that help application developers to build their ideas around the ESP32 series hardware. The software development framework by Espressif is intended for rapidly developing Internet-of-Things (IoT) applications, with Wi-Fi, Bluetooth, power management and several other system features.
Espressif provides the basic hardware and software resources that help application developers to build their ideas around the ESP8266EX series hardware. The software development framework by Espressif is intended for rapidly developing Internet-of-Things (IoT) applications, with Wi-Fi, power management and several other system features.
What You Need
=============
To develop applications for ESP32 you need:
To develop applications for ESP8266EX 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**
* **Toolchain** to build the **Application** for ESP8266EX
* **ESP8266\_RTOS\_SDK** that essentially contains API for ESP8266EX and scripts to operate the **Toolchain**
* A text editor to write programs (**Projects**) in C, e.g. `Eclipse <https://www.eclipse.org/>`_
* The **ESP32** board itself and a **USB cable** to connect it to the **PC**
* The **ESP8266EX** board itself and a **USB cable** to connect it to the **PC**
.. figure:: ../../_static/what-you-need.png
:align: center
:alt: Development of applications for ESP32
:alt: Development of applications for ESP8266EX
:figclass: align-center
Development of applications for ESP32
Development of applications for ESP8266EX
Preparation of development environment consists of three steps:
1. Setup of **Toolchain**
2. Getting of **ESP-IDF** from GitHub
2. Getting of **ESP8266\_RTOS\_SDK** from GitHub
3. Installation and configuration of **Eclipse**
You may skip the last step, if you prefer to use different editor.
@ -45,7 +42,7 @@ Having environment set up, you are ready to start the most interesting part - th
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**
3. Flashing (uploading) of the **Application** to **ESP8266EX**
4. Monitoring / debugging of the **Application**
See instructions below that will walk you through these steps.
@ -54,14 +51,12 @@ 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.
If you have one of ESP8266 development boards listed below, click on provided links to get you up and running.
.. toctree::
:maxdepth: 1
ESP32 DevKitC <get-started-devkitc>
ESP-WROVER-KIT <get-started-wrover-kit>
ESP32-PICO-KIT <get-started-pico-kit>
ESP8266 DevKitC <get-started-devkitc>
If you have different board, move to sections below.
@ -71,7 +66,7 @@ If you have different board, move to sections below.
Setup Toolchain
===============
The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions.
The quickest way to start development with ESP8266EX is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions.
.. toctree::
:hidden:
@ -101,53 +96,44 @@ The quickest way to start development with ESP32 is by installing a prebuilt too
.. note::
We are using ``~/esp`` directory to install the prebuilt toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands.
We are using ``~/esp`` directory to install the prebuilt toolchain, ESP8266_RTOS_SDK and sample applications. You can use different directory, but need to adjust respective commands.
Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup`.
Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment..
Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf`.
.. _get-started-get-esp-idf:
Get ESP-IDF
===========
Get ESP8266\_RTOS\_SDK
======================
.. highlight:: bash
Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_.
Besides the toolchain (that contains programs to compile and build the application), you also need ESP8266 specific API / libraries. They are provided by Espressif in `ESP8266_RTOS_SDK repository <https://github.com/espressif/ESP8266_RTOS_SDK>`_.
.. include:: /_build/inc/git-clone.inc
Consult :doc:`/versions` for information about which version of ESP-IDF to use in a given situation.
.. 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 --recursive
.. _get-started-setup-path:
Setup Path to ESP-IDF
=====================
Setup Path to ESP8266\_RTOS\_SDK
================================
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 <add-idf_path-to-profile-windows>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos>` in section :doc:`add-idf_path-to-profile`.
The toolchain programs access ESP8266\_RTOS\_SDK 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.
.. _get-started-get-packages:
Install the Required Python Packages
====================================
Python packages required by ESP-IDF are located in the ``$IDF_PATH/requirements.txt`` file. You can install them by running::
Python packages required by ESP8266\_RTOS\_SDK are located in the ``$IDF_PATH/requirements.txt`` file. You can install them by running::
python -m pip install --user -r $IDF_PATH/requirements.txt
.. note::
Please invoke that version of the Python interpreter which you will be using with ESP-IDF. The version of the
Please invoke that version of the Python interpreter which you will be using with ESP8266_RTOS_SDK. The version of the
interpreter can be checked by running command ``python --version`` and depending on the result, you might want to
use ``python2``, ``python2.7`` or similar instead of ``python``, e.g.::
@ -158,18 +144,18 @@ Python packages required by ESP-IDF are located in the ``$IDF_PATH/requirements.
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.
Now you are ready to prepare your application for ESP8266. To start off quickly, we will use :example:`get-started/project_template` project from :idf:`examples` directory in IDF.
Copy :example:`get-started/hello_world` to ``~/esp`` directory::
Copy :example:`get-started/project_template` to ``~/esp`` directory::
cd ~/esp
cp -r $IDF_PATH/examples/get-started/hello_world .
cp -r $IDF_PATH/examples/get-started/project_template .
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.
The ESP8266_RTOS_SDK build system does not support spaces in paths to ESP8266_RTOS_SDK or to projects.
.. _get-started-connect:
@ -177,7 +163,7 @@ You can also find a range of example projects under the :idf:`examples` director
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.
You are almost there. To be able to proceed further, connect ESP8266 board to PC, check under what serial port the board is visible and verify if serial communication works. Note the port number, as it will be required in the next step.
.. _get-started-configure:
@ -185,9 +171,9 @@ You are almost there. To be able to proceed further, connect ESP32 board to PC,
Configure
=========
Being in terminal window, go to directory of ``hello_world`` application by typing ``cd ~/esp/hello_world``. Then start project configuration utility ``menuconfig``::
Being in terminal window, go to directory of ``project_template`` application by typing ``cd ~/esp/project_template``. Then start project configuration utility ``menuconfig``::
cd ~/esp/hello_world
cd ~/esp/project_template
make menuconfig
If previous steps have been done correctly, the following menu will be displayed:
@ -204,7 +190,6 @@ In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to
.. note::
On Windows, serial ports have names like COM1. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``.
(See :doc:`establish-serial-connection` for full details.)
Here are couple of tips on navigation and use of ``menuconfig``:
@ -220,10 +205,6 @@ Here are couple of tips on navigation and use of ``menuconfig``:
If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``.
.. attention::
When using ESP32-DevKitC board with ESP32-SOLO-1 module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing example applications.
.. _get-started-build-flash:
@ -234,39 +215,37 @@ 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.
This will compile the application and all the ESP8266\_RTOS\_SDK components, generate bootloader, partition table, and application binaries, and flash these binaries to your ESP8266 board.
.. highlight:: none
::
esptool.py v2.0-beta2
esptool.py v2.4.0
Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
esptool.py v2.0-beta2
Connecting........___
esptool.py v2.4.0
Connecting....
Chip is ESP8266EX
Features: WiFi
MAC: ec:fa:bc:1d:33:2d
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)...
Compressed 7952 bytes to 5488...
Wrote 7952 bytes (5488 compressed) at 0x00000000 in 0.5 seconds (effective 129.9 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)...
Compressed 234800 bytes to 162889...
Wrote 234800 bytes (162889 compressed) at 0x00010000 in 14.4 seconds (effective 130.6 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)...
Compressed 3072 bytes to 83...
Wrote 3072 bytes (83 compressed) at 0x00008000 in 0.0 seconds (effective 1789.8 kbit/s)...
Hash of data verified.
Leaving...
Hard resetting...
Hard resetting via RTS pin...
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 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 "project_template" application will start.
If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide <eclipse-setup>`.
@ -276,27 +255,29 @@ If you'd like to use the Eclipse IDE instead of running ``make``, check out the
Monitor
=======
To see if "hello_world" application is indeed running, type ``make monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
To see if "project_template" application is indeed running, type ``make monitor``.
$ make monitor
MONITOR
--- idf_monitor on /dev/ttyUSB0 115200 ---
--- idf_monitor on /dev/ttyUSB0 74880 ---
--- 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
ets Jan 8 2013,rst cause:1, boot mode:(3,6)
load 0x40100000, len 4400, room 16
0x40100000: _stext at ??:?
tail 0
chksum 0x6f
load 0x3ffe8408, len 3516, room 8
tail 4
chksum 0x5d
...
Several lines below, after start up and diagnostic log, you should see "Hello world!" printed out by the application. ::
Several lines below, after start up and diagnostic log, you should see "SDK version: xxxxxxx" 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...
SDK version:v3.1-dev-311-g824cd8c8-dirty
To exit the monitor use shortcut ``Ctrl+]``.
@ -307,11 +288,9 @@ To exit the monitor use shortcut ``Ctrl+]``.
e<EFBFBD><EFBFBD><EFBFBD>)(Xn@<40>y.!<21><>(<28>PW+)<29><>Hn9a؅/9<>!<21>t5<74><35>P<EFBFBD>~<7E>k<EFBFBD><6B>e<EFBFBD>ea<65>5<EFBFBD>jA
~zY<7A><59>Y(1<>,1<15><> e<><65><EFBFBD>)(Xn@<40>y.!Dr<44>zY(<28>jpi<70>|<7C>+z5Ymvp
or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``make menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
To execute ``make flash`` and ``make monitor`` in one go, type ``make flash monitor``.
To execute ``make flash`` and ``make monitor`` in one go, type ``make flash monitor``. Check section :doc:`IDF Monitor <idf-monitor>` for handy shortcuts and more details on using this application.
That's all what you need to get started with ESP32!
That's all what you need to get started with ESP8266!
Now you are ready to try some other :idf:`examples`, or go right to developing your own applications.
@ -343,29 +322,14 @@ Some environment variables can be specified whilst calling ``make`` allowing use
All subsequent calls of ``make`` within the same terminal session will use
the exported value given that the variable is not simultaneously overridden.
Updating ESP-IDF
================
After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf`.
If downloading to a new path, remember to :doc:`add-idf_path-to-profile` so that the toolchain scripts know where to find the ESP-IDF in its release specific location.
Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using <updating>`.
Related Documents
=================
.. toctree::
:maxdepth: 1
add-idf_path-to-profile
establish-serial-connection
make-project
eclipse-setup
idf-monitor
toolchain-setup-scratch
.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
.. _Releases page: https://github.com/espressif/esp-idf/releases
.. _Stable version: https://github.com/espressif/ESP8266_RTOS_SDK/tree/master/docs/en
.. _Releases page: https://github.com/espressif/ESP8266_RTOS_SDK/releases

70
docs/en/get-started/linux-setup.rst
View File

@ -1,71 +1,61 @@
*************************************
*************************************
Standard Setup of Toolchain for Linux
*************************************
:link_to_translation:`zh_CN:[中文]`
Install Prerequisites
=====================
To compile with ESP-IDF you need to get the following packages:
To compile with ESP8266_RTOS_SDK you need to get the following packages:
- CentOS 7::
sudo yum install gcc git wget make ncurses-devel flex bison gperf python python2-cryptography
sudo yum install gcc git wget make ncurses-devel flex bison gperf python pyserial
- Ubuntu and Debian::
sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future
sudo apt-get install gcc 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 python2-cryptography python2-future
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial
.. note::
Some older Linux distributions may be missing some of the Python packages listed above (or may use ``pyserial`` version 2.x which is not supported by ESP-IDF). It is possible to install these packages via ``pip`` instead - as described in section :ref:`get-started-get-packages`.
Toolchain Setup
===============
.. include:: /_build/inc/download-links.inc
ESP32 toolchain for Linux is available for download from Espressif website:
ESP8266 toolchain for Linux is available for download from Espressif website:
- for 64-bit Linux:
|download_link_linux64|
https://dl.espressif.com/dl/xtensa-lx106-elf-linux64-1.22.0-88-gde0bdc1-4.8.5.tar.gz
- for 32-bit Linux:
|download_link_linux32|
https://dl.espressif.com/dl/xtensa-lx106-elf-linux32-1.22.0-88-gde0bdc1-4.8.5.tar.gz
1. Download this file, then extract it in ``~/esp`` directory:
1. Download this file, then extract it in ``~/esp`` directory::
- for 64-bit Linux:
.. include:: /_build/inc/unpack-code-linux64.inc
- for 32-bit Linux:
.. include:: /_build/inc/unpack-code-linux32.inc
mkdir -p ~/esp
cd ~/esp
tar -xzf ~/Downloads/https://dl.espressif.com/dl/xtensa-lx106-elf-linux64-1.22.0-88-gde0bdc1-4.8.5.tar.gz
.. _setup-linux-toolchain-add-it-to-path:
2. The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
2. The toolchain will be extracted into ``~/esp/xtensa-lx106-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::
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-lx106-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
export PATH="$PATH:$HOME/esp/xtensa-lx106-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="$HOME/esp/xtensa-esp32-elf/bin:$PATH"'
alias get_lx106='export PATH="$PATH:$HOME/esp/xtensa-lx106-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``.
Then when you need the toolchain you can type ``get_lx106`` on the command line and the toolchain will be added to your ``PATH``.
.. note::
If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead. In CentOS, ``alias`` should set in ``.bashrc``.
If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead.
3. Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set::
@ -74,7 +64,7 @@ ESP32 toolchain for Linux is available for download from Espressif website:
You are looking for similar result containing toolchain's path at the end of displayed string::
$ printenv PATH
/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/home/user-name/esp/xtensa-esp32-elf/bin
/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/home/user-name/esp/xtense-lx106-elf/bin
Instead of ``/home/user-name`` there should be a home path specific to your installation.
@ -82,22 +72,7 @@ ESP32 toolchain for Linux is available for download from Espressif website:
Permission issues /dev/ttyUSB0
------------------------------
With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group>`.
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/
Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above.
Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.
With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP8266.
Next Steps
@ -109,10 +84,5 @@ To carry on with development environment setup, proceed to section :ref:`get-sta
Related Documents
=================
.. toctree::
:maxdepth: 1
linux-setup-scratch
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository

37
docs/en/get-started/macos-setup.rst
View File

@ -1,7 +1,6 @@
**************************************
Standard Setup of Toolchain for Mac OS
**************************************
:link_to_translation:`zh_CN:[中文]`
Install Prerequisites
=====================
@ -10,48 +9,40 @@ Install Prerequisites
sudo easy_install pip
.. note::
- install pyserial::
sudo pip install pyserial
``pip`` will be used later for installing :ref:`the required Python packages <get-started-get-packages>`.
Toolchain Setup
===============
.. include:: /_build/inc/download-links.inc
ESP8266 toolchain for macOS is available for download from Espressif website:
ESP32 toolchain for macOS is available for download from Espressif website:
https://dl.espressif.com/dl/xtensa-lx106-elf-osx-1.22.0-88-gde0bdc1-4.8.5.tar.gz
|download_link_osx|
Download this file, then extract it in ``~/esp`` directory::
Download this file, then extract it in ``~/esp`` directory:
.. include:: /_build/inc/unpack-code-osx.inc
mkdir -p ~/esp
cd ~/esp
tar -xzf ~/Downloads/xtensa-lx106-elf-osx-1.22.0-88-gde0bdc1-4.8.5.tar.gz
.. _setup-macos-toolchain-add-it-to-path:
The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
The toolchain will be extracted into ``~/esp/xtensa-lx106-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::
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-lx106-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH
export PATH=$PATH:$HOME/esp/xtensa-lx106-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=$HOME/esp/xtensa-esp32-elf/bin:$PATH"
alias get_lx106="export PATH=$PATH:$HOME/esp/xtensa-lx106-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``.
Then when you need the toolchain you can type ``get_lx106`` 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

26
docs/en/get-started/windows-setup.rst
View File

@ -1,7 +1,6 @@
***************************************
Standard Setup of Toolchain for Windows
***************************************
:link_to_translation:`zh_CN:[中文]`
Introduction
============
@ -14,7 +13,7 @@ Toolchain Setup
The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com:
https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20181001.zip
https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20180110.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.
@ -22,7 +21,7 @@ Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``
Check it Out
============
Open a MSYS2 MINGW32 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. Create a directory named ``esp`` that is a default location to develop ESP32 applications. To do so, run the following shell command::
Open a MSYS2 MINGW32 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. Create a directory named ``esp`` that is a default location to develop ESP8266 applications. To do so, run the following shell command::
mkdir -p ~/esp
@ -35,7 +34,7 @@ By typing ``cd ~/esp`` you can then move to the newly created directory. If ther
MSYS2 MINGW32 shell window
Use this window in the following steps setting up development environment for ESP32.
Use this window in the following steps setting up development environment for ESP8266.
Next Steps
@ -43,28 +42,9 @@ Next Steps
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
Updating The Environment
========================
When IDF is updated, sometimes new toolchains are required or new requirements are added to the Windows MSYS2 environment. To move any data from an old version of the precompiled environment to a new one:
- Take the old MSYS2 environment (ie ``C:\msys32``) and move/rename it to a different directory (ie ``C:\msys32_old``).
- Download the new precompiled environment using the steps above.
- Unzip the new MSYS2 environment to ``C:\msys32`` (or another location).
- Find the old ``C:\msys32_old\home`` directory and move this into ``C:\msys32``.
- You can now delete the ``C:\msys32_old`` directory if you no longer need it.
You can have independent different MSYS2 environments on your system, as long as they are in different directories.
There are :ref:`also steps to update the existing environment without downloading a new one <updating-existing-windows-environment>`, although this is more complex.
Related Documents
=================
.. toctree::
:maxdepth: 1
windows-setup-scratch
.. _MSYS2: https://msys2.github.io/

37
docs/en/index.rst
View File

@ -1,17 +1,12 @@
ESP-IDF Programming Guide
=========================
:link_to_translation:`zh_CN:[中文]`
ESP8266\_RTOS\_SDK (IDF Style) Programming Guide
================================================
This is the documentation for Espressif IoT Development Framework (`esp-idf <https://github.com/espressif/esp-idf>`_). ESP-IDF is the official development framework for the `ESP32 <https://espressif.com/en/products/hardware/esp32/overview>`_ chip.
This is the documentation for the new `ESP8266_RTOS_SDK <https://github.com/espressif/ESP8266_RTOS_SDK>`_ which refacted to be ESP-IDF Style. ESP8266\_RTOS\_SDK is the official development framework for the `ESP8266EX <https://www.espressif.com/en/products/hardware/esp8266ex/overview>`_ chip.
================== ================== ==================
|Get Started|_ |API Reference|_ |H/W Reference|_
|Get Started|_ |API Reference|_ |API Guides|_
------------------ ------------------ ------------------
`Get Started`_ `API Reference`_ `H/W Reference`_
------------------ ------------------ ------------------
|API Guides|_ |Contribute|_ |Resources|_
------------------ ------------------ ------------------
`API Guides`_ `Contribute`_ `Resources`_
`Get Started`_ `API Reference`_ `API Guides`_
================== ================== ==================
.. |Get Started| image:: ../_static/get-started.gif
@ -20,36 +15,14 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf <htt
.. |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::
:hidden:
Get Started <get-started/index>
Get Started (CMake Preview) <get-started-cmake/index>
API Reference <api-reference/index>
H/W Reference <hw-reference/index>
API Guides <api-guides/index>
Contribute <contribute/index>
Versions <versions>
Resources <resources>
Copyrights <COPYRIGHT>
About <about>
语言/Languages <languages>
Guide Downloads <https://readthedocs.com/projects/espressif-esp-idf/downloads/>
* :ref:`genindex`

2
docs/gen-toolchain-links.py
View File

@ -60,7 +60,7 @@ def main():
unpack_cmd = p[2]
unpack_code = p[3]
archive_name = 'xtensa-esp32-elf-{}-{}-{}.{}'.format(
archive_name = 'xtensa-lx106-elf-{}-{}-{}.{}'.format(
platform_name, toolchain_desc, gcc_version, extension)
print('.. |download_link_{}| replace:: {}{}'.format(

42
docs/gen-version-specific-includes.py
View File

@ -16,12 +16,12 @@ TEMPLATES = {
"en" : {
"git-clone" : {
"template" : """
To obtain a local copy: open terminal, navigate to the directory you want to put ESP-IDF, and clone the repository using ``git clone`` command::
To obtain a local copy: open terminal, navigate to the directory you want to put ESP8266_RTOS_SDK, and clone the repository using ``git clone`` command::
cd ~/esp
git clone %(clone_args)s--recursive https://github.com/espressif/esp-idf.git
git clone %(clone_args)s--recursive https://github.com/espressif/ESP8266_RTOS_SDK.git
ESP-IDF will be downloaded into ``~/esp/esp-idf``.
ESP8266_RTOS_SDK will be downloaded into ``~/esp/ESP8266_RTOS_SDK``.
.. note::
@ -31,37 +31,37 @@ ESP-IDF will be downloaded into ``~/esp/esp-idf``.
%(zipfile_note)s
"""
,"master" : 'This command will clone the master branch, which has the latest development ("bleeding edge") version of ESP-IDF. It is fully functional and updated on weekly basis with the most recent features and bugfixes.'
,"branch" : 'The ``git clone`` option ``-b %(clone_arg)s`` tells git to clone the %(ver_type)s in the ESP-IDF repository corresponding to this version of the documentation.'
,"master" : 'This command will clone the master branch, which has the latest development ("bleeding edge") version of ESP8266_RTOS_SDK. It is fully functional and updated on weekly basis with the most recent features and bugfixes.'
,"branch" : 'The ``git clone`` option ``-b %(clone_arg)s`` tells git to clone the %(ver_type)s in the ESP8266_RTOS_SDK repository corresponding to this version of the documentation.'
,"zipfile" : {
"stable" : 'As a fallback, it is also possible to download a zip file of this stable release from the `Releases page`_. Do not download the "Source code" zip file(s) generated automatically by GitHub, they do not work with ESP-IDF.'
,"unstable" : 'GitHub\'s "Download zip file" feature does not work with ESP-IDF, a ``git clone`` is required. As a fallback, `Stable version`_ can be installed without Git.'
"stable" : 'As a fallback, it is also possible to download a zip file of this stable release from the `Releases page`_. Do not download the "Source code" zip file(s) generated automatically by GitHub, they do not work with ESP8266_RTOS_SDK.'
,"unstable" : 'GitHub\'s "Download zip file" feature does not work with ESP8266_RTOS_SDK, a ``git clone`` is required. As a fallback, `Stable version`_ can be installed without Git.'
}, # zipfile
}, # git-clone
"version-note" : {
"master" : """
.. note::
This is documentation for the master branch (latest version) of ESP-IDF. This version is under continual development. `Stable version`_ documentation is available, as well as other :doc:`/versions`.
This is documentation for the master branch (latest version) of ESP8266_RTOS_SDK. This version is under continual development. `Stable version`_ documentation is available, as well as other :doc:`/versions`.
"""
,"stable" : """
.. note::
This is documentation for stable version %s of ESP-IDF. Other :doc:`/versions` are also available.
This is documentation for stable version %s of ESP8266_RTOS_SDK. Other :doc:`/versions` are also available.
"""
,"branch" : """
.. note::
This is documentation for %s ``%s`` of ESP-IDF. Other :doc:`/versions` are also available.
This is documentation for %s ``%s`` of ESP8266_RTOS_SDK. Other :doc:`/versions` are also available.
"""
}, # version-note
}, # en
"zh_CN" : {
"git-clone" : {
"template" : """
获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库::
获取本地副本：打开终端，切换到你要存放 ESP8266_RTOS_SDK 的工作目录，使用 ``git clone`` 命令克隆远程仓库::
cd ~/esp
git clone %(clone_args)s--recursive https://github.com/espressif/esp-idf.git
git clone %(clone_args)s--recursive https://github.com/espressif/ESP8266_RTOS_SDK.git
ESP-IDF 将会被下载到 ``~/esp/esp-idf`` 目录下。
ESP8266_RTOS_SDK 将会被下载到 ``~/esp/ESP8266_RTOS_SDK`` 目录下。
.. note::
@ -71,26 +71,26 @@ ESP-IDF 将会被下载到 ``~/esp/esp-idf`` 目录下。
%(zipfile_note)s
"""
,"master" : '此命令将克隆 master 分支，该分支保存着 ESP-IDF 的最新版本，它功能齐全，每周都会更新一些新功能并修正一些错误。'
,"branch" : '``git clone`` 命令的 ``-b %(clone_arg)s`` 选项告诉 git 从 ESP-IDF 仓库中克隆与此版本的文档对应的分支。'
,"master" : '此命令将克隆 master 分支，该分支保存着 ESP8266_RTOS_SDK 的最新版本，它功能齐全，每周都会更新一些新功能并修正一些错误。'
,"branch" : '``git clone`` 命令的 ``-b %(clone_arg)s`` 选项告诉 git 从 ESP8266_RTOS_SDK 仓库中克隆与此版本的文档对应的分支。'
,"zipfile" : {
"stable" : '作为备份，还可以从 `Releases page`_ 下载此稳定版本的 zip 文件。不要下载由 GitHub 自动生成的"源代码"的 zip 文件，它们不适用于 ESP-IDF。'
,"unstable" : 'GitHub 中"下载 zip 文档"的功能不适用于 ESP-IDF，所以需要使用 ``git clone`` 命令。作为备份，可以在没有安装 Git 的环境中下载 `Stable version`_ 的 zip 归档文件。'
"stable" : '作为备份，还可以从 `Releases page`_ 下载此稳定版本的 zip 文件。不要下载由 GitHub 自动生成的"源代码"的 zip 文件，它们不适用于 ESP8266_RTOS_SDK。'
,"unstable" : 'GitHub 中"下载 zip 文档"的功能不适用于 ESP8266_RTOS_SDK，所以需要使用 ``git clone`` 命令。作为备份，可以在没有安装 Git 的环境中下载 `Stable version`_ 的 zip 归档文件。'
}, # zipfile
}, # git-clone
"version-note" : {
"master" : """
.. note::
这是ESP-IDF master 分支（最新版本）的文档，该版本在持续开发中。还有 `Stable version`_ 的文档，以及其他版本的文档 :doc:`/versions` 供参考。
This is documentation for the master branch (latest version) of ESP-IDF. This version is under continual development. `Stable version`_ documentation is available, as well as other :doc:`/versions`.
这是ESP8266_RTOS_SDK master 分支（最新版本）的文档，该版本在持续开发中。还有 `Stable version`_ 的文档，以及其他版本的文档 :doc:`/versions` 供参考。
This is documentation for the master branch (latest version) of ESP8266_RTOS_SDK. This version is under continual development. `Stable version`_ documentation is available, as well as other :doc:`/versions`.
"""
,"stable" : """
.. note::
这是ESP-IDF 稳定版本 %s 的文档，还有其他版本的文档 :doc:`/versions` 供参考。
这是ESP8266_RTOS_SDK 稳定版本 %s 的文档，还有其他版本的文档 :doc:`/versions` 供参考。
"""
,"branch" : """
.. note::
这是ESP-IDF %s ``%s`` 版本的文档，还有其他版本的文档 :doc:`/versions` 供参考。
这是ESP8266_RTOS_SDK %s ``%s`` 版本的文档，还有其他版本的文档 :doc:`/versions` 供参考。
"""
}, # version-note
}# zh_CN

2
docs/link-roles.py
View File

@ -20,7 +20,7 @@ def setup(app):
rev = get_github_rev()
# links to files or folders on the GitHub
baseurl = 'https://github.com/espressif/esp-idf'
baseurl = 'https://github.com/espressif/ESP8266_RTOS_SDK'
app.add_role('idf', autolink('{}/tree/{}/%s'.format(baseurl, rev)))
app.add_role('idf_file', autolink('{}/blob/{}/%s'.format(baseurl, rev)))
app.add_role('idf_raw', autolink('{}/raw/{}/%s'.format(baseurl, rev)))

18
docs/requirements.txt
View File

@ -1,12 +1,12 @@
# This is a list of python packages used to generate documentation. This file is used with pip:
# pip install --user -r requirements.txt
#
sphinx==1.6.5
sphinx-rtd-theme
breathe==4.7.3
sphinxcontrib-blockdiag==1.5.3
sphinxcontrib-seqdiag==0.8.5
sphinxcontrib-actdiag==0.8.5
sphinxcontrib-nwdiag==0.9.5
recommonmark
future>=0.16.0 # for ../tools/gen_esp_err_to_name.py
#sphinx==1.6.5
#sphinx-rtd-theme
#breathe==4.7.3
#sphinxcontrib-blockdiag==1.5.3
#sphinxcontrib-seqdiag==0.8.5
#sphinxcontrib-actdiag==0.8.5
#sphinxcontrib-nwdiag==0.9.5
#recommonmark
#future>=0.16.0 # for ../tools/gen_esp_err_to_name.py