From fcf76320c84f92c37379f72024b226af3d38b477 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Mon, 11 Nov 2019 11:39:42 +0800 Subject: [PATCH 01/47] docs: Start refactoring IDF-specific docs features into extensions Run the actual IDF build system to determine what components are linked for a particular target. --- docs/conf_common.py | 70 +++------------------------- docs/idf_build_system/CMakeLists.txt | 6 +++ docs/idf_build_system/__init__.py | 48 +++++++++++++++++++ docs/kconfig_reference.py | 52 +++++++++++++++++++++ 4 files changed, 112 insertions(+), 64 deletions(-) create mode 100644 docs/idf_build_system/CMakeLists.txt create mode 100644 docs/idf_build_system/__init__.py create mode 100644 docs/kconfig_reference.py diff --git a/docs/conf_common.py b/docs/conf_common.py index 84cf86a3b1..4622eccb4d 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -35,12 +35,16 @@ try: except KeyError: builddir = '_build' +builddir = os.path.abspath(builddir) + # Fill in a default IDF_PATH if it's missing (ie when Read The Docs is building the docs) try: idf_path = os.environ['IDF_PATH'] except KeyError: idf_path = os.path.realpath(os.path.join(os.path.dirname(__file__), '..')) +# Set the idf_target chip. This is a hack right now. +idf_target = 'esp32s2' def call_with_python(cmd): # using sys.executable ensures that the scripts are called with the same Python interpreter @@ -60,70 +64,6 @@ copy_if_modified('xml/', 'xml_in/') # Generate 'api_name.inc' files using the XML files by Doxygen call_with_python('../gen-dxd.py') - -def find_component_files(parent_dir, target_filename): - parent_dir = os.path.abspath(parent_dir) - result = [] - - component_files = dict() - - for (dirpath, dirnames, filenames) in os.walk(parent_dir): - try: - # note: trimming "examples" dir as MQTT submodule - # has its own examples directory in the submodule, not part of IDF - dirnames.remove("examples") - except ValueError: - pass - if target_filename in filenames: - component_files[os.path.basename(dirpath)] = os.path.join(dirpath, target_filename) - - components = sorted(component_files.keys()) - - for component in components: - result.append(component_files[component]) - - print("List of %s: %s" % (target_filename, ", ".join(components))) - return result - - -# Generate 'kconfig.inc' file from components' Kconfig files -print("Generating kconfig.inc from kconfig contents") -kconfig_inc_path = '{}/inc/kconfig.inc'.format(builddir) -temp_sdkconfig_path = '{}/sdkconfig.tmp'.format(builddir) - -kconfigs = find_component_files("../../components", "Kconfig") -kconfig_projbuilds = find_component_files("../../components", "Kconfig.projbuild") -sdkconfig_renames = find_component_files("../../components", "sdkconfig.rename") - -kconfigs_source_path = '{}/inc/kconfigs_source.in'.format(builddir) -kconfig_projbuilds_source_path = '{}/inc/kconfig_projbuilds_source.in'.format(builddir) - -prepare_kconfig_files_args = [sys.executable, - "../../tools/kconfig_new/prepare_kconfig_files.py", - "--env", "COMPONENT_KCONFIGS={}".format(" ".join(kconfigs)), - "--env", "COMPONENT_KCONFIGS_PROJBUILD={}".format(" ".join(kconfig_projbuilds)), - "--env", "COMPONENT_KCONFIGS_SOURCE_FILE={}".format(kconfigs_source_path), - "--env", "COMPONENT_KCONFIGS_PROJBUILD_SOURCE_FILE={}".format(kconfig_projbuilds_source_path), - ] -subprocess.check_call(prepare_kconfig_files_args) - -confgen_args = [sys.executable, - "../../tools/kconfig_new/confgen.py", - "--kconfig", "../../Kconfig", - "--sdkconfig-rename", "../../sdkconfig.rename", - "--config", temp_sdkconfig_path, - "--env", "COMPONENT_KCONFIGS={}".format(" ".join(kconfigs)), - "--env", "COMPONENT_KCONFIGS_PROJBUILD={}".format(" ".join(kconfig_projbuilds)), - "--env", "COMPONENT_SDKCONFIG_RENAMES={}".format(" ".join(sdkconfig_renames)), - "--env", "COMPONENT_KCONFIGS_SOURCE_FILE={}".format(kconfigs_source_path), - "--env", "COMPONENT_KCONFIGS_PROJBUILD_SOURCE_FILE={}".format(kconfig_projbuilds_source_path), - "--env", "IDF_PATH={}".format(idf_path), - "--env", "IDF_TARGET={}".format(os.environ.get('IDF_TARGET', 'esp32')), - "--output", "docs", kconfig_inc_path + '.in' - ] -subprocess.check_call(confgen_args) -copy_if_modified(kconfig_inc_path + '.in', kconfig_inc_path) - # Generate 'esp_err_defs.inc' file with ESP_ERR_ error code definitions esp_err_inc_path = '{}/inc/esp_err_defs.inc'.format(builddir) call_with_python('../../tools/gen_esp_err_to_name.py --rst_output ' + esp_err_inc_path + '.in') @@ -176,6 +116,8 @@ extensions = ['breathe', 'sphinxcontrib.rackdiag', 'sphinxcontrib.packetdiag', 'html_redirects', + 'idf_build_system', + 'kconfig_reference', 'sphinx.ext.todo', ] diff --git a/docs/idf_build_system/CMakeLists.txt b/docs/idf_build_system/CMakeLists.txt new file mode 100644 index 0000000000..32ab221c98 --- /dev/null +++ b/docs/idf_build_system/CMakeLists.txt @@ -0,0 +1,6 @@ +# The following lines of boilerplate have to be in your project's +# CMakeLists in this exact order for cmake to work correctly +cmake_minimum_required(VERSION 3.5) + +include($ENV{IDF_PATH}/tools/cmake/project.cmake) +project(dummy_project) diff --git a/docs/idf_build_system/__init__.py b/docs/idf_build_system/__init__.py new file mode 100644 index 0000000000..db57103e40 --- /dev/null +++ b/docs/idf_build_system/__init__.py @@ -0,0 +1,48 @@ +# Sphinx extension to integrate IDF build system information +# into the Sphinx Build +# +# Runs early in the Sphinx process, runs CMake to generate the dummy IDF project +# in this directory - including resolving paths, etc. +# +# Then emits the new 'idf-info' event which has information read from IDF +# build system, that other extensions can use to generate relevant data. +import os.path +import sys +import subprocess +import json + +# this directory also contains the dummy IDF project +project_path = os.path.abspath(os.path.dirname(__file__)) +project_build_dir = os.path.join(project_path, "build") + +def setup(app): + builddir = os.path.dirname(app.doctreedir.rstrip(os.sep)) + app.add_config_value('idf_path', os.environ.get("IDF_PATH", ""), 'env') + app.add_config_value('idf_target', 'esp32', 'env') + app.add_event('idf-info') + + # Attaching the generate event to env-get-outdated is a bit of a hack, + # we want this to run early in the docs build but unclear exactly when + app.connect('env-get-outdated', generate_idf_info) + +def generate_idf_info(app, env, added, changed, removed): + print("Running CMake on dummy project to get build info...") + idf_py_path = os.path.join(app.config.idf_path, "tools", "idf.py") + print("Running idf.py...") + subprocess.check_call([sys.executable, + idf_py_path, + "-C", + project_path, + "set-target", + app.config.idf_target]) + # TODO: can call these in one execution pass? + subprocess.check_call([sys.executable, + idf_py_path, + "-C", + project_path, + "reconfigure"]) + with open(os.path.join(project_build_dir, "project_description.json")) as f: + project_description = json.load(f) + app.emit('idf-info', project_description) + + return [] diff --git a/docs/kconfig_reference.py b/docs/kconfig_reference.py new file mode 100644 index 0000000000..3c172bd544 --- /dev/null +++ b/docs/kconfig_reference.py @@ -0,0 +1,52 @@ +# Extension to generate the KConfig reference list +import os.path +import sys +import subprocess + +from local_util import copy_if_modified + +def setup(app): + # The idf_build_system extension will emit this event once it + # has parsed the IDF project's information + app.connect('idf-info', generate_reference) + +def generate_reference(app, project_description): + build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep)) + + # Generate 'kconfig.inc' file from components' Kconfig files + print("Generating kconfig.inc from kconfig contents") + kconfig_inc_path = '{}/inc/kconfig.inc'.format(build_dir) + temp_sdkconfig_path = '{}/sdkconfig.tmp'.format(build_dir) + + kconfigs = project_description["config_environment"]["COMPONENT_KCONFIGS"].split(";") + kconfig_projbuilds = project_description["config_environment"]["COMPONENT_KCONFIGS_PROJBUILD"].split(";") + + sdkconfig_renames = set() + # TODO: this should be generated in project description as well, if possible + for k in kconfigs + kconfig_projbuilds: + component_dir = os.path.dirname(k) + sdkconfig_rename = os.path.join(component_dir, "sdkconfig.rename") + if os.path.exists(sdkconfig_rename): + sdkconfig_renames.add(sdkconfig_rename) + + kconfigs_source_path = '{}/inc/kconfigs_source.in'.format(build_dir) + kconfig_projbuilds_source_path = '{}/inc/kconfig_projbuilds_source.in'.format(build_dir) + + confgen_args = [sys.executable, + "../../tools/kconfig_new/confgen.py", + "--kconfig", "../../Kconfig", + "--sdkconfig-rename", "../../sdkconfig.rename", + "--config", temp_sdkconfig_path, + "--env", "COMPONENT_KCONFIGS={}".format(" ".join(kconfigs)), + "--env", "COMPONENT_KCONFIGS_PROJBUILD={}".format(" ".join(kconfig_projbuilds)), + "--env", "COMPONENT_SDKCONFIG_RENAMES={}".format(" ".join(sdkconfig_renames)), + "--env", "COMPONENT_KCONFIGS_SOURCE_FILE={}".format(kconfigs_source_path), + "--env", "COMPONENT_KCONFIGS_PROJBUILD_SOURCE_FILE={}".format(kconfig_projbuilds_source_path), + "--env", "IDF_PATH={}".format(app.config.idf_path), + "--env", "IDF_TARGET={}".format(app.config.idf_target), + "--output", "docs", kconfig_inc_path + '.in' + ] + subprocess.check_call(confgen_args) + copy_if_modified(kconfig_inc_path + '.in', kconfig_inc_path) + + From 783856d557b8960fe113b036c1803555691ab7c6 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 12 Nov 2019 18:42:03 +0800 Subject: [PATCH 02/47] docs: Move Doxygen build to a Sphinx extension, load sdkconfig & soc caps headers --- docs/Doxyfile | 1 + docs/conf_common.py | 31 ++-------- docs/doxygen_idf.py | 67 +++++++++++++++++++++ docs/en/Makefile | 2 - docs/gen-dxd.py | 97 ++++++++++++++++++++++++++++++- docs/html_redirects.py | 8 ++- docs/idf_build_system/__init__.py | 26 ++++----- docs/local_util.py | 6 ++ docs/zh_CN/Makefile | 2 - 9 files changed, 194 insertions(+), 46 deletions(-) create mode 100644 docs/doxygen_idf.py delete mode 100644 docs/en/Makefile delete mode 100644 docs/zh_CN/Makefile diff --git a/docs/Doxyfile b/docs/Doxyfile index b114de3b61..5755d335a0 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -300,6 +300,7 @@ ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES PREDEFINED = \ + $(ENV_DOXYGEN_DEFINES) \ __attribute__(x)= \ IDF_DEPRECATED(X)= \ IRAM_ATTR= \ diff --git a/docs/conf_common.py b/docs/conf_common.py index 4622eccb4d..9851d17447 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -25,7 +25,7 @@ import subprocess # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute -from local_util import run_cmd_get_output, copy_if_modified +from local_util import run_cmd_get_output, copy_if_modified, call_with_python # build_docs on the CI server sometimes fails under Python3. This is a workaround: sys.setrecursionlimit(3500) @@ -46,29 +46,10 @@ except KeyError: # Set the idf_target chip. This is a hack right now. idf_target = 'esp32s2' -def call_with_python(cmd): - # using sys.executable ensures that the scripts are called with the same Python interpreter - if os.system('{} {}'.format(sys.executable, cmd)) != 0: - raise RuntimeError('{} failed'.format(cmd)) - - -# Call Doxygen to get XML files from the header files -print("Calling Doxygen to generate latest XML files") -if os.system("doxygen ../Doxyfile") != 0: - raise RuntimeError('Doxygen call failed') - -# Doxygen has generated XML files in 'xml' directory. -# Copy them to 'xml_in', only touching the files which have changed. -copy_if_modified('xml/', 'xml_in/') - -# Generate 'api_name.inc' files using the XML files by Doxygen -call_with_python('../gen-dxd.py') - -# Generate 'esp_err_defs.inc' file with ESP_ERR_ error code definitions -esp_err_inc_path = '{}/inc/esp_err_defs.inc'.format(builddir) -call_with_python('../../tools/gen_esp_err_to_name.py --rst_output ' + esp_err_inc_path + '.in') -copy_if_modified(esp_err_inc_path + '.in', esp_err_inc_path) - +try: + os.mkdir(builddir) +except OSError: + pass # Generate version-related includes # @@ -79,7 +60,6 @@ def generate_version_specific_includes(app): call_with_python('../gen-version-specific-includes.py {} {}'.format(app.config.language, version_tmpdir)) copy_if_modified(version_tmpdir, '{}/inc'.format(builddir)) - # Generate toolchain download links print("Generating toolchain download links") base_url = 'https://dl.espressif.com/dl/' @@ -118,6 +98,7 @@ extensions = ['breathe', 'html_redirects', 'idf_build_system', 'kconfig_reference', + 'doxygen_idf', 'sphinx.ext.todo', ] diff --git a/docs/doxygen_idf.py b/docs/doxygen_idf.py new file mode 100644 index 0000000000..79b2429450 --- /dev/null +++ b/docs/doxygen_idf.py @@ -0,0 +1,67 @@ +# Extension to generate Doxygen XML include files, with IDF config & soc macros included +import glob +import os.path +import re +import sys +import subprocess + +from local_util import copy_if_modified, call_with_python + +def setup(app): + # The idf_build_system extension will emit this event once it + app.connect('idf-info', generate_doxygen) + + +def _parse_defines(header_path): + defines = {} + # Note: we run C preprocessor here without any -I arguments, so assumption is + # that these headers are all self-contained and don't include any other headers + # not in the same directory + print("Reading macros from %s..." % (header_path)) + processed_output = subprocess.check_output(["xtensa-esp32-elf-gcc", "-dM", "-E", header_path]) + for line in processed_output.split("\n"): + line = line.strip() + m = re.search("#define ([^ ]+) ?(.*)", line) + if m and not m.group(1).startswith("_"): + defines[m.group(1)] = m.group(2) + + return defines + + +def generate_doxygen(app, project_description): + build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep)) + + # Parse kconfig macros to pass into doxygen + # + # TODO: this should use the set of "config which can't be changed" eventually, + # not the header + defines = _parse_defines(os.path.join(project_description["build_dir"], + "config", "sdkconfig.h")) + + # Add all SOC _caps.h headers to the defines + # + # kind of a hack, be nicer to add a component info dict in project_description.json + soc_path = [p for p in project_description["build_component_paths"] if p.endswith("/soc")][0] + for soc_header in glob.glob(os.path.join(soc_path, project_description["target"], + "include", "soc", "*_caps.h")): + defines.update(_parse_defines(soc_header)) + + # Call Doxygen to get XML files from the header files + print("Calling Doxygen to generate latest XML files") + doxy_env = { + "ENV_DOXYGEN_DEFINES": " ".join(defines) + } + subprocess.check_call(["doxygen", "../Doxyfile"], env=doxy_env) + + # Doxygen has generated XML files in 'xml' directory. + # Copy them to 'xml_in', only touching the files which have changed. + copy_if_modified('xml/', 'xml_in/') + + # Generate 'api_name.inc' files using the XML files by Doxygen + call_with_python('../gen-dxd.py') + + # Generate 'esp_err_defs.inc' file with ESP_ERR_ error code definitions from inc file + esp_err_inc_path = '{}/inc/esp_err_defs.inc'.format(build_dir) + call_with_python('../../tools/gen_esp_err_to_name.py --rst_output ' + esp_err_inc_path + '.in') + copy_if_modified(esp_err_inc_path + '.in', esp_err_inc_path) + diff --git a/docs/en/Makefile b/docs/en/Makefile deleted file mode 100644 index 281b720196..0000000000 --- a/docs/en/Makefile +++ /dev/null @@ -1,2 +0,0 @@ -LANGUAGE=en -include ../docs_common.mk diff --git a/docs/gen-dxd.py b/docs/gen-dxd.py index 2a6b9ba405..3ff76cb071 100755 --- a/docs/gen-dxd.py +++ b/docs/gen-dxd.py @@ -46,7 +46,102 @@ all_kinds = [ """ -def get_doxyfile_input(): +def setup(app): + # The idf_build_system extension will emit this event once it + app.connect('idf-info', generate_doxygen) + + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} + + +def _parse_defines(header_path): + defines = {} + # Note: we run C preprocessor here without any -I arguments, so assumption is + # that these headers are all self-contained and don't include any other headers + # not in the same directory + print("Reading macros from %s..." % (header_path)) + processed_output = subprocess.check_output(["xtensa-esp32-elf-gcc", "-dM", "-E", header_path]).decode() + for line in processed_output.split("\n"): + line = line.strip() + m = re.search("#define ([^ ]+) ?(.*)", line) + if m and not m.group(1).startswith("_"): + defines[m.group(1)] = m.group(2) + + return defines + + +def generate_doxygen(app, project_description): + build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep)) + + # Parse kconfig macros to pass into doxygen + # + # TODO: this should use the set of "config which can't be changed" eventually, + # not the header + defines = _parse_defines(os.path.join(project_description["build_dir"], + "config", "sdkconfig.h")) + + # Add all SOC _caps.h headers to the defines + # + # kind of a hack, be nicer to add a component info dict in project_description.json + soc_path = [p for p in project_description["build_component_paths"] if p.endswith("/soc")][0] + for soc_header in glob.glob(os.path.join(soc_path, project_description["target"], + "include", "soc", "*_caps.h")): + defines.update(_parse_defines(soc_header)) + + # Call Doxygen to get XML files from the header files + print("Calling Doxygen to generate latest XML files") + doxy_env = { + "ENV_DOXYGEN_DEFINES": " ".join(defines), + "IDF_PATH": app.config.idf_path, + "IDF_TARGET": app.config.idf_target, + } + doxyfile = os.path.join(app.config.docs_root, "Doxyfile") + print("Running doxygen with doxyfile {}".format(doxyfile)) + # note: run Doxygen in the build directory, so the xml & xml_in files end up in there + subprocess.check_call(["doxygen", doxyfile], env=doxy_env, cwd=build_dir) + + # Doxygen has generated XML files in 'xml' directory. + # Copy them to 'xml_in', only touching the files which have changed. + copy_if_modified(os.path.join(build_dir, 'xml/'), os.path.join(build_dir, 'xml_in/')) + + # Generate 'api_name.inc' files from the Doxygen XML files + convert_api_xml_to_inc(app, doxyfile) + + +def convert_api_xml_to_inc(app, doxyfile): + """ Generate header_file.inc files + with API reference made of doxygen directives + for each header file + specified in the 'INPUT' statement of the Doxyfile. + """ + build_dir = app.config.build_dir + + xml_directory_path = "{}/xml".format(build_dir) + inc_directory_path = "{}/inc".format(build_dir) + + if not os.path.isdir(xml_directory_path): + raise RuntimeError("Directory {} does not exist!".format(xml_directory_path)) + + if not os.path.exists(inc_directory_path): + os.makedirs(inc_directory_path) + + header_paths = get_doxyfile_input_paths(app, doxyfile) + print("Generating 'api_name.inc' files with Doxygen directives") + for header_file_path in header_paths: + api_name = get_api_name(header_file_path) + inc_file_path = inc_directory_path + "/" + api_name + ".inc" + rst_output = generate_directives(header_file_path, xml_directory_path) + + previous_rst_output = '' + if os.path.isfile(inc_file_path): + with open(inc_file_path, "r", encoding='utf-8') as inc_file_old: + previous_rst_output = inc_file_old.read() + + if previous_rst_output != rst_output: + with open(inc_file_path, "w", encoding='utf-8') as inc_file: + inc_file.write(rst_output) + + +def get_doxyfile_input_paths(app, doxyfile_path): """Get contents of Doxyfile's INPUT statement. Returns: diff --git a/docs/html_redirects.py b/docs/html_redirects.py index a4012cd739..ec2811c33e 100644 --- a/docs/html_redirects.py +++ b/docs/html_redirects.py @@ -41,10 +41,12 @@ REDIRECT_TEMPLATE = """ def setup(app): app.add_config_value('html_redirect_pages', [], 'html') - app.connect('build-finished', create_redirect_pages) + # attaching to this event is a hack, but it's a convenient stage in the build + # to create HTML redirects + app.connect('html-collect-pages', create_redirect_pages) -def create_redirect_pages(app, docname): +def create_redirect_pages(app): if not isinstance(app.builder, StandaloneHTMLBuilder): return # only relevant for standalone HTML output @@ -66,3 +68,5 @@ def create_redirect_pages(app, docname): with open(out_file, "w") as rp: rp.write(content) + + return [] diff --git a/docs/idf_build_system/__init__.py b/docs/idf_build_system/__init__.py index db57103e40..bb22408231 100644 --- a/docs/idf_build_system/__init__.py +++ b/docs/idf_build_system/__init__.py @@ -13,7 +13,6 @@ import json # this directory also contains the dummy IDF project project_path = os.path.abspath(os.path.dirname(__file__)) -project_build_dir = os.path.join(project_path, "build") def setup(app): builddir = os.path.dirname(app.doctreedir.rstrip(os.sep)) @@ -27,21 +26,20 @@ def setup(app): def generate_idf_info(app, env, added, changed, removed): print("Running CMake on dummy project to get build info...") + build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep)) + cmake_build_dir = os.path.join(build_dir, "build_dummy_project") idf_py_path = os.path.join(app.config.idf_path, "tools", "idf.py") print("Running idf.py...") - subprocess.check_call([sys.executable, - idf_py_path, - "-C", - project_path, - "set-target", - app.config.idf_target]) - # TODO: can call these in one execution pass? - subprocess.check_call([sys.executable, - idf_py_path, - "-C", - project_path, - "reconfigure"]) - with open(os.path.join(project_build_dir, "project_description.json")) as f: + idf_py = [sys.executable, + idf_py_path, + "-B", + cmake_build_dir, + "-C", + project_path] + subprocess.check_call(idf_py + [ "set-target", app.config.idf_target]) + # TODO: can call these two in one execution pass? + subprocess.check_call(idf_py + [ "reconfigure"]) + with open(os.path.join(cmake_build_dir, "project_description.json")) as f: project_description = json.load(f) app.emit('idf-info', project_description) diff --git a/docs/local_util.py b/docs/local_util.py index d0fa1ce9c6..6d8998f387 100644 --- a/docs/local_util.py +++ b/docs/local_util.py @@ -18,6 +18,7 @@ from __future__ import unicode_literals from io import open import os import shutil +import sys try: import urllib.request @@ -75,3 +76,8 @@ def download_file_if_missing(from_url, to_path): with open(filename_with_path, 'wb') as fobj: with open(tmp_file, 'rb') as tmp: fobj.write(tmp.read()) + +def call_with_python(cmd): + # using sys.executable ensures that the scripts are called with the same Python interpreter + if os.system('{} {}'.format(sys.executable, cmd)) != 0: + raise RuntimeError('{} failed'.format(cmd)) diff --git a/docs/zh_CN/Makefile b/docs/zh_CN/Makefile deleted file mode 100644 index bf7ce5d14f..0000000000 --- a/docs/zh_CN/Makefile +++ /dev/null @@ -1,2 +0,0 @@ -LANGUAGE=zh_CN -include ../docs_common.mk From e6211c7864505f3a66687b402faeb06fa7377f25 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Wed, 13 Nov 2019 11:46:16 +0800 Subject: [PATCH 03/47] docs: add new top-level docs builder that builds docs for a single chip --- docs/Doxyfile | 356 +++++++++--------- docs/build_docs.py | 89 +++++ docs/conf_common.py | 32 +- docs/docs_common.mk | 217 ----------- docs/doxygen_idf.py | 21 +- .../bluetooth/controller_vhci.rst | 2 +- .../api-reference/bluetooth/esp-ble-mesh.rst | 26 +- docs/en/api-reference/bluetooth/esp_a2dp.rst | 2 +- docs/en/api-reference/bluetooth/esp_avrc.rst | 2 +- docs/en/api-reference/bluetooth/esp_blufi.rst | 2 +- .../api-reference/bluetooth/esp_bt_defs.rst | 2 +- .../api-reference/bluetooth/esp_bt_device.rst | 2 +- .../api-reference/bluetooth/esp_bt_main.rst | 2 +- .../api-reference/bluetooth/esp_gap_ble.rst | 2 +- .../en/api-reference/bluetooth/esp_gap_bt.rst | 2 +- .../api-reference/bluetooth/esp_gatt_defs.rst | 2 +- docs/en/api-reference/bluetooth/esp_gattc.rst | 2 +- docs/en/api-reference/bluetooth/esp_gatts.rst | 2 +- .../api-reference/bluetooth/esp_hf_client.rst | 2 +- .../api-reference/bluetooth/esp_hf_defs.rst | 2 +- docs/en/api-reference/bluetooth/esp_spp.rst | 2 +- .../api-reference/bluetooth/nimble/index.rst | 2 +- docs/en/api-reference/error-codes.rst | 2 +- docs/en/api-reference/kconfig.rst | 2 +- docs/en/api-reference/network/esp_eth.rst | 10 +- docs/en/api-reference/network/esp_mesh.rst | 2 +- docs/en/api-reference/network/esp_netif.rst | 4 +- .../network/esp_netif_driver.rst | 2 +- docs/en/api-reference/network/esp_now.rst | 2 +- .../api-reference/network/esp_smartconfig.rst | 2 +- docs/en/api-reference/network/esp_wifi.rst | 4 +- docs/en/api-reference/peripherals/adc.rst | 6 +- docs/en/api-reference/peripherals/can.rst | 4 +- docs/en/api-reference/peripherals/dac.rst | 4 +- docs/en/api-reference/peripherals/gpio.rst | 4 +- docs/en/api-reference/peripherals/i2c.rst | 2 +- docs/en/api-reference/peripherals/i2s.rst | 2 +- docs/en/api-reference/peripherals/ledc.rst | 2 +- docs/en/api-reference/peripherals/mcpwm.rst | 5 +- docs/en/api-reference/peripherals/pcnt.rst | 2 +- docs/en/api-reference/peripherals/rmt.rst | 2 +- .../api-reference/peripherals/sdio_slave.rst | 5 +- .../api-reference/peripherals/sdmmc_host.rst | 2 +- .../api-reference/peripherals/sdspi_host.rst | 2 +- .../api-reference/peripherals/sigmadelta.rst | 2 +- .../api-reference/peripherals/spi_master.rst | 6 +- .../api-reference/peripherals/spi_slave.rst | 2 +- .../api-reference/peripherals/temp_sensor.rst | 2 +- docs/en/api-reference/peripherals/timer.rst | 2 +- .../api-reference/peripherals/touch_pad.rst | 6 +- docs/en/api-reference/peripherals/uart.rst | 4 +- .../protocols/esp_http_client.rst | 2 +- .../protocols/esp_http_server.rst | 2 +- .../protocols/esp_https_server.rst | 2 +- .../protocols/esp_local_ctrl.rst | 2 +- .../protocols/esp_serial_slave_link.rst | 4 +- docs/en/api-reference/protocols/esp_tls.rst | 2 +- .../protocols/esp_websocket_client.rst | 2 +- docs/en/api-reference/protocols/icmp_echo.rst | 2 +- docs/en/api-reference/protocols/mdns.rst | 2 +- docs/en/api-reference/protocols/mqtt.rst | 2 +- .../api-reference/provisioning/protocomm.rst | 12 +- .../provisioning/wifi_provisioning.rst | 10 +- docs/en/api-reference/storage/nvs_flash.rst | 4 +- docs/en/api-reference/storage/sdmmc.rst | 4 +- docs/en/api-reference/storage/spi_flash.rst | 10 +- docs/en/api-reference/storage/spiffs.rst | 2 +- docs/en/api-reference/storage/vfs.rst | 4 +- .../api-reference/storage/wear-levelling.rst | 2 +- .../api-reference/system/app_image_format.rst | 2 +- docs/en/api-reference/system/app_trace.rst | 4 +- docs/en/api-reference/system/efuse.rst | 2 +- docs/en/api-reference/system/esp_err.rst | 2 +- docs/en/api-reference/system/esp_event.rst | 4 +- .../api-reference/system/esp_event_legacy.rst | 2 +- .../system/esp_expression_with_stack.rst | 2 +- .../en/api-reference/system/esp_https_ota.rst | 2 +- docs/en/api-reference/system/esp_pthread.rst | 2 +- docs/en/api-reference/system/esp_timer.rst | 2 +- docs/en/api-reference/system/freertos.rst | 10 +- .../system/freertos_additions.rst | 4 +- docs/en/api-reference/system/heap_debug.rst | 2 +- docs/en/api-reference/system/himem.rst | 2 +- docs/en/api-reference/system/intr_alloc.rst | 2 +- docs/en/api-reference/system/ipc.rst | 2 +- docs/en/api-reference/system/log.rst | 2 +- docs/en/api-reference/system/mem_alloc.rst | 6 +- docs/en/api-reference/system/ota.rst | 2 +- docs/en/api-reference/system/perfmon.rst | 4 +- .../api-reference/system/power_management.rst | 4 +- docs/en/api-reference/system/sleep_modes.rst | 2 +- docs/en/api-reference/system/system.rst | 4 +- docs/en/api-reference/system/wdts.rst | 2 +- docs/en/api-reference/template.rst | 2 +- docs/en/get-started-legacy/index.rst | 6 +- .../linux-setup-scratch.rst | 2 +- docs/en/get-started-legacy/linux-setup.rst | 6 +- .../macos-setup-scratch.rst | 2 +- docs/en/get-started-legacy/macos-setup.rst | 4 +- .../windows-setup-scratch.rst | 2 +- docs/en/get-started/index.rst | 4 +- docs/en/get-started/linux-setup-scratch.rst | 2 +- docs/en/get-started/macos-setup-scratch.rst | 2 +- docs/en/get-started/windows-setup-scratch.rst | 6 +- docs/gen-dxd.py | 6 +- docs/idf_build_system/__init__.py | 15 +- docs/include_build_file.py | 18 + docs/kconfig_reference.py | 17 +- docs/zh_CN/api-reference/network/esp_eth.rst | 10 +- .../api-reference/network/esp_smartconfig.rst | 2 +- docs/zh_CN/api-reference/network/esp_wifi.rst | 4 +- .../zh_CN/api-reference/peripherals/timer.rst | 2 +- .../api-reference/peripherals/touch_pad.rst | 6 +- .../protocols/esp_http_server.rst | 2 +- docs/zh_CN/api-reference/protocols/mdns.rst | 2 +- .../zh_CN/api-reference/storage/nvs_flash.rst | 4 +- docs/zh_CN/api-reference/storage/sdmmc.rst | 4 +- .../zh_CN/api-reference/storage/spi_flash.rst | 10 +- docs/zh_CN/api-reference/storage/spiffs.rst | 2 +- docs/zh_CN/api-reference/storage/vfs.rst | 4 +- .../api-reference/storage/wear-levelling.rst | 2 +- .../api-reference/system/power_management.rst | 4 +- docs/zh_CN/get-started-legacy/index.rst | 6 +- .../linux-setup-scratch.rst | 2 +- docs/zh_CN/get-started-legacy/linux-setup.rst | 6 +- .../macos-setup-scratch.rst | 2 +- docs/zh_CN/get-started-legacy/macos-setup.rst | 4 +- .../windows-setup-scratch.rst | 2 +- docs/zh_CN/get-started/index.rst | 4 +- .../zh_CN/get-started/linux-setup-scratch.rst | 2 +- .../zh_CN/get-started/macos-setup-scratch.rst | 2 +- .../get-started/windows-setup-scratch.rst | 6 +- tools/ci/executable-list.txt | 4 +- 133 files changed, 566 insertions(+), 637 deletions(-) create mode 100755 docs/build_docs.py delete mode 100644 docs/docs_common.mk create mode 100644 docs/include_build_file.py diff --git a/docs/Doxyfile b/docs/Doxyfile index 5755d335a0..823959f2a3 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -24,270 +24,270 @@ INPUT = \ ## ## Wi-Fi - API Reference ## - ../../components/esp_wifi/include/esp_wifi.h \ - ../../components/esp_wifi/include/esp_wifi_types.h \ - ../../components/esp_wifi/include/esp_smartconfig.h \ - ../../components/esp_wifi/include/esp_now.h \ - ../../components/esp_wifi/include/esp_wifi_default.h \ + $(IDF_PATH)/components/esp_wifi/include/esp_wifi.h \ + $(IDF_PATH)/components/esp_wifi/include/esp_wifi_types.h \ + $(IDF_PATH)/components/esp_wifi/include/esp_smartconfig.h \ + $(IDF_PATH)/components/esp_wifi/include/esp_now.h \ + $(IDF_PATH)/components/esp_wifi/include/esp_wifi_default.h \ ## Mesh - API Reference - ../../components/esp_wifi/include/esp_mesh.h \ + $(IDF_PATH)/components/esp_wifi/include/esp_mesh.h \ ## Event loop - API Reference - ../../components/esp_event/include/esp_event.h \ - ../../components/esp_event/include/esp_event_base.h \ - ../../components/esp_event/include/esp_event_legacy.h \ + $(IDF_PATH)/components/esp_event/include/esp_event.h \ + $(IDF_PATH)/components/esp_event/include/esp_event_base.h \ + $(IDF_PATH)/components/esp_event/include/esp_event_legacy.h \ ## Bluetooth - API Reference ## Controller && VHCI - ../../components/bt/include/esp_bt.h \ + $(IDF_PATH)/components/bt/include/esp_bt.h \ ## Bluetooth COMMON ## Issue with __attribute__ - ../../components/bt/host/bluedroid/api/include/api/esp_bt_defs.h \ - ../../components/bt/host/bluedroid/api/include/api/esp_bt_main.h \ - ../../components/bt/host/bluedroid/api/include/api/esp_bt_device.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_main.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_device.h \ ## Bluetooth LE - ../../components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h \ ## Issue with __attribute__ - ../../components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h \ - ../../components/bt/host/bluedroid/api/include/api/esp_gatts_api.h \ - ../../components/bt/host/bluedroid/api/include/api/esp_gattc_api.h \ - ../../components/bt/host/bluedroid/api/include/api/esp_blufi_api.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_blufi_api.h \ ## Bluetooth Classic - ../../components/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h \ ## Issue with __attribute__ - ../../components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h \ - ../../components/bt/host/bluedroid/api/include/api/esp_avrc_api.h \ - ../../components/bt/host/bluedroid/api/include/api/esp_spp_api.h \ - ../../components/bt/host/bluedroid/api/include/api/esp_hf_defs.h \ - ../../components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h \ - ../../components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_avrc_api.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_spp_api.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_defs.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h \ ## NimBLE related Bluetooth APIs - ../../components/bt/host/nimble/esp-hci/include/esp_nimble_hci.h \ + $(IDF_PATH)/components/bt/host/nimble/esp-hci/include/esp_nimble_hci.h \ ## ESP BLE Mesh APIs - ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_common_api.h \ - ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_local_data_operation_api.h \ - ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_low_power_api.h \ - ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_networking_api.h \ - ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_provisioning_api.h \ - ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_proxy_api.h \ - ../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_config_model_api.h \ - ../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_generic_model_api.h \ - ../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_health_model_api.h \ - ../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_lighting_model_api.h \ - ../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_sensor_model_api.h \ - ../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_time_scene_model_api.h \ - ../../components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_common_api.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_local_data_operation_api.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_low_power_api.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_networking_api.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_provisioning_api.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_proxy_api.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_config_model_api.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_generic_model_api.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_health_model_api.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_lighting_model_api.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_sensor_model_api.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_time_scene_model_api.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h \ ## ## Ethernet - API Reference ## - ../../components/esp_eth/include/esp_eth.h \ - ../../components/esp_eth/include/esp_eth_com.h \ - ../../components/esp_eth/include/esp_eth_mac.h \ - ../../components/esp_eth/include/esp_eth_phy.h \ - ../../components/esp_eth/include/esp_eth_netif_glue.h \ + $(IDF_PATH)/components/esp_eth/include/esp_eth.h \ + $(IDF_PATH)/components/esp_eth/include/esp_eth_com.h \ + $(IDF_PATH)/components/esp_eth/include/esp_eth_mac.h \ + $(IDF_PATH)/components/esp_eth/include/esp_eth_phy.h \ + $(IDF_PATH)/components/esp_eth/include/esp_eth_netif_glue.h \ ## ## Peripherals - API Reference ## - ../../components/driver/include/driver/adc.h \ - ../../components/driver/include/driver/can.h \ - ../../components/soc/include/hal/can_types.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/soc/include/hal/mcpwm_types.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/esp32s2/include/temp_sensor.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/include/hal/rmt_types.h \ - ../../components/soc/include/hal/spi_types.h \ - ../../components/soc/include/hal/pcnt_types.h \ - ../../components/soc/include/hal/i2s_types.h \ - ../../components/soc/include/hal/rtc_io_types.h \ - ../../components/soc/include/hal/sigmadelta_types.h \ - ../../components/soc/include/hal/timer_types.h \ - ../../components/soc/include/hal/ledc_types.h \ - ../../components/soc/include/hal/i2c_types.h \ - ../../components/soc/include/hal/dac_types.h \ - ../../components/soc/include/hal/adc_types.h \ - ../../components/soc/include/hal/gpio_types.h \ - ../../components/soc/include/hal/uart_types.h \ - ../../components/soc/include/hal/touch_sensor_types.h \ - ../../components/soc/esp32/include/soc/adc_channel.h \ - ../../components/soc/esp32/include/soc/dac_channel.h \ - ../../components/soc/esp32/include/soc/touch_sensor_channel.h \ - ../../components/soc/esp32/include/soc/uart_channel.h \ - ../../components/soc/esp32/include/soc/rtc_io_channel.h \ + $(IDF_PATH)/components/driver/include/driver/adc.h \ + $(IDF_PATH)/components/driver/include/driver/can.h \ + $(IDF_PATH)/components/soc/include/hal/can_types.h \ + $(IDF_PATH)/components/driver/include/driver/dac.h \ + $(IDF_PATH)/components/driver/include/driver/gpio.h \ + $(IDF_PATH)/components/driver/include/driver/rtc_io.h \ + $(IDF_PATH)/components/driver/include/driver/i2c.h \ + $(IDF_PATH)/components/driver/include/driver/i2s.h \ + $(IDF_PATH)/components/driver/include/driver/ledc.h \ + $(IDF_PATH)/components/driver/include/driver/mcpwm.h \ + $(IDF_PATH)/components/soc/include/hal/mcpwm_types.h \ + $(IDF_PATH)/components/driver/include/driver/pcnt.h \ + $(IDF_PATH)/components/driver/include/driver/rmt.h \ + $(IDF_PATH)/components/driver/include/driver/sigmadelta.h \ + $(IDF_PATH)/components/driver/include/driver/spi_common.h \ + $(IDF_PATH)/components/driver/include/driver/spi_master.h \ + $(IDF_PATH)/components/driver/include/driver/spi_slave.h \ + $(IDF_PATH)/components/driver/esp32s2/include/temp_sensor.h \ + $(IDF_PATH)/components/driver/include/driver/timer.h \ + $(IDF_PATH)/components/driver/include/driver/touch_pad.h \ + $(IDF_PATH)/components/driver/include/driver/uart.h \ + $(IDF_PATH)/components/esp_adc_cal/include/esp_adc_cal.h \ + $(IDF_PATH)/components/soc/include/hal/rmt_types.h \ + $(IDF_PATH)/components/soc/include/hal/spi_types.h \ + $(IDF_PATH)/components/soc/include/hal/pcnt_types.h \ + $(IDF_PATH)/components/soc/include/hal/i2s_types.h \ + $(IDF_PATH)/components/soc/include/hal/rtc_io_types.h \ + $(IDF_PATH)/components/soc/include/hal/sigmadelta_types.h \ + $(IDF_PATH)/components/soc/include/hal/timer_types.h \ + $(IDF_PATH)/components/soc/include/hal/ledc_types.h \ + $(IDF_PATH)/components/soc/include/hal/i2c_types.h \ + $(IDF_PATH)/components/soc/include/hal/dac_types.h \ + $(IDF_PATH)/components/soc/include/hal/adc_types.h \ + $(IDF_PATH)/components/soc/include/hal/gpio_types.h \ + $(IDF_PATH)/components/soc/include/hal/uart_types.h \ + $(IDF_PATH)/components/soc/include/hal/touch_sensor_types.h \ + $(IDF_PATH)/components/soc/esp32/include/soc/adc_channel.h \ + $(IDF_PATH)/components/soc/esp32/include/soc/dac_channel.h \ + $(IDF_PATH)/components/soc/esp32/include/soc/touch_sensor_channel.h \ + $(IDF_PATH)/components/soc/esp32/include/soc/uart_channel.h \ + $(IDF_PATH)/components/soc/esp32/include/soc/rtc_io_channel.h \ ## esp_netif - API Reference - ../../components/esp_netif/include/esp_netif.h \ - ../../components/esp_netif/include/esp_netif_net_stack.h \ + $(IDF_PATH)/components/esp_netif/include/esp_netif.h \ + $(IDF_PATH)/components/esp_netif/include/esp_netif_net_stack.h \ ## ## Protocols - API Reference ## ## ESP-TLS - ../../components/esp-tls/esp_tls.h \ + $(IDF_PATH)/components/esp-tls/esp_tls.h \ ## MQTT - ../../components/mqtt/esp-mqtt/include/mqtt_client.h \ + $(IDF_PATH)/components/mqtt/esp-mqtt/include/mqtt_client.h \ ## ICMP-ECHO - ../../components/lwip/include/apps/ping/ping_sock.h \ + $(IDF_PATH)/components/lwip/include/apps/ping/ping_sock.h \ ## SNTP - ../../components/lwip/include/apps/sntp/sntp.h \ + $(IDF_PATH)/components/lwip/include/apps/sntp/sntp.h \ ## mDNS - ../../components/mdns/include/mdns.h \ - ../../components/esp_http_client/include/esp_http_client.h \ - ../../components/esp_websocket_client/include/esp_websocket_client.h \ + $(IDF_PATH)/components/mdns/include/mdns.h \ + $(IDF_PATH)/components/esp_http_client/include/esp_http_client.h \ + $(IDF_PATH)/components/esp_websocket_client/include/esp_websocket_client.h \ ## HTTP / HTTPS Server - ../../components/esp_http_server/include/esp_http_server.h \ - ../../components/esp_https_server/include/esp_https_server.h \ + $(IDF_PATH)/components/esp_http_server/include/esp_http_server.h \ + $(IDF_PATH)/components/esp_https_server/include/esp_https_server.h \ ## ESP Local Ctrl - ../../components/esp_local_ctrl/include/esp_local_ctrl.h \ + $(IDF_PATH)/components/esp_local_ctrl/include/esp_local_ctrl.h \ ## ESP Serial Slave Link - ../../components/esp_serial_slave_link/include/esp_serial_slave_link/essl.h \ - ../../components/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h \ + $(IDF_PATH)/components/esp_serial_slave_link/include/esp_serial_slave_link/essl.h \ + $(IDF_PATH)/components/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.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 \ + $(IDF_PATH)/components/protocomm/include/common/protocomm.h \ + $(IDF_PATH)/components/protocomm/include/security/protocomm_security.h \ + $(IDF_PATH)/components/protocomm/include/security/protocomm_security0.h \ + $(IDF_PATH)/components/protocomm/include/security/protocomm_security1.h \ + $(IDF_PATH)/components/protocomm/include/transports/protocomm_ble.h \ + $(IDF_PATH)/components/protocomm/include/transports/protocomm_console.h \ + $(IDF_PATH)/components/protocomm/include/transports/protocomm_httpd.h \ ## WiFi Provisioning - ../../components/wifi_provisioning/include/wifi_provisioning/manager.h \ - ../../components/wifi_provisioning/include/wifi_provisioning/scheme_ble.h \ - ../../components/wifi_provisioning/include/wifi_provisioning/scheme_softap.h \ - ../../components/wifi_provisioning/include/wifi_provisioning/scheme_console.h \ - ../../components/wifi_provisioning/include/wifi_provisioning/wifi_config.h \ - ../../components/wifi_provisioning/include/wifi_provisioning/wifi_scan.h \ + $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/manager.h \ + $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_ble.h \ + $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_softap.h \ + $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_console.h \ + $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/wifi_config.h \ + $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/wifi_scan.h \ ## ## Storage - API Reference ## ## SPI Flash and Partition APIs - ../../components/spi_flash/include/esp_flash_spi_init.h \ - ../../components/spi_flash/include/esp_flash.h \ - ../../components/spi_flash/include/esp_partition.h \ - ../../components/bootloader_support/include/esp_flash_encrypt.h \ - ../../components/soc/include/hal/spi_flash_types.h \ + $(IDF_PATH)/components/spi_flash/include/esp_flash_spi_init.h \ + $(IDF_PATH)/components/spi_flash/include/esp_flash.h \ + $(IDF_PATH)/components/spi_flash/include/esp_partition.h \ + $(IDF_PATH)/components/bootloader_support/include/esp_flash_encrypt.h \ + $(IDF_PATH)/components/soc/include/hal/spi_flash_types.h \ ## SPIFFS - ../../components/spiffs/include/esp_spiffs.h \ + $(IDF_PATH)/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 \ + $(IDF_PATH)/components/sdmmc/include/sdmmc_cmd.h \ + $(IDF_PATH)/components/driver/include/driver/sdmmc_host.h \ + $(IDF_PATH)/components/driver/include/driver/sdmmc_types.h \ + $(IDF_PATH)/components/driver/include/driver/sdspi_host.h \ ## SDIO slave - ../../components/driver/include/driver/sdio_slave.h \ - ../../components/soc/include/hal/sdio_slave_types.h \ + $(IDF_PATH)/components/driver/include/driver/sdio_slave.h \ + $(IDF_PATH)/components/soc/include/hal/sdio_slave_types.h \ ## Non-Volatile Storage - ../../components/nvs_flash/include/nvs.h \ - ../../components/nvs_flash/include/nvs_flash.h \ + $(IDF_PATH)/components/nvs_flash/include/nvs.h \ + $(IDF_PATH)/components/nvs_flash/include/nvs_flash.h \ ## Virtual Filesystem - ../../components/vfs/include/esp_vfs.h \ - ../../components/vfs/include/esp_vfs_dev.h \ - ../../components/vfs/include/esp_vfs_semihost.h \ + $(IDF_PATH)/components/vfs/include/esp_vfs.h \ + $(IDF_PATH)/components/vfs/include/esp_vfs_dev.h \ + $(IDF_PATH)/components/vfs/include/esp_vfs_semihost.h \ ## FAT Filesystem ## NOTE: for two lines below header_file.inc is not used - ../../components/fatfs/vfs/esp_vfs_fat.h \ - ../../components/fatfs/diskio/diskio_impl.h \ - ../../components/fatfs/diskio/diskio_sdmmc.h \ - ../../components/fatfs/diskio/diskio_wl.h \ - ../../components/fatfs/diskio/diskio_rawflash.h \ + $(IDF_PATH)/components/fatfs/vfs/esp_vfs_fat.h \ + $(IDF_PATH)/components/fatfs/diskio/diskio_impl.h \ + $(IDF_PATH)/components/fatfs/diskio/diskio_sdmmc.h \ + $(IDF_PATH)/components/fatfs/diskio/diskio_wl.h \ + $(IDF_PATH)/components/fatfs/diskio/diskio_rawflash.h \ ## Wear Levelling - ../../components/wear_levelling/include/wear_levelling.h \ + $(IDF_PATH)/components/wear_levelling/include/wear_levelling.h \ ## ## System - API Reference ## ## 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 \ + $(IDF_PATH)/components/heap/include/esp_heap_caps.h \ + $(IDF_PATH)/components/heap/include/esp_heap_trace.h \ + $(IDF_PATH)/components/heap/include/esp_heap_caps_init.h \ + $(IDF_PATH)/components/heap/include/multi_heap.h \ ## Himem - ../../components/esp32/include/esp32/himem.h \ + $(IDF_PATH)/components/esp32/include/esp32/himem.h \ ## Interrupt Allocation - ../../components/esp32/include/esp_intr_alloc.h \ + $(IDF_PATH)/components/esp32/include/esp_intr_alloc.h \ ## Watchdogs ## NOTE: for two lines below header_file.inc is not used - ../../components/esp_common/include/esp_int_wdt.h \ - ../../components/esp_common/include/esp_task_wdt.h \ + $(IDF_PATH)/components/esp_common/include/esp_int_wdt.h \ + $(IDF_PATH)/components/esp_common/include/esp_task_wdt.h \ ## Hooks - ../../components/esp_common/include/esp_freertos_hooks.h \ + $(IDF_PATH)/components/esp_common/include/esp_freertos_hooks.h \ ## Inter-Processor Call - ../../components/esp_common/include/esp_ipc.h \ + $(IDF_PATH)/components/esp_common/include/esp_ipc.h \ ## Call Function with External stack - ../../components/esp_common/include/esp_expression_with_stack.h \ + $(IDF_PATH)/components/esp_common/include/esp_expression_with_stack.h \ ## Over The Air Updates (OTA) - ../../components/app_update/include/esp_ota_ops.h \ + $(IDF_PATH)/components/app_update/include/esp_ota_ops.h \ ## ESP HTTPS OTA - ../../components/esp_https_ota/include/esp_https_ota.h \ + $(IDF_PATH)/components/esp_https_ota/include/esp_https_ota.h \ ## Sleep - ../../components/esp32/include/esp_sleep.h \ + $(IDF_PATH)/components/esp32/include/esp_sleep.h \ ## Logging - ../../components/log/include/esp_log.h \ + $(IDF_PATH)/components/log/include/esp_log.h \ ## Base MAC address ## NOTE: for line below header_file.inc is not used - ../../components/esp_common/include/esp_system.h \ + $(IDF_PATH)/components/esp_common/include/esp_system.h \ ## IDF version - ../../components/esp_common/include/esp_idf_version.h \ + $(IDF_PATH)/components/esp_common/include/esp_idf_version.h \ ## ## ULP Coprocessor - API Guides ## ## NOTE: for line below header_file.inc is not used - ../../components/ulp/include/esp32/ulp.h \ - ../../components/ulp/include/ulp_common.h \ + $(IDF_PATH)/components/ulp/include/esp32/ulp.h \ + $(IDF_PATH)/components/ulp/include/ulp_common.h \ ## ## Application Level Tracing - API Reference ## - ../../components/app_trace/include/esp_app_trace.h \ - ../../components/app_trace/include/esp_sysview_trace.h \ + $(IDF_PATH)/components/app_trace/include/esp_app_trace.h \ + $(IDF_PATH)/components/app_trace/include/esp_sysview_trace.h \ ### Power management - ../../components/esp_common/include/esp_pm.h \ - ../../components/esp32/include/esp32/pm.h \ + $(IDF_PATH)/components/esp_common/include/esp_pm.h \ + $(IDF_PATH)/components/esp32/include/esp32/pm.h \ ### esp_timer, High Resolution Timer - ../../components/esp_timer/include/esp_timer.h \ + $(IDF_PATH)/components/esp_timer/include/esp_timer.h \ ### esp_event, Event Loop Library - ../../components/esp_event/include/esp_event.h \ - ../../components/esp_event/include/esp_event_base.h \ + $(IDF_PATH)/components/esp_event/include/esp_event.h \ + $(IDF_PATH)/components/esp_event/include/esp_event_base.h \ ### eFuse Manager - ../../components/efuse/include/esp_efuse.h \ + $(IDF_PATH)/components/efuse/include/esp_efuse.h \ ### App Image Format - ../../components/bootloader_support/include/esp_app_format.h \ + $(IDF_PATH)/components/bootloader_support/include/esp_app_format.h \ ### ESP Pthread parameters - ../../components/pthread/include/esp_pthread.h \ + $(IDF_PATH)/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 \ + $(IDF_PATH)/components/freertos/include/freertos/task.h \ + $(IDF_PATH)/components/freertos/include/freertos/queue.h \ + $(IDF_PATH)/components/freertos/include/freertos/semphr.h \ + $(IDF_PATH)/components/freertos/include/freertos/timers.h \ + $(IDF_PATH)/components/freertos/include/freertos/event_groups.h \ ### Ringbuffer - ../../components/esp_ringbuf/include/freertos/ringbuf.h \ + $(IDF_PATH)/components/esp_ringbuf/include/freertos/ringbuf.h \ ### Helper functions for error codes - ../../components/esp_common/include/esp_err.h \ + $(IDF_PATH)/components/esp_common/include/esp_err.h \ ### System APIs - ../../components/esp_common/include/esp_system.h \ + $(IDF_PATH)/components/esp_common/include/esp_system.h \ ### Modbus controller component header file - ../../components/freemodbus/common/include/esp_modbus_common.h \ - ../../components/freemodbus/common/include/esp_modbus_slave.h \ - ../../components/freemodbus/common/include/esp_modbus_master.h \ + $(IDF_PATH)/components/freemodbus/common/include/esp_modbus_common.h \ + $(IDF_PATH)/components/freemodbus/common/include/esp_modbus_slave.h \ + $(IDF_PATH)/components/freemodbus/common/include/esp_modbus_master.h \ ### Performance Monitor component header file - ../../components/perfmon/include/xtensa_perfmon_access.h \ - ../../components/perfmon/include/xtensa_perfmon_apis.h \ - ../../components/perfmon/include/xtensa_perfmon_masks.h + $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_access.h \ + $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_apis.h \ + $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_masks.h ## Get warnings for functions that have no documentation for their parameters or return value diff --git a/docs/build_docs.py b/docs/build_docs.py new file mode 100755 index 0000000000..47381ee967 --- /dev/null +++ b/docs/build_docs.py @@ -0,0 +1,89 @@ +#!/usr/bin/env python +# +# Top-level docs builder +# +# This is just a front-end to sphinx-build that can call it multiple times for different language/target combinations +# +# Will build out to _build/LANG/TARGET by default +# +# Specific custom docs functionality should be added in conf_common.py or in a Sphinx extension, not here. +# +import argparse +import os +import os.path +import subprocess +import sys + +LANGUAGES = ["en", "zh_CN"] +TARGETS = ["esp32", "esp32s2"] + +def main(): + # check Python dependencies for docs + try: + subprocess.check_call([sys.executable, + os.path.join(os.environ["IDF_PATH"], + "tools", + "check_python_dependencies.py"), + "-r", + "{}/docs/requirements.txt".format(os.environ["IDF_PATH"]) + ]) + except subprocess.CalledProcessError: + raise SystemExit(2) # stdout will already have these errors + + parser = argparse.ArgumentParser(description='build_docs.py: Build IDF docs', + prog='build_docs.py') + parser.add_argument("--language", "-l", choices=LANGUAGES, + required=False) + parser.add_argument("--target", "-t", choices=TARGETS, required=False) + parser.add_argument("--build-dir", "-b", type=str, default="_build") + + args = parser.parse_args() + + if args.language is None: + print("Building all languages") + languages = LANGUAGES + else: + languages = [ args.language ] + + if args.target is None: + print("Building all targets") + targets = TARGETS + else: + targets = [ args.target ] + + for language in languages: + for target in targets: + build_dir = os.path.realpath(os.path.join(args.build_dir, language, target)) + build_docs(language, target, build_dir) + + +def build_docs(language, target, build_dir): + print("Building language:%s target:%s build_dir:%s" % (language, target, build_dir)) + try: + os.makedirs(build_dir) + except OSError: + pass + try: + environ = {} + environ.update(os.environ) + environ['BUILDDIR'] = build_dir + + args = [sys.executable, "-m", "sphinx", + "-b", "html", # TODO: PDFs + "-d", os.path.join(build_dir, "doctrees"), + # TODO: support multiple sphinx-warning.log files, somehow + "-w", "sphinx-warning.log", + "-D", "idf_target={}".format(target), + os.path.join(os.path.abspath(os.path.dirname(__file__)), language), # srcdir for this language + os.path.join(build_dir, "html") # build directory + ] + cwd = build_dir # also run sphinx in the build directory + print("Running '{}'".format(" ".join(args))) + subprocess.check_call(args, cwd=cwd, env=environ) + except subprocess.CalledProcessError: + print("Sphinx failed for language:%s target:%s" % (language, target)) + raise SystemExit(1) # rest of the details should be in stdout + + +if __name__ == "__main__": + main() diff --git a/docs/conf_common.py b/docs/conf_common.py index 9851d17447..b8f811e13d 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -31,11 +31,11 @@ from local_util import run_cmd_get_output, copy_if_modified, call_with_python sys.setrecursionlimit(3500) try: - builddir = os.environ['BUILDDIR'] + build_dir = os.environ['BUILDDIR'] except KeyError: - builddir = '_build' + build_dir = '_build' -builddir = os.path.abspath(builddir) +build_dir = os.path.abspath(build_dir) # Fill in a default IDF_PATH if it's missing (ie when Read The Docs is building the docs) try: @@ -43,11 +43,15 @@ try: except KeyError: idf_path = os.path.realpath(os.path.join(os.path.dirname(__file__), '..')) -# Set the idf_target chip. This is a hack right now. -idf_target = 'esp32s2' +docs_root = os.path.join(idf_path, "docs") try: - os.mkdir(builddir) + os.mkdir(build_dir) +except OSError: + pass + +try: + os.mkdir(os.path.join(build_dir, 'inc')) except OSError: pass @@ -56,16 +60,16 @@ except OSError: # (Note: this is in a function as it needs to access configuration to get the language) def generate_version_specific_includes(app): print("Generating version-specific includes...") - version_tmpdir = '{}/version_inc'.format(builddir) - call_with_python('../gen-version-specific-includes.py {} {}'.format(app.config.language, version_tmpdir)) - copy_if_modified(version_tmpdir, '{}/inc'.format(builddir)) + version_tmpdir = '{}/version_inc'.format(build_dir) + call_with_python('{}/gen-version-specific-includes.py {} {}'.format(docs_root, app.config.language, version_tmpdir)) + copy_if_modified(version_tmpdir, '{}/inc'.format(build_dir)) # Generate toolchain download links print("Generating toolchain download links") base_url = 'https://dl.espressif.com/dl/' -toolchain_tmpdir = '{}/toolchain_inc'.format(builddir) -call_with_python('../gen-toolchain-links.py ../../tools/toolchain_versions.mk {} {}'.format(base_url, toolchain_tmpdir)) -copy_if_modified(toolchain_tmpdir, '{}/inc'.format(builddir)) +toolchain_tmpdir = '{}/toolchain_inc'.format(build_dir) +call_with_python('{}/gen-toolchain-links.py ../../tools/toolchain_versions.mk {} {}'.format(docs_root, base_url, toolchain_tmpdir)) +copy_if_modified(toolchain_tmpdir, '{}/inc'.format(build_dir)) print("Generating IDF Tools list") os.environ["IDF_MAINTAINER"] = "1" @@ -100,6 +104,7 @@ extensions = ['breathe', 'kconfig_reference', 'doxygen_idf', 'sphinx.ext.todo', + 'include_build_file', ] # sphinx.ext.todo extension parameters @@ -115,7 +120,7 @@ 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_projects = {"esp32-idf": os.path.join(build_dir, "xml_in/")} breathe_default_project = "esp32-idf" # Add any paths that contain templates here, relative to this directory. @@ -364,5 +369,6 @@ texinfo_documents = [ # Override RTD CSS theme to introduce the theme corrections # https://github.com/rtfd/sphinx_rtd_theme/pull/432 def setup(app): + app.config.build_dir = build_dir app.add_stylesheet('theme_overrides.css') generate_version_specific_includes(app) diff --git a/docs/docs_common.mk b/docs/docs_common.mk deleted file mode 100644 index e1298bd661..0000000000 --- a/docs/docs_common.mk +++ /dev/null @@ -1,217 +0,0 @@ -# "Common" Makefile for Sphinx documentation -# -# (included from en/Makefile & zh_CN/Makefile -# -# NOTE: This makefile runs with cwd=either en or zh_CN subfolder, so this -# (docs/) directory is '..' relative to it. - -# ************ IMPORTANT ***************** -# -# ReadTheDocs DOES NOT USE THIS MAKEFILE, -# so any behaviour additions must be -# done via Sphinx Config not here -# -# **************************************** - -# You can set these variables from the command line. -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 -PAPER = -BUILDDIR = _build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -w sphinx-warning-log.txt . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext dependencies version-specific-includes check_python_packages - -help: - @echo "Please use \`make \' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled) " - -clean: - rm -rf $(BUILDDIR)/* - -# Notify users when some of the required python packages are not installed. -# Note: This is intended to help developers who generate the documentation on their local machine. Read The Docs uses -# the requirements.txt file directly and calls sphinx also directly without the use of the makefile! -check_python_packages: - $(IDF_PATH)/tools/check_python_dependencies.py -r $(IDF_PATH)/docs/requirements.txt - -html: | check_python_packages - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: | check_python_packages - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: | check_python_packages - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: | check_python_packages - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: | check_python_packages - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: | check_python_packages - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: | check_python_packages - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ReadtheDocsTemplate.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ReadtheDocsTemplate.qhc" - -devhelp: | check_python_packages - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/ReadtheDocsTemplate" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ReadtheDocsTemplate" - @echo "# devhelp" - -epub: | check_python_packages - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: | check_python_packages - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: | check_python_packages - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: | check_python_packages - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: | check_python_packages - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: | check_python_packages - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: | check_python_packages - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: | check_python_packages - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: | check_python_packages - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: | check_python_packages - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: | check_python_packages - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -gh-linkcheck: | check_python_packages - @echo "Checking for hardcoded GitHub links" # note: exception for links to support policy doc as we *want* this to be a link to master's policy - @if (find ../ -name '*.rst' | xargs grep \ - 'https://github.com/espressif/esp-idf/tree\|https://github.com/espressif/esp-idf/blob\|https://github.com/espressif/esp-idf/raw' \ - | grep -v 'SUPPORT_POLICY\.md' \ - ); \ - then \ - echo "WARNINIG: Some .rst files contain hardcoded Github links."; \ - echo "Please check above output and replace links with one of the following:"; \ - echo "- :idf:\`dir\` - points to directory inside ESP-IDF"; \ - echo "- :idf_file:\`file\` - points to file inside ESP-IDF"; \ - echo "- :idf_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \ - echo "- :component:\`dir\` - points to directory inside ESP-IDF components dir"; \ - echo "- :component_file:\`file\` - points to file inside ESP-IDF components dir"; \ - echo "- :component_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \ - echo " components dir"; \ - echo "- :example:\`dir\` - points to directory inside ESP-IDF examples dir"; \ - echo "- :example_file:\`file\` - points to file inside ESP-IDF examples dir"; \ - echo "- :example_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \ - echo " examples dir"; \ - echo "These link types will point to the correct GitHub version automatically"; \ - exit 1; \ - fi - @echo "No hardcoded links found" - -doctest: | check_python_packages - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -xml: | check_python_packages - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: | check_python_packages - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/doxygen_idf.py b/docs/doxygen_idf.py index 79b2429450..4cb49b6dd3 100644 --- a/docs/doxygen_idf.py +++ b/docs/doxygen_idf.py @@ -4,6 +4,7 @@ import os.path import re import sys import subprocess +gen_dxd = __import__("gen-dxd") from local_util import copy_if_modified, call_with_python @@ -18,7 +19,7 @@ def _parse_defines(header_path): # that these headers are all self-contained and don't include any other headers # not in the same directory print("Reading macros from %s..." % (header_path)) - processed_output = subprocess.check_output(["xtensa-esp32-elf-gcc", "-dM", "-E", header_path]) + processed_output = subprocess.check_output(["xtensa-esp32-elf-gcc", "-dM", "-E", header_path]).decode() for line in processed_output.split("\n"): line = line.strip() m = re.search("#define ([^ ]+) ?(.*)", line) @@ -49,19 +50,27 @@ def generate_doxygen(app, project_description): # Call Doxygen to get XML files from the header files print("Calling Doxygen to generate latest XML files") doxy_env = { - "ENV_DOXYGEN_DEFINES": " ".join(defines) + "ENV_DOXYGEN_DEFINES": " ".join(defines), + "IDF_PATH": app.config.idf_path, } - subprocess.check_call(["doxygen", "../Doxyfile"], env=doxy_env) + doxyfile = os.path.join(app.config.docs_root, "Doxyfile") + # note: run Doxygen in the build directory, so the xml & xml_in files end up in there + subprocess.check_call(["doxygen", doxyfile], env=doxy_env, cwd=build_dir) # Doxygen has generated XML files in 'xml' directory. # Copy them to 'xml_in', only touching the files which have changed. - copy_if_modified('xml/', 'xml_in/') + copy_if_modified(os.path.join(build_dir, 'xml/'), os.path.join(build_dir, 'xml_in/')) # Generate 'api_name.inc' files using the XML files by Doxygen - call_with_python('../gen-dxd.py') + gen_dxd.builddir = build_dir + gen_dxd.doxyfile_path = doxyfile + gen_dxd.header_file_path_prefix = "components/" + gen_dxd.xml_directory_path = "{}/xml".format(build_dir) + gen_dxd.inc_directory_path = "{}/inc".format(build_dir) + gen_dxd.generate_api_inc_files() # Generate 'esp_err_defs.inc' file with ESP_ERR_ error code definitions from inc file esp_err_inc_path = '{}/inc/esp_err_defs.inc'.format(build_dir) - call_with_python('../../tools/gen_esp_err_to_name.py --rst_output ' + esp_err_inc_path + '.in') + call_with_python('{}/tools/gen_esp_err_to_name.py --rst_output {}.in'.format(app.config.idf_path, esp_err_inc_path)) copy_if_modified(esp_err_inc_path + '.in', esp_err_inc_path) diff --git a/docs/en/api-reference/bluetooth/controller_vhci.rst b/docs/en/api-reference/bluetooth/controller_vhci.rst index abc037b662..2f98339290 100644 --- a/docs/en/api-reference/bluetooth/controller_vhci.rst +++ b/docs/en/api-reference/bluetooth/controller_vhci.rst @@ -18,4 +18,4 @@ Check :example:`bluetooth/bluedroid/hci` folder in ESP-IDF examples, which conta API Reference ------------- -.. include:: /_build/inc/esp_bt.inc +.. include-build-file:: inc/esp_bt.inc diff --git a/docs/en/api-reference/bluetooth/esp-ble-mesh.rst b/docs/en/api-reference/bluetooth/esp-ble-mesh.rst index a10c79fe29..62b5703b30 100644 --- a/docs/en/api-reference/bluetooth/esp-ble-mesh.rst +++ b/docs/en/api-reference/bluetooth/esp-ble-mesh.rst @@ -42,7 +42,7 @@ This section contains only one header file, which lists the following items of E * Structs used to transmit/receive messages * Event types and related event parameters -.. include:: /_build/inc/esp_ble_mesh_defs.inc +.. include-build-file:: inc/esp_ble_mesh_defs.inc ESP-BLE-MESH Core API Reference @@ -64,37 +64,37 @@ This API reference covers six components: ESP-BLE-MESH Stack Initialization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include:: /_build/inc/esp_ble_mesh_common_api.inc +.. include-build-file:: inc/esp_ble_mesh_common_api.inc Reading of Local Data Information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include:: /_build/inc/esp_ble_mesh_local_data_operation_api.inc +.. include-build-file:: inc/esp_ble_mesh_local_data_operation_api.inc Low Power Operation (Updating) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include:: /_build/inc/esp_ble_mesh_low_power_api.inc +.. include-build-file:: inc/esp_ble_mesh_low_power_api.inc Send/Publish Messages, add Local AppKey, etc. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include:: /_build/inc/esp_ble_mesh_networking_api.inc +.. include-build-file:: inc/esp_ble_mesh_networking_api.inc ESP-BLE-MESH Node/Provisioner Provisioning ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include:: /_build/inc/esp_ble_mesh_provisioning_api.inc +.. include-build-file:: inc/esp_ble_mesh_provisioning_api.inc ESP-BLE-MESH GATT Proxy Server ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include:: /_build/inc/esp_ble_mesh_proxy_api.inc +.. include-build-file:: inc/esp_ble_mesh_proxy_api.inc ESP-BLE-MESH Models API Reference @@ -120,35 +120,35 @@ There are six categories of models: Configuration Client/Server Models ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include:: /_build/inc/esp_ble_mesh_config_model_api.inc +.. include-build-file:: inc/esp_ble_mesh_config_model_api.inc Health Client/Server Models ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include:: /_build/inc/esp_ble_mesh_generic_model_api.inc +.. include-build-file:: inc/esp_ble_mesh_generic_model_api.inc Generic Client/Server Models ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include:: /_build/inc/esp_ble_mesh_health_model_api.inc +.. include-build-file:: inc/esp_ble_mesh_health_model_api.inc Sensor Client/Server Models ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include:: /_build/inc/esp_ble_mesh_lighting_model_api.inc +.. include-build-file:: inc/esp_ble_mesh_lighting_model_api.inc Time and Scenes Client/Server Models ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include:: /_build/inc/esp_ble_mesh_sensor_model_api.inc +.. include-build-file:: inc/esp_ble_mesh_sensor_model_api.inc Lighting Client/Server Models ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include:: /_build/inc/esp_ble_mesh_time_scene_model_api.inc +.. include-build-file:: inc/esp_ble_mesh_time_scene_model_api.inc diff --git a/docs/en/api-reference/bluetooth/esp_a2dp.rst b/docs/en/api-reference/bluetooth/esp_a2dp.rst index 873c9405cc..8dea862fc1 100644 --- a/docs/en/api-reference/bluetooth/esp_a2dp.rst +++ b/docs/en/api-reference/bluetooth/esp_a2dp.rst @@ -18,5 +18,5 @@ Check :example:`bluetooth/bluedroid/classic_bt` folder in ESP-IDF examples, whic API Reference ------------- -.. include:: /_build/inc/esp_a2dp_api.inc +.. include-build-file:: inc/esp_a2dp_api.inc diff --git a/docs/en/api-reference/bluetooth/esp_avrc.rst b/docs/en/api-reference/bluetooth/esp_avrc.rst index ca4993de16..1c15c7b69c 100644 --- a/docs/en/api-reference/bluetooth/esp_avrc.rst +++ b/docs/en/api-reference/bluetooth/esp_avrc.rst @@ -18,6 +18,6 @@ Application Example API Reference ------------- -.. include:: /_build/inc/esp_avrc_api.inc +.. include-build-file:: inc/esp_avrc_api.inc diff --git a/docs/en/api-reference/bluetooth/esp_blufi.rst b/docs/en/api-reference/bluetooth/esp_blufi.rst index 1f20ae16e8..2eb2b2a6d0 100644 --- a/docs/en/api-reference/bluetooth/esp_blufi.rst +++ b/docs/en/api-reference/bluetooth/esp_blufi.rst @@ -19,5 +19,5 @@ Check :example:`bluetooth/bluedroid/ble` folder in ESP-IDF examples, which conta API Reference ------------- -.. include:: /_build/inc/esp_blufi_api.inc +.. include-build-file:: inc/esp_blufi_api.inc diff --git a/docs/en/api-reference/bluetooth/esp_bt_defs.rst b/docs/en/api-reference/bluetooth/esp_bt_defs.rst index 58b2ad03e0..85e73d0688 100644 --- a/docs/en/api-reference/bluetooth/esp_bt_defs.rst +++ b/docs/en/api-reference/bluetooth/esp_bt_defs.rst @@ -17,5 +17,5 @@ Application Example API Reference ------------- -.. include:: /_build/inc/esp_bt_defs.inc +.. include-build-file:: inc/esp_bt_defs.inc diff --git a/docs/en/api-reference/bluetooth/esp_bt_device.rst b/docs/en/api-reference/bluetooth/esp_bt_device.rst index 936b5a318f..b234cea14c 100644 --- a/docs/en/api-reference/bluetooth/esp_bt_device.rst +++ b/docs/en/api-reference/bluetooth/esp_bt_device.rst @@ -18,4 +18,4 @@ Application Example API Reference ------------- -.. include:: /_build/inc/esp_bt_device.inc +.. include-build-file:: inc/esp_bt_device.inc diff --git a/docs/en/api-reference/bluetooth/esp_bt_main.rst b/docs/en/api-reference/bluetooth/esp_bt_main.rst index 06055ffadb..321f9331e2 100644 --- a/docs/en/api-reference/bluetooth/esp_bt_main.rst +++ b/docs/en/api-reference/bluetooth/esp_bt_main.rst @@ -17,6 +17,6 @@ Application Example API Reference ------------- -.. include:: /_build/inc/esp_bt_main.inc +.. include-build-file:: inc/esp_bt_main.inc diff --git a/docs/en/api-reference/bluetooth/esp_gap_ble.rst b/docs/en/api-reference/bluetooth/esp_gap_ble.rst index b997daff7d..8f95906853 100644 --- a/docs/en/api-reference/bluetooth/esp_gap_ble.rst +++ b/docs/en/api-reference/bluetooth/esp_gap_ble.rst @@ -26,5 +26,5 @@ Check :example:`bluetooth/bluedroid/ble` folder in ESP-IDF examples, which conta API Reference ------------- -.. include:: /_build/inc/esp_gap_ble_api.inc +.. include-build-file:: inc/esp_gap_ble_api.inc diff --git a/docs/en/api-reference/bluetooth/esp_gap_bt.rst b/docs/en/api-reference/bluetooth/esp_gap_bt.rst index 38b005b31f..346f7ec90a 100644 --- a/docs/en/api-reference/bluetooth/esp_gap_bt.rst +++ b/docs/en/api-reference/bluetooth/esp_gap_bt.rst @@ -16,5 +16,5 @@ Application Example API Reference ------------- -.. include:: /_build/inc/esp_gap_bt_api.inc +.. include-build-file:: inc/esp_gap_bt_api.inc diff --git a/docs/en/api-reference/bluetooth/esp_gatt_defs.rst b/docs/en/api-reference/bluetooth/esp_gatt_defs.rst index fd383ab72d..931802126f 100644 --- a/docs/en/api-reference/bluetooth/esp_gatt_defs.rst +++ b/docs/en/api-reference/bluetooth/esp_gatt_defs.rst @@ -16,6 +16,6 @@ Application Example API Reference ------------- -.. include:: /_build/inc/esp_gatt_defs.inc +.. include-build-file:: inc/esp_gatt_defs.inc diff --git a/docs/en/api-reference/bluetooth/esp_gattc.rst b/docs/en/api-reference/bluetooth/esp_gattc.rst index 90f9782b11..708888d2b5 100644 --- a/docs/en/api-reference/bluetooth/esp_gattc.rst +++ b/docs/en/api-reference/bluetooth/esp_gattc.rst @@ -30,5 +30,5 @@ Check :example:`bluetooth/bluedroid/ble` folder in ESP-IDF examples, which conta API Reference ------------- -.. include:: /_build/inc/esp_gattc_api.inc +.. include-build-file:: inc/esp_gattc_api.inc diff --git a/docs/en/api-reference/bluetooth/esp_gatts.rst b/docs/en/api-reference/bluetooth/esp_gatts.rst index 7915a653d8..1b48fccc89 100644 --- a/docs/en/api-reference/bluetooth/esp_gatts.rst +++ b/docs/en/api-reference/bluetooth/esp_gatts.rst @@ -30,5 +30,5 @@ Check :example:`bluetooth/bluedroid/ble` folder in ESP-IDF examples, which conta API Reference ------------- -.. include:: /_build/inc/esp_gatts_api.inc +.. include-build-file:: inc/esp_gatts_api.inc diff --git a/docs/en/api-reference/bluetooth/esp_hf_client.rst b/docs/en/api-reference/bluetooth/esp_hf_client.rst index 7c8a2d88c9..b79eb743f7 100644 --- a/docs/en/api-reference/bluetooth/esp_hf_client.rst +++ b/docs/en/api-reference/bluetooth/esp_hf_client.rst @@ -11,4 +11,4 @@ Overview API Reference ------------- -.. include:: /_build/inc/esp_hf_client_api.inc +.. include-build-file:: inc/esp_hf_client_api.inc diff --git a/docs/en/api-reference/bluetooth/esp_hf_defs.rst b/docs/en/api-reference/bluetooth/esp_hf_defs.rst index 615b623862..4633a81f67 100644 --- a/docs/en/api-reference/bluetooth/esp_hf_defs.rst +++ b/docs/en/api-reference/bluetooth/esp_hf_defs.rst @@ -11,6 +11,6 @@ Overview API Reference ------------- -.. include:: /_build/inc/esp_hf_defs.inc +.. include-build-file:: inc/esp_hf_defs.inc diff --git a/docs/en/api-reference/bluetooth/esp_spp.rst b/docs/en/api-reference/bluetooth/esp_spp.rst index 2a6a6acc51..ced5340899 100644 --- a/docs/en/api-reference/bluetooth/esp_spp.rst +++ b/docs/en/api-reference/bluetooth/esp_spp.rst @@ -18,5 +18,5 @@ Check :example:`bluetooth/bluedroid/classic_bt` folder in ESP-IDF examples, whic API Reference ------------- -.. include:: /_build/inc/esp_spp_api.inc +.. include-build-file:: inc/esp_spp_api.inc diff --git a/docs/en/api-reference/bluetooth/nimble/index.rst b/docs/en/api-reference/bluetooth/nimble/index.rst index a8ff60d19f..8600c86049 100644 --- a/docs/en/api-reference/bluetooth/nimble/index.rst +++ b/docs/en/api-reference/bluetooth/nimble/index.rst @@ -41,4 +41,4 @@ This documentation does not cover NimBLE APIs. Refer to `NimBLE tutorial `. -.. include:: /_build/inc/esp_err_defs.inc +.. include-build-file:: inc/esp_err_defs.inc diff --git a/docs/en/api-reference/kconfig.rst b/docs/en/api-reference/kconfig.rst index 2c23c8dd4d..21e6b68f16 100644 --- a/docs/en/api-reference/kconfig.rst +++ b/docs/en/api-reference/kconfig.rst @@ -85,7 +85,7 @@ Subsequent sections contain the list of available ESP-IDF options, automatically By convention, all option names are upper case with underscores. When Kconfig generates sdkconfig and sdkconfig.h files, option names are prefixed with ``CONFIG_``. So if an option ``ENABLE_FOO`` is defined in a Kconfig file and selected in menuconfig, then sdkconfig and sdkconfig.h files will have ``CONFIG_ENABLE_FOO`` defined. In this reference, option names are also prefixed with ``CONFIG_``, same as in the source code. -.. include:: /_build/inc/kconfig.inc +.. include-build-file:: inc/kconfig.inc Customisations ============== diff --git a/docs/en/api-reference/network/esp_eth.rst b/docs/en/api-reference/network/esp_eth.rst index db9990e359..88cd39168f 100644 --- a/docs/en/api-reference/network/esp_eth.rst +++ b/docs/en/api-reference/network/esp_eth.rst @@ -37,24 +37,24 @@ Ethernet PHY Common Registers API Reference - Driver Model ---------------------------- -.. include:: /_build/inc/esp_eth.inc +.. include-build-file:: inc/esp_eth.inc API Reference - Common Interface -------------------------------- -.. include:: /_build/inc/esp_eth_com.inc +.. include-build-file:: inc/esp_eth_com.inc API Reference - MAC Interface ----------------------------- -.. include:: /_build/inc/esp_eth_mac.inc +.. include-build-file:: inc/esp_eth_mac.inc API Reference - PHY Interface ----------------------------- -.. include:: /_build/inc/esp_eth_phy.inc +.. include-build-file:: inc/esp_eth_phy.inc API Reference - Glue for esp_netif ---------------------------------- -.. include:: /_build/inc/esp_eth_netif_glue.inc +.. include-build-file:: inc/esp_eth_netif_glue.inc diff --git a/docs/en/api-reference/network/esp_mesh.rst b/docs/en/api-reference/network/esp_mesh.rst index 051841a0da..02efbe0349 100644 --- a/docs/en/api-reference/network/esp_mesh.rst +++ b/docs/en/api-reference/network/esp_mesh.rst @@ -332,4 +332,4 @@ ESP-IDF contains these ESP-MESH example projects: API Reference -------------- -.. include:: /_build/inc/esp_mesh.inc +.. include-build-file:: inc/esp_mesh.inc diff --git a/docs/en/api-reference/network/esp_netif.rst b/docs/en/api-reference/network/esp_netif.rst index 77bb21c9f8..16c00cc9a2 100644 --- a/docs/en/api-reference/network/esp_netif.rst +++ b/docs/en/api-reference/network/esp_netif.rst @@ -168,10 +168,10 @@ configured with default settings, which as a consequence, means that: API Reference ------------- -.. include:: /_build/inc/esp_netif.inc +.. include-build-file:: inc/esp_netif.inc WiFi default API reference ^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include:: /_build/inc/esp_wifi_default.inc +.. include-build-file:: inc/esp_wifi_default.inc diff --git a/docs/en/api-reference/network/esp_netif_driver.rst b/docs/en/api-reference/network/esp_netif_driver.rst index 4dd7f1c6a8..000d5eb37d 100644 --- a/docs/en/api-reference/network/esp_netif_driver.rst +++ b/docs/en/api-reference/network/esp_netif_driver.rst @@ -94,4 +94,4 @@ The packet data path functions for transmitting and freeing the rx buffer (defin the esp-netif, specifically from its TCP/IP stack connecting layer. The following API reference outlines these network stack interaction with the esp-netif. -.. include:: /_build/inc/esp_netif_net_stack.inc +.. include-build-file:: inc/esp_netif_net_stack.inc diff --git a/docs/en/api-reference/network/esp_now.rst b/docs/en/api-reference/network/esp_now.rst index 172e8789f2..83df9f2cb9 100644 --- a/docs/en/api-reference/network/esp_now.rst +++ b/docs/en/api-reference/network/esp_now.rst @@ -84,4 +84,4 @@ Instead, post the necessary data to a queue and handle it from a lower priority API Reference ------------- -.. include:: /_build/inc/esp_now.inc +.. include-build-file:: inc/esp_now.inc diff --git a/docs/en/api-reference/network/esp_smartconfig.rst b/docs/en/api-reference/network/esp_smartconfig.rst index f21453aa57..7b195c6790 100644 --- a/docs/en/api-reference/network/esp_smartconfig.rst +++ b/docs/en/api-reference/network/esp_smartconfig.rst @@ -6,4 +6,4 @@ SmartConfig API Reference ------------- -.. include:: /_build/inc/esp_smartconfig.inc +.. include-build-file:: inc/esp_smartconfig.inc diff --git a/docs/en/api-reference/network/esp_wifi.rst b/docs/en/api-reference/network/esp_wifi.rst index 0d50703802..17dde21e3b 100644 --- a/docs/en/api-reference/network/esp_wifi.rst +++ b/docs/en/api-reference/network/esp_wifi.rst @@ -30,7 +30,7 @@ In addition, there is a simple `esp-idf-template `. Task API -------- -.. include:: /_build/inc/task.inc +.. include-build-file:: inc/task.inc Queue API --------- -.. include:: /_build/inc/queue.inc +.. include-build-file:: inc/queue.inc Semaphore API ------------- -.. include:: /_build/inc/semphr.inc +.. include-build-file:: inc/semphr.inc Timer API --------- -.. include:: /_build/inc/timers.inc +.. include-build-file:: inc/timers.inc Event Group API --------------- -.. include:: /_build/inc/event_groups.inc +.. include-build-file:: inc/event_groups.inc diff --git a/docs/en/api-reference/system/freertos_additions.rst b/docs/en/api-reference/system/freertos_additions.rst index ea38fd7d35..969cc2d874 100644 --- a/docs/en/api-reference/system/freertos_additions.rst +++ b/docs/en/api-reference/system/freertos_additions.rst @@ -469,7 +469,7 @@ Ring Buffer API Reference of tasks using the ring buffer simultaneously is low, and the ring buffer is not operating near maximum capacity. -.. include:: /_build/inc/ringbuf.inc +.. include-build-file:: inc/ringbuf.inc .. _hooks: @@ -518,4 +518,4 @@ in turn. Hooks API Reference ------------------- -.. include:: /_build/inc/esp_freertos_hooks.inc +.. include-build-file:: inc/esp_freertos_hooks.inc diff --git a/docs/en/api-reference/system/heap_debug.rst b/docs/en/api-reference/system/heap_debug.rst index fe0882e9d4..d00f17e480 100644 --- a/docs/en/api-reference/system/heap_debug.rst +++ b/docs/en/api-reference/system/heap_debug.rst @@ -402,4 +402,4 @@ One way to differentiate between "real" and "false positive" memory leaks is to API Reference - Heap Tracing ---------------------------- -.. include:: /_build/inc/esp_heap_trace.inc +.. include-build-file:: inc/esp_heap_trace.inc diff --git a/docs/en/api-reference/system/himem.rst b/docs/en/api-reference/system/himem.rst index 1c5dd0129a..00529485d5 100644 --- a/docs/en/api-reference/system/himem.rst +++ b/docs/en/api-reference/system/himem.rst @@ -30,4 +30,4 @@ An example doing a simple memory test of the high memory range is available in e API Reference ------------- -.. include:: /_build/inc/himem.inc +.. include-build-file:: inc/himem.inc diff --git a/docs/en/api-reference/system/intr_alloc.rst b/docs/en/api-reference/system/intr_alloc.rst index 63cf5516e5..da15992432 100644 --- a/docs/en/api-reference/system/intr_alloc.rst +++ b/docs/en/api-reference/system/intr_alloc.rst @@ -100,6 +100,6 @@ or the status should be handled in other enabled interrupt properly**. You may l API Reference ------------- -.. include:: /_build/inc/esp_intr_alloc.inc +.. include-build-file:: inc/esp_intr_alloc.inc diff --git a/docs/en/api-reference/system/ipc.rst b/docs/en/api-reference/system/ipc.rst index a409719039..5ced8393e6 100644 --- a/docs/en/api-reference/system/ipc.rst +++ b/docs/en/api-reference/system/ipc.rst @@ -38,6 +38,6 @@ IPC, especially when attempting to take a mutex within the function. API Reference ------------- -.. include:: /_build/inc/esp_ipc.inc +.. include-build-file:: inc/esp_ipc.inc diff --git a/docs/en/api-reference/system/log.rst b/docs/en/api-reference/system/log.rst index 72609c69a1..475439804e 100644 --- a/docs/en/api-reference/system/log.rst +++ b/docs/en/api-reference/system/log.rst @@ -12,7 +12,7 @@ The logging library is commonly used by most esp-idf components and examples. Fo API Reference ------------- -.. include:: /_build/inc/esp_log.inc +.. include-build-file:: inc/esp_log.inc diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst index d2e5222f40..65ab940435 100644 --- a/docs/en/api-reference/system/mem_alloc.rst +++ b/docs/en/api-reference/system/mem_alloc.rst @@ -111,7 +111,7 @@ To use the region above the 4MiB limit, you can use the :doc:`himem API Date: Fri, 22 Nov 2019 16:57:09 +1100 Subject: [PATCH 04/47] docs: Add "explicit only" directive & use only:: to block out some chip-specific parts of docs --- docs/build_docs.py | 1 + docs/conf_common.py | 4 ++++ docs/en/api-guides/build-system.rst | 9 +++++-- docs/en/api-guides/fatal-errors.rst | 8 ++++++- .../api-reference/system/power_management.rst | 8 ++++++- docs/en/api-reference/system/system.rst | 10 ++++---- docs/en/get-started/index.rst | 24 ++++++++++--------- docs/en/get-started/windows-setup.rst | 6 +++-- docs/requirements.txt | 1 + 9 files changed, 50 insertions(+), 21 deletions(-) diff --git a/docs/build_docs.py b/docs/build_docs.py index 47381ee967..dbcb7d638a 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -73,6 +73,7 @@ def build_docs(language, target, build_dir): "-d", os.path.join(build_dir, "doctrees"), # TODO: support multiple sphinx-warning.log files, somehow "-w", "sphinx-warning.log", + "-t", target, "-D", "idf_target={}".format(target), os.path.join(os.path.abspath(os.path.dirname(__file__)), language), # srcdir for this language os.path.join(build_dir, "html") # build directory diff --git a/docs/conf_common.py b/docs/conf_common.py index b8f811e13d..6412dff2be 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -105,6 +105,10 @@ extensions = ['breathe', 'doxygen_idf', 'sphinx.ext.todo', 'include_build_file', + # from https://github.com/pfalcon/sphinx_selective_exclude + 'sphinx_selective_exclude.eager_only', + #'sphinx_selective_exclude.search_auto_exclude', + #'sphinx_selective_exclude.modindex_exclude', ] # sphinx.ext.todo extension parameters diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 329a9cf7b2..343330d2ff 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -883,7 +883,9 @@ the ESP-IDF build system entirely by using a CMake feature called ExternalProjec - The second set of commands adds a library target, which points to the "imported" library file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is. - Finally, the generated library is added to `ADDITIONAL_MAKE_CLEAN_FILES`_. This means ``make clean`` will delete this library. (Note that the other object files from the build won't be deleted.) -.. note:: When using an external build process with PSRAM, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag. +.. only:: esp32 + + .. note:: When using an external build process with PSRAM, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag. .. _ADDITIONAL_MAKE_CLEAN_FILES_note: @@ -1108,7 +1110,10 @@ It is possible to do so by using the :ref:`build system APIs provided` using a custom CMake project. -.. note:: The IDF build system can only set compiler flags for source files that it builds. When an external CMakeLists.txt file is used and PSRAM is enabled, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag. +.. only:: esp32 + + .. note:: The IDF build system can only set compiler flags for source files that it builds. When an external CMakeLists.txt file is used and PSRAM is enabled, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag. + .. _cmake_buildsystem_api: ESP-IDF CMake Build System API diff --git a/docs/en/api-guides/fatal-errors.rst b/docs/en/api-guides/fatal-errors.rst index fe07381a3e..51f3ef9031 100644 --- a/docs/en/api-guides/fatal-errors.rst +++ b/docs/en/api-guides/fatal-errors.rst @@ -58,7 +58,13 @@ Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32_PAN Behavior of panic handler is affected by two other configuration options. -- If :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used. +.. only:: esp32 + + - If :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used. + +.. only:: esp32s2beta + + - If :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used. - If :doc:`Core Dump ` feature is enabled (``CONFIG_ESP32_ENABLE_COREDUMP_TO_FLASH`` or ``CONFIG_ESP32_ENABLE_COREDUMP_TO_UART`` options), then system state (task stacks and registers) will be dumped either to Flash or UART, for later analysis. diff --git a/docs/en/api-reference/system/power_management.rst b/docs/en/api-reference/system/power_management.rst index 86a2814b9a..a6e35bd918 100644 --- a/docs/en/api-reference/system/power_management.rst +++ b/docs/en/api-reference/system/power_management.rst @@ -31,7 +31,13 @@ Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in an a - ``min_freq_mhz``: Minimum CPU frequency in MHz, i.e., the frequency used when only the ``ESP_PM_APB_FREQ_MAX`` lock is acquired. This field can be set to the XTAL frequency value, or the XTAL frequency divided by an integer. Note that 10 MHz is the lowest frequency at which the default REF_TICK clock of 1 MHz can be generated. - ``light_sleep_enable``: Whether the system should automatically enter light sleep when no locks are acquired (``true``/``false``). -Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency. +.. only:: esp32 + + Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency. + +.. only:: esp32s2beta + + Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_ESP32S2_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency. .. note:: diff --git a/docs/en/api-reference/system/system.rst b/docs/en/api-reference/system/system.rst index 9922cc54a5..d0c8221cb4 100644 --- a/docs/en/api-reference/system/system.rst +++ b/docs/en/api-reference/system/system.rst @@ -105,13 +105,15 @@ If the universally administered MAC addresses are not enough for all of the netw See `this article `_ for the definition of local and universally administered MAC addresses. -The number of universally administered MAC address can be configured using :ref:`CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES` for ESP32. +.. only:: esp32 -If the number of universal MAC addresses is two, only two interfaces (Wi-Fi Station and Bluetooth) receive a universally administered MAC address. These are generated sequentially by adding 0 and 1 (respectively) to the base MAC address. The remaining two interfaces (Wi-Fi SoftAP and Ethernet) receive local MAC addresses. These are derived from the universal Wi-Fi station and Bluetooth MAC addresses, respectively. + The number of universally administered MAC address can be configured using :ref:`CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES`. -If the number of universal MAC addresses is four, all four interfaces (Wi-Fi Station, Wi-Fi SoftAP, Bluetooth and Ethernet) receive a universally administered MAC address. These are generated sequentially by adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address. + If the number of universal MAC addresses is two, only two interfaces (Wi-Fi Station and Bluetooth) receive a universally administered MAC address. These are generated sequentially by adding 0 and 1 (respectively) to the base MAC address. The remaining two interfaces (Wi-Fi SoftAP and Ethernet) receive local MAC addresses. These are derived from the universal Wi-Fi station and Bluetooth MAC addresses, respectively. -When using the default (Espressif-assigned) base MAC address, either setting can be used. When using a custom universal MAC address range, the correct setting will depend on the allocation of MAC addresses in this range (either 2 or 4 per device.) + If the number of universal MAC addresses is four, all four interfaces (Wi-Fi Station, Wi-Fi SoftAP, Bluetooth and Ethernet) receive a universally administered MAC address. These are generated sequentially by adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address. + + When using the default (Espressif-assigned) base MAC address, either setting can be used. When using a custom universal MAC address range, the correct setting will depend on the allocation of MAC addresses in this range (either 2 or 4 per device.) .. todo:: diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index 2a40816444..cb346d6062 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -463,19 +463,21 @@ After startup and diagnostic logs scroll up, you should see "Hello world!" print To exit IDF monitor use the shortcut ``Ctrl+]``. -If IDF monitor fails shortly after the upload, or, if instead of the messages above, you see random garbage similar to what is given below, your board is likely using a 26MHz crystal. Most development board designs use 40MHz, so ESP-IDF uses this frequency as a default value. +.. only:: esp32 -.. figure:: ../../_static/get-started-garbled-output.png - :align: center - :alt: Garbled output - :figclass: align-center + If IDF monitor fails shortly after the upload, or, if instead of the messages above, you see random garbage similar to what is given below, your board is likely using a 26MHz crystal. Most development board designs use 40MHz, so ESP-IDF uses this frequency as a default value. -If you have such a problem, do the following: - -1. Exit the monitor. -2. Go back to :ref:`menuconfig `. -3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz. -4. After that, :ref:`build and flash ` the application again. + .. figure:: ../../_static/get-started-garbled-output.png + :align: center + :alt: Garbled output + :figclass: align-center + + If you have such a problem, do the following: + + 1. Exit the monitor. + 2. Go back to :ref:`menuconfig `. + 3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz. + 4. After that, :ref:`build and flash ` the application again. .. note:: diff --git a/docs/en/get-started/windows-setup.rst b/docs/en/get-started/windows-setup.rst index 2819a50d05..ccf983ae90 100644 --- a/docs/en/get-started/windows-setup.rst +++ b/docs/en/get-started/windows-setup.rst @@ -4,8 +4,10 @@ Standard Setup of Toolchain for Windows :link_to_translation:`zh_CN:[中文]` -.. note:: - Currently only 64-bit versions of Windows are supported. 32-bit Windows can use the :doc:`Legacy GNU Make Build System<../get-started-legacy/windows-setup>`. +.. only:: esp32 + + .. note:: + Currently only 64-bit versions of Windows are supported. 32-bit Windows can use the :doc:`Legacy GNU Make Build System<../get-started-legacy/windows-setup>`. Introduction ============ diff --git a/docs/requirements.txt b/docs/requirements.txt index 15e6b9fb48..f914e2cbde 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -12,3 +12,4 @@ sphinxcontrib-nwdiag>=0.9.5, <2.0.0 nwdiag==1.0.4 recommonmark future>=0.16.0 # for ../tools/gen_esp_err_to_name.py +sphinx_selective_exclude==1.0.1 From 9399f04da060aef29ae39bd97bd450f1c3c41c3c Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 22 Nov 2019 16:58:04 +1100 Subject: [PATCH 05/47] docs: Add 'toctree filter' directive & filter out ESP32-only pages from S2 docs --- docs/conf_common.py | 17 ++++- docs/en/api-guides/build-system.rst | 4 +- docs/en/api-guides/external-ram.rst | 33 ++-------- docs/en/api-guides/fatal-errors.rst | 29 ++++++--- .../inc/external-ram-esp32-notes.inc | 24 +++++++ docs/en/api-guides/index.rst | 10 +-- .../jtag-debugging/tips-and-quirks.rst | 9 ++- docs/en/api-guides/tools/idf-monitor.rst | 8 ++- docs/en/api-guides/ulp.rst | 4 +- docs/en/api-reference/index.rst | 2 +- docs/en/api-reference/peripherals/can.rst | 6 +- docs/en/api-reference/protocols/index.rst | 2 +- .../system/inc/power_management_esp32.rst | 40 ++++++++++++ .../api-reference/system/power_management.rst | 64 ++++++------------- docs/en/conf.py | 3 + docs/en/get-started/eclipse-setup.rst | 4 +- docs/en/get-started/index.rst | 2 +- docs/en/get-started/windows-setup.rst | 5 +- docs/toctree_filter.py | 43 +++++++++++++ docs/zh_CN/conf.py | 3 + 20 files changed, 213 insertions(+), 99 deletions(-) create mode 100644 docs/en/api-guides/inc/external-ram-esp32-notes.inc create mode 100644 docs/en/api-reference/system/inc/power_management_esp32.rst create mode 100644 docs/toctree_filter.py diff --git a/docs/conf_common.py b/docs/conf_common.py index 6412dff2be..ee80513fd2 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -105,6 +105,7 @@ extensions = ['breathe', 'doxygen_idf', 'sphinx.ext.todo', 'include_build_file', + 'toctree_filter', # from https://github.com/pfalcon/sphinx_selective_exclude 'sphinx_selective_exclude.eager_only', #'sphinx_selective_exclude.search_auto_exclude', @@ -168,7 +169,21 @@ print('Version: {0} Release: {1}'.format(version, release)) # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build','README.md'] +exclude_patterns = ['**/inc/**'] + +# Add target-specific excludes based on tags. Haven't found any better way to do this yet +def update_exclude_patterns(tags): + if "esp32" not in tags: + # Exclude ESP32-only document pages so they aren't found in the initial search for .rst files + # note: in toctrees, these also need to be marked with a :esp32: filter + for e in ['api-guides/blufi.rst', + 'api-guides/build-system-legacy.rst', + 'api-guides/esp-ble-mesh/**', + 'api-guides/ulp-legacy.rst', + 'api-guides/unit-tests-legacy.rst', + 'api-reference/bluetooth/**', + 'get-started-legacy/**']: + exclude_patterns.append(e) # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 343330d2ff..a99fdbb0ff 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -5,7 +5,9 @@ Build System This document explains the implementation of the ESP-IDF build system and the concept of "components". Read this document if you want to know how to organise and build a new ESP-IDF project or component. -.. note:: This document describes the CMake-based build system, which is the default since ESP-IDF V4.0. ESP-IDF also supports a :doc:`legacy build system based on GNU Make `, which was the default before ESP-IDF V4.0. +.. only:: esp32 + + .. note:: This document describes the CMake-based build system, which is the default since ESP-IDF V4.0. ESP-IDF also supports a :doc:`legacy build system based on GNU Make `, which was the default before ESP-IDF V4.0. Overview diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index fa22c06d31..6aa14019a6 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -119,36 +119,11 @@ External RAM use has the following restrictions: * When flash cache is disabled (for example, if the flash is being written to), the external RAM also becomes inaccessible; any reads from or writes to it will lead to an illegal cache access exception. This is also the reason why ESP-IDF does not by default allocate any task stacks in external RAM (see below). * External RAM cannot be used as a place to store DMA transaction descriptors or as a buffer for a DMA transfer to read from or write into. Any buffers that will be used in combination with DMA must be allocated using ``heap_caps_malloc(size, MALLOC_CAP_DMA)`` and can be freed using a standard ``free()`` call. * External RAM uses the same cache region as the external flash. This means that frequently accessed variables in external RAM can be read and modified almost as quickly as in internal ram. However, when accessing large chunks of data (>32 KB), the cache can be insufficient, and speeds will fall back to the access speed of the external RAM. Moreover, accessing large chunks of data can "push out" cached flash, possibly making the execution of code slower afterwards. - * External RAM cannot be used as task stack memory. Due to this, :cpp:func:`xTaskCreate` and similar functions will always allocate internal memory for stack and task TCBs, and functions such as :cpp:func:`xTaskCreateStatic` will check if the buffers passed are internal. However, for tasks not calling on code in ROM in any way, directly or indirectly, the menuconfig option :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` will eliminate the check in xTaskCreateStatic, allowing a task's stack to be in external RAM. Using this is not advised, however. + * External RAM cannot be used as task stack memory. Due to this, :cpp:func:`xTaskCreate` and similar functions will always allocate internal memory for stack and task TCBs, and functions such as :cpp:func:`xTaskCreateStatic` will check if the buffers passed are internal. * By default, failure to initialize external RAM will cause the ESP-IDF startup to abort. This can be disabled by enabling the config item :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND`. If :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` is enabled, the option to ignore failure is not available as the linker will have assigned symbols to external memory addresses at link time. - * When used at 80 MHz clock speed, external RAM must also occupy either the HSPI or VSPI bus. Select which SPI host will be used by :ref:`CONFIG_SPIRAM_OCCUPY_SPI_HOST`. - - -Chip revisions -============== - -There are some issues with certain revisions of ESP32 that have repercussions for use with external RAM. The issues are documented in the ESP32 ECO_ document. In particular, ESP-IDF handles the bugs mentioned in the following ways: - - -ESP32 rev v0 ------------- -ESP-IDF has no workaround for the bugs in this revision of silicon, and it cannot be used to map external PSRAM into ESP32's main memory map. - - -ESP32 rev v1 ------------- -The bugs in this revision of silicon cause issues if certain sequences of machine instructions operate on external memory. (ESP32 ECO 3.2). As a workaround, the GCC compiler received the flag ``-mfix-esp32-psram-cache-issue`` to filter these sequences and only output the code that can safely be executed. Enable this flag by checking :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`. - -Aside from linking to a recompiled version of Newlib with the additional flag, ESP-IDF also does the following: - -- Avoids using some ROM functions -- Allocates static memory for the WiFi stack - - -.. _ECO: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf - - - +.. only:: esp32 + .. include:: inc/external-ram-esp32-notes.inc +.. _ESP32 ECO: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf diff --git a/docs/en/api-guides/fatal-errors.rst b/docs/en/api-guides/fatal-errors.rst index 51f3ef9031..7cac04253d 100644 --- a/docs/en/api-guides/fatal-errors.rst +++ b/docs/en/api-guides/fatal-errors.rst @@ -38,21 +38,27 @@ For some of the system level checks (interrupt watchdog, cache access error), th In all cases, error cause will be printed in parens. See `Guru Meditation Errors`_ for a list of possible error causes. -Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32_PANIC` configuration choice. The available options are: +.. only:: esp32 -- Print registers and reboot (``CONFIG_ESP32_PANIC_PRINT_REBOOT``) — default option. + Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32_PANIC` configuration choice. The available options are: + +.. only:: esp32s2 + + Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32S2_PANIC` configuration choice. The available options are: + +- Print registers and reboot — default option. This will print register values at the point of the exception, print the backtrace, and restart the chip. -- Print registers and halt (``CONFIG_ESP32_PANIC_PRINT_HALT``) +- Print registers and halt Similar to the above option, but halt instead of rebooting. External reset is required to restart the program. -- Silent reboot (``CONFIG_ESP32_PANIC_SILENT_REBOOT``) +- Silent reboot Don't print registers or backtrace, restart the chip immediately. -- Invoke GDB Stub (``CONFIG_ESP32_PANIC_GDBSTUB``) +- Invoke GDB Stub Start GDB server which can communicate with GDB over console UART port. See `GDB Stub`_ for more details. @@ -62,11 +68,11 @@ Behavior of panic handler is affected by two other configuration options. - If :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used. -.. only:: esp32s2beta +.. only:: esp32s2 - If :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used. -- If :doc:`Core Dump ` feature is enabled (``CONFIG_ESP32_ENABLE_COREDUMP_TO_FLASH`` or ``CONFIG_ESP32_ENABLE_COREDUMP_TO_UART`` options), then system state (task stacks and registers) will be dumped either to Flash or UART, for later analysis. +- If :doc:`Core Dump ` feature is enabled, then system state (task stacks and registers) will be dumped either to Flash or UART, for later analysis. - If :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM` is disabled (disabled by default), the panic handler code is placed in flash memory not IRAM. This means that if ESP-IDF crashes while flash cache is disabled, the panic handler will automatically re-enable flash cache before running GDB Stub or Core Dump. This adds some minor risk, if the flash cache status is also corrupted during the crash. @@ -271,7 +277,14 @@ Other Fatal Errors Brownout ^^^^^^^^ -ESP32 has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_ESP32_BROWNOUT_DET` and :ref:`CONFIG_ESP32_BROWNOUT_DET_LVL_SEL` options. +.. only:: esp32 + + ESP32 has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_ESP32_BROWNOUT_DET` and :ref:`CONFIG_ESP32_BROWNOUT_DET_LVL_SEL` options. + +.. only:: esp32s2 + + ESP32-S2 has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_ESP32S2_BROWNOUT_DET` and :ref:`CONFIG_ESP32S2_BROWNOUT_DET_LVL_SEL` options. + When brownout detector triggers, the following message is printed:: Brownout detector was triggered diff --git a/docs/en/api-guides/inc/external-ram-esp32-notes.inc b/docs/en/api-guides/inc/external-ram-esp32-notes.inc new file mode 100644 index 0000000000..39a133a6a9 --- /dev/null +++ b/docs/en/api-guides/inc/external-ram-esp32-notes.inc @@ -0,0 +1,24 @@ +* Regarding stacks in PSRAM: For tasks not calling on code in ROM in any way, directly or indirectly, the menuconfig option :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` will eliminate the check in xTaskCreateStatic, allowing a task's stack to be in external RAM. Using this is not advised, however. +32 +* When used at 80 MHz clock speed, external RAM must also occupy either the HSPI or VSPI bus. Select which SPI host will be used by :ref:`CONFIG_SPIRAM_OCCUPY_SPI_HOST`. + + +Chip revisions +============== + +There are some issues with certain revisions of ESP32 that have repercussions for use with external RAM. The issues are documented in the `ESP32 ECO`_ document. In particular, ESP-IDF handles the bugs mentioned in the following ways: + + +ESP32 rev v0 +------------ +ESP-IDF has no workaround for the bugs in this revision of silicon, and it cannot be used to map external PSRAM into ESP32's main memory map. + + +ESP32 rev v1 +------------ +The bugs in this revision of silicon cause issues if certain sequences of machine instructions operate on external memory. (`ESP32 ECO`_ 3.2). As a workaround, the GCC compiler received the flag ``-mfix-esp32-psram-cache-issue`` to filter these sequences and only output the code that can safely be executed. Enable this flag by checking :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`. + +Aside from linking to a recompiled version of Newlib with the additional flag, ESP-IDF also does the following: + +- Avoids using some ROM functions +- Allocates static memory for the WiFi stack diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index 4883d08640..bd6e61eaac 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -6,14 +6,14 @@ API Guides :maxdepth: 1 Application Level Tracing - BluFi + :esp32: BluFi Bootloader Build System - Build System (Legacy GNU Make) + :esp32: Build System (Legacy GNU Make) Console Component Deep Sleep Wake Stubs Error Handling - ESP-BLE-MESH + :esp32: ESP-BLE-MESH ESP-MESH (Wi-Fi) ESP32 Core Dump Event Handling @@ -33,7 +33,7 @@ API Guides Thread Local Storage Tools ULP Coprocessor - ULP Coprocessor (Legacy GNU Make) - Unit Testing (Legacy GNU Make) + :esp32: ULP Coprocessor (Legacy GNU Make) Unit Testing + :esp32: Unit Testing (Legacy GNU Make) WiFi Driver diff --git a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst index 3103b0d3d5..866977c5bd 100644 --- a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst @@ -55,7 +55,14 @@ Support options for OpenOCD at compile time ESP-IDF has some support options for OpenOCD debugging which can be set at compile time: -* :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger. +.. only:: esp32 + + * :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger. + +.. only:: esp32s2 + + * :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger. + * :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` (disabled by default) sets watchpoint index 1 (the second of two) at the end of any task stack. This is the most accurate way to debug task stack overflows. Click the link for more details. Please see the :ref:`project configuration menu ` menu for more details on setting compile-time options. diff --git a/docs/en/api-guides/tools/idf-monitor.rst b/docs/en/api-guides/tools/idf-monitor.rst index c93b31f2f2..2a5022ef04 100644 --- a/docs/en/api-guides/tools/idf-monitor.rst +++ b/docs/en/api-guides/tools/idf-monitor.rst @@ -103,7 +103,13 @@ By default, if esp-idf crashes, the panic handler prints relevant registers and Optionally, the panic handler can be configured to run GDBStub, the tool which can communicate with GDB_ project debugger. GDBStub allows to read memory, examine call stack frames and variables, etc. It is not as versatile as JTAG debugging, but this method does not require any special hardware. -To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32_PANIC` to ``Invoke GDBStub``. +.. only:: esp32 + + To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32_PANIC` to ``Invoke GDBStub``. + +.. only:: esp32s2 + + To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32S2_PANIC` to ``Invoke GDBStub``. In this case, if the panic handler is triggered, as soon as IDF Monitor sees that GDBStub has loaded, it automatically pauses serial monitoring and runs GDB with necessary arguments. After GDB exits, the board is reset via the RTS serial line. If this line is not connected, please reset the board manually by pressing its Reset button. diff --git a/docs/en/api-guides/ulp.rst b/docs/en/api-guides/ulp.rst index ad2509e0ca..5de0e49f95 100644 --- a/docs/en/api-guides/ulp.rst +++ b/docs/en/api-guides/ulp.rst @@ -20,7 +20,9 @@ The ULP coprocessor code is written in assembly and compiled using the `binutils If you have already set up ESP-IDF with CMake build system according to the :doc:`Getting Started Guide <../../get-started/index>`, then the ULP toolchain will already be installed. -If you are using ESP-IDF with the legacy GNU Make based build system, refer to the instructions on this page: :doc:`ulp-legacy`. +.. only:: esp32 + + If you are using ESP-IDF with the legacy GNU Make based build system, refer to the instructions on this page: :doc:`ulp-legacy`. Compiling the ULP Code ----------------------- diff --git a/docs/en/api-reference/index.rst b/docs/en/api-reference/index.rst index 92e57f8cc8..6ee0b74e77 100644 --- a/docs/en/api-reference/index.rst +++ b/docs/en/api-reference/index.rst @@ -6,7 +6,7 @@ API Reference .. toctree:: :maxdepth: 2 - Bluetooth + :esp32: Bluetooth Networking Peripherals Protocols diff --git a/docs/en/api-reference/peripherals/can.rst b/docs/en/api-reference/peripherals/can.rst index 944ee4b127..d6d986722d 100644 --- a/docs/en/api-reference/peripherals/can.rst +++ b/docs/en/api-reference/peripherals/can.rst @@ -168,7 +168,11 @@ The operating bit rate of the CAN controller is configured using the :cpp:type:` 2. **Timing Segment 1** consists of 1 to 16 time quanta before sample point 3. **Timing Segment 2** consists of 1 to 8 time quanta after sample point -The **Baudrate Prescaler** is used to determine the period of each time quanta by dividing the CAN controller's source clock (80 MHz APB clock). The ``brp`` can be **any even number from 2 to 128**. If the ESP32 is a revision 2 or later chip, the ``brp`` will also support **any multiple of 4 from 132 to 256**, and can be enabled by setting the :ref:`CONFIG_ESP32_REV_MIN` to revision 2 or higher. +The **Baudrate Prescaler** is used to determine the period of each time quanta by dividing the CAN controller's source clock (80 MHz APB clock). The ``brp`` can be **any even number from 2 to 128**. + +.. only:: esp32 + + If the ESP32 is a revision 2 or later chip, the ``brp`` will also support **any multiple of 4 from 132 to 256**, and can be enabled by setting the :ref:`CONFIG_ESP32_REV_MIN` to revision 2 or higher. .. packetdiag:: ../../../_static/diagrams/can/can_bit_timing.diag :caption: Bit timing configuration for 500kbit/s given BRP = 8 diff --git a/docs/en/api-reference/protocols/index.rst b/docs/en/api-reference/protocols/index.rst index ded1cbbae1..2fe0218599 100644 --- a/docs/en/api-reference/protocols/index.rst +++ b/docs/en/api-reference/protocols/index.rst @@ -16,7 +16,7 @@ Application Protocols mDNS Modbus Websocket Client - ESP Serial Slave Link + :esp32: ESP Serial Slave Link Code examples for this API section are provided in the :example:`protocols` directory of ESP-IDF examples. diff --git a/docs/en/api-reference/system/inc/power_management_esp32.rst b/docs/en/api-reference/system/inc/power_management_esp32.rst new file mode 100644 index 0000000000..14177485eb --- /dev/null +++ b/docs/en/api-reference/system/inc/power_management_esp32.rst @@ -0,0 +1,40 @@ +ESP32 Power Management Algorithm +-------------------------------- + +The table below shows how CPU and APB frequencies will be switched if dynamic frequency scaling is enabled. You can specify the maximum CPU frequency with either :cpp:func:`esp_pm_configure` or :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ`. + + ++---------------+---------------------------------------+-------------------------------------+ +| Max CPU | Lock Acquisition | CPU and APB Frequncies | +| Frequency Set | | | ++---------------+---------------------------------------+-------------------------------------+ +| 240 | | Any of ``ESP_PM_CPU_FREQ_MAX`` | | +| | | or ``ESP_PM_APB_FREQ_MAX`` acquired | | CPU: 240 MHz | +| | | | APB: 80 MHz | ++ +---------------------------------------+-------------------------------------+ +| | None | Min values for both frequencies set | +| | | with :cpp:func:`esp_pm_configure` | ++---------------+---------------------------------------+-------------------------------------+ +| 160 | ``ESP_PM_CPU_FREQ_MAX`` acquired | | CPU: 160 MHz | +| | | | APB: 80 MHz | ++ +---------------------------------------+-------------------------------------+ +| | ``ESP_PM_CPU_FREQ_MAX`` acquired, | | CPU: 80 MHz | +| | ``ESP_PM_APB_FREQ_MAX`` not acquired | | APB: 80 MHz | ++ +---------------------------------------+-------------------------------------+ +| | None | Min values for both frequencies set | +| | | with :cpp:func:`esp_pm_configure` | ++---------------+---------------------------------------+-------------------------------------+ +| 80 | | Any of ``ESP_PM_CPU_FREQ_MAX`` | | CPU: 80 MHz | +| | | or ``ESP_PM_APB_FREQ_MAX`` acquired | | APB: 80 MHz | ++ +---------------------------------------+-------------------------------------+ +| | None | Min values for both frequencies set | +| | | with :cpp:func:`esp_pm_configure` | ++---------------+---------------------------------------+-------------------------------------+ + + +If none of the locks are acquired, and light sleep is enabled in a call to :cpp:func:`esp_pm_configure`, the system will go into light sleep mode. The duration of light sleep will be determined by: + +- FreeRTOS tasks blocked with finite timeouts +- Timers registered with :doc:`High resolution timer ` APIs + +Light sleep duration will be chosen to wake up the chip before the nearest event (task being unblocked, or timer elapses). diff --git a/docs/en/api-reference/system/power_management.rst b/docs/en/api-reference/system/power_management.rst index a6e35bd918..49acb39f8a 100644 --- a/docs/en/api-reference/system/power_management.rst +++ b/docs/en/api-reference/system/power_management.rst @@ -27,7 +27,7 @@ Enabling power management features comes at the cost of increased interrupt late Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in an application by calling the function :cpp:func:`esp_pm_configure`. Its argument is a structure defining the frequency scaling settings, :cpp:class:`esp_pm_config_esp32_t`. In this structure, three fields need to be initialized: -- ``max_freq_mhz``: Maximum CPU frequency in MHz, i.e., the frequency used when the ``ESP_PM_CPU_FREQ_MAX`` lock is acquired. This field will usually be set to :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ`. +- ``max_freq_mhz``: Maximum CPU frequency in MHz, i.e., the frequency used when the ``ESP_PM_CPU_FREQ_MAX`` lock is acquired. This field will usually be set to the default CPU frequency. - ``min_freq_mhz``: Minimum CPU frequency in MHz, i.e., the frequency used when only the ``ESP_PM_APB_FREQ_MAX`` lock is acquired. This field can be set to the XTAL frequency value, or the XTAL frequency divided by an integer. Note that 10 MHz is the lowest frequency at which the default REF_TICK clock of 1 MHz can be generated. - ``light_sleep_enable``: Whether the system should automatically enter light sleep when no locks are acquired (``true``/``false``). @@ -68,46 +68,9 @@ Lock Description ============================ ====================================================== -ESP32 Power Management Algorithm --------------------------------- +.. only:: esp32 -The table below shows how CPU and APB frequencies will be switched if dynamic frequency scaling is enabled. You can specify the maximum CPU frequency with either :cpp:func:`esp_pm_configure` or :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ`. - - -+---------------+---------------------------------------+-------------------------------------+ -| Max CPU | Lock Acquisition | CPU and APB Frequncies | -| Frequency Set | | | -+---------------+---------------------------------------+-------------------------------------+ -| 240 | | Any of ``ESP_PM_CPU_FREQ_MAX`` | | -| | | or ``ESP_PM_APB_FREQ_MAX`` acquired | | CPU: 240 MHz | -| | | | APB: 80 MHz | -+ +---------------------------------------+-------------------------------------+ -| | None | Min values for both frequencies set | -| | | with :cpp:func:`esp_pm_configure` | -+---------------+---------------------------------------+-------------------------------------+ -| 160 | ``ESP_PM_CPU_FREQ_MAX`` acquired | | CPU: 160 MHz | -| | | | APB: 80 MHz | -+ +---------------------------------------+-------------------------------------+ -| | ``ESP_PM_CPU_FREQ_MAX`` acquired, | | CPU: 80 MHz | -| | ``ESP_PM_APB_FREQ_MAX`` not acquired | | APB: 80 MHz | -+ +---------------------------------------+-------------------------------------+ -| | None | Min values for both frequencies set | -| | | with :cpp:func:`esp_pm_configure` | -+---------------+---------------------------------------+-------------------------------------+ -| 80 | | Any of ``ESP_PM_CPU_FREQ_MAX`` | | CPU: 80 MHz | -| | | or ``ESP_PM_APB_FREQ_MAX`` acquired | | APB: 80 MHz | -+ +---------------------------------------+-------------------------------------+ -| | None | Min values for both frequencies set | -| | | with :cpp:func:`esp_pm_configure` | -+---------------+---------------------------------------+-------------------------------------+ - - -If none of the locks are acquired, and light sleep is enabled in a call to :cpp:func:`esp_pm_configure`, the system will go into light sleep mode. The duration of light sleep will be determined by: - -- FreeRTOS tasks blocked with finite timeouts -- Timers registered with :doc:`High resolution timer ` APIs - -Light sleep duration will be chosen to wake up the chip before the nearest event (task being unblocked, or timer elapses). + .. include:: inc/power_management_esp32.rst Dynamic Frequency Scaling and Peripheral Drivers @@ -133,15 +96,26 @@ The following drivers will hold the ``ESP_PM_APB_FREQ_MAX`` lock while the drive - **SPI slave**: between calls to :cpp:func:`spi_slave_initialize` and :cpp:func:`spi_slave_free`. - **Ethernet**: between calls to :cpp:func:`esp_eth_driver_install` and :cpp:func:`esp_eth_driver_uninstall`. - **WiFi**: between calls to :cpp:func:`esp_wifi_start` and :cpp:func:`esp_wifi_stop`. If modem sleep is enabled, the lock will be released for the periods of time when radio is disabled. -- **Bluetooth**: between calls to :cpp:func:`esp_bt_controller_enable` and :cpp:func:`esp_bt_controller_disable`. If Bluetooth modem sleep is enabled, the ``ESP_PM_APB_FREQ_MAX`` lock will be released for the periods of time when radio is disabled. However the ``ESP_PM_NO_LIGHT_SLEEP`` lock will still be held, unless :ref:`CONFIG_BTDM_LOW_POWER_CLOCK` option is set to "External 32kHz crystal". - **CAN**: between calls to :cpp:func:`can_driver_install` and :cpp:func:`can_driver_uninstall`. +.. only:: esp32 + + - **Bluetooth**: between calls to :cpp:func:`esp_bt_controller_enable` and :cpp:func:`esp_bt_controller_disable`. If Bluetooth modem sleep is enabled, the ``ESP_PM_APB_FREQ_MAX`` lock will be released for the periods of time when radio is disabled. However the ``ESP_PM_NO_LIGHT_SLEEP`` lock will still be held, unless :ref:`CONFIG_BTDM_LOW_POWER_CLOCK` option is set to "External 32kHz crystal". + The following peripheral drivers are not aware of DFS yet. Applications need to acquire/release locks themselves, when necessary: -- MCPWM -- PCNT -- Sigma-delta -- Timer group +.. only:: esp32 + + - PCNT + - Sigma-delta + - Timer group + - MCPWM + +.. only:: esp32s2 + + - PCNT + - Sigma-delta + - Timer group API Reference diff --git a/docs/en/conf.py b/docs/en/conf.py index 0713b97f1d..68bcf87663 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -31,3 +31,6 @@ actdiag_fontpath = '../_static/DejaVuSans.ttf' nwdiag_fontpath = '../_static/DejaVuSans.ttf' rackdiag_fontpath = '../_static/DejaVuSans.ttf' packetdiag_fontpath = '../_static/DejaVuSans.ttf' + +update_exclude_patterns(tags) + diff --git a/docs/en/get-started/eclipse-setup.rst b/docs/en/get-started/eclipse-setup.rst index f6a4995617..0d9107be6d 100644 --- a/docs/en/get-started/eclipse-setup.rst +++ b/docs/en/get-started/eclipse-setup.rst @@ -7,4 +7,6 @@ ESP-IDF V4.0 has a new CMake-based build system as the default build system. There is a new ESP-IDF Eclipse Plugin that works with the CMake-based build system. Please refer to https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md for further instructions. -If you require Eclipse IDE support for legacy ESP_IDF Make build system, you can follow the :doc:`legacy GNU Make build system Getting Started guide ` which has steps for :doc:`Building and Flashing with Eclipse IDE `. +.. only:: esp32 + + If you require Eclipse IDE support for legacy ESP_IDF Make build system, you can follow the :doc:`legacy GNU Make build system Getting Started guide ` which has steps for :doc:`Building and Flashing with Eclipse IDE `. diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index cb346d6062..23f04922a8 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -515,7 +515,7 @@ Related Documents eclipse-setup ../api-guides/tools/idf-monitor toolchain-setup-scratch - ../get-started-legacy/index + :esp32: ../get-started-legacy/index .. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ .. _Releases page: https://github.com/espressif/esp-idf/releases diff --git a/docs/en/get-started/windows-setup.rst b/docs/en/get-started/windows-setup.rst index ccf983ae90..6593bde3be 100644 --- a/docs/en/get-started/windows-setup.rst +++ b/docs/en/get-started/windows-setup.rst @@ -16,8 +16,9 @@ ESP-IDF requires some prerequisite tools to be installed so you can build firmwa For this Getting Started we're going to use the Command Prompt, but after ESP-IDF is installed you can use :doc:`Eclipse ` or another graphical IDE with CMake support instead. -.. note:: - Previous versions of ESP-IDF used the :doc:`Legacy GNU Make Build System<../get-started-legacy/windows-setup>` and MSYS2_ Unix compatibility environment. This is no longer required, ESP-IDF can be used from the Windows Command Prompt. +.. only:: esp32 + .. note:: + Previous versions of ESP-IDF used the :doc:`Legacy GNU Make Build System<../get-started-legacy/windows-setup>` and MSYS2_ Unix compatibility environment. This is no longer required, ESP-IDF can be used from the Windows Command Prompt. .. _get-started-windows-tools-installer: diff --git a/docs/toctree_filter.py b/docs/toctree_filter.py new file mode 100644 index 0000000000..be58a8c0fc --- /dev/null +++ b/docs/toctree_filter.py @@ -0,0 +1,43 @@ +# Based on https://stackoverflow.com/a/46600038 with some modifications +import re +from sphinx.directives.other import TocTree +from sphinx.util.nodes import explicit_title_re +from sphinx.util import docname_join + +def setup(app): + app.add_directive('toctree', TocTreeFilt, override=True) + + +class TocTreeFilt(TocTree): + """ + Override normal toctree directive to support clauses of the kind + + :filter: Name + + Where the :filter: part becomes selective to only include the document if + one of the provided tags is set, same as the logic used by the "only" directive. + + If no :filter: is supplied, works the same as default Sphinx :toctree: + + Note that excluding via filter doesn't prevent Sphinx from finding these .rst files + when it scan the src/ directory, so it's also necessary to make sure that the files + are covered by the exclude_patterns list in conf.py + """ + RE_PATTERN = re.compile('^\s*:(.+):\s*(.+)$') + + + def run(self): + # Remove all TOC entries that should not be on display + env = self.state.document.settings.env + self.content = [ self.filter_entry(env, e) for e in self.content if e is not None ] + return super(TocTreeFilt, self).run() + + + def filter_entry(self, env, entry): + m = self.RE_PATTERN.match(entry) + if m is not None: + tag_filter, entry = m.groups() + if not env.app.builder.tags.eval_condition(tag_filter): + return None + return entry + diff --git a/docs/zh_CN/conf.py b/docs/zh_CN/conf.py index 0f7c85199f..49c89ee995 100644 --- a/docs/zh_CN/conf.py +++ b/docs/zh_CN/conf.py @@ -31,3 +31,6 @@ actdiag_fontpath = '../_static/NotoSansSC-Regular.otf' nwdiag_fontpath = '../_static/NotoSansSC-Regular.otf' rackdiag_fontpath = '../_static/NotoSansSC-Regular.otf' packetdiag_fontpath = '../_static/NotoSansSC-Regular.otf' + +update_exclude_patterns(tags) + From e753c1b50988d7ea0707e0af3db493e85bf3319e Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 22 Nov 2019 16:58:34 +1100 Subject: [PATCH 06/47] docs: Edit out some unnecessary instances of "ESP32" in the doc text --- docs/en/api-guides/build-system.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index a99fdbb0ff..758d7f08f4 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -16,7 +16,7 @@ Overview An ESP-IDF project can be seen as an amalgamation of a number of components. For example, for a webserver that shows the current humidity, there could be: -- The ESP32 base libraries (libc, ROM bindings, etc) +- The ESP-IDF base libraries (libc, ROM bindings, etc) - The WiFi drivers - A TCP/IP stack - The FreeRTOS operating system @@ -63,7 +63,7 @@ The ``idf.py`` command line tool provides a front-end for easily managing your p - CMake_, which configures the project to be built - A command line build tool (either Ninja_ build or `GNU Make`) -- `esptool.py`_ for flashing ESP32. +- `esptool.py`_ for flashing the target. The :ref:`getting started guide ` contains a brief introduction to how to set up ``idf.py`` to configure, build, and flash projects. @@ -82,10 +82,10 @@ Type ``idf.py --help`` for a list of commands. Here are a summary of the most us Building is incremental so if no source files or configuration has changed since the last build, nothing will be done. - ``idf.py clean`` will "clean" the project by deleting build output files from the build directory, forcing a "full rebuild" the next time the project is built. Cleaning doesn't delete CMake configuration output and some other files. - ``idf.py fullclean`` will delete the entire "build" directory contents. This includes all CMake configuration output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively deletes *all* files in the build directory, so use with care. Project configuration is not deleted. -- ``idf.py flash`` will automatically build the project if necessary, and then flash it to an ESP32. The ``-p`` and ``-b`` options can be used to set serial port name and flasher baud rate, respectively. -- ``idf.py monitor`` will display serial output from the ESP32. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor. See :doc:`tools/idf-monitor` for more details about using the monitor. +- ``idf.py flash`` will automatically build the project if necessary, and then flash it to the target. The ``-p`` and ``-b`` options can be used to set serial port name and flasher baud rate, respectively. +- ``idf.py monitor`` will display serial output from the target. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor. See :doc:`tools/idf-monitor` for more details about using the monitor. -Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the ESP32 before running the serial monitor. +Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the target before running the serial monitor. For commands that are not known to ``idf.py`` an attempt to execute them as a build system target will be made. @@ -97,8 +97,8 @@ Advanced Commands ^^^^^^^^^^^^^^^^^ - ``idf.py app``, ``idf.py bootloader``, ``idf.py partition_table`` can be used to build only the app, bootloader, or partition table from the project as applicable. -- There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the ESP32. -- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the ESP32's entire flash chip. +- There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the target. +- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the target's entire flash chip. - ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively. If you define variable ``-DOUTPUT_JSON=1`` when running CMake (or ``idf.py``), the output will be formatted as JSON not as human readable text. - ``idf.py reconfigure`` re-runs CMake_ even if it doesn't seem to need re-running. This isn't necessary during normal usage, but can be useful after adding/removing files from the source tree, or when modifying CMake cache variables. For example, ``idf.py -DNAME='VALUE' reconfigure`` can be used to set variable ``NAME`` in CMake cache to value ``VALUE``. From b0748b4364e802b45a030de3aba0d99713ac9683 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 26 Nov 2019 17:22:50 +1100 Subject: [PATCH 07/47] docs: Mark some more docs sections as ESP32 only --- docs/conf_common.py | 3 ++- docs/en/get-started/linux-setup-scratch.rst | 28 ++++++++++++++++++++- docs/en/get-started/linux-setup.rst | 2 +- docs/en/get-started/windows-setup.rst | 1 + 4 files changed, 31 insertions(+), 3 deletions(-) diff --git a/docs/conf_common.py b/docs/conf_common.py index ee80513fd2..c30c5e7a71 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -182,7 +182,8 @@ def update_exclude_patterns(tags): 'api-guides/ulp-legacy.rst', 'api-guides/unit-tests-legacy.rst', 'api-reference/bluetooth/**', - 'get-started-legacy/**']: + 'get-started-legacy/**', + 'gnu-make-legacy.rst']: exclude_patterns.append(e) # The reST default role (used for this markup: `text`) to use for all diff --git a/docs/en/get-started/linux-setup-scratch.rst b/docs/en/get-started/linux-setup-scratch.rst index d7f8c7d116..361b54499a 100644 --- a/docs/en/get-started/linux-setup-scratch.rst +++ b/docs/en/get-started/linux-setup-scratch.rst @@ -70,7 +70,33 @@ Build the toolchain:: ./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``. +Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. + +Add Toolchain to PATH +===================== + +The custom toolchain needs to be copied to a binary directory and added to the ``PATH``. + +Choose a directory, for example ``~/esp/xtensa-esp32-elf/``, and copy the build output to this 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="$HOME/esp/xtensa-esp32-elf/bin:$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``. + +Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set:: + + printenv PATH + +You are looking for similar result containing toolchain's path at the beginning of displayed string:: + + $ printenv PATH + /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 + +Instead of ``/home/user-name`` there should be a home path specific to your installation. Next Steps diff --git a/docs/en/get-started/linux-setup.rst b/docs/en/get-started/linux-setup.rst index eae5821b47..e647b79764 100644 --- a/docs/en/get-started/linux-setup.rst +++ b/docs/en/get-started/linux-setup.rst @@ -44,7 +44,7 @@ Related Documents .. toctree:: :maxdepth: 1 - linux-setup-scratch + :esp32: linux-setup-scratch .. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository diff --git a/docs/en/get-started/windows-setup.rst b/docs/en/get-started/windows-setup.rst index 6593bde3be..e617ddedb0 100644 --- a/docs/en/get-started/windows-setup.rst +++ b/docs/en/get-started/windows-setup.rst @@ -17,6 +17,7 @@ ESP-IDF requires some prerequisite tools to be installed so you can build firmwa For this Getting Started we're going to use the Command Prompt, but after ESP-IDF is installed you can use :doc:`Eclipse ` or another graphical IDE with CMake support instead. .. only:: esp32 + .. note:: Previous versions of ESP-IDF used the :doc:`Legacy GNU Make Build System<../get-started-legacy/windows-setup>` and MSYS2_ Unix compatibility environment. This is no longer required, ESP-IDF can be used from the Windows Command Prompt. From d1373119e1cc83b445229c64e8e265621397e511 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Thu, 28 Nov 2019 16:00:02 +1100 Subject: [PATCH 08/47] docs: Cleanup build warnings --- docs/Doxyfile | 1 + docs/en/api-reference/bluetooth/esp_hf_ag.rst | 9 +-------- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 823959f2a3..e62b4604ea 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -302,6 +302,7 @@ EXPAND_ONLY_PREDEF = YES PREDEFINED = \ $(ENV_DOXYGEN_DEFINES) \ __attribute__(x)= \ + _Static_assert(x, y) = \ IDF_DEPRECATED(X)= \ IRAM_ATTR= \ configSUPPORT_DYNAMIC_ALLOCATION=1 \ diff --git a/docs/en/api-reference/bluetooth/esp_hf_ag.rst b/docs/en/api-reference/bluetooth/esp_hf_ag.rst index 7cea249b34..a4dcfff36e 100644 --- a/docs/en/api-reference/bluetooth/esp_hf_ag.rst +++ b/docs/en/api-reference/bluetooth/esp_hf_ag.rst @@ -1,14 +1,7 @@ HFP AG API ============== -Overview --------- - -`Instructions`_ - -.. _Instructions: ../template.html - API Reference ------------- -.. include:: /_build/inc/esp_hf_ag_api.inc +.. include-build-file:: inc/esp_hf_ag_api.inc From cbede3a3a445b8a6e07b4a8639ce7f56e98871af Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Thu, 28 Nov 2019 16:00:24 +1100 Subject: [PATCH 09/47] docs: Try to enable parallel reads & writes Reads still single threaded in Sphinx 1.8.5, though. --- docs/build_docs.py | 1 + docs/doxygen_idf.py | 2 ++ docs/html_redirects.py | 2 ++ docs/idf_build_system/__init__.py | 2 ++ docs/include_build_file.py | 2 ++ docs/kconfig_reference.py | 2 ++ docs/link-roles.py | 2 ++ docs/toctree_filter.py | 1 + 8 files changed, 14 insertions(+) diff --git a/docs/build_docs.py b/docs/build_docs.py index dbcb7d638a..4e3932e39b 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -69,6 +69,7 @@ def build_docs(language, target, build_dir): environ['BUILDDIR'] = build_dir args = [sys.executable, "-m", "sphinx", + "-j", "auto", # use all the cores! (where possible) "-b", "html", # TODO: PDFs "-d", os.path.join(build_dir, "doctrees"), # TODO: support multiple sphinx-warning.log files, somehow diff --git a/docs/doxygen_idf.py b/docs/doxygen_idf.py index 4cb49b6dd3..af7fb633aa 100644 --- a/docs/doxygen_idf.py +++ b/docs/doxygen_idf.py @@ -12,6 +12,8 @@ def setup(app): # The idf_build_system extension will emit this event once it app.connect('idf-info', generate_doxygen) + return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' } + def _parse_defines(header_path): defines = {} diff --git a/docs/html_redirects.py b/docs/html_redirects.py index ec2811c33e..45a28cac37 100644 --- a/docs/html_redirects.py +++ b/docs/html_redirects.py @@ -45,6 +45,8 @@ def setup(app): # to create HTML redirects app.connect('html-collect-pages', create_redirect_pages) + return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' } + def create_redirect_pages(app): if not isinstance(app.builder, StandaloneHTMLBuilder): diff --git a/docs/idf_build_system/__init__.py b/docs/idf_build_system/__init__.py index b9e4b2db18..9f3e662ed0 100644 --- a/docs/idf_build_system/__init__.py +++ b/docs/idf_build_system/__init__.py @@ -26,6 +26,8 @@ def setup(app): # we want this to run early in the docs build but unclear exactly when app.connect('env-get-outdated', generate_idf_info) + return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' } + def generate_idf_info(app, env, added, changed, removed): print("Running CMake on dummy project to get build info...") build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep)) diff --git a/docs/include_build_file.py b/docs/include_build_file.py index 0eb153cc73..84bc296e1d 100644 --- a/docs/include_build_file.py +++ b/docs/include_build_file.py @@ -16,3 +16,5 @@ class IncludeBuildFile(BaseInclude, SphinxDirective): def setup(app): directives.register_directive('include-build-file', IncludeBuildFile) + + return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' } diff --git a/docs/kconfig_reference.py b/docs/kconfig_reference.py index 7cf5a41fde..7137093e56 100644 --- a/docs/kconfig_reference.py +++ b/docs/kconfig_reference.py @@ -10,6 +10,8 @@ def setup(app): # has parsed the IDF project's information app.connect('idf-info', generate_reference) + return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' } + def generate_reference(app, project_description): build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep)) diff --git a/docs/link-roles.py b/docs/link-roles.py index e97eb2e6e9..2c748500d5 100644 --- a/docs/link-roles.py +++ b/docs/link-roles.py @@ -46,6 +46,8 @@ def setup(app): app.add_role('link_to_translation', crosslink('%s../../%s/{}/%s.html'.format(tag_rev))) + return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' } + def autolink(pattern): def role(name, rawtext, text, lineno, inliner, options={}, content=[]): diff --git a/docs/toctree_filter.py b/docs/toctree_filter.py index be58a8c0fc..7082fad7b3 100644 --- a/docs/toctree_filter.py +++ b/docs/toctree_filter.py @@ -7,6 +7,7 @@ from sphinx.util import docname_join def setup(app): app.add_directive('toctree', TocTreeFilt, override=True) + return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' } class TocTreeFilt(TocTree): """ From a148d8e6bad0cb44c0684ac282009bbb7cb1e14d Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 29 Nov 2019 08:56:53 +1100 Subject: [PATCH 10/47] docs: Refactor extensions into packages, update the add-ons-reference docs page Includes converting some of the remaining standalone scripts into Sphinx extensions. Make flake8 clean --- docs/Doxyfile | 2 +- docs/build_docs.py | 9 +- docs/conf_common.py | 104 +++----- docs/doxygen_idf.py | 78 ------ docs/en/api-guides/external-ram.rst | 1 + docs/en/api-guides/tools/idf-tools.rst | 2 +- docs/en/conf.py | 5 +- docs/en/contribute/add-ons-reference.rst | 132 ++++++++-- docs/extensions/README.md | 1 + docs/extensions/__init__.py | 0 docs/{ => extensions}/html_redirects.py | 4 +- docs/{ => extensions}/toctree_filter.py | 13 +- docs/idf_extensions/README.md | 2 + docs/idf_extensions/__init__.py | 0 .../build_system}/CMakeLists.txt | 0 .../build_system}/__init__.py | 43 +++- docs/idf_extensions/esp_err_definitions.py | 14 ++ docs/idf_extensions/gen_idf_tools_links.py | 19 ++ .../gen_toolchain_links.py} | 49 ++-- .../gen_version_specific_includes.py} | 33 ++- .../include_build_file.py | 10 +- .../{ => idf_extensions}/kconfig_reference.py | 12 +- .../link_roles.py} | 19 +- .../run_doxygen.py} | 227 ++++++------------ .../{local_util.py => idf_extensions/util.py} | 5 +- docs/requirements.txt | 2 +- docs/zh_CN/conf.py | 5 +- tools/check_python_dependencies.py | 3 + 28 files changed, 360 insertions(+), 434 deletions(-) delete mode 100644 docs/doxygen_idf.py create mode 100644 docs/extensions/README.md create mode 100644 docs/extensions/__init__.py rename docs/{ => extensions}/html_redirects.py (94%) rename docs/{ => extensions}/toctree_filter.py (79%) create mode 100644 docs/idf_extensions/README.md create mode 100644 docs/idf_extensions/__init__.py rename docs/{idf_build_system => idf_extensions/build_system}/CMakeLists.txt (100%) rename docs/{idf_build_system => idf_extensions/build_system}/__init__.py (60%) create mode 100644 docs/idf_extensions/esp_err_definitions.py create mode 100644 docs/idf_extensions/gen_idf_tools_links.py rename docs/{gen-toolchain-links.py => idf_extensions/gen_toolchain_links.py} (67%) rename docs/{gen-version-specific-includes.py => idf_extensions/gen_version_specific_includes.py} (89%) rename docs/{ => idf_extensions}/include_build_file.py (70%) rename docs/{ => idf_extensions}/kconfig_reference.py (94%) rename docs/{link-roles.py => idf_extensions/link_roles.py} (82%) rename docs/{gen-dxd.py => idf_extensions/run_doxygen.py} (66%) mode change 100755 => 100644 rename docs/{local_util.py => idf_extensions/util.py} (97%) diff --git a/docs/Doxyfile b/docs/Doxyfile index e62b4604ea..3975405111 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -302,7 +302,7 @@ EXPAND_ONLY_PREDEF = YES PREDEFINED = \ $(ENV_DOXYGEN_DEFINES) \ __attribute__(x)= \ - _Static_assert(x, y) = \ + _Static_assert(x) = \ IDF_DEPRECATED(X)= \ IRAM_ATTR= \ configSUPPORT_DYNAMIC_ALLOCATION=1 \ diff --git a/docs/build_docs.py b/docs/build_docs.py index 4e3932e39b..be354fa4c3 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -17,6 +17,7 @@ import sys LANGUAGES = ["en", "zh_CN"] TARGETS = ["esp32", "esp32s2"] + def main(): # check Python dependencies for docs try: @@ -43,13 +44,13 @@ def main(): print("Building all languages") languages = LANGUAGES else: - languages = [ args.language ] + languages = [args.language] if args.target is None: print("Building all targets") targets = TARGETS else: - targets = [ args.target ] + targets = [args.target] for language in languages: for target in targets: @@ -76,9 +77,9 @@ def build_docs(language, target, build_dir): "-w", "sphinx-warning.log", "-t", target, "-D", "idf_target={}".format(target), - os.path.join(os.path.abspath(os.path.dirname(__file__)), language), # srcdir for this language + os.path.join(os.path.abspath(os.path.dirname(__file__)), language), # srcdir for this language os.path.join(build_dir, "html") # build directory - ] + ] cwd = build_dir # also run sphinx in the build directory print("Running '{}'".format(" ".join(args))) subprocess.check_call(args, cwd=cwd, env=environ) diff --git a/docs/conf_common.py b/docs/conf_common.py index c30c5e7a71..2deb903a93 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -18,65 +18,13 @@ from __future__ import print_function from __future__ import unicode_literals import sys import os +import os.path import re import subprocess -# Note: If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute - -from local_util import run_cmd_get_output, copy_if_modified, call_with_python - # build_docs on the CI server sometimes fails under Python3. This is a workaround: sys.setrecursionlimit(3500) -try: - build_dir = os.environ['BUILDDIR'] -except KeyError: - build_dir = '_build' - -build_dir = os.path.abspath(build_dir) - -# Fill in a default IDF_PATH if it's missing (ie when Read The Docs is building the docs) -try: - idf_path = os.environ['IDF_PATH'] -except KeyError: - idf_path = os.path.realpath(os.path.join(os.path.dirname(__file__), '..')) - -docs_root = os.path.join(idf_path, "docs") - -try: - os.mkdir(build_dir) -except OSError: - pass - -try: - os.mkdir(os.path.join(build_dir, 'inc')) -except OSError: - pass - -# Generate version-related includes -# -# (Note: this is in a function as it needs to access configuration to get the language) -def generate_version_specific_includes(app): - print("Generating version-specific includes...") - version_tmpdir = '{}/version_inc'.format(build_dir) - call_with_python('{}/gen-version-specific-includes.py {} {}'.format(docs_root, app.config.language, version_tmpdir)) - copy_if_modified(version_tmpdir, '{}/inc'.format(build_dir)) - -# Generate toolchain download links -print("Generating toolchain download links") -base_url = 'https://dl.espressif.com/dl/' -toolchain_tmpdir = '{}/toolchain_inc'.format(build_dir) -call_with_python('{}/gen-toolchain-links.py ../../tools/toolchain_versions.mk {} {}'.format(docs_root, base_url, toolchain_tmpdir)) -copy_if_modified(toolchain_tmpdir, '{}/inc'.format(build_dir)) - -print("Generating IDF Tools list") -os.environ["IDF_MAINTAINER"] = "1" -tools_rst = os.path.join(builddir, 'idf-tools-inc.rst') -tools_rst_tmp = os.path.join(builddir, 'inc', 'idf-tools-inc.rst') -call_with_python("{}/tools/idf_tools.py gen-doc --output {}".format(idf_path, tools_rst_tmp)) -copy_if_modified(tools_rst_tmp, tools_rst) # http://stackoverflow.com/questions/12772927/specifying-an-online-image-in-sphinx-restructuredtext-format # @@ -84,7 +32,6 @@ suppress_warnings = ['image.nonlocal_uri'] # -- General configuration ------------------------------------------------ - # If your documentation needs a minimal Sphinx version, state it here. # needs_sphinx = '1.0' @@ -92,24 +39,33 @@ suppress_warnings = ['image.nonlocal_uri'] # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = ['breathe', - 'link-roles', + + 'sphinx.ext.todo', + 'sphinxcontrib.blockdiag', 'sphinxcontrib.seqdiag', 'sphinxcontrib.actdiag', 'sphinxcontrib.nwdiag', 'sphinxcontrib.rackdiag', 'sphinxcontrib.packetdiag', - 'html_redirects', - 'idf_build_system', - 'kconfig_reference', - 'doxygen_idf', - 'sphinx.ext.todo', - 'include_build_file', - 'toctree_filter', + + 'extensions.html_redirects', + 'extensions.toctree_filter', + + 'idf_extensions.include_build_file', + 'idf_extensions.link_roles', + 'idf_extensions.build_system', + 'idf_extensions.esp_err_definitions', + 'idf_extensions.gen_toolchain_links', + 'idf_extensions.gen_version_specific_includes', + 'idf_extensions.kconfig_reference', + 'idf_extensions.run_doxygen', + 'idf_extensions.gen_idf_tools_links', + # from https://github.com/pfalcon/sphinx_selective_exclude 'sphinx_selective_exclude.eager_only', - #'sphinx_selective_exclude.search_auto_exclude', - #'sphinx_selective_exclude.modindex_exclude', + # TODO: determine if we need search_auto_exclude + # 'sphinx_selective_exclude.search_auto_exclude', ] # sphinx.ext.todo extension parameters @@ -120,13 +76,6 @@ todo_include_todos = False # Enabling this fixes cropping of blockdiag edge labels seqdiag_antialias = True -# Breathe extension variables - -# 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": os.path.join(build_dir, "xml_in/")} -breathe_default_project = "esp32-idf" # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -155,7 +104,7 @@ master_doc = 'index' # This is supposed to be "the short X.Y version", but it's the only version # visible when you open index.html. # Display full version to make things less confusing. -version = run_cmd_get_output('git describe') +version = subprocess.check_output(['git', 'describe']).strip() # The full version, including alpha/beta/rc tags. # If needed, nearest tag is returned by 'git describe --abbrev=0'. release = version @@ -171,7 +120,8 @@ print('Version: {0} Release: {1}'.format(version, release)) # directories to ignore when looking for source files. exclude_patterns = ['**/inc/**'] -# Add target-specific excludes based on tags. Haven't found any better way to do this yet + +# Add target-specific excludes based on tags (for the IDF_TARGET). Haven't found any better way to do this yet def update_exclude_patterns(tags): if "esp32" not in tags: # Exclude ESP32-only document pages so they aren't found in the initial search for .rst files @@ -186,6 +136,7 @@ def update_exclude_patterns(tags): 'gnu-make-legacy.rst']: exclude_patterns.append(e) + # The reST default role (used for this markup: `text`) to use for all # documents. # default_role = None @@ -389,6 +340,9 @@ texinfo_documents = [ # Override RTD CSS theme to introduce the theme corrections # https://github.com/rtfd/sphinx_rtd_theme/pull/432 def setup(app): - app.config.build_dir = build_dir app.add_stylesheet('theme_overrides.css') - generate_version_specific_includes(app) + + # Breathe extension variables (depend on build_dir) + # note: we generate into xml_in and then copy_if_modified to xml dir + app.config.breathe_projects = {"esp32-idf": os.path.join(app.config.build_dir, "xml_in/")} + app.config.breathe_default_project = "esp32-idf" diff --git a/docs/doxygen_idf.py b/docs/doxygen_idf.py deleted file mode 100644 index af7fb633aa..0000000000 --- a/docs/doxygen_idf.py +++ /dev/null @@ -1,78 +0,0 @@ -# Extension to generate Doxygen XML include files, with IDF config & soc macros included -import glob -import os.path -import re -import sys -import subprocess -gen_dxd = __import__("gen-dxd") - -from local_util import copy_if_modified, call_with_python - -def setup(app): - # The idf_build_system extension will emit this event once it - app.connect('idf-info', generate_doxygen) - - return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' } - - -def _parse_defines(header_path): - defines = {} - # Note: we run C preprocessor here without any -I arguments, so assumption is - # that these headers are all self-contained and don't include any other headers - # not in the same directory - print("Reading macros from %s..." % (header_path)) - processed_output = subprocess.check_output(["xtensa-esp32-elf-gcc", "-dM", "-E", header_path]).decode() - for line in processed_output.split("\n"): - line = line.strip() - m = re.search("#define ([^ ]+) ?(.*)", line) - if m and not m.group(1).startswith("_"): - defines[m.group(1)] = m.group(2) - - return defines - - -def generate_doxygen(app, project_description): - build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep)) - - # Parse kconfig macros to pass into doxygen - # - # TODO: this should use the set of "config which can't be changed" eventually, - # not the header - defines = _parse_defines(os.path.join(project_description["build_dir"], - "config", "sdkconfig.h")) - - # Add all SOC _caps.h headers to the defines - # - # kind of a hack, be nicer to add a component info dict in project_description.json - soc_path = [p for p in project_description["build_component_paths"] if p.endswith("/soc")][0] - for soc_header in glob.glob(os.path.join(soc_path, project_description["target"], - "include", "soc", "*_caps.h")): - defines.update(_parse_defines(soc_header)) - - # Call Doxygen to get XML files from the header files - print("Calling Doxygen to generate latest XML files") - doxy_env = { - "ENV_DOXYGEN_DEFINES": " ".join(defines), - "IDF_PATH": app.config.idf_path, - } - doxyfile = os.path.join(app.config.docs_root, "Doxyfile") - # note: run Doxygen in the build directory, so the xml & xml_in files end up in there - subprocess.check_call(["doxygen", doxyfile], env=doxy_env, cwd=build_dir) - - # Doxygen has generated XML files in 'xml' directory. - # Copy them to 'xml_in', only touching the files which have changed. - copy_if_modified(os.path.join(build_dir, 'xml/'), os.path.join(build_dir, 'xml_in/')) - - # Generate 'api_name.inc' files using the XML files by Doxygen - gen_dxd.builddir = build_dir - gen_dxd.doxyfile_path = doxyfile - gen_dxd.header_file_path_prefix = "components/" - gen_dxd.xml_directory_path = "{}/xml".format(build_dir) - gen_dxd.inc_directory_path = "{}/inc".format(build_dir) - gen_dxd.generate_api_inc_files() - - # Generate 'esp_err_defs.inc' file with ESP_ERR_ error code definitions from inc file - esp_err_inc_path = '{}/inc/esp_err_defs.inc'.format(build_dir) - call_with_python('{}/tools/gen_esp_err_to_name.py --rst_output {}.in'.format(app.config.idf_path, esp_err_inc_path)) - copy_if_modified(esp_err_inc_path + '.in', esp_err_inc_path) - diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index 6aa14019a6..8fa7569c9f 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -122,6 +122,7 @@ External RAM use has the following restrictions: * External RAM cannot be used as task stack memory. Due to this, :cpp:func:`xTaskCreate` and similar functions will always allocate internal memory for stack and task TCBs, and functions such as :cpp:func:`xTaskCreateStatic` will check if the buffers passed are internal. * By default, failure to initialize external RAM will cause the ESP-IDF startup to abort. This can be disabled by enabling the config item :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND`. If :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` is enabled, the option to ignore failure is not available as the linker will have assigned symbols to external memory addresses at link time. + .. only:: esp32 .. include:: inc/external-ram-esp32-notes.inc diff --git a/docs/en/api-guides/tools/idf-tools.rst b/docs/en/api-guides/tools/idf-tools.rst index 628364f452..6ea511a3ff 100644 --- a/docs/en/api-guides/tools/idf-tools.rst +++ b/docs/en/api-guides/tools/idf-tools.rst @@ -138,4 +138,4 @@ Although the methods above are recommended for ESP-IDF users, they are not a mus List of IDF Tools ----------------- -.. include:: /_build/inc/idf-tools-inc.rst +.. include-build-file:: idf-tools-inc.rst diff --git a/docs/en/conf.py b/docs/en/conf.py index 68bcf87663..ec996f62f2 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -10,7 +10,7 @@ import sys import os sys.path.insert(0, os.path.abspath('..')) from conf_common import * # noqa: F401, F403 - need to make available everything from common -from local_util import download_file_if_missing # noqa: E402 - need to import from common folder +from idf_extensions.util import download_file_if_missing # noqa: E402 - need to import from common folder # General information about the project. project = u'ESP-IDF Programming Guide' @@ -32,5 +32,4 @@ nwdiag_fontpath = '../_static/DejaVuSans.ttf' rackdiag_fontpath = '../_static/DejaVuSans.ttf' packetdiag_fontpath = '../_static/DejaVuSans.ttf' -update_exclude_patterns(tags) - +update_exclude_patterns(tags) # noqa: F405, need to import * from conf_common diff --git a/docs/en/contribute/add-ons-reference.rst b/docs/en/contribute/add-ons-reference.rst index b1942b46e7..30fedb8ede 100644 --- a/docs/en/contribute/add-ons-reference.rst +++ b/docs/en/contribute/add-ons-reference.rst @@ -5,6 +5,8 @@ This documentation is created using `Sphinx `_ appli Besides Sphinx there are several other applications that help to provide nicely formatted and easy to navigate documentation. These applications are listed in section :ref:`setup-for-building-documentation` with the installed version numbers provided in file :idf_file:`docs/requirements.txt`. +We build ESP-IDF documentation for two languages (English, Simplified Chinese) and for multiple chips. Therefore we don't run ``sphinx`` directly, there is a wrapper Python program ``build_docs.py`` that runs Sphinx. + On top of that we have created a couple of custom add-ons and extensions to help integrate documentation with underlining `ESP-IDF`_ repository and further improve navigation as well as maintenance of documentation. The purpose of this section is to provide a quick reference to the add-ons and the extensions. @@ -17,48 +19,43 @@ Documentation Folder Structure * The ``docs`` folder contains localized documentation in :idf:`docs/en` (English) and :idf:`docs/zh_CN` (simplified Chinese) subfolders. * Graphics files and fonts common to localized documentation are contained in :idf:`docs/_static` subfolder * Remaining files in the root of ``docs`` as well as ``docs/en`` and ``docs/zh_CN`` provide configuration and scripts used to automate documentation processing including the add-ons and extensions. -* Several folders and files are generated dynamically during documentations build and placed primarily in ``docs/[lang]/_build`` folders. These folders are temporary and not visible in `ESP-IDF`_ repository, +* Sphinx extensions are provided in two directories, ``extensions`` and ``idf_extensions`` +* A ``_build`` directory is created in the ``docs`` folder by ``build_docs.py``. This directory is not added to the `ESP-IDF`_ repository. Add-ons and Extensions Reference -------------------------------- +Config Files +^^^^^^^^^^^^ + :idf_file:`docs/conf_common.py` This file contains configuration common to each localized documentation (e.g. English, Chinese). The contents of this file is imported to standard Sphinx configuration file ``conf.py`` located in respective language folders (e.g. ``docs/en``, ``docs/zh_CN``) during build for each language. -:idf_file:`docs/check_doc_warnings.sh` - If there are any warnings reported during documentation build, then the build is failed. The warnings should be resolved before merging any documentation updates. This script is doing check for warnings in respective log file to fail the build. See also description of ``sphinx-known-warnings.txt`` below. +:idf_file:`docs/sphinx-known-warnings.txt` + There are couple of spurious Sphinx warnings that cannot be resolved without doing update to the Sphinx source code itself. For such specific cases respective warnings are documented in ``sphinx-known-warnings.txt`` file, that is checked during documentation build, to ignore the spurious warnings. + + +Scripts +^^^^^^^ + +:idf_file:`docs/build_docs.py` + + Top-level executable program which runs a Sphinx build for one or more language/target combinations. Run ``build_docs.py --help`` for full command line options. + + When ``build_docs.py`` runs Sphinx it sets the ``idf_target`` configuration variable, sets a Sphinx tag with the same name as the configuration variable, and uses some environment variables to communicate paths to :ref:`IDF-Specific Extensions`. :idf_file:`docs/check_lang_folder_sync.sh` To reduce potential discrepancies when maintaining concurrent language version, the structure and filenames of language folders ``docs/en`` and ``docs/zh_CN`` folders should be kept identical. The script ``check_lang_folder_sync.sh`` is run on each documentation build to verify if this condition is met. - .. note:: +.. note:: If a new content is provided in e.g. English, and there is no any translation yet, then the corresponding file in ``zh_CN`` folder should contain an ``.. include::`` directive pointing to the source file in English. This will automatically include the English version visible to Chinese readers. For example if a file ``docs/zh_CN/contribute/documenting-code.rst`` does not have a Chinese translation, then it should contain ``.. include:: ../../en/contribute/documenting-code.rst`` instead. -:idf_file:`docs/docs_common.mk` - It contains the common code which is included into the language-specific ``Makefiles``. Note that this file contains couple of customizations comparing to what is provided within standard Sphinx installation, e.g. ``gh-linkcheck`` command has been added. +Non-Docs Scripts +^^^^^^^^^^^^^^^^ -:idf_file:`docs/gen-dxd.py` - A Python script that generates API reference files based on Doxygen ``xml`` output. The files have an ``inc`` extension and are located in ``docs/[lang]/_build/inc`` directory created dynamically when documentation is build. Please refer to :doc:`documenting-code` and :doc:`../api-reference/template`, section **API Reference** for additional details on this process. - -:idf_file:`docs/gen-toolchain-links.py` - There couple of places in documentation that provide links to download the toolchain. To provide one source of this information and reduce effort to manually update several files, this script generates toolchain download links and toolchain unpacking code snippets based on information found in :idf_file:`tools/toolchain_versions.mk`. - -:idf_file:`docs/gen-version-specific-includes.py` - Another Python script to automatically generate reStructuredText Text ``.inc`` snippets with version-based content for this ESP-IDF version. - -:idf_file:`docs/html_redirects.py` - During documentation lifetime some source files are moved between folders or renamed. This Python script is adding a mechanism to redirect documentation pages that have changed URL by generating in the Sphinx output static HTML redirect pages. The script is used together with a redirection list ``html_redirect_pages`` defined in file :idf_file:`docs/conf_common.py`. - -:idf_file:`docs/link-roles.py` - This is an implementation of a custom `Sphinx Roles `_ to help linking from documentation to specific files and folders in `ESP-IDF`_. For description of implemented roles please see :ref:`link-custom-roles` and :ref:`link-language-versions`. - -:idf_file:`docs/local_util.py` - A collection of utility functions useful primarily when building documentation locally (see :ref:`setup-for-building-documentation`) to reduce the time to generate documentation on a second and subsequent builds. The utility functions check what Doxygen ``xml`` input files have been changed and copy these files to destination folders, so only the changed files are used during build process. - -:idf_file:`docs/sphinx-known-warnings.txt` - There are couple of spurious Sphinx warnings that cannot be resolved without doing update to the Sphinx source code itself. For such specific cases respective warnings are documented in ``sphinx-known-warnings.txt`` file, that is checked during documentation build, to ignore the spurious warnings. +These scripts are used to build docs but also used for other purposes: :idf_file:`tools/gen_esp_err_to_name.py` This script is traversing the `ESP-IDF`_ directory structure looking for error codes and messages in source code header files to generate an ``.inc`` file to include in documentation under :doc:`../api-reference/error-codes`. @@ -66,7 +63,89 @@ Add-ons and Extensions Reference :idf_file:`tools/kconfig_new/confgen.py` Options to configure ESP-IDF's :idf:`components` are contained in ``Kconfig`` files located inside directories of individual components, e.g. :idf_file:`components/bt/Kconfig`. This script is traversing the ``component`` directories to collect configuration options and generate an ``.inc`` file to include in documentation under :ref:`configuration-options-reference`. +Generic Extensions +^^^^^^^^^^^^^^^^^^ +These are Sphinx extensions developed for IDF that don't rely on any IDF-docs-specific behaviour or configuration: + +:idf_file:`docs/extensions/toctree_filter.py` + Sphinx extensions overrides the ``:toctree:`` directive to allow filtering entries based on whether a tag is set, as ``:tagname: toctree_entry``. See the Python file for a more complete description. + +:idf_file:`docs/extensions/html_redirects.py` + During documentation lifetime some source files are moved between folders or renamed. This Sphinx extension adds a mechanism to redirect documentation pages that have changed URL by generating in the Sphinx output static HTML redirect pages. The script is used together with a redirection list ``html_redirect_pages``. ``conf_common.py`` builds this list from :idf_file:`docs/page_redirects.txt` + + +Third Party Extensions +^^^^^^^^^^^^^^^^^^^^^^ + +- ``sphinxcontrib`` extensions for blockdiag, seqdiag, actdiag, nwdiag, rackdiag & packetdiag diagrams. +- `Sphinx selective exclude`_ ``eager_only`` extension + +.. _idf-specific extensions: + +IDF-Specific Extensions +^^^^^^^^^^^^^^^^^^^^^^^ + +Build System Integration +######################## + +:idf:`docs/idf_extensions/build_system/` + +Python package implementing a Sphinx extension to pull IDF build system information into the docs build + +* Creates a dummy CMake IDF project and runs CMake to generate metadata +* Registers some new configuration variables and emits a new Sphinx event, both for use by other extensions. + +Configuration Variables +@@@@@@@@@@@@@@@@@@@@@@@ + +* ``docs_root`` - The absolute path of the $IDF_PATH/docs directory +* ``idf_path`` - The value of IDF_PATH variable, or the absolute path of IDF_PATH if environment unset +* ``build_dir`` - The build directory passed in by ``build_docs.py``, default will be like ``_build//`` +* ``idf_target`` - The IDF_TARGET value. Expected that ``build_docs.py`` set this on the Sphinx command line + +New Event +@@@@@@@@@ + +``idf-info`` event is emitted early in the build, after the dummy project CMake run is complete. + +Arguments are ``(app, project_description)`` where ``project_description`` is a dict containing the values parsed from ``project_description.json`` in the CMake build directory. + +Other IDF-specific extensions subscribe to this event and use it to set up some docs parameters based on build system info. + +Other Extensions +################ + +:idf_file:`docs/idf_extensions/include_build_file.py` + The ``include-build-file`` directive is like the built-in ``include-file`` directive, but file path is evaluated relative to ``build_dir``. + + +:idf_file:`docs/idf_extensions/kconfig_reference.py` + Subscribes to ``idf-info`` event and uses confgen to generate ``kconfig.inc`` from the components included in the default project build. This file is then included into :doc:`/api-reference/kconfig`. + +:idf_file:`docs/idf_extensions/link_roles.py` + This is an implementation of a custom `Sphinx Roles `_ to help linking from documentation to specific files and folders in `ESP-IDF`_. For description of implemented roles please see :ref:`link-custom-roles` and :ref:`link-language-versions`. + +:idf_file:`docs/idf_extensions/run_doxygen.py` + Subscribes to ``idf-info`` event and runs Doxygen (:idf_file:`docs/Doxyfile`) to generate XML files describing key headers, and then runs Breathe to convert these to ``.inc`` files which can be included directly into API reference pages. + + Pushes a number of target-specific custom environment variables into Doxygen, including all macros defined in the project's default ``sdkconfig.h`` file and all macros defined in all ``soc`` component ``xxx_caps.h`` headers. This means that public API headers can depend on target-specific configuration options or ``soc`` capabilities headers options as ``#ifdef`` & ``#if`` preprocessor selections in the header. + + This means we can generate different Doxygen files, depending on the target we are building docs for. + + Please refer to :doc:`documenting-code` and :doc:`../api-reference/template`, section **API Reference** for additional details on this process. + +:idf_file:`docs/idf_extensions/esp_err_definitions.py` + Small wrapper extension that calls ``gen_esp_err_to_name.py`` and updates the included .rst file if it has changed. + +:idf_file:`docs/idf_extensions/gen_toolchain_links.py` + There couple of places in documentation that provide links to download the toolchain. To provide one source of this information and reduce effort to manually update several files, this script generates toolchain download links and toolchain unpacking code snippets based on information found in :idf_file:`tools/toolchain_versions.mk`. + +:idf_file:`docs/idf_extensions/gen_version_specific_includes.py` + Another extension to automatically generate reStructuredText Text ``.inc`` snippets with version-based content for this ESP-IDF version. + +:idf_file:`docs/idf_extensions/util.py` + A collection of utility functions useful primarily when building documentation locally (see :ref:`setup-for-building-documentation`) to reduce the time to generate documentation on a second and subsequent builds. Related Documents ----------------- @@ -75,3 +154,4 @@ Related Documents .. _ESP-IDF: https://github.com/espressif/esp-idf/ +.. _Sphinx selective exclude: https://github.com/pfalcon/sphinx_selective_exclude diff --git a/docs/extensions/README.md b/docs/extensions/README.md new file mode 100644 index 0000000000..e32b49af06 --- /dev/null +++ b/docs/extensions/README.md @@ -0,0 +1 @@ +See docs/en/contribute/add-ons-reference.rst (or in the IDF docs) for details. diff --git a/docs/extensions/__init__.py b/docs/extensions/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/html_redirects.py b/docs/extensions/html_redirects.py similarity index 94% rename from docs/html_redirects.py rename to docs/extensions/html_redirects.py index 45a28cac37..5019e84a61 100644 --- a/docs/html_redirects.py +++ b/docs/extensions/html_redirects.py @@ -17,7 +17,7 @@ # Mechanism to generate static HTML redirect pages in the output # # Uses redirect_template.html and the list of pages given in -# conf.html_redirect_pages +# the file conf.html_redirect_pages # # Adapted from ideas in https://tech.signavio.com/2017/managing-sphinx-redirects import os.path @@ -45,7 +45,7 @@ def setup(app): # to create HTML redirects app.connect('html-collect-pages', create_redirect_pages) - return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' } + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} def create_redirect_pages(app): diff --git a/docs/toctree_filter.py b/docs/extensions/toctree_filter.py similarity index 79% rename from docs/toctree_filter.py rename to docs/extensions/toctree_filter.py index 7082fad7b3..2f537a5fea 100644 --- a/docs/toctree_filter.py +++ b/docs/extensions/toctree_filter.py @@ -1,13 +1,13 @@ # Based on https://stackoverflow.com/a/46600038 with some modifications import re from sphinx.directives.other import TocTree -from sphinx.util.nodes import explicit_title_re -from sphinx.util import docname_join + def setup(app): app.add_directive('toctree', TocTreeFilt, override=True) - return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' } + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} + class TocTreeFilt(TocTree): """ @@ -24,16 +24,14 @@ class TocTreeFilt(TocTree): when it scan the src/ directory, so it's also necessary to make sure that the files are covered by the exclude_patterns list in conf.py """ - RE_PATTERN = re.compile('^\s*:(.+):\s*(.+)$') - + RE_PATTERN = re.compile(r'^\s*:(.+):\s*(.+)$') def run(self): # Remove all TOC entries that should not be on display env = self.state.document.settings.env - self.content = [ self.filter_entry(env, e) for e in self.content if e is not None ] + self.content = [self.filter_entry(env, e) for e in self.content if e is not None] return super(TocTreeFilt, self).run() - def filter_entry(self, env, entry): m = self.RE_PATTERN.match(entry) if m is not None: @@ -41,4 +39,3 @@ class TocTreeFilt(TocTree): if not env.app.builder.tags.eval_condition(tag_filter): return None return entry - diff --git a/docs/idf_extensions/README.md b/docs/idf_extensions/README.md new file mode 100644 index 0000000000..0d7cb9d910 --- /dev/null +++ b/docs/idf_extensions/README.md @@ -0,0 +1,2 @@ +See docs/en/contribute/add-ons-reference.rst (or in the IDF docs) for details. + diff --git a/docs/idf_extensions/__init__.py b/docs/idf_extensions/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/idf_build_system/CMakeLists.txt b/docs/idf_extensions/build_system/CMakeLists.txt similarity index 100% rename from docs/idf_build_system/CMakeLists.txt rename to docs/idf_extensions/build_system/CMakeLists.txt diff --git a/docs/idf_build_system/__init__.py b/docs/idf_extensions/build_system/__init__.py similarity index 60% rename from docs/idf_build_system/__init__.py rename to docs/idf_extensions/build_system/__init__.py index 9f3e662ed0..f1e2e0913d 100644 --- a/docs/idf_build_system/__init__.py +++ b/docs/idf_extensions/build_system/__init__.py @@ -14,19 +14,43 @@ import json # this directory also contains the dummy IDF project project_path = os.path.abspath(os.path.dirname(__file__)) + def setup(app): - builddir = os.path.dirname(app.doctreedir.rstrip(os.sep)) - app.add_config_value('docs_root', "", 'env') - app.add_config_value('idf_path', os.environ.get("IDF_PATH", ""), 'env') + # Setup some common paths + + try: + build_dir = os.environ["BUILDDIR"] # TODO see if we can remove this + except KeyError: + build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep)) + + try: + os.mkdir(build_dir) + except OSError: + pass + + try: + os.mkdir(os.path.join(build_dir, 'inc')) + except OSError: + pass + + # Fill in a default IDF_PATH if it's missing (ie when Read The Docs is building the docs) + try: + idf_path = os.environ['IDF_PATH'] + except KeyError: + idf_path = os.path.realpath(os.path.join(os.path.dirname(__file__), '..')) + + app.add_config_value('docs_root', os.path.join(idf_path, "docs"), 'env') + app.add_config_value('idf_path', idf_path, 'env') app.add_config_value('idf_target', 'esp32', 'env') - app.add_config_value('build_dir', os.environ.get("BUILDDIR", ""), 'env') # not actually an IDF thing + app.add_config_value('build_dir', build_dir, 'env') # not actually an IDF thing app.add_event('idf-info') # Attaching the generate event to env-get-outdated is a bit of a hack, # we want this to run early in the docs build but unclear exactly when app.connect('env-get-outdated', generate_idf_info) - return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' } + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} + def generate_idf_info(app, env, added, changed, removed): print("Running CMake on dummy project to get build info...") @@ -43,17 +67,20 @@ def generate_idf_info(app, env, added, changed, removed): if not os.path.exists(os.path.join(cmake_build_dir, "CMakeCache.txt")): # if build directory not created yet, run a reconfigure pass over it print("Starting new dummy IDF project...") - subprocess.check_call(idf_py + [ "set-target", app.config.idf_target]) + subprocess.check_call(idf_py + ["set-target", app.config.idf_target]) else: print("Re-running CMake on the existing IDF project in {}".format(cmake_build_dir)) - subprocess.check_call(idf_py + [ "reconfigure"]) + subprocess.check_call(idf_py + ["reconfigure"]) with open(os.path.join(cmake_build_dir, "project_description.json")) as f: project_description = json.load(f) if project_description["target"] != app.config.idf_target: # this shouldn't really happen unless someone has been moving around directories inside _build, as # the cmake_build_dir path should be target-specific - raise RuntimeError("Error configuring the dummy IDF project for {}. Target in project description is {}. Is _build directory contents corrupt?".format(app.config.idf_target, project_description["target"])) + raise RuntimeError(("Error configuring the dummy IDF project for {}. " + + "Target in project description is {}. " + + "Is build directory contents corrupt?") + .format(app.config.idf_target, project_description["target"])) app.emit('idf-info', project_description) return [] diff --git a/docs/idf_extensions/esp_err_definitions.py b/docs/idf_extensions/esp_err_definitions.py new file mode 100644 index 0000000000..c77ff5bb75 --- /dev/null +++ b/docs/idf_extensions/esp_err_definitions.py @@ -0,0 +1,14 @@ +# Extension to generate esp_err definition as .rst +from util import copy_if_modified, call_with_python + + +def setup(app): + app.connect('idf-info', generate_err_defs) + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} + + +def generate_err_defs(app, project_description): + # Generate 'esp_err_defs.inc' file with ESP_ERR_ error code definitions from inc file + esp_err_inc_path = '{}/inc/esp_err_defs.inc'.format(app.config.build_dir) + call_with_python('{}/tools/gen_esp_err_to_name.py --rst_output {}.in'.format(app.config.idf_path, esp_err_inc_path)) + copy_if_modified(esp_err_inc_path + '.in', esp_err_inc_path) diff --git a/docs/idf_extensions/gen_idf_tools_links.py b/docs/idf_extensions/gen_idf_tools_links.py new file mode 100644 index 0000000000..abba61daa5 --- /dev/null +++ b/docs/idf_extensions/gen_idf_tools_links.py @@ -0,0 +1,19 @@ +# Generate toolchain download links from toolchain info makefile +from __future__ import print_function +import os.path +from util import copy_if_modified, call_with_python + +def setup(app): + # we don't actually need idf-info, just a convenient event to trigger this on + app.connect('idf-info', generate_idf_tools_links) + + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} + + +def generate_idf_tools_links(app, project_description): + print("Generating IDF Tools list") + os.environ["IDF_MAINTAINER"] = "1" + tools_rst = os.path.join(app.config.build_dir, 'inc', 'idf-tools-inc.rst') + tools_rst_tmp = os.path.join(app.config.build_dir, 'idf-tools-inc.rst') + call_with_python("{}/tools/idf_tools.py gen-doc --output {}".format(app.config.idf_path, tools_rst_tmp)) + copy_if_modified(tools_rst_tmp, tools_rst) diff --git a/docs/gen-toolchain-links.py b/docs/idf_extensions/gen_toolchain_links.py similarity index 67% rename from docs/gen-toolchain-links.py rename to docs/idf_extensions/gen_toolchain_links.py index b98a68e2c0..183e39f81b 100644 --- a/docs/gen-toolchain-links.py +++ b/docs/idf_extensions/gen_toolchain_links.py @@ -1,15 +1,10 @@ -#!/usr/bin/env python -# -*- coding: utf-8 -*- -# -# This script generates toolchain download links and toolchain unpacking -# code snippets based on information found in $IDF_PATH/tools/toolchain_versions.mk -# - +# Generate toolchain download links from toolchain info makefile from __future__ import print_function - -import sys -import os +import os.path from collections import namedtuple +from util import copy_if_modified + +BASE_URL = 'https://dl.espressif.com/dl/' PlatformInfo = namedtuple("PlatformInfo", [ "platform_name", @@ -20,19 +15,22 @@ PlatformInfo = namedtuple("PlatformInfo", [ ]) -def main(): - if len(sys.argv) != 4: - print("Usage: gen-toolchain-links.py ") - sys.exit(1) +def setup(app): + # we don't actually need idf-info, just a convenient event to trigger this on + app.connect('idf-info', generate_toolchain_download_links) - out_dir = sys.argv[3] - if not os.path.exists(out_dir): - print("Creating directory %s" % out_dir) - os.mkdir(out_dir) + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} - base_url = sys.argv[2] - versions_file = sys.argv[1] +def generate_toolchain_download_links(app, project_description): + print("Generating toolchain download links") + toolchain_tmpdir = '{}/toolchain_inc'.format(app.config.build_dir) + toolchain_versions = os.path.join(app.config.idf_path, "tools/toolchain_versions.mk") + gen_toolchain_links(toolchain_versions, toolchain_tmpdir) + copy_if_modified(toolchain_tmpdir, '{}/inc'.format(app.config.build_dir)) + + +def gen_toolchain_links(versions_file, out_dir): version_vars = {} with open(versions_file) as f: for line in f: @@ -67,13 +65,18 @@ def main(): PlatformInfo("win32", "win32", "zip", None, None) ] + try: + os.mkdir(out_dir) + except OSError: + pass + with open(os.path.join(out_dir, 'download-links.inc'), "w") as links_file: for p in platform_info: archive_name = 'xtensa-esp32-elf-gcc{}-{}-{}.{}'.format( gcc_version.replace('.', '_'), toolchain_desc, p.platform_archive_suffix, p.extension) print('.. |download_link_{}| replace:: {}{}'.format( - p.platform_name, base_url, archive_name), file=links_file) + p.platform_name, BASE_URL, archive_name), file=links_file) if p.unpack_code is not None: with open(os.path.join(out_dir, 'unpack-code-%s.inc' % p.platform_name), "w") as f: @@ -81,7 +84,3 @@ def main(): with open(os.path.join(out_dir, 'scratch-build-code.inc'), "w") as code_file: print(scratch_build_code_linux_macos.format(toolchain_desc), file=code_file) - - -if __name__ == "__main__": - main() diff --git a/docs/gen-version-specific-includes.py b/docs/idf_extensions/gen_version_specific_includes.py similarity index 89% rename from docs/gen-version-specific-includes.py rename to docs/idf_extensions/gen_version_specific_includes.py index 08b111d651..483f94c84b 100755 --- a/docs/gen-version-specific-includes.py +++ b/docs/idf_extensions/gen_version_specific_includes.py @@ -1,15 +1,15 @@ #!/usr/bin/env python # -*- coding: utf-8 -*- # -# Python script to generate ReSTructured Text .inc snippets +# Sphinx extension to generate ReSTructured Text .inc snippets # with version-based content for this IDF version from __future__ import print_function from __future__ import unicode_literals from io import open +from util import copy_if_modified import subprocess import os -import sys import re TEMPLATES = { @@ -120,23 +120,26 @@ TEMPLATES = { } -def main(): - if len(sys.argv) != 3: - print("Usage: gen-git-clone.py ") - sys.exit(1) +def setup(app): + # doesn't need to be this event specifically, but this is roughly the right time + app.connect('idf-info', generate_version_specific_includes) + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} - language = sys.argv[1] - out_dir = sys.argv[2] - if not os.path.exists(out_dir): - print("Creating directory %s" % out_dir) - os.mkdir(out_dir) + +def generate_version_specific_includes(app, project_description): + language = app.config.language + tmp_out_dir = os.path.join(app.config.build_dir, "version_inc") + if not os.path.exists(tmp_out_dir): + print("Creating directory %s" % tmp_out_dir) + os.mkdir(tmp_out_dir) template = TEMPLATES[language] version, ver_type, is_stable = get_version() - write_git_clone_inc_files(template, out_dir, version, ver_type, is_stable) - write_version_note(template["version-note"], out_dir, version, ver_type, is_stable) + write_git_clone_inc_files(template, tmp_out_dir, version, ver_type, is_stable) + write_version_note(template["version-note"], tmp_out_dir, version, ver_type, is_stable) + copy_if_modified(tmp_out_dir, os.path.join(app.config.build_dir, "inc")) print("Done") @@ -217,7 +220,3 @@ def get_version(): return ("master", "branch", False) else: return (branches[0], "branch", False) # take whatever the first branch is - - -if __name__ == "__main__": - main() diff --git a/docs/include_build_file.py b/docs/idf_extensions/include_build_file.py similarity index 70% rename from docs/include_build_file.py rename to docs/idf_extensions/include_build_file.py index 84bc296e1d..7472129574 100644 --- a/docs/include_build_file.py +++ b/docs/idf_extensions/include_build_file.py @@ -1,8 +1,9 @@ import os.path -from docutils.parsers.rst import Directive, directives +from docutils.parsers.rst import directives from docutils.parsers.rst.directives.misc import Include as BaseInclude from sphinx.util.docutils import SphinxDirective + class IncludeBuildFile(BaseInclude, SphinxDirective): """ Like the standard "Include" directive, but relative to the app @@ -14,7 +15,8 @@ class IncludeBuildFile(BaseInclude, SphinxDirective): self.env.note_included(abspath) return super(IncludeBuildFile, self).run() -def setup(app): - directives.register_directive('include-build-file', IncludeBuildFile) - return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' } +def setup(app): + directives.register_directive('include-build-file', IncludeBuildFile) + + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} diff --git a/docs/kconfig_reference.py b/docs/idf_extensions/kconfig_reference.py similarity index 94% rename from docs/kconfig_reference.py rename to docs/idf_extensions/kconfig_reference.py index 7137093e56..2176683e2f 100644 --- a/docs/kconfig_reference.py +++ b/docs/idf_extensions/kconfig_reference.py @@ -3,14 +3,16 @@ import os.path import sys import subprocess -from local_util import copy_if_modified +from util import copy_if_modified + def setup(app): # The idf_build_system extension will emit this event once it # has parsed the IDF project's information app.connect('idf-info', generate_reference) - return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' } + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} + def generate_reference(app, project_description): build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep)) @@ -40,7 +42,7 @@ def generate_reference(app, project_description): "--env", "COMPONENT_KCONFIGS_PROJBUILD={}".format(" ".join(kconfig_projbuilds)), "--env", "COMPONENT_KCONFIGS_SOURCE_FILE={}".format(kconfigs_source_path), "--env", "COMPONENT_KCONFIGS_PROJBUILD_SOURCE_FILE={}".format(kconfig_projbuilds_source_path), - ] + ] subprocess.check_call(prepare_kconfig_files_args) confgen_args = [sys.executable, @@ -56,8 +58,6 @@ def generate_reference(app, project_description): "--env", "IDF_PATH={}".format(app.config.idf_path), "--env", "IDF_TARGET={}".format(app.config.idf_target), "--output", "docs", kconfig_inc_path + '.in' - ] + ] subprocess.check_call(confgen_args, cwd=app.config.idf_path) copy_if_modified(kconfig_inc_path + '.in', kconfig_inc_path) - - diff --git a/docs/link-roles.py b/docs/idf_extensions/link_roles.py similarity index 82% rename from docs/link-roles.py rename to docs/idf_extensions/link_roles.py index 2c748500d5..ee1a6adc57 100644 --- a/docs/link-roles.py +++ b/docs/idf_extensions/link_roles.py @@ -4,17 +4,20 @@ from __future__ import print_function from __future__ import unicode_literals import re import os +import subprocess from docutils import nodes -from local_util import run_cmd_get_output def get_github_rev(): - path = run_cmd_get_output('git rev-parse --short HEAD') - tag = run_cmd_get_output('git describe --exact-match') + path = subprocess.check_output(['git', 'rev-parse', '--short', 'HEAD']).strip() + try: + tag = subprocess.check_output(['git', 'describe', '--exact-match']).strip() + except subprocess.CalledProcessError: + tag = None print('Git commit ID: ', path) - if len(tag): + if tag: print('Git tag: ', tag) - path = tag + return tag return path @@ -38,15 +41,15 @@ def setup(app): if on_rtd: # provide RTD specific commit identification to be included in the link tag_rev = 'latest' - if (run_cmd_get_output('git rev-parse --short HEAD') != rev): + if (subprocess.check_output(['git','rev-parse', '--short', 'HEAD']).strip() != rev): tag_rev = rev else: # if not on the RTD then provide generic identification - tag_rev = run_cmd_get_output('git describe --always') + tag_rev = subprocess.check_output(['git', 'describe', '--always']).strip() app.add_role('link_to_translation', crosslink('%s../../%s/{}/%s.html'.format(tag_rev))) - return { 'parallel_read_safe' : True, 'parallel_write_safe': True, 'version': '0.1' } + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} def autolink(pattern): diff --git a/docs/gen-dxd.py b/docs/idf_extensions/run_doxygen.py old mode 100755 new mode 100644 similarity index 66% rename from docs/gen-dxd.py rename to docs/idf_extensions/run_doxygen.py index bbc3314844..b14c5c747d --- a/docs/gen-dxd.py +++ b/docs/idf_extensions/run_doxygen.py @@ -1,40 +1,15 @@ -#!/usr/bin/env python -# -# gen-dxd.py - Generate Doxygen Directives -# -# This code is in the Public Domain (or CC0 licensed, at your option.) -# Unless required by applicable law or agreed to in writing, this -# software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR -# CONDITIONS OF ANY KIND, either express or implied. -# - +# Extension to generate Doxygen XML include files, with IDF config & soc macros included from __future__ import print_function from __future__ import unicode_literals -from builtins import range from io import open -import sys +import glob import os +import os.path import re +import subprocess +from util import copy_if_modified -# Determime build directory -builddir = '_build' -if 'BUILDDIR' in os.environ: - builddir = os.environ['BUILDDIR'] - -# Script configuration -header_file_path_prefix = "../components/" -"""string: path prefix for header files. -""" -doxyfile_path = "./Doxyfile" -"""string: path to a file containing header files to processs. -""" -xml_directory_path = os.path.join(builddir, "xml") -"""string: path to directory with XML files by Doxygen. -""" -inc_directory_path = os.path.join(builddir, 'inc') -"""string: path prefix for header files. -""" -all_kinds = [ +ALL_KINDS = [ ("function", "Functions"), ("union", "Unions"), ("struct", "Structures"), @@ -124,7 +99,7 @@ def convert_api_xml_to_inc(app, doxyfile): if not os.path.exists(inc_directory_path): os.makedirs(inc_directory_path) - header_paths = get_doxyfile_input_paths(app, doxyfile) + header_paths = get_doxyfile_input_paths(doxyfile) print("Generating 'api_name.inc' files with Doxygen directives") for header_file_path in header_paths: api_name = get_api_name(header_file_path) @@ -141,7 +116,7 @@ def convert_api_xml_to_inc(app, doxyfile): inc_file.write(rst_output) -def get_doxyfile_input_paths(app, doxyfile_path): +def get_doxyfile_input_paths(doxyfile_path): """Get contents of Doxyfile's INPUT statement. Returns: @@ -149,37 +124,35 @@ def get_doxyfile_input_paths(app, doxyfile_path): """ if not os.path.isfile(doxyfile_path): - print("Doxyfile '%s' does not exist!" % doxyfile_path) - sys.exit() + raise RuntimeError("Doxyfile '{}' does not exist!".format(doxyfile_path)) print("Getting Doxyfile's INPUT") - input_file = open(doxyfile_path, "r", encoding='utf-8') - - line = input_file.readline() - # read contents of Doxyfile until 'INPUT' statement - while line: - if line.find("INPUT") == 0: - break + with open(doxyfile_path, "r", encoding='utf-8') as input_file: line = input_file.readline() + # read contents of Doxyfile until 'INPUT' statement + while line: + if line.find("INPUT") == 0: + break + line = input_file.readline() - doxyfile_INPUT = "" - line = input_file.readline() - # skip input_file contents until end of 'INPUT' statement - while line: - if line.isspace(): - # we have reached the end of 'INPUT' statement - break - # process only lines that are not comments - if line.find("#") == -1: - # extract header file path inside components folder - m = re.search(header_file_path_prefix + "(.*\.h)", line) # noqa: W605 - regular expression - header_file_path = m.group(1) - doxyfile_INPUT += header_file_path + "\n" - # proceed reading next line + doxyfile_INPUT = [] line = input_file.readline() + # skip input_file contents until end of 'INPUT' statement + while line: + if line.isspace(): + # we have reached the end of 'INPUT' statement + break + # process only lines that are not comments + if line.find("#") == -1: + # extract header file path inside components folder + m = re.search("components/(.*\.h)", line) # noqa: W605 - regular expression + header_file_path = m.group(1) + doxyfile_INPUT.append(header_file_path) + + # proceed reading next line + line = input_file.readline() - input_file.close() return doxyfile_INPUT @@ -202,6 +175,42 @@ def get_api_name(header_file_path): return api_name +def generate_directives(header_file_path, xml_directory_path): + """Generate API reference with Doxygen directives for a header file. + + Args: + header_file_path: a path to the header file with API. + + Returns: + Doxygen directives for the header file. + + """ + + api_name = get_api_name(header_file_path) + + # in XLT file name each "_" in the api name is expanded by Doxygen to "__" + xlt_api_name = api_name.replace("_", "__") + xml_file_path = "%s/%s_8h.xml" % (xml_directory_path, xlt_api_name) + + rst_output = "" + rst_output = ".. File automatically generated by 'gen-dxd.py'\n" + rst_output += "\n" + rst_output += get_rst_header("Header File") + rst_output += "* :component_file:`" + header_file_path + "`\n" + rst_output += "\n" + + try: + import xml.etree.cElementTree as ET + except ImportError: + import xml.etree.ElementTree as ET + + tree = ET.ElementTree(file=xml_file_path) + for kind, label in ALL_KINDS: + rst_output += get_directives(tree, kind) + + return rst_output + + def get_rst_header(header_name): """Get rst formatted code with a header. @@ -305,109 +314,7 @@ def get_directives(tree, kind): rst_output += ".. doxygen%s:: " % kind rst_output += name.text + "\n" if rst_output: - all_kinds_dict = dict(all_kinds) + all_kinds_dict = dict(ALL_KINDS) rst_output = get_rst_header(all_kinds_dict[kind]) + rst_output + "\n" return rst_output - - -def generate_directives(header_file_path): - """Generate API reference with Doxygen directives for a header file. - - Args: - header_file_path: a path to the header file with API. - - Returns: - Doxygen directives for the header file. - - """ - - api_name = get_api_name(header_file_path) - - # in XLT file name each "_" in the api name is expanded by Doxygen to "__" - xlt_api_name = api_name.replace("_", "__") - xml_file_path = "%s/%s_8h.xml" % (xml_directory_path, xlt_api_name) - - rst_output = "" - rst_output = ".. File automatically generated by 'gen-dxd.py'\n" - rst_output += "\n" - rst_output += get_rst_header("Header File") - rst_output += "* :component_file:`" + header_file_path + "`\n" - rst_output += "\n" - - try: - import xml.etree.cElementTree as ET - except ImportError: - import xml.etree.ElementTree as ET - - tree = ET.ElementTree(file=xml_file_path) - for i in range(len(all_kinds)): - kind = all_kinds[i][0] - rst_output += get_directives(tree, kind) - - return rst_output - - -def generate_api_inc_files(): - """Generate header_file.inc files - with API reference made of doxygen directives - for each header file - specified in the 'INPUT' statement of Doxyfile. - - """ - - if not os.path.isdir(xml_directory_path): - print("Directory %s does not exist!" % xml_directory_path) - sys.exit() - - if not os.path.exists(inc_directory_path): - os.makedirs(inc_directory_path) - - list_to_generate = get_doxyfile_input() - print("Generating 'api_name.inc' files with Doxygen directives") - for header_file_path in list_to_generate.splitlines(): - api_name = get_api_name(header_file_path) - inc_file_path = inc_directory_path + "/" + api_name + ".inc" - rst_output = generate_directives(header_file_path) - - previous_rst_output = '' - if os.path.isfile(inc_file_path): - with open(inc_file_path, "r", encoding='utf-8') as inc_file_old: - previous_rst_output = inc_file_old.read() - - if previous_rst_output != rst_output: - with open(inc_file_path, "w", encoding='utf-8') as inc_file: - inc_file.write(rst_output) - - -if __name__ == "__main__": - """The main script that generates - Doxygen directives. - - """ - - # Process command line arguments, if any - if len(sys.argv) > 1: - if not os.path.isdir(xml_directory_path): - print("Directory %s does not exist!" % xml_directory_path) - sys.exit() - header_file_path = sys.argv[1] - api_name = get_api_name(header_file_path) - if api_name: - rst_output = generate_directives(header_file_path) - print("Doxygen directives for '%s'" % header_file_path) - print() - print(rst_output) - else: - print("Options to execute 'gen-dxd.py' application:") - print("1: $ python gen-dxd.py") - print(" Generate API 'header_file.inc' files for headers defined in '%s'" % doxyfile_path) - print("2: $ python gen-dxd.py header_file_path") - print(" Print out Doxygen directives for a single header file") - print(" example: $ python gen-dxd.py mdns/include/mdns.h") - print(" NOTE: Run Doxygen first to get XML files for the header file") - - sys.exit() - - # No command line arguments given - generate_api_inc_files() diff --git a/docs/local_util.py b/docs/idf_extensions/util.py similarity index 97% rename from docs/local_util.py rename to docs/idf_extensions/util.py index 6d8998f387..f5f271d23c 100644 --- a/docs/local_util.py +++ b/docs/idf_extensions/util.py @@ -29,10 +29,6 @@ except ImportError: _urlretrieve = urllib.urlretrieve -def run_cmd_get_output(cmd): - return os.popen(cmd).read().strip() - - def files_equal(path_1, path_2): if not os.path.exists(path_1) or not os.path.exists(path_2): return False @@ -77,6 +73,7 @@ def download_file_if_missing(from_url, to_path): with open(tmp_file, 'rb') as tmp: fobj.write(tmp.read()) + def call_with_python(cmd): # using sys.executable ensures that the scripts are called with the same Python interpreter if os.system('{} {}'.format(sys.executable, cmd)) != 0: diff --git a/docs/requirements.txt b/docs/requirements.txt index f914e2cbde..c217a40043 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -12,4 +12,4 @@ sphinxcontrib-nwdiag>=0.9.5, <2.0.0 nwdiag==1.0.4 recommonmark future>=0.16.0 # for ../tools/gen_esp_err_to_name.py -sphinx_selective_exclude==1.0.1 +sphinx_selective_exclude>=1.0.3 diff --git a/docs/zh_CN/conf.py b/docs/zh_CN/conf.py index 49c89ee995..b857bc0d75 100644 --- a/docs/zh_CN/conf.py +++ b/docs/zh_CN/conf.py @@ -10,7 +10,7 @@ import sys import os sys.path.insert(0, os.path.abspath('..')) from conf_common import * # noqa: F401, F403 - need to make available everything from common -from local_util import download_file_if_missing # noqa: E402 - need to import from common folder +from idf_extensions.util import download_file_if_missing # noqa: E402 - need to import from common folder # General information about the project. project = u'ESP-IDF 编程指南' @@ -32,5 +32,4 @@ nwdiag_fontpath = '../_static/NotoSansSC-Regular.otf' rackdiag_fontpath = '../_static/NotoSansSC-Regular.otf' packetdiag_fontpath = '../_static/NotoSansSC-Regular.otf' -update_exclude_patterns(tags) - +update_exclude_patterns(tags) # noqa: F405, need to import * from conf_common diff --git a/tools/check_python_dependencies.py b/tools/check_python_dependencies.py index 1dc5e8f813..103d98d10f 100755 --- a/tools/check_python_dependencies.py +++ b/tools/check_python_dependencies.py @@ -16,6 +16,7 @@ import argparse import os +import re import sys try: @@ -52,6 +53,8 @@ if __name__ == "__main__": # adjustments for options which we use. if line.startswith('file://'): line = os.path.basename(line) + if line.startswith('-e') and '#egg=' in line: # version control URLs, take the egg= part at the end only + line = re.search(r'#egg=([^\s]+)', line).group(1) try: pkg_resources.require(line) except Exception: From 66462ca26f0aa8469f508637976d1f1bc92121b1 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 29 Nov 2019 13:28:42 +1100 Subject: [PATCH 11/47] docs: Apply the same basic ESP32/ESP32-S2 warning filters to Chinese docs --- docs/en/api-guides/external-ram.rst | 2 +- ...notes.inc => external-ram-esp32-notes.rst} | 1 - docs/zh_CN/api-guides/build-system.rst | 8 ++- docs/zh_CN/api-guides/external-ram.rst | 24 +------ docs/zh_CN/api-guides/fatal-errors.rst | 25 ++++++- docs/zh_CN/api-guides/index.rst | 10 +-- .../jtag-debugging/tips-and-quirks.rst | 9 ++- docs/zh_CN/api-guides/tools/idf-monitor.rst | 8 ++- docs/zh_CN/api-guides/ulp.rst | 4 +- docs/zh_CN/api-reference/index.rst | 2 +- .../api-reference/peripherals/touch_pad.rst | 2 +- .../api-reference/system/power_management.rst | 70 +++++++++---------- docs/zh_CN/get-started/eclipse-setup.rst | 4 +- docs/zh_CN/get-started/index.rst | 26 +++---- docs/zh_CN/get-started/linux-setup.rst | 2 +- docs/zh_CN/get-started/windows-setup.rst | 12 ++-- 16 files changed, 115 insertions(+), 94 deletions(-) rename docs/en/api-guides/inc/{external-ram-esp32-notes.inc => external-ram-esp32-notes.rst} (99%) diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index 8fa7569c9f..18eb536b01 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -125,6 +125,6 @@ External RAM use has the following restrictions: .. only:: esp32 - .. include:: inc/external-ram-esp32-notes.inc + .. include:: inc/external-ram-esp32-notes.rst .. _ESP32 ECO: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf diff --git a/docs/en/api-guides/inc/external-ram-esp32-notes.inc b/docs/en/api-guides/inc/external-ram-esp32-notes.rst similarity index 99% rename from docs/en/api-guides/inc/external-ram-esp32-notes.inc rename to docs/en/api-guides/inc/external-ram-esp32-notes.rst index 39a133a6a9..5b4e4f1d8d 100644 --- a/docs/en/api-guides/inc/external-ram-esp32-notes.inc +++ b/docs/en/api-guides/inc/external-ram-esp32-notes.rst @@ -1,5 +1,4 @@ * Regarding stacks in PSRAM: For tasks not calling on code in ROM in any way, directly or indirectly, the menuconfig option :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` will eliminate the check in xTaskCreateStatic, allowing a task's stack to be in external RAM. Using this is not advised, however. -32 * When used at 80 MHz clock speed, external RAM must also occupy either the HSPI or VSPI bus. Select which SPI host will be used by :ref:`CONFIG_SPIRAM_OCCUPY_SPI_HOST`. diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index e9616ec0c3..88a7c8b990 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -2,7 +2,9 @@ ******************** :link_to_translation:`en:[English]` -本文档将介绍基于 CMake 的 ESP-IDF 构建系统的实现原理以及 ``组件`` 等相关概念，此外 ESP-IDF 还支持 :doc:`基于 GNU Make 的构建系统 `。 +.. only:: esp32 + + 本文档将介绍基于 CMake 的 ESP-IDF 构建系统的实现原理以及 ``组件`` 等相关概念，此外 ESP-IDF 还支持 :doc:`基于 GNU Make 的构建系统 `。 如需您想了解如何使用 CMake 构建系统来组织和构建新的 ESP-IDF 项目或组件，请阅读本文档。 @@ -721,7 +723,9 @@ ESP-IDF 还支持自动生成链接脚本，它允许组件通过链接片段文 - 第二组命令添加了一个目标库，指向外部构建系统生成的库文件。为了添加 include 目录，并告知 CMake 该文件的位置，需要再设置一些属性。 - 最后，生成的库被添加到 `ADDITIONAL_MAKE_CLEAN_FILES`_ 中。即执行 ``make clean`` 后会删除该库。请注意，构建系统中的其他目标文件不会被删除。 -.. note:: 当外部构建系统使用 PSRAM 时，请记得将 ``-mfix-esp32-psram-cache-issue`` 添加到 C 编译器的参数中。关于该标志的更多详细信息，请参考 :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`。 +.. only:: esp32 + + .. note:: 当外部构建系统使用 PSRAM 时，请记得将 ``-mfix-esp32-psram-cache-issue`` 添加到 C 编译器的参数中。关于该标志的更多详细信息，请参考 :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`。 .. _ADDITIONAL_MAKE_CLEAN_FILES_note: diff --git a/docs/zh_CN/api-guides/external-ram.rst b/docs/zh_CN/api-guides/external-ram.rst index 922be9483e..aaa6710fb2 100644 --- a/docs/zh_CN/api-guides/external-ram.rst +++ b/docs/zh_CN/api-guides/external-ram.rst @@ -118,30 +118,10 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据 * 默认情况下，片外 RAM 初始化失败将终止 ESP-IDF 启动。如果想禁用此功能，可启用 :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND` 配置选项。如果启用 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`，:ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND` 选项将不能使用，这是因为在链接时，链接器已经向片外 RAM 分配符号。 - * 时钟频率为 80 MHz 时，片外 RAM 须占用 HSPI 总线或 VSPI 总线。请使用 :ref:`CONFIG_SPIRAM_OCCUPY_SPI_HOST` 选择要用的 SPI 主机。 +.. only:: esp32 -芯片版本 -============== - -有些 ESP32 芯片版本存在某些已知问题，可能会影响片外 RAM 的使用。请参考 ESP32 勘误表_，查看详细信息。为了解决这些问题，ESP-IDF 采取了以下措施： - -ESP32 rev v0 ------------- -ESP-IDF 尚未提供针对此版本硅片 bug 的解决方法，因此在 ESP32 rev v0 中，ESP-IDF 无法将片外 PSRAM 映射到 ESP32 主内存映射中。 - -ESP32 rev v1 ------------- -当某些机器指令序列在片外存储器位置上运行时，此芯片版本中的错误可能会引发芯片故障（详情见 ESP32 勘误表_ 第 3.2 章节）。 为了解决这个问题，用于编译 ESP-IDF 项目的 GCC 编译器扩展了一个旗标：-mfix-esp32-psram-cache-issue。在命令行中将此旗标传递给 GCC，编译器对这些序列进行处理，然后仅输出可以安全执行的代码。如需启用此旗标，请选择 :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`。 - -ESP-IDF 还采取了其他措施确保不同时使用 PSRAM 访问和出错指令集： - -- 链接到使用 GCC 旗标重新编译的 Newlib 版本； -- 避免使用某些 ROM 函数； -- 为 Wi-Fi 栈分配静态内存。 - -.. _勘误表: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_cn.pdf - + .. include:: inc/external-ram-esp32-notes.rst diff --git a/docs/zh_CN/api-guides/fatal-errors.rst b/docs/zh_CN/api-guides/fatal-errors.rst index 211658f689..a9f40b672e 100644 --- a/docs/zh_CN/api-guides/fatal-errors.rst +++ b/docs/zh_CN/api-guides/fatal-errors.rst @@ -39,7 +39,13 @@ 不管哪种情况，错误原因都会被打印在括号中。请参阅 :ref:`Guru-Meditation-Errors` 以查看所有可能的出错原因。 -紧急处理程序接下来的行为将取决于 :ref:`CONFIG_ESP32_PANIC` 的设置，支持的选项包括： +.. only:: esp32 + + 紧急处理程序接下来的行为将取决于 :ref:`CONFIG_ESP32_PANIC` 的设置，支持的选项包括： + +.. only:: esp32s2 + + 紧急处理程序接下来的行为将取决于 :ref:`CONFIG_ESP32S2_PANIC` 的设置，支持的选项包括： - 打印 CPU 寄存器，然后重启（``CONFIG_ESP32_PANIC_PRINT_REBOOT``）- 默认选项 @@ -59,7 +65,13 @@ 紧急处理程序的行为还受到另外两个配置项的影响： -- 如果 :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` 被使能了（默认），紧急处理程序会检测 ESP32 是否已经连接 JTAG 调试器。如果检测成功，程序会暂停运行，并将控制权交给调试器。在这种情况下，寄存器和回溯不会被打印到控制台，并且也不会使用 GDB Stub 和 Core Dump 的功能。 +.. only:: esp32 + + - 如果 :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` 被使能了（默认），紧急处理程序会检测 ESP32 是否已经连接 JTAG 调试器。如果检测成功，程序会暂停运行，并将控制权交给调试器。在这种情况下，寄存器和回溯不会被打印到控制台，并且也不会使用 GDB Stub 和 Core Dump 的功能。 + +.. only:: esp32s2 + + - 如果 :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` 被使能了（默认），紧急处理程序会检测 ESP32-S2 是否已经连接 JTAG 调试器。如果检测成功，程序会暂停运行，并将控制权交给调试器。在这种情况下，寄存器和回溯不会被打印到控制台，并且也不会使用 GDB Stub 和 Core Dump 的功能。 - 如果使能了 :doc:`Core Dump ` 功能（``CONFIG_ESP32_ENABLE_COREDUMP_TO_FLASH`` 或者 ``CONFIG_ESP32_ENABLE_COREDUMP_TO_UART`` 选项），系统状态（任务堆栈和寄存器）会被转储到 Flash 或者 UART 以供后续分析。 @@ -265,7 +277,14 @@ Cache disabled but cached memory region accessed 欠压 ^^^^ -ESP32 内部集成掉电检测电路，并且会默认启用。如果电源电压低于安全值，掉电检测器可以触发系统复位。掉电检测器可以使用 :ref:`CONFIG_ESP32_BROWNOUT_DET` 和 :ref:`CONFIG_ESP32_BROWNOUT_DET_LVL_SEL` 这两个选项进行设置。 +.. only:: esp32 + + ESP32 内部集成掉电检测电路，并且会默认启用。如果电源电压低于安全值，掉电检测器可以触发系统复位。掉电检测器可以使用 :ref:`CONFIG_ESP32_BROWNOUT_DET` 和 :ref:`CONFIG_ESP32_BROWNOUT_DET_LVL_SEL` 这两个选项进行设置。 + +.. only:: esp32s2 + + ESP32-S2 内部集成掉电检测电路，并且会默认启用。如果电源电压低于安全值，掉电检测器可以触发系统复位。掉电检测器可以使用 :ref:`CONFIG_ESP32S2_BROWNOUT_DET` 和 :ref:`CONFIG_ESP32S2_BROWNOUT_DET_LVL_SEL` 这两个选项进行设置。 + 当掉电检测器被触发时，会打印如下信息:: Brownout detector was triggered diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index cac15e0d8f..9df13bf124 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -7,7 +7,7 @@ API 指南 一般注意事项 构建系统 - 构建系统 (传统 GNU Make) + :esp32: 构建系统 (传统 GNU Make) 错误处理 严重错误 Event Handling @@ -22,17 +22,17 @@ API 指南 分区表 Secure Boot <../security/secure-boot> ULP 协处理器 - ULP ( Legacy GNU Make) + :esp32: ULP (传统 GNU Make) 单元测试 - 单元测试 (传统 GNU Make) + :esp32: 单元测试 (传统 GNU Make) 应用层跟踪 控制台终端组件 ROM debug console RF Calibration WiFi Driver - ESP-BLE-MESH + :esp32: ESP-BLE-MESH ESP-MESH (Wi-Fi) - BluFi + :esp32: BluFi External SPI-connected RAM 链接脚本生成机制 LwIP diff --git a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst index bd1a6427d3..54963a3ccf 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst @@ -54,7 +54,14 @@ OpenOCD 支持的编译时的选项 ESP-IDF 有一些针对 OpenOCD 调试功能的选项可以在编译时进行设置： -* :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` 默认会被使能。如果程序抛出了不可修复或者未处理的异常，并且此时已经连接上了 JTAG 调试器（即 OpenOCD 正在运行），那么 ESP-IDF 将会进入调试器工作模式。 +.. only:: esp32 + + * :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` 默认会被使能。如果程序抛出了不可修复或者未处理的异常，并且此时已经连接上了 JTAG 调试器（即 OpenOCD 正在运行），那么 ESP-IDF 将会进入调试器工作模式。 + +.. only:: esp32s2 + + * :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` 默认会被使能。如果程序抛出了不可修复或者未处理的异常，并且此时已经连接上了 JTAG 调试器（即 OpenOCD 正在运行），那么 ESP-IDF 将会进入调试器工作模式。 + * :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` 默认没有使能。在所有任务堆栈的末尾设置观察点，从 1 号开始索引。这是调试任务堆栈溢出的最准确的方式。 更多有关设置编译时的选项的信息，请参阅 :ref:`项目配置菜单 `。 diff --git a/docs/zh_CN/api-guides/tools/idf-monitor.rst b/docs/zh_CN/api-guides/tools/idf-monitor.rst index 72651108f2..15078eb0b9 100644 --- a/docs/zh_CN/api-guides/tools/idf-monitor.rst +++ b/docs/zh_CN/api-guides/tools/idf-monitor.rst @@ -92,7 +92,13 @@ IDF 监视器在后台运行以下命令，解码各地址:: 或者选择配置 panic 处理器以运行 GDBStub，GDBStub 工具可以与 GDB_ 项目调试器进行通信，允许读取内存、检查调用堆栈帧和变量等。GDBStub 虽然没有 JTAG 通用，但不需要使用特殊硬件。 -如需启用 GDBStub，请运行 ``idf.py menuconfig`` （适用于 CMake 编译系统），并将 :ref:`CONFIG_ESP32_PANIC` 选项设置为 ``Invoke GDBStub``。 +.. only:: esp32 + + 如需启用 GDBStub，请运行 ``idf.py menuconfig`` （适用于 CMake 编译系统），并将 :ref:`CONFIG_ESP32_PANIC` 选项设置为 ``Invoke GDBStub``。 + +.. only:: esp32s2 + + 如需启用 GDBStub，请运行 ``idf.py menuconfig`` （适用于 CMake 编译系统），并将 :ref:`CONFIG_ESP32S2_PANIC` 选项设置为 ``Invoke GDBStub``。 在这种情况下，如果 panic 处理器被触发，只要 IDF 监视器监控到 GDBStub 已经加载，panic 处理器就会自动暂停串行监控并使用必要的参数运行 GDB。GDB 退出后，通过 RTS 串口线复位开发板。如果未连接 RTS 串口线，请按复位键，手动复位开发板。 diff --git a/docs/zh_CN/api-guides/ulp.rst b/docs/zh_CN/api-guides/ulp.rst index 5ad56a860a..223e42df4e 100644 --- a/docs/zh_CN/api-guides/ulp.rst +++ b/docs/zh_CN/api-guides/ulp.rst @@ -20,7 +20,9 @@ ULP 协处理器代码是用汇编语言编写的，并使用 `binutils-esp32ulp 如果你已经按照 :doc:`快速入门指南 <../../get-started/index>` 中的介绍安装好了 ESP-IDF 及其 CMake 构建系统，那么 ULP 工具链已经被默认安装到了你的开发环境中。 -如果你的 ESP-IDF 仍在使用传统的基于 GNU Make 的构建系统，请参考 :doc:`ulp-legacy` 一文中的说明，完成工具链的安装。 +.. only:: esp32 + + 如果你的 ESP-IDF 仍在使用传统的基于 GNU Make 的构建系统，请参考 :doc:`ulp-legacy` 一文中的说明，完成工具链的安装。 编译 ULP 代码 diff --git a/docs/zh_CN/api-reference/index.rst b/docs/zh_CN/api-reference/index.rst index 1af37ab796..0d4e86a1bc 100644 --- a/docs/zh_CN/api-reference/index.rst +++ b/docs/zh_CN/api-reference/index.rst @@ -6,7 +6,7 @@ API 参考 .. toctree:: :maxdepth: 2 - Bluetooth + :esp32: Bluetooth Networking Peripherals 协议 diff --git a/docs/zh_CN/api-reference/peripherals/touch_pad.rst b/docs/zh_CN/api-reference/peripherals/touch_pad.rst index a870e50610..c8ba473b63 100644 --- a/docs/zh_CN/api-reference/peripherals/touch_pad.rst +++ b/docs/zh_CN/api-reference/peripherals/touch_pad.rst @@ -167,4 +167,4 @@ GPIO 宏查找表 .. include-build-file:: inc/touch_sensor_channel.inc -.. include-build-file:: inc/touch_channel.inc +.. include-build-file:: inc/touch_sensor_types.inc diff --git a/docs/zh_CN/api-reference/system/power_management.rst b/docs/zh_CN/api-reference/system/power_management.rst index 499c5960e0..acf3fb728b 100644 --- a/docs/zh_CN/api-reference/system/power_management.rst +++ b/docs/zh_CN/api-reference/system/power_management.rst @@ -27,12 +27,25 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求， 应用程序可以通过调用 :cpp:func:`esp_pm_configure` 函数启用动态调频 (DFS) 功能和自动 Light-sleep 模式。此函数的参数为 :cpp:class:`esp_pm_config_esp32_t`，定义了频率调节的相关设置。在此参数结构中，需要初始化下面三个字段： -- ``max_freq_mhz``：最大 CPU 频率 (MHz)，即获取 ``ESP_PM_CPU_FREQ_MAX`` 锁后所使用的频率。该字段通常设置为 :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ`。 +.. only:: esp32 + + - ``max_freq_mhz``：最大 CPU 频率 (MHz)，即获取 ``ESP_PM_CPU_FREQ_MAX`` 锁后所使用的频率。该字段通常设置为 :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ`。 + +.. only:: esp32s2 + + - ``max_freq_mhz``：最大 CPU 频率 (MHz)，即获取 ``ESP_PM_CPU_FREQ_MAX`` 锁后所使用的频率。该字段通常设置为 :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ`。 + - ``min_freq_mhz``：最小 CPU 频率 (MHz)，即仅获取 ``ESP_PM_APB_FREQ_MAX`` 锁后所使用的频率。该字段可设置为晶振 (XTAL) 频率值，或者 XTAL 频率值除以整数。注意，10 MHz 是生成 1 MHz 的 REF_TICK 默认时钟所需的最小频率。 - ``light_sleep_enable``：没有获取任何管理锁时，决定系统是否需要自动进入 Light-sleep 状态 (``true``/``false``)。 -或者，如果在 menuconfig 中启用了 :ref:`CONFIG_PM_DFS_INIT_AUTO` 选项，最大 CPU 频率将由 :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` 设置决定，最小 CPU 频率将锁定为 XTAL 频率。 +.. only:: esp32 + + 或者，如果在 menuconfig 中启用了 :ref:`CONFIG_PM_DFS_INIT_AUTO` 选项，最大 CPU 频率将由 :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` 设置决定，最小 CPU 频率将锁定为 XTAL 频率。 + +.. only:: esp32s2 + + 或者，如果在 menuconfig 中启用了 :ref:`CONFIG_PM_DFS_INIT_AUTO` 选项，最大 CPU 频率将由 :ref:`CONFIG_ESP32S2_DEFAULT_CPU_FREQ_MHZ` 设置决定，最小 CPU 频率将锁定为 XTAL 频率。 .. note:: @@ -58,37 +71,9 @@ ESP32 支持下表中所述的三种电源管理锁。 ``ESP_PM_NO_LIGHT_SLEEP`` 禁止自动切换至 Light-sleep 模式。 ============================ ====================================================== +.. only:: esp32 -电源管理算法 --------------------------------- - -下表列出了启用动态调频时如何切换 CPU 频率和 APB 频率。您可以使用 :cpp:func:`esp_pm_configure` 或者 :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` 指定 CPU 最大频率。 - -+--------------+---------------------------------------------------------+----------------------------------------------------+ -| CPU 最高频率 | 电源管理锁获取情况 | CPU 频率和 APB 频率 | -+--------------+---------------------------------------------------------+----------------------------------------------------+ -| 240 MHz | 获取 ``ESP_PM_CPU_FREQ_MAX`` 或 ``ESP_PM_APB_FREQ_MAX`` | CPU: 240 MHz APB: 80 MHz | -+ +---------------------------------------------------------+----------------------------------------------------+ -| \ | 无 | 使用 :cpp:func:`esp_pm_configure` 为二者设置最小值 | -+--------------+---------------------------------------------------------+----------------------------------------------------+ -| 160 MHz | 获取 ``ESP_PM_CPU_FREQ_MAX`` | CPU: 160 MHz APB: 80 MHz | -+ +---------------------------------------------------------+----------------------------------------------------+ -| \ | 获取 ``ESP_PM_CPU_FREQ_MAX``， | CPU: 80 MHz APB: 80 MHz | -| | 未获取 ``ESP_PM_APB_FREQ_MAX`` | | -+ +---------------------------------------------------------+----------------------------------------------------+ -| \ | 无 | 使用 :cpp:func:`esp_pm_configure` 为二者设置最小值 | -+--------------+---------------------------------------------------------+----------------------------------------------------+ -| 80 MHz | 获取 ``ESP_PM_CPU_FREQ_MAX`` 或 ``ESP_PM_APB_FREQ_MAX`` | CPU: 80 MHz APB: 80 MHz | -+ +---------------------------------------------------------+----------------------------------------------------+ -| \ | 无 | 使用 :cpp:func:`esp_pm_configure` 为二者设置最小值 | -+--------------+---------------------------------------------------------+----------------------------------------------------+ - -如果没有获取任何管理锁，调用 :cpp:func:`esp_pm_configure` 将启动 Light-sleep 模式。 Light-sleep 模式持续时间由以下因素决定： - -- 处于阻塞状态的 FreeRTOS 任务数（有限超时） -- :doc:`高分辨率定时器 ` API 注册的计数器数量 - -您也可以设置 Light-sleep 模式在最近事件（任务解除阻塞，或计时器超时）之前持续多久才唤醒芯片。 + .. include:: inc/power_management_esp32.rst 动态调频和外设驱动 ------------------------------------------------ @@ -113,15 +98,26 @@ ESP32 支持下表中所述的三种电源管理锁。 - **SPI slave**：从调用 :cpp:func:`spi_slave_initialize` 至 :cpp:func:`spi_slave_free` 期间。 - **Ethernet**：从调用 :cpp:func:`esp_eth_driver_install` 至 :cpp:func:`esp_eth_driver_uninstall` 期间。 - **WiFi**：从调用 :cpp:func:`esp_wifi_start` 至 :cpp:func:`esp_wifi_stop` 期间。如果启用了调制解调器睡眠模式，广播关闭时将释放此管理锁。 -- **Bluetooth**：从调用 :cpp:func:`esp_bt_controller_enable` 至 :cpp:func:`esp_bt_controller_disable` 期间。如果启用了蓝牙调制解调器，广播关闭时将释放此管理锁。但依然占用 ``ESP_PM_NO_LIGHT_SLEEP`` 锁。 - **CAN**：从调用 :cpp:func:`can_driver_install` 至 :cpp:func:`can_driver_uninstall` 期间。 +.. only:: esp32 + + - **Bluetooth**：从调用 :cpp:func:`esp_bt_controller_enable` 至 :cpp:func:`esp_bt_controller_disable` 期间。如果启用了蓝牙调制解调器，广播关闭时将释放此管理锁。但依然占用 ``ESP_PM_NO_LIGHT_SLEEP`` 锁。 + 以下外设驱动程序无法感知动态调频，应用程序需自己获取/释放管理锁： -- MCPWM -- PCNT -- Sigma-delta -- Timer Group +.. only:: esp32 + + - PCNT + - Sigma-delta + - Timer group + - MCPWM + +.. only:: esp32s2 + + - PCNT + - Sigma-delta + - Timer group API 参考 diff --git a/docs/zh_CN/get-started/eclipse-setup.rst b/docs/zh_CN/get-started/eclipse-setup.rst index 6014124101..bc55aec9f0 100644 --- a/docs/zh_CN/get-started/eclipse-setup.rst +++ b/docs/zh_CN/get-started/eclipse-setup.rst @@ -8,4 +8,6 @@ ESP-IDF V4.0 将默认采用基于 CMake 的编译系统。 对此，我们还推出了针对 CMake 编译系统的新 ESP-IDF Eclipse 插件。具体操作，请见 `ESP-IDF Eclipse 插件 `。 -如您仍需要对传统 GNU Make 编译系统的 Eclipse 支持，请前往 :doc:`传统 GNU Make 编译系统入门指南 `，查看 :doc:`使用 Eclipse IDE 进行编译与烧录 ` 章节。 \ No newline at end of file +.. only:: esp32 + + 如您仍需要对传统 GNU Make 编译系统的 Eclipse 支持，请前往 :doc:`传统 GNU Make 编译系统入门指南 `，查看 :doc:`使用 Eclipse IDE 进行编译与烧录 ` 章节。 diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst index 390911ee78..6040bdf56b 100644 --- a/docs/zh_CN/get-started/index.rst +++ b/docs/zh_CN/get-started/index.rst @@ -457,19 +457,21 @@ Windows 操作系统 您可使用快捷键 ``Ctrl+]``，退出 IDF 监视器。 -如果 IDF 监视器在烧录后很快发生错误，或打印信息全是乱码（见下），很有可能是因为您的开发板采用了 26 MHz 晶振，而 ESP-IDF 默认支持大多数开发板使用的 40 MHz 晶振。 +.. only:: esp32 -.. figure:: ../../_static/get-started-garbled-output.png - :align: center - :alt: 乱码输出 - :figclass: align-center + 如果 IDF 监视器在烧录后很快发生错误，或打印信息全是乱码（见下），很有可能是因为您的开发板采用了 26 MHz 晶振，而 ESP-IDF 默认支持大多数开发板使用的 40 MHz 晶振。 -此时，您可以： - -1. 退出监视器。 -2. 打开 :ref:`menuconfig `。 -3. 进入 ``Component config`` --> ``ESP32-specific`` --> ``Main XTAL frequency`` 进行配置，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 设置为 26 MHz。 -4. 然后，请重新 :ref:`编译和烧录 ` 应用程序。 + .. figure:: ../../_static/get-started-garbled-output.png + :align: center + :alt: 乱码输出 + :figclass: align-center + + 此时，您可以： + + 1. 退出监视器。 + 2. 打开 :ref:`menuconfig `。 + 3. 进入 ``Component config`` --> ``ESP32-specific`` --> ``Main XTAL frequency`` 进行配置，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 设置为 26 MHz。 + 4. 然后，请重新 :ref:`编译和烧录 ` 应用程序。 .. note:: @@ -507,7 +509,7 @@ Windows 操作系统 eclipse-setup ../api-guides/tools/idf-monitor toolchain-setup-scratch - ../get-started-legacy/index + :esp32: ../get-started-legacy/index .. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/ .. _Releases page: https://github.com/espressif/esp-idf/releases diff --git a/docs/zh_CN/get-started/linux-setup.rst b/docs/zh_CN/get-started/linux-setup.rst index 11e8b81563..0f30654ca3 100644 --- a/docs/zh_CN/get-started/linux-setup.rst +++ b/docs/zh_CN/get-started/linux-setup.rst @@ -44,7 +44,7 @@ Linux 平台工具链的标准设置 .. toctree:: :maxdepth: 1 - linux-setup-scratch + :esp32: linux-setup-scratch .. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository diff --git a/docs/zh_CN/get-started/windows-setup.rst b/docs/zh_CN/get-started/windows-setup.rst index 523956d015..1a5b763bf8 100644 --- a/docs/zh_CN/get-started/windows-setup.rst +++ b/docs/zh_CN/get-started/windows-setup.rst @@ -4,8 +4,10 @@ Windows 平台工具链的标准设置 :link_to_translation:`en:[English]` -.. note:: - 目前，基于 CMake 的构建系统仅支持 64 位 Windows 版本。32 位 Windows 版本的用户可根据 :doc:`传统 GNU Make 构建系统<../get-started-legacy/windows-setup>` 中的介绍进行操作。 +.. only:: esp32 + + .. note:: + 目前，基于 CMake 的构建系统仅支持 64 位 Windows 版本。32 位 Windows 版本的用户可根据 :doc:`传统 GNU Make 构建系统<../get-started-legacy/windows-setup>` 中的介绍进行操作。 概述 ============ @@ -14,8 +16,10 @@ ESP-IDF 需要安装一些必备工具，才能围绕 ESP32 构建固件，包 在本入门指南中，我们通过 **命令提示符** 进行有关操作。不过，您在安装 ESP-IDF 后还可以使用 :doc:`Eclipse ` 或其他支持 CMake 的图形化工具 IDE。 -.. note:: - 较早 ESP-IDF 版本使用 :doc:`传统 GNU Make 编译系统<../get-started-legacy/windows-setup>` 和 MSYS2_ Unix 兼容环境。但如今已非必需，用户可直接通过 Windows 命令提示符使用 ESP-IDF。 +.. only:: esp32 + + .. note:: + 较早 ESP-IDF 版本使用 :doc:`传统 GNU Make 编译系统<../get-started-legacy/windows-setup>` 和 MSYS2_ Unix 兼容环境。但如今已非必需，用户可直接通过 Windows 命令提示符使用 ESP-IDF。 .. _get-started-windows-tools-installer: From fdbcc1240134f32d85ec6962a8a46c2b62dc34ec Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 10 Dec 2019 16:57:57 +1100 Subject: [PATCH 12/47] doc: Fix RMT waveform path warnings --- docs/en/api-reference/peripherals/rmt.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/en/api-reference/peripherals/rmt.rst b/docs/en/api-reference/peripherals/rmt.rst index 2a1c8cdb12..c4c7985499 100644 --- a/docs/en/api-reference/peripherals/rmt.rst +++ b/docs/en/api-reference/peripherals/rmt.rst @@ -23,13 +23,13 @@ The signal, which consists of a series of pulses, is generated by RMT's transmit a [style=none, width=100, label="{11,high,7,low},\n{5,high,5,low},\n..."] b [label="Waveform\nGenerator"] - c [style=none, label="", background="../_static/rmt-waveform.png"] + c [style=none, label="", background="../../../_static/rmt-waveform.png"] d [shape=beginpoint, label="mod"] e [style=none, width=60, height=40, label="Carrier\nenable"] f [label="Carrier\nGenerator"] - g [style=none, label="", background="../_static/rmt-carrier.png"] + g [style=none, label="", background="../../../_static/rmt-carrier.png"] h [shape=none] - o [style=none, label="", background="../_static/rmt-waveform-modulated.png"] + o [style=none, label="", background="../../../_static/rmt-waveform-modulated.png"] group { label = Input @@ -63,7 +63,7 @@ The reverse operation is performed by the receiver, where a series of pulses is e -- f; f -> b [folded]; - a [style=none, label="", background="../_static/rmt-waveform.png"] + a [style=none, label="", background="../../../_static/rmt-waveform.png"] b [label=Filter] c [label="Edge\nDetect"] d [style=none, width=100, label="{11,high,7,low},\n{5,high,5,low},\n..."] From d97b587871f99d56c515419a11c3cdc224d3a63c Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 10 Dec 2019 16:59:15 +1100 Subject: [PATCH 13/47] docs: Clear _Static_assert related warnings Unclear why defining _Static_assert(x, y) in PREDEFINED list doesn't match anything, but defining _Static_assert() does match. --- docs/Doxyfile | 2 +- docs/sphinx-known-warnings.txt | 57 ---------------------------------- 2 files changed, 1 insertion(+), 58 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 3975405111..6ff8d2f76a 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -302,7 +302,7 @@ EXPAND_ONLY_PREDEF = YES PREDEFINED = \ $(ENV_DOXYGEN_DEFINES) \ __attribute__(x)= \ - _Static_assert(x) = \ + _Static_assert()= \ IDF_DEPRECATED(X)= \ IRAM_ATTR= \ configSUPPORT_DYNAMIC_ALLOCATION=1 \ diff --git a/docs/sphinx-known-warnings.txt b/docs/sphinx-known-warnings.txt index 140b700665..bb2c611b6c 100644 --- a/docs/sphinx-known-warnings.txt +++ b/docs/sphinx-known-warnings.txt @@ -76,63 +76,6 @@ If type alias or template alias: void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param) ----^ -mcpwm.inc:line: WARNING: Error when parsing function declaration. -If the function has no return type: - Error in declarator or parameters and qualifiers - Invalid definition: Expected identifier in nested name. [error at 31] - _Static_assert(MCPWM_UNIT_MAX, "MCPWM unit number not equal to chip capabilities") - -------------------------------^ -If the function has a return type: - Error in declarator - If pointer to member declarator: - Invalid definition: Expected identifier in nested name. [error at 14] - _Static_assert(MCPWM_UNIT_MAX, "MCPWM unit number not equal to chip capabilities") - --------------^ - If declId, parameters, and qualifiers: - Invalid definition: Expected identifier in nested name. [error at 14] - _Static_assert(MCPWM_UNIT_MAX, "MCPWM unit number not equal to chip capabilities") - --------------^ - If parenthesis in noptr-declarator: - Error in declarator or parameters and qualifiers - If pointer to member declarator: - Invalid definition: Expected '::' in pointer to member (function). [error at 29] - _Static_assert(MCPWM_UNIT_MAX, "MCPWM unit number not equal to chip capabilities") - -----------------------------^ - If declarator-id: - Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 29] - _Static_assert(MCPWM_UNIT_MAX, "MCPWM unit number not equal to chip capabilities") - -----------------------------^ -mcpwm.inc:line: WARNING: Error when parsing function declaration. -If the function has no return type: - Error in declarator or parameters and qualifiers - Invalid definition: Expected identifier in nested name, got keyword: sizeof [error at 21] - _Static_assert(sizeof( ulp_insn_t ), "ULP coprocessor instruction size should be 4 bytes") - ---------------------^ -If the function has a return type: - Error in declarator - If pointer to member declarator: - Invalid definition: Expected identifier in nested name. [error at 14] - _Static_assert(sizeof( ulp_insn_t ), "ULP coprocessor instruction size should be 4 bytes") - --------------^ - If declId, parameters, and qualifiers: - Invalid definition: Expected identifier in nested name. [error at 14] - _Static_assert(sizeof( ulp_insn_t ), "ULP coprocessor instruction size should be 4 bytes") - --------------^ - If parenthesis in noptr-declarator: - Error in declarator or parameters and qualifiers - If pointer to member declarator: - Invalid definition: Expected identifier in nested name, got keyword: sizeof [error at 21] - _Static_assert(sizeof( ulp_insn_t ), "ULP coprocessor instruction size should be 4 bytes") - ---------------------^ - If declarator-id: - Invalid definition: Expected identifier in nested name, got keyword: sizeof [error at 21] - _Static_assert(sizeof( ulp_insn_t ), "ULP coprocessor instruction size should be 4 bytes") - ---------------------^ -mcpwm.inc:line: WARNING: doxygenfunction: Unable to resolve multiple matches for function "_Static_assert" with arguments () in doxygen xml output for project "esp32-idf" from directory: xml_in/. -Potential matches: - - _Static_assert(MCPWM_UNIT_MAX, "MCPWM unit number not equal to chip capabilities") - - _Static_assert(sizeof( ulp_insn_t ), "ULP coprocessor instruction size should be 4 bytes") - # # Issue present only when building on msys2 / mingw32 END <<< # From 1318623831973753b5b3afbd3e00901b69cf8f4c Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 10 Dec 2019 17:26:12 +1100 Subject: [PATCH 14/47] docs: Don't search in _static directories for rst files --- docs/conf_common.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf_common.py b/docs/conf_common.py index 2deb903a93..7075a1e501 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -118,7 +118,7 @@ print('Version: {0} Release: {1}'.format(version, release)) # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['**/inc/**'] +exclude_patterns = ['**/inc/**', '_static'] # Add target-specific excludes based on tags (for the IDF_TARGET). Haven't found any better way to do this yet From c848aa74ac034e0ea819909c52509b8b12519569 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Fri, 6 Dec 2019 17:22:55 +0800 Subject: [PATCH 15/47] doc: Add extension that replaces generic target variable with idf_target Also changed event trigger for idf-extension to use config-updated, as this makes more logical sense Includes functionality for defining local (single .rst file) substitution strings that depend on chip target. Substitutions can be defined with {IDF_TARGET_X: default = "IO3", esp32 = "IO4"} and then used locally as {IDF_TARGET_X} Also added global substitution for TRM links {IDF_TARGET_TRM_URL} --- docs/conf_common.py | 12 ++- docs/idf_extensions/build_system/__init__.py | 9 +- docs/idf_extensions/format_idf_target.py | 94 ++++++++++++++++++++ 3 files changed, 108 insertions(+), 7 deletions(-) create mode 100644 docs/idf_extensions/format_idf_target.py diff --git a/docs/conf_common.py b/docs/conf_common.py index 7075a1e501..213c03d875 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -34,7 +34,7 @@ suppress_warnings = ['image.nonlocal_uri'] # If your documentation needs a minimal Sphinx version, state it here. # needs_sphinx = '1.0' - +idf_target = '' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. @@ -61,6 +61,7 @@ extensions = ['breathe', 'idf_extensions.kconfig_reference', 'idf_extensions.run_doxygen', 'idf_extensions.gen_idf_tools_links', + 'idf_extensions.format_idf_target', # from https://github.com/pfalcon/sphinx_selective_exclude 'sphinx_selective_exclude.eager_only', @@ -131,7 +132,13 @@ def update_exclude_patterns(tags): 'api-guides/esp-ble-mesh/**', 'api-guides/ulp-legacy.rst', 'api-guides/unit-tests-legacy.rst', + 'api-guides/jtag-debugging/configure-wrover.rst', 'api-reference/bluetooth/**', + 'api-reference/system/himem.rst', + 'hw-reference/get-started-devkitc.rst', + 'hw-reference/get-started-ethernet-kit.rst', + 'hw-reference/get-started-pico-kit.rst', + 'hw-reference/get-started-wrover-kit.rst', 'get-started-legacy/**', 'gnu-make-legacy.rst']: exclude_patterns.append(e) @@ -337,11 +344,12 @@ texinfo_documents = [ # texinfo_no_detailmenu = False + # Override RTD CSS theme to introduce the theme corrections # https://github.com/rtfd/sphinx_rtd_theme/pull/432 def setup(app): app.add_stylesheet('theme_overrides.css') - + app.add_config_value('idf_target', '', 'env') # Breathe extension variables (depend on build_dir) # note: we generate into xml_in and then copy_if_modified to xml dir app.config.breathe_projects = {"esp32-idf": os.path.join(app.config.build_dir, "xml_in/")} diff --git a/docs/idf_extensions/build_system/__init__.py b/docs/idf_extensions/build_system/__init__.py index f1e2e0913d..e990633c5a 100644 --- a/docs/idf_extensions/build_system/__init__.py +++ b/docs/idf_extensions/build_system/__init__.py @@ -39,20 +39,19 @@ def setup(app): except KeyError: idf_path = os.path.realpath(os.path.join(os.path.dirname(__file__), '..')) + app.add_config_value('docs_root', os.path.join(idf_path, "docs"), 'env') app.add_config_value('idf_path', idf_path, 'env') - app.add_config_value('idf_target', 'esp32', 'env') app.add_config_value('build_dir', build_dir, 'env') # not actually an IDF thing app.add_event('idf-info') - # Attaching the generate event to env-get-outdated is a bit of a hack, # we want this to run early in the docs build but unclear exactly when - app.connect('env-get-outdated', generate_idf_info) + app.connect('config-inited', generate_idf_info) return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} -def generate_idf_info(app, env, added, changed, removed): +def generate_idf_info(app, config): print("Running CMake on dummy project to get build info...") build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep)) cmake_build_dir = os.path.join(build_dir, "build_dummy_project") @@ -66,7 +65,7 @@ def generate_idf_info(app, env, added, changed, removed): project_path] if not os.path.exists(os.path.join(cmake_build_dir, "CMakeCache.txt")): # if build directory not created yet, run a reconfigure pass over it - print("Starting new dummy IDF project...") + print("Starting new dummy IDF project... w") subprocess.check_call(idf_py + ["set-target", app.config.idf_target]) else: print("Re-running CMake on the existing IDF project in {}".format(cmake_build_dir)) diff --git a/docs/idf_extensions/format_idf_target.py b/docs/idf_extensions/format_idf_target.py new file mode 100644 index 0000000000..8a2204f444 --- /dev/null +++ b/docs/idf_extensions/format_idf_target.py @@ -0,0 +1,94 @@ +import re + +TARGET_NAMES = {'esp32': 'ESP32', 'esp32s2': 'ESP32-S2'} +TOOLCHAIN_NAMES = {'esp32': 'esp', 'esp32s2': 'esp32s2'} +CONFIG_PREFIX = {'esp32': 'ESP32', 'esp32s2': 'ESP32S2'} + +TRM_URL = {'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf', + 'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf'} + +class StringSubstituter: + """ Allows for string substitution of target related strings + before any markup is parsed + + Supports the following replacements (examples shown is for target=esp32s2): + {IDF_TARGET_NAME}, replaced with the current target name, e.g. ESP32-S2 Beta + {IDF_TARGET_PATH_NAME}, replaced with the path name, e.g. esp32s2 + {IDF_TARGET_TOOLCHAIN_NAME}, replaced with the toolchain name, e.g. esp32s2 + {IDF_TARGET_CFG_PREFIX}, replaced with the prefix used for config parameters, e.g. ESP32S2 + {IDF_TARGET_TRM_URL}, replaced with the url to the technical reference manual + + Also supports defines of local (single rst file) with the format: + {IDF_TARGET_TX_PIN:default="IO3",esp32="IO4",esp32s2="IO5"} + + This will define a replacement of the tag {IDF_TARGET_TX_PIN} in the current rst-file, see e.g. uart.rst for example + + """ + RE_PATTERN = re.compile(r'^\s*{IDF_TARGET_(\w+?):(.+?)}', re.MULTILINE) + + def __init__(self): + self.substitute_strings = {} + self.local_sub_strings = {} + + def add_pair(self, tag, replace_value): + self.substitute_strings[tag] = replace_value + + def init_sub_strings(self, app, config): + self.target_name = config.idf_target + + self.add_pair("{IDF_TARGET_NAME}", TARGET_NAMES[config.idf_target]) + self.add_pair("{IDF_TARGET_PATH_NAME}", config.idf_target) + self.add_pair("{IDF_TARGET_TOOLCHAIN_NAME}", TOOLCHAIN_NAMES[config.idf_target]) + self.add_pair("{IDF_TARGET_CFG_PREFIX}", CONFIG_PREFIX[config.idf_target]) + self.add_pair("{IDF_TARGET_TRM_URL}", TRM_URL[config.idf_target]) + + def add_local_subs(self, matches): + + for sub_def in matches: + if len(sub_def) != 2: + raise ValueError("IDF_TARGET_X substitution define invalid, val={}".format(sub_def)) + + tag = "{" + "IDF_TARGET_{}".format(sub_def[0]) + "}" + + match_default = re.match(r'^\s*default(\s*)=(\s*)\"(.*?)\"', sub_def[1]) + + if match_default is None: + # There should always be a default value + raise ValueError("No default value in IDF_TARGET_X substitution define, val={}".format(sub_def)) + + match_target = re.match(r'^.*{}(\s*)=(\s*)\"(.*?)\"'.format(self.target_name), sub_def[1]) + + if match_target is None: + sub_value = match_default.groups()[2] + else: + sub_value = match_target.groups()[2] + + self.local_sub_strings[tag] = sub_value + + def substitute(self, app, docname, source): + # Add any new local tags that matches the reg.ex. + sub_defs = re.findall(self.RE_PATTERN, source[0]) + + if len(sub_defs) is not 0: + self.add_local_subs(sub_defs) + + # Remove the tag defines + source[0] = re.sub(self.RE_PATTERN,'', source[0]) + + for key in self.local_sub_strings: + source[0] = source[0].replace(key, self.local_sub_strings[key]) + + self.local_sub_strings = {} + + for key in self.substitute_strings: + source[0] = source[0].replace(key, self.substitute_strings[key]) + + +def setup(app): + sub = StringSubstituter() + + # Config values not available when setup is called + app.connect('config-inited', sub.init_sub_strings) + app.connect('source-read', sub.substitute) + + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} From 9352899d695fbc4a995f0b38d3eba83f406ba7ac Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Mon, 9 Dec 2019 11:01:09 +0800 Subject: [PATCH 16/47] doc: Update English pages with generic target name --- docs/conf_common.py | 6 + docs/en/about.rst | 15 +- docs/en/api-guides/RF_calibration.rst | 39 +- docs/en/api-guides/app_trace.rst | 27 +- docs/en/api-guides/blufi.rst | 70 +-- docs/en/api-guides/build-system-legacy.rst | 32 +- docs/en/api-guides/console.rst | 4 +- docs/en/api-guides/core_dump.rst | 10 +- docs/en/api-guides/deep-sleep-stub.rst | 10 +- .../api-guides/esp-ble-mesh/ble-mesh-faq.rst | 4 +- .../esp-ble-mesh/ble-mesh-index.rst | 12 +- docs/en/api-guides/external-ram.rst | 12 +- docs/en/api-guides/fatal-errors.rst | 70 ++- docs/en/api-guides/freertos-smp.rst | 241 +++++----- docs/en/api-guides/general-notes.rst | 22 +- docs/en/api-guides/hlinterrupts.rst | 8 +- docs/en/api-guides/index.rst | 2 +- .../jtag-debugging/building-openocd-linux.rst | 8 +- .../jtag-debugging/building-openocd-macos.rst | 9 +- .../building-openocd-windows.rst | 12 +- .../jtag-debugging/configure-other-jtag.rst | 62 ++- .../jtag-debugging/debugging-examples.rst | 155 +++--- docs/en/api-guides/jtag-debugging/index.rst | 66 +-- .../jtag-debugging/tips-and-quirks.rst | 130 +++--- .../jtag-debugging/using-debugger.rst | 46 +- .../api-guides/linker-script-generation.rst | 40 +- docs/en/api-guides/partition-tables.rst | 10 +- docs/en/api-guides/romconsole.rst | 12 +- docs/en/api-guides/tools/idf-monitor.rst | 16 +- docs/en/api-guides/ulp.rst | 16 +- docs/en/api-guides/ulp_instruction_set.rst | 28 +- docs/en/api-guides/unit-tests.rst | 22 +- docs/en/api-guides/wifi.rst | 440 +++++++++--------- docs/en/api-reference/network/esp_wifi.rst | 8 +- docs/en/api-reference/peripherals/adc.rst | 59 +-- docs/en/api-reference/peripherals/can.rst | 14 +- docs/en/api-reference/peripherals/dac.rst | 8 +- .../peripherals/esp_slave_protocol.rst | 2 +- docs/en/api-reference/peripherals/gpio.rst | 14 +- docs/en/api-reference/peripherals/i2c.rst | 13 +- docs/en/api-reference/peripherals/i2s.rst | 8 +- docs/en/api-reference/peripherals/ledc.rst | 13 +- docs/en/api-reference/peripherals/mcpwm.rst | 13 +- docs/en/api-reference/peripherals/rmt.rst | 16 +- .../protocols/esp_http_server.rst | 2 +- docs/en/api-reference/protocols/mdns.rst | 28 +- docs/en/api-reference/storage/nvs_flash.rst | 6 +- docs/en/api-reference/storage/spiffs.rst | 8 +- .../api-reference/system/app_image_format.rst | 8 +- docs/en/api-reference/system/app_trace.rst | 2 +- docs/en/api-reference/system/efuse.rst | 76 +-- docs/en/api-reference/system/heap_debug.rst | 2 +- docs/en/api-reference/system/index.rst | 4 +- docs/en/api-reference/system/intr_alloc.rst | 22 +- docs/en/api-reference/system/mem_alloc.rst | 14 +- docs/en/api-reference/system/ota.rst | 15 +- docs/en/api-reference/system/perfmon.rst | 4 +- .../api-reference/system/power_management.rst | 13 +- docs/en/api-reference/system/sleep_modes.rst | 32 +- docs/en/api-reference/system/system.rst | 54 +-- docs/en/api-reference/system/wdts.rst | 54 +-- docs/en/contribute/add-ons-reference.rst | 7 +- .../establish-serial-connection.rst | 63 +-- docs/en/get-started/index.rst | 94 ++-- docs/en/get-started/linux-setup-scratch.rst | 14 +- docs/en/get-started/linux-setup.rst | 2 +- docs/en/get-started/macos-setup-scratch.rst | 6 +- docs/en/get-started/windows-setup-scratch.rst | 6 +- docs/en/hw-reference/index.rst | 40 +- .../cloud-frameworks.rst | 10 +- docs/en/security/flash-encryption.rst | 89 ++-- docs/en/security/secure-boot.rst | 22 +- 72 files changed, 1346 insertions(+), 1175 deletions(-) diff --git a/docs/conf_common.py b/docs/conf_common.py index 213c03d875..0425b077b9 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -135,9 +135,15 @@ def update_exclude_patterns(tags): 'api-guides/jtag-debugging/configure-wrover.rst', 'api-reference/bluetooth/**', 'api-reference/system/himem.rst', + 'api-reference/system/ipc.rst', + 'hw-reference/get-started-devkitc-v2.rst', 'hw-reference/get-started-devkitc.rst', + 'hw-reference/get-started-ethernet-kit-v1.0.rst', 'hw-reference/get-started-ethernet-kit.rst', + 'hw-reference/get-started-pico-kit-v3.rst', 'hw-reference/get-started-pico-kit.rst', + 'hw-reference/get-started-wrover-kit-v2.rst', + 'hw-reference/get-started-wrover-kit-v3.rst', 'hw-reference/get-started-wrover-kit.rst', 'get-started-legacy/**', 'gnu-make-legacy.rst']: diff --git a/docs/en/about.rst b/docs/en/about.rst index c23ed2b602..2f0540106f 100644 --- a/docs/en/about.rst +++ b/docs/en/about.rst @@ -2,9 +2,18 @@ About ===== :link_to_translation:`zh_CN:[中文]` -This is documentation of `ESP-IDF `_, the framework to develop applications for `ESP32 `_ chip by `Espressif `_. +.. only:: esp32 -The ESP32 is 2.4 GHz Wi-Fi and Bluetooth combo, which integrates one or two 32-bit microprocessors, with up to 600 DMIPS processing power. + This is documentation of `ESP-IDF `_, the framework to develop applications for `{IDF_TARGET_NAME} `_ chip by `Espressif `_. + + The {IDF_TARGET_NAME} is 2.4 GHz Wi-Fi and Bluetooth combo, which integrates one or two 32-bit microprocessors, with up to 600 DMIPS processing power. + + +.. only:: esp32s2 + + This is documentation of `ESP-IDF `_, the framework to develop applications for {IDF_TARGET_NAME}. + + The {IDF_TARGET_NAME} is a 2.4 GHz Wi-Fi module, which integrates a 32-bit microprocessors, with up to 600 DMIPS processing power. .. figure:: ../_static/about-doc.png :align: center @@ -13,5 +22,5 @@ The ESP32 is 2.4 GHz Wi-Fi and Bluetooth combo, which integrates one or two 32-b Espressif IoT Integrated Development Framework -The ESP-IDF, Espressif IoT Development Framework, provides toolchain, API, components and workflows to develop applications for ESP32 using Windows, Linux and Mac OS operating systems. +The ESP-IDF, Espressif IoT Development Framework, provides toolchain, API, components and workflows to develop applications for {IDF_TARGET_NAME} using Windows, Linux and Mac OS operating systems. diff --git a/docs/en/api-guides/RF_calibration.rst b/docs/en/api-guides/RF_calibration.rst index 696cc53239..25b5862e34 100644 --- a/docs/en/api-guides/RF_calibration.rst +++ b/docs/en/api-guides/RF_calibration.rst @@ -1,7 +1,7 @@ RF calibration ============== -ESP32 supports three RF calibration methods during RF initialization: +{IDF_TARGET_NAME} supports three RF calibration methods during RF initialization: 1. Partial calibration @@ -11,8 +11,8 @@ ESP32 supports three RF calibration methods during RF initialization: Partial calibration ------------------- -During RF initialization, the partial calibration method is used by default for RF calibration. -It is done based on the full calibration data which is stored in the NVS. +During RF initialization, the partial calibration method is used by default for RF calibration. +It is done based on the full calibration data which is stored in the NVS. To use this method, please go to ``menuconfig`` and enable :ref:`CONFIG_ESP32_PHY_CALIBRATION_AND_DATA_STORAGE`. Full calibration @@ -20,8 +20,8 @@ Full calibration Full calibration is triggered in the follwing conditions: 1. NVS does not exist. - -2. The NVS partition to store calibration data is erased. + +2. The NVS partition to store calibration data is erased. 3. Hardware MAC address is changed. @@ -29,31 +29,32 @@ Full calibration is triggered in the follwing conditions: 5. The RF calibration data loaded from the NVS partition is broken. -It takes about 100ms more than partial calibration. -If boot duration is not critical, it is suggested to use the full calibration method. -To switch to the full calibration method, go to ``menuconfig`` and disable :ref:`CONFIG_ESP32_PHY_CALIBRATION_AND_DATA_STORAGE`. +It takes about 100ms more than partial calibration. +If boot duration is not critical, it is suggested to use the full calibration method. +To switch to the full calibration method, go to ``menuconfig`` and disable :ref:`CONFIG_ESP32_PHY_CALIBRATION_AND_DATA_STORAGE`. If you use the default method of RF calibration, there are two ways to add the function of triggering full calibration as a last-resort remedy. 1. Erase the NVS partition if you don't mind all of the data stored in the NVS partition is erased. That is indeed the easiest way. -2. Call API :cpp:func:`esp_phy_erase_cal_data_in_nvs` before initializing WiFi and BT/BLE based on some conditions (e.g. an option provided in some diagnostic mode). +2. Call API :cpp:func:`esp_phy_erase_cal_data_in_nvs` before initializing WiFi and BT/BLE based on some conditions (e.g. an option provided in some diagnostic mode). In this case, only phy namespace of the NVS partition is erased. No calibration --------------- -No calibration method is only used when ESP32 wakes up from deep sleep. +No calibration method is only used when {IDF_TARGET_NAME} wakes up from deep sleep. PHY initialization data ----------------------- -The PHY initialization data is used for RF calibration. -There are two ways to get the PHY initialization data. +The PHY initialization data is used for RF calibration. +There are two ways to get the PHY initialization data. -One is the default initialization data which is located in the header file :idf_file:`components/esp_wifi/esp32/include/phy_init_data.h`. -It is embedded into the application binary after compiling and then stored into read-only memory (DROM). -To use the default initialization data, please go to ``menuconfig`` and disable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION`. +One is the default initialization data which is located in the header file :idf_file:`components/esp_wifi/{IDF_TARGET_PATH_NAME}/include/phy_init_data.h`. -Another is the initialization data which is stored in a partition. -When using a custom partition table, make sure that PHY data partition is included (type: `data`, subtype: `phy`). -With default partition table, this is done automatically. -If initialization data is stored in a partition, it has to be flashed there, otherwise runtime error will occur. +It is embedded into the application binary after compiling and then stored into read-only memory (DROM). +To use the default initialization data, please go to ``menuconfig`` and disable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION`. + +Another is the initialization data which is stored in a partition. +When using a custom partition table, make sure that PHY data partition is included (type: `data`, subtype: `phy`). +With default partition table, this is done automatically. +If initialization data is stored in a partition, it has to be flashed there, otherwise runtime error will occur. To switch to the initialization data stored in a partition, go to ``menuconfig`` and enable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION`. diff --git a/docs/en/api-guides/app_trace.rst b/docs/en/api-guides/app_trace.rst index 71ecdf501a..dd95b985be 100644 --- a/docs/en/api-guides/app_trace.rst +++ b/docs/en/api-guides/app_trace.rst @@ -5,7 +5,7 @@ Application Level Tracing library Overview -------- -IDF provides useful feature for program behavior analysis: application level tracing. It is implemented in the corresponding library and can be enabled in menuconfig. This feature allows to transfer arbitrary data between host and ESP32 via JTAG interface with small overhead on program execution. +IDF provides useful feature for program behavior analysis: application level tracing. It is implemented in the corresponding library and can be enabled in menuconfig. This feature allows to transfer arbitrary data between host and {IDF_TARGET_NAME} via JTAG interface with small overhead on program execution. Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are: @@ -31,7 +31,7 @@ The library supports two modes of operation: **Post-mortem mode**. This is the default mode. The mode does not need interaction with the host side. In this mode tracing module does not check whether host has read all the data from *HW UP BUFFER* buffer and overwrites old data with the new ones. This mode is useful when only the latest trace data are interesting to the user, e.g. for analyzing program's behavior just before the crash. Host can read the data later on upon user request, e.g. via special OpenOCD command in case of working via JTAG interface. -**Streaming mode.** Tracing module enters this mode when host connects to ESP32. In this mode before writing new data to *HW UP BUFFER* tracing module checks that there is enough space in it and if necessary waits for the host to read data and free enough memory. Maximum waiting time is controlled via timeout values passed by users to corresponding API routines. So when application tries to write data to trace buffer using finite value of the maximum waiting time it is possible situation that this data will be dropped. Especially this is true for tracing from time critical code (ISRs, OS scheduler code etc.) when infinite timeouts can lead to system malfunction. In order to avoid loss of such critical data developers can enable additional data buffering via menuconfig option :ref:`CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX`. This macro specifies the size of data which can be buffered in above conditions. The option can also help to overcome situation when data transfer to the host is temporarily slowed down, e.g due to USB bus congestions etc. But it will not help when average bitrate of trace data stream exceeds HW interface capabilities. +**Streaming mode.** Tracing module enters this mode when host connects to {IDF_TARGET_NAME}. In this mode before writing new data to *HW UP BUFFER* tracing module checks that there is enough space in it and if necessary waits for the host to read data and free enough memory. Maximum waiting time is controlled via timeout values passed by users to corresponding API routines. So when application tries to write data to trace buffer using finite value of the maximum waiting time it is possible situation that this data will be dropped. Especially this is true for tracing from time critical code (ISRs, OS scheduler code etc.) when infinite timeouts can lead to system malfunction. In order to avoid loss of such critical data developers can enable additional data buffering via menuconfig option :ref:`CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX`. This macro specifies the size of data which can be buffered in above conditions. The option can also help to overcome situation when data transfer to the host is temporarily slowed down, e.g due to USB bus congestions etc. But it will not help when average bitrate of trace data stream exceeds HW interface capabilities. Configuration Options and Dependencies @@ -55,7 +55,7 @@ There are two additional menuconfig options not mentioned above: How to use this library ----------------------- -This library provides API for transferring arbitrary data between host and ESP32. When enabled in menuconfig target application tracing module is initialized automatically at the system startup, so all what the user needs to do is to call corresponding API to send, receive or flush the data. +This library provides API for transferring arbitrary data between host and {IDF_TARGET_NAME}. When enabled in menuconfig target application tracing module is initialized automatically at the system startup, so all what the user needs to do is to call corresponding API to send, receive or flush the data. .. _app_trace-application-specific-tracing: @@ -192,7 +192,7 @@ Start command syntax: ``outfile`` Path to file to save data from both CPUs. This argument should have the following format: ``file://path/to/file``. ``poll_period`` - Data polling period (in ms) for available trace data. If greater than 0 then command runs in non-blocking mode. By default 1 ms. + Data polling period (in ms) for available trace data. If greater than 0 then command runs in non-blocking mode. By default 1 ms. ``trace_size`` Maximum size of data to collect (in bytes). Tracing is stopped after specified amount of data is received. By default -1 (trace size stop trigger is disabled). ``stop_tmo`` @@ -216,7 +216,7 @@ Command usage examples: esp32 apptrace start file://trace.log 1 2048 5 0 0 - The tracing data will be retrieved and saved in non-blocking mode. This process will stop automatically after 2048 bytes are collected, or if no data are available for more than 5 seconds. + The tracing data will be retrieved and saved in non-blocking mode. This process will stop automatically after 2048 bytes are collected, or if no data are available for more than 5 seconds. .. note:: @@ -326,7 +326,7 @@ How To Use It Support for this feature is enabled by *Component config > Application Level Tracing > FreeRTOS SystemView Tracing* (:ref:`CONFIG_SYSVIEW_ENABLE`) menuconfig option. There are several other options enabled under the same menu: -1. *ESP32 timer to use as SystemView timestamp source* (:ref:`CONFIG_SYSVIEW_TS_SOURCE`) selects the source of timestamps for SystemView events. In single core mode timestamps are generated using ESP32 internal cycle counter running at maximum 240 Mhz (~4 ns granularity). In dual-core mode external timer working at 40 Mhz is used, so timestamp granularity is 25 ns. +1. {IDF_TARGET_NAME} timer to use as SystemView timestamp source: (:ref:`CONFIG_SYSVIEW_TS_SOURCE`) selects the source of timestamps for SystemView events. In single core mode timestamps are generated using {IDF_TARGET_NAME} internal cycle counter running at maximum 240 Mhz (~4 ns granularity). In dual-core mode external timer working at 40 Mhz is used, so timestamp granularity is 25 ns. 2. Individually enabled or disabled collection of SystemView events (``CONFIG_SYSVIEW_EVT_XXX``): - Trace Buffer Overflow Event @@ -340,7 +340,7 @@ Support for this feature is enabled by *Component config > Application Level Tra - Task Create Event - Task Terminate Event - System Idle Event - - Timer Enter Event + - Timer Enter Event - Timer Exit Event IDF has all the code required to produce SystemView compatible traces, so user can just configure necessary project options (see above), build, download the image to target and use OpenOCD to collect data as described in the previous sections. @@ -371,7 +371,7 @@ Start command syntax: ``outfile2`` Path to file to save data from APP CPU. This argument should have the following format: ``file://path/to/file``. ``poll_period`` - Data polling period (in ms) for available trace data. If greater then 0 then command runs in non-blocking mode. By default 1 ms. + Data polling period (in ms) for available trace data. If greater then 0 then command runs in non-blocking mode. By default 1 ms. ``trace_size`` Maximum size of data to collect (in bytes). Tracing is stopped after specified amount of data is received. By default -1 (trace size stop trigger is disabled). ``stop_tmo`` @@ -405,7 +405,7 @@ Command usage examples: Data Visualization """""""""""""""""" -After trace data are collected user can use special tool to visualize the results and inspect behavior of the program. Unfortunately SystemView does not support tracing from multiple cores. So when tracing from ESP32 working in dual-core mode two files are generated: one for PRO CPU and another one for APP CPU. User can load every file into separate instance of the tool. +After trace data are collected user can use special tool to visualize the results and inspect behavior of the program. Unfortunately SystemView does not support tracing from multiple cores. So when tracing from {IDF_TARGET_NAME} working in dual-core mode two files are generated: one for PRO CPU and another one for APP CPU. User can load every file into separate instance of the tool. It is uneasy and awkward to analyze data for every core in separate instance of the tool. Fortunately there is Eclipse plugin called *Impulse* which can load several trace files and makes it possible to inspect events from both cores in one view. Also this plugin has no limitation of 1,000,000 events as compared to free version of SystemView. @@ -501,7 +501,7 @@ The dumping of coverage data is done via OpenOCD (see :doc:`JTAG Debugging <../a When the target dumps code coverage data, the ``.gcda`` files are stored in the project's build directory. For example, if ``gcov_example_main.c`` of the ``main`` component was compiled with the ``--coverage`` option, then dumping the code coverage data would generate a ``gcov_example_main.gcda`` in ``build/esp-idf/main/CMakeFiles/__idf_main.dir/gcov_example_main.c.gcda`` (or ``build/main/gcov_example_main.gcda`` if using the legacy Make build system). Note that the ``.gcno`` files produced during compilation are also placed in the same directory. -The dumping of code coverage data can be done multiple times throughout an application's life time. Each dump will simply update the ``.gcda`` file with the newest code coverage information. Code coverage data is accumulative, thus the newest data will contain the total execution count of each code path over the application's entire lifetime. +The dumping of code coverage data can be done multiple times throughout an application's life time. Each dump will simply update the ``.gcda`` file with the newest code coverage information. Code coverage data is accumulative, thus the newest data will contain the total execution count of each code path over the application's entire lifetime. ESP-IDF supports two methods of dumping code coverage data form the target to the host: @@ -511,15 +511,12 @@ ESP-IDF supports two methods of dumping code coverage data form the target to th Instant Run-Time Dump ~~~~~~~~~~~~~~~~~~~~~ -An Instant Run-Time Dump is triggered by calling the ``esp32 gcov`` OpenOCD command (via a telnet session). Once called, OpenOCD will immediately preempt the ESP32's current state and execute a builtin IDF Gcov debug stub function. The debug stub function will handle the dumping of data to the Host. Upon completion, the ESP32 will resume it's current state. - -.. note:: - Due to the use of the debug stub function, the OpenOCD Debug Stub option must be enabled in project configuration. The option can be found under ``Component config -> ESP32-specific -> OpenOCD debug stubs``. +An Instant Run-Time Dump is triggered by calling the ``esp32 gcov`` OpenOCD command (via a telnet session). Once called, OpenOCD will immediately preempt the {IDF_TARGET_NAME}'s current state and execute a builtin IDF Gcov debug stub function. The debug stub function will handle the dumping of data to the Host. Upon completion, the {IDF_TARGET_NAME} will resume it's current state. Hard-coded Dump ~~~~~~~~~~~~~~~ -A Hard-coded Dump is triggered by the application itself by calling :cpp:func:`esp_gcov_dump` from somewhere within the application. When called, the application will halt and wait for OpenOCD to connect and retrieve the code coverage data. Once :cpp:func:`esp_gcov_dump` is called, the Host must execute the ``esp32 gcov dump`` OpenOCD command (via a telnet session). The ``esp32 gcov dump`` command will cause OpenOCD to connect to the ESP32, retrieve the code coverage data, then disconnect from the ESP32 thus allowing the application to resume. Hard-coded Dumps can also be triggered multiple times throughout an application's lifetime. +A Hard-coded Dump is triggered by the application itself by calling :cpp:func:`esp_gcov_dump` from somewhere within the application. When called, the application will halt and wait for OpenOCD to connect and retrieve the code coverage data. Once :cpp:func:`esp_gcov_dump` is called, the Host must execute the ``esp32 gcov dump`` OpenOCD command (via a telnet session). The ``esp32 gcov dump`` command will cause OpenOCD to connect to the {IDF_TARGET_NAME}, retrieve the code coverage data, then disconnect from the {IDF_TARGET_NAME} thus allowing the application to resume. Hard-coded Dumps can also be triggered multiple times throughout an application's lifetime. Hard-coded dumps are useful if code coverage data is required at certain points of an application's lifetime by placing :cpp:func:`esp_gcov_dump` where necessary (e.g., after application initialization, during each iteration of an application's main loop). diff --git a/docs/en/api-guides/blufi.rst b/docs/en/api-guides/blufi.rst index 97b04dff2c..81eb66bbf6 100644 --- a/docs/en/api-guides/blufi.rst +++ b/docs/en/api-guides/blufi.rst @@ -4,7 +4,7 @@ BluFi Overview -------- -The BluFi for ESP32 is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to the ESP32. Using this information ESP32 can then e.g. connect to an AP or establish a SoftAP. +The BluFi for {IDF_TARGET_NAME} is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to the {IDF_TARGET_NAME}. Using this information {IDF_TARGET_NAME} can then e.g. connect to an AP or establish a SoftAP. Fragmenting, data encryption, checksum verification in the BluFi layer are the key elements of this process. @@ -16,29 +16,29 @@ The BluFi networking flow includes the configuration of the SoftAP and Station. The following uses Station as an example to illustrate the core parts of the procedure, including broadcast, connection, service discovery, negotiation of the shared key, data transmission, connection status backhaul. -1. Set the ESP32 into GATT Server mode and then it will send broadcasts with specific *advertising data*. You can customize this broadcast as needed, which is not a part of the BluFi Profile. +1. Set the {IDF_TARGET_NAME} into GATT Server mode and then it will send broadcasts with specific *advertising data*. You can customize this broadcast as needed, which is not a part of the BluFi Profile. -2. Use the App installed on the mobile phone to search for this particular broadcast. The mobile phone will connect to ESP32 as the GATT Client once the broadcast is confirmed. The App used during this part is up to you. +2. Use the App installed on the mobile phone to search for this particular broadcast. The mobile phone will connect to {IDF_TARGET_NAME} as the GATT Client once the broadcast is confirmed. The App used during this part is up to you. -3. After the GATT connection is successfully established, the mobile phone will send a data frame for key negotiation to ESP32 (see the section :ref:`frame_formats` for details). +3. After the GATT connection is successfully established, the mobile phone will send a data frame for key negotiation to {IDF_TARGET_NAME} (see the section :ref:`frame_formats` for details). -4. After ESP32 receives the data frame of key negotiation, it will parse the content according to the user-defined negotiation method. +4. After {IDF_TARGET_NAME} receives the data frame of key negotiation, it will parse the content according to the user-defined negotiation method. -5. The mobile phone works with ESP32 for key negotiation using the encryption algorithms such as DH, RSA or ECC. +5. The mobile phone works with {IDF_TARGET_NAME} for key negotiation using the encryption algorithms such as DH, RSA or ECC. -6. After the negotiation process is completed, the mobile phone will send a control frame for security-mode setup to ESP32. +6. After the negotiation process is completed, the mobile phone will send a control frame for security-mode setup to {IDF_TARGET_NAME}. -7. When receiving this control frame, ESP32 will be able to encrypt and decrypt the communication data using the shared key and the security configuration. +7. When receiving this control frame, {IDF_TARGET_NAME} will be able to encrypt and decrypt the communication data using the shared key and the security configuration. -8. The mobile phone sends the data frame defined in the section of :ref:`frame_formats`，with the Wi-Fi configuration information to ESP32, including SSID, password, etc. +8. The mobile phone sends the data frame defined in the section of :ref:`frame_formats`，with the Wi-Fi configuration information to {IDF_TARGET_NAME}, including SSID, password, etc. -9. The mobile phone sends a control frame of Wi-Fi connection request to ESP32. When receiving this control frame, ESP32 will regard the communication of essential information as done and get ready to connect to the Wi-Fi. +9. The mobile phone sends a control frame of Wi-Fi connection request to {IDF_TARGET_NAME}. When receiving this control frame, {IDF_TARGET_NAME} will regard the communication of essential information as done and get ready to connect to the Wi-Fi. -10. After connecting to the Wi-Fi, ESP32 will send a control frame of Wi-Fi connection status report to the mobile phone，to report the connection status. At this point the networking procedure is completed. +10. After connecting to the Wi-Fi, {IDF_TARGET_NAME} will send a control frame of Wi-Fi connection status report to the mobile phone，to report the connection status. At this point the networking procedure is completed. .. note:: - 1. After ESP32 receives the control frame of security-mode configuration, it will execute the operations in accordance with the defined security mode. + 1. After {IDF_TARGET_NAME} receives the control frame of security-mode configuration, it will execute the operations in accordance with the defined security mode. 2. The data lengths before and after symmetric encryption/decryption must stay the same. It also supports in-place encryption and decryption. @@ -55,18 +55,18 @@ The flow chart of BluFi node_height = 60; edge_length = 380; span_height = 10; - default_fontsize = 12; + default_fontsize = 12; - Phone <- ESP32 [label="Advertising"]; - Phone -> ESP32 [label="Create GATT connection"]; - Phone <- ESP32 [label="Negotiate key procedure"]; - Phone -> ESP32 [label="Negotiate key procedure"]; - Phone -> ESP32 [label="CTRL: Set ESP32 to Phone Security mode"]; - Phone -> ESP32 [label="DATA: SSID"]; - Phone -> ESP32 [label="DATA: Password"]; - Phone -> ESP32 [label="DATA: Other information, such as CA certification"]; - Phone -> ESP32 [label="CTRL: Connect to AP"]; - Phone <- ESP32 [label="DATA: Connection State Report"]; + Phone <- {IDF_TARGET_NAME} [label="Advertising"]; + Phone -> {IDF_TARGET_NAME} [label="Create GATT connection"]; + Phone <- {IDF_TARGET_NAME} [label="Negotiate key procedure"]; + Phone -> {IDF_TARGET_NAME} [label="Negotiate key procedure"]; + Phone -> {IDF_TARGET_NAME} [label="CTRL: Set {IDF_TARGET_NAME} to Phone Security mode"]; + Phone -> {IDF_TARGET_NAME} [label="DATA: SSID"]; + Phone -> {IDF_TARGET_NAME} [label="DATA: Password"]; + Phone -> {IDF_TARGET_NAME} [label="DATA: Other information, such as CA certification"]; + Phone -> {IDF_TARGET_NAME} [label="CTRL: Connect to AP"]; + Phone <- {IDF_TARGET_NAME} [label="DATA: Connection State Report"]; } .. _frame_formats: @@ -74,7 +74,7 @@ The flow chart of BluFi The Frame Formats Defined in BluFi ----------------------------------- -The frame formats for the communication between the mobile phone App and ESP32 are defined as follows: +The frame formats for the communication between the mobile phone App and {IDF_TARGET_NAME} are defined as follows: The frame format with no fragment (8 bit)： @@ -144,8 +144,8 @@ The format of Ack Frame（8 bit）： * The control frame is not encrypted for the time being and supports to be verified; * The data frame supports to be encrypted and verified. - - **1.1 Control Frame (0x0 b’00)** + + **1.1 Control Frame (0x0 b’00)** +-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ | Control Frame (Binary) | Implication | Explanation | Note | @@ -391,8 +391,8 @@ The format of Ack Frame（8 bit）： This field takes 2 bytes that is used to check "sequence + data length + clear text data". -The Security Implementation of ESP32 -------------------------------------- +The Security Implementation of {IDF_TARGET_NAME} +------------------------------------------------ 1. Securing data @@ -410,15 +410,15 @@ The Security Implementation of ESP32 It is added to the Sequence field and used during the checksum verification. - For the coding of ESP32, you can determine and develop the security processing, such as key negotiation. The mobile application sends the negotiation data to ESP32 and then the data will be sent to the application layer for processing. If the application layer does not process it, you can use the DH encryption algorithm provided by BluFi to negotiate the key. - + For the coding of {IDF_TARGET_NAME}, you can determine and develop the security processing, such as key negotiation. The mobile application sends the negotiation data to {IDF_TARGET_NAME} and then the data will be sent to the application layer for processing. If the application layer does not process it, you can use the DH encryption algorithm provided by BluFi to negotiate the key. + The application layer needs to register several security-related functions to BluFi: -.. code-block:: c +.. code-block:: c typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free) -This function is for ESP32 to receive normal data during negotiation, and after processing is completed, the data will be transmitted using Output_data and Output_len. +This function is for {IDF_TARGET_NAME} to receive normal data during negotiation, and after processing is completed, the data will be transmitted using Output_data and Output_len. BluFi will send output_data from Negotiate_data_handler after Negotiate_data_handler is called. @@ -426,7 +426,7 @@ Here are two "*", because the length of the data to be emitted is unknown that r .. code-block:: c - typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int cyprt_len) + typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int cyprt_len) The data to be encrypted and decrypted must use the same length. The IV8 is a 8 bit sequence value of frames, which can be used as a 8 bit of IV. @@ -450,6 +450,6 @@ UUID BluFi Service UUID: 0xFFFF，16 bit -BluFi (the mobile -> ESP32): 0xFF01, writable +BluFi (the mobile -> {IDF_TARGET_NAME}): 0xFF01, writable -Blufi (ESP32 -> the mobile phone): 0xFF02, readable and callable +Blufi ({IDF_TARGET_NAME} -> the mobile phone): 0xFF02, readable and callable diff --git a/docs/en/api-guides/build-system-legacy.rst b/docs/en/api-guides/build-system-legacy.rst index b1ab9eb14f..553236f1c1 100644 --- a/docs/en/api-guides/build-system-legacy.rst +++ b/docs/en/api-guides/build-system-legacy.rst @@ -22,7 +22,7 @@ Overview An ESP-IDF project can be seen as an amalgamation of a number of components. For example, for a webserver that shows the current humidity, there could be: -- The ESP32 base libraries (libc, rom bindings etc) +- The {IDF_TARGET_NAME} base libraries (libc, rom bindings etc) - The Wi-Fi drivers - A TCP/IP stack - The FreeRTOS operating system @@ -107,7 +107,7 @@ Minimal Example Makefile :: PROJECT_NAME := myProject - + include $(IDF_PATH)/make/project.mk @@ -150,10 +150,10 @@ 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 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 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. +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. Minimal Component Makefile @@ -191,7 +191,7 @@ The following variables are set at the project level, but exported for use in th - ``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_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: Components of ESP-IDF version, to be used in conditional expressions. Note that this information is less precise than that provided by ``IDF_VER`` variable. ``v4.0-dev-*``, ``v4.0-beta1``, ``v4.0-rc1`` and ``v4.0`` will all have the same values of ``ESP_IDF_VERSION_*`` variables, but different ``IDF_VER`` values. -- ``PROJECT_VER``: Project version. +- ``PROJECT_VER``: Project version. * If :ref:`CONFIG_APP_PROJECT_VER_FROM_CONFIG` option is set, the value of :ref:`CONFIG_APP_PROJECT_VER` will be used. * Else, if ``PROJECT_VER`` variable is set in project Makefile file, its value will be used. @@ -285,7 +285,7 @@ The following variables can be set inside ``component.mk`` to control the build settings. Component-specific additions can be made via ``CXXFLAGS +=``. It is also possible (although not recommended) to override this variable completely for a component. -- ``COMPONENT_ADD_LDFRAGMENTS``: Paths to linker fragment files for the linker +- ``COMPONENT_ADD_LDFRAGMENTS``: Paths to linker fragment files for the linker script generation functionality. See :doc:`Linker Script Generation `. To apply compilation flags to a single source file, you can add a variable override as a target, ie:: @@ -326,7 +326,7 @@ Top Level: Project Makefile - ``project.mk`` fills in default project-level make variables and includes make variables from the project configuration. If the generated makefile containing project configuration is out of date, then it is regenerated (via targets in ``project_config.mk``) and then the make process restarts from the top. - ``project.mk`` builds a list of components to build, based on the default component directories or a custom list of components set in `optional project variables`. - Each component can set some `optional project-wide component variables`_. These are included via generated makefiles named ``component_project_vars.mk`` - there is one per component. These generated makefiles are included into ``project.mk``. If any are missing or out of date, they are regenerated (via a recursive make call to the component makefile) and then the make process restarts from the top. -- `Makefile.projbuild` files from components are included into the make process, to add extra targets or configuration. +- `Makefile.projbuild` files from components are included into the make process, to add extra targets or configuration. - By default, the project makefile also generates top-level build & clean targets for each component and sets up `app` and `clean` targets to invoke all of these sub-targets. - In order to compile each component, a recursive make is performed for the component makefile. @@ -484,11 +484,11 @@ has the compile_only_if and compile_only_if_not macros: $(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o) -As can be seen in the example, the ``compile_only_if`` macro takes a condition and a +As can be seen in the example, the ``compile_only_if`` macro takes a condition and a list of object files as parameters. If the condition is true (in this case: if the BAR feature is enabled in menuconfig) the object files (in this case: bar.o) will -always be compiled. The opposite goes as well: if the condition is not true, bar.o -will never be compiled. ``compile_only_if_not`` does the opposite: compile if the +always be compiled. The opposite goes as well: if the condition is not true, bar.o +will never be compiled. ``compile_only_if_not`` does the opposite: compile if the condition is false, not compile if the condition is true. This can also be used to select or stub out an implementation, as such: @@ -523,12 +523,12 @@ This can also be used to select or stub out an implementation, as such: $(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o) 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 +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 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 -``COMPONENT_OBJS``. While this still is possible, this will only work when all object +``COMPONENT_OBJS``. While this still is possible, this will only work when all object files for a component are named explicitely, and will not clean up deselected object files in a ``make clean`` pass.) @@ -596,8 +596,8 @@ For an example of using this technique, see :example:`protocols/https_request` - Code and Data Placements ------------------------ -ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through -linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking +ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through +linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking app binary. See :doc:`Linker Script Generation ` for a quick start guide as well as a detailed discussion of the mechanism. diff --git a/docs/en/api-guides/console.rst b/docs/en/api-guides/console.rst index 3f10279db8..c04309924b 100644 --- a/docs/en/api-guides/console.rst +++ b/docs/en/api-guides/console.rst @@ -14,9 +14,9 @@ These facilities can be used together or independently. For example, it is possi Line editing ------------ -Line editing feature lets users compose commands by typing them, erasing symbols using 'backspace' key, navigating within the command using left/right keys, navigating to previously typed commands using up/down keys, and performing autocompletion using 'tab' key. +Line editing feature lets users compose commands by typing them, erasing symbols using 'backspace' key, navigating within the command using left/right keys, navigating to previously typed commands using up/down keys, and performing autocompletion using 'tab' key. -.. note:: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running get_started/console example instead of a command prompt (``[esp32]>``), it means that the serial monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and idf_monitor.py (which can be invoked using ``idf.py monitor`` from project directory). +.. note:: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running get_started/console example instead of a command prompt (``[{IDF_TARGET_PATH_NAME}]>``), it means that the serial monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and idf_monitor.py (which can be invoked using ``idf.py monitor`` from project directory). Here is an overview of functions provided by `linenoise`_ library. diff --git a/docs/en/api-guides/core_dump.rst b/docs/en/api-guides/core_dump.rst index 68f5224154..8a6c0427e6 100644 --- a/docs/en/api-guides/core_dump.rst +++ b/docs/en/api-guides/core_dump.rst @@ -1,9 +1,15 @@ -ESP32 Core Dump -=============== +{IDF_TARGET_NAME} Core Dump +=========================== Overview -------- +.. only:: esp32s2 + + .. note:: + + The python utility does not currently support ESP32-S2 + ESP-IDF provides support to generate core dumps on unrecoverable software errors. This useful technique allows post-mortem analysis of software state at the moment of failure. Upon the crash system enters panic state, prints some information and halts or reboots depending configuration. User can choose to generate core dump in order to analyse the reason of failure on PC later on. Core dump contains snapshots of all tasks in the system at the moment of failure. Snapshots include tasks control blocks (TCB) and stacks. diff --git a/docs/en/api-guides/deep-sleep-stub.rst b/docs/en/api-guides/deep-sleep-stub.rst index 5cd98144eb..28732497e3 100644 --- a/docs/en/api-guides/deep-sleep-stub.rst +++ b/docs/en/api-guides/deep-sleep-stub.rst @@ -1,7 +1,7 @@ Deep Sleep Wake Stubs ===================== -ESP32 supports running a "deep sleep wake stub" when coming out of deep sleep. This function runs immediately as soon as the chip wakes up - before any normal initialisation, bootloader, or ESP-IDF code has run. After the wake stub runs, the SoC can go back to sleep or continue to start ESP-IDF normally. +{IDF_TARGET_NAME} supports running a "deep sleep wake stub" when coming out of deep sleep. This function runs immediately as soon as the chip wakes up - before any normal initialisation, bootloader, or ESP-IDF code has run. After the wake stub runs, the SoC can go back to sleep or continue to start ESP-IDF normally. Deep sleep wake stub code is loaded into "RTC Fast Memory" and any data which it uses must also be loaded into RTC memory. RTC memory regions hold their contents during deep sleep. @@ -33,7 +33,7 @@ It is not necessary to implement ``esp_wake_deep_sleep()`` in your app in order If you want to swap between different deep sleep stubs at runtime, it is also possible to do this by calling the ``esp_set_deep_sleep_wake_stub()`` function. This is not necessary if you only use the default ``esp_wake_deep_sleep()`` function. -All of these functions are declared in the ``esp_deepsleep.h`` header under components/esp32. +All of these functions are declared in the ``esp_sleep.h`` header under components/{IDF_TARGET_PATH_NAME}. Loading Code Into RTC Memory ---------------------------- @@ -69,9 +69,11 @@ The first way is to use the ``RTC_DATA_ATTR`` and ``RTC_RODATA_ATTR`` to specify ets_printf(fmt_str, wake_count++); } -The RTC memory area where this data will be placed can be configured via menuconfig option named ``CONFIG_ESP32_RTCDATA_IN_FAST_MEM``. This option allows to keep slow memory area for ULP programs and once it is enabled the data marked with ``RTC_DATA_ATTR`` and ``RTC_RODATA_ATTR`` are placed in the RTC fast memory segment otherwise it goes to RTC slow memory (default option). This option depends on the ``CONFIG_FREERTOS_UNICORE`` because RTC fast memory can be accessed only by PRO_CPU. +.. only:: esp32 -The similar attributes ``RTC_FAST_ATTR`` and ``RTC_SLOW_ATTR`` can be used to specify data that will be force placed into RTC_FAST and RTC_SLOW memory respectively. Any access to data marked with ``RTC_FAST_ATTR`` is allowed by PRO_CPU only and it is responsibility of user to make sure about it. + The RTC memory area where this data will be placed can be configured via menuconfig option named ``CONFIG_ESP32_RTCDATA_IN_FAST_MEM``. This option allows to keep slow memory area for ULP programs and once it is enabled the data marked with ``RTC_DATA_ATTR`` and ``RTC_RODATA_ATTR`` are placed in the RTC fast memory segment otherwise it goes to RTC slow memory (default option). This option depends on the ``CONFIG_FREERTOS_UNICORE`` because RTC fast memory can be accessed only by PRO_CPU. + +The attributes ``RTC_FAST_ATTR`` and ``RTC_SLOW_ATTR`` can be used to specify data that will be force placed into RTC_FAST and RTC_SLOW memory respectively. Any access to data marked with ``RTC_FAST_ATTR`` is allowed by PRO_CPU only and it is responsibility of user to make sure about it. Unfortunately, any string constants used in this way must be declared as arrays and marked with RTC_RODATA_ATTR, as shown in the example above. diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst index 6fef33dce7..55eaddca7e 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst @@ -647,8 +647,8 @@ You can find meaning of errors or warnings when they appear at the bottom of ESP The examples use :cpp:func:`ESP_LOG_BUFFER_HEX` to print the message context while the ESP-BLE-MESH protocol stack uses :cpp:func:`bt_hex`. -7.2 Which API can be used to restart ESP32? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +7.2 Which API can be used to restart {IDF_TARGET_NAME}? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The API :cpp:func:`esp_restart`. diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst index 231b755a36..3e610a9a6e 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst @@ -14,11 +14,11 @@ Built on top of Zephyr Bluetooth Mesh stack, the ESP-BLE-MESH implementation sup Please see the :doc:`ble-mesh-architecture` for information about the implementation of ESP-BLE-MESH architecture and :doc:`ESP-BLE-MESH API Reference <../../api-reference/bluetooth/esp-ble-mesh>` for information about respective API. -ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.1, users can refer `here `_ for the certification details of ESP-BLE-MESH. +ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.1, users can refer `here `_ for the certification details of ESP-BLE-MESH. .. note:: - If you are looking for Wi-Fi based implementation of mesh for ESP32, please check another product by Espressif called ESP-MESH. For more information and documentation see :doc:`ESP-MESH <../../api-reference/network/esp_mesh>`. + If you are looking for Wi-Fi based implementation of mesh for {IDF_TARGET_NAME}, please check another product by Espressif called ESP-MESH. For more information and documentation see :doc:`ESP-MESH <../../api-reference/network/esp_mesh>`. .. _getting-started-with-ble-mesh: @@ -26,7 +26,7 @@ ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0. Getting Started with ESP-BLE-MESH ================================= -This section is intended to help you get started with ESP-BLE-MESH for the hardware based on the ESP32 chip by Espressif. +This section is intended to help you get started with ESP-BLE-MESH for the hardware based on the {IDF_TARGET_NAME} chip by Espressif. We are going to demonstrate process of setting and operation of a small ESP-BLE-MESH network of three nodes. This process will cover device provisioning and node configuration, and then sending on/off commands to Generic OnOff Server Models on specific nodes. @@ -38,14 +38,14 @@ What You Need Hardware: -* Three ESP32 boards, see :ref:`options `. +* Three {IDF_TARGET_NAME} boards, see :ref:`options `. * USB cables to connect the boards. * Computer configured with ESP-IDF. * Mobile phone or tablet running Android or iOS. Software: -* Example application :example:`bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server` code to load to the ESP32 boards. +* Example application :example:`bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server` code to load to the ${IDF_TARGET_NAME} boards. * Mobile App: **nRF Mesh** for Android or iOS. Optionally you can use some other Apps: - `EspBleMesh `_ Android App @@ -219,7 +219,7 @@ ESP-BLE-MESH Examples * ESP-BLE-MESH Fast Provisioning - :example:`Client ` and :example:`Server ` - this example is used for showing how fast provisioning can be used in order to create a mesh network. It takes no more than 60 seconds to provision 100 devices, see :example:`example client code ` and :example:`example server code `. -* :example:`ESP-BLE-MESH and Wi-Fi Coexistence ` - an example that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of ESP32. Simply put, users can use the Wi-Fi while operating Bluetooth, see :example:`example code `. +* :example:`ESP-BLE-MESH and Wi-Fi Coexistence ` - an example that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of {IDF_TARGET_NAME}. Simply put, users can use the Wi-Fi while operating Bluetooth, see :example:`example code `. * ESP-BLE-MESH Node Console - an example that implements BLE Mesh node basic features. Within this example a node can be scanned and provisioned by Provisioner and reply to get/set message from Provisioner, see :example:`example node code ` and :example:`example Provisioner code `. diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index 18eb536b01..2771ded682 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -9,15 +9,15 @@ Support for external RAM Introduction ============ -ESP32 has a few hundred kilobytes of internal RAM, residing on the same die as the rest of the chip components. It can be insufficient for some purposes, so ESP32 has the ability to also use up to 4 MB of external SPI RAM memory. The external memory is incorporated in the memory map and, with certain restrictions, is usable in the same way as internal data RAM. +{IDF_TARGET_NAME} has a few hundred kilobytes of internal RAM, residing on the same die as the rest of the chip components. It can be insufficient for some purposes, so {IDF_TARGET_NAME} has the ability to also use up to 4 MB of external SPI RAM memory. The external memory is incorporated in the memory map and, with certain restrictions, is usable in the same way as internal data RAM. Hardware ======== -ESP32 supports SPI PSRAM connected in parallel with the SPI flash chip. While ESP32 is capable of supporting several types of RAM chips, the ESP32 SDK only supports the ESP-PSRAM32 chip at the moment. +{IDF_TARGET_NAME} supports SPI PSRAM connected in parallel with the SPI flash chip. While {IDF_TARGET_NAME} is capable of supporting several types of RAM chips, ESP-IDF only supports the ESP-PSRAM32 chip at the moment. -The ESP-PSRAM32 chip is a 1.8 V device which can only be used in parallel with a 1.8 V flash component. Make sure to either set the MTDI pin to a high signal level on bootup, or program ESP32 eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip. +The ESP-PSRAM32 chip is a 1.8 V device which can only be used in parallel with a 1.8 V flash component. Make sure to either set the MTDI pin to a high signal level on bootup, or program {IDF_TARGET_NAME} eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip. To connect the ESP-PSRAM32 chip to ESP32D0W*, connect the following signals: @@ -50,10 +50,10 @@ ESP-IDF fully supports the use of external memory in applications. Once the exte .. _external_ram_config_memory_map: -Integrate RAM into the ESP32 memory map ---------------------------------------- +Integrate RAM into the {IDF_TARGET_NAME} memory map +--------------------------------------------------- -Select this option by choosing "Integrate RAM into ESP32 memory map" from :ref:`CONFIG_SPIRAM_USE`. +Select this option by choosing "Integrate RAM into memory map" from :ref:`CONFIG_SPIRAM_USE`. This is the most basic option for external SPI RAM integration. Most likely, you will need another, more advanced option. diff --git a/docs/en/api-guides/fatal-errors.rst b/docs/en/api-guides/fatal-errors.rst index 7cac04253d..8dd54b561f 100644 --- a/docs/en/api-guides/fatal-errors.rst +++ b/docs/en/api-guides/fatal-errors.rst @@ -38,16 +38,10 @@ For some of the system level checks (interrupt watchdog, cache access error), th In all cases, error cause will be printed in parens. See `Guru Meditation Errors`_ for a list of possible error causes. -.. only:: esp32 - - Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32_PANIC` configuration choice. The available options are: - -.. only:: esp32s2 - - Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32S2_PANIC` configuration choice. The available options are: +Subsequent behavior of the panic handler can be set using :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC` configuration choice. The available options are: - Print registers and reboot — default option. - + This will print register values at the point of the exception, print the backtrace, and restart the chip. - Print registers and halt @@ -64,18 +58,12 @@ In all cases, error cause will be printed in parens. See `Guru Meditation Errors Behavior of panic handler is affected by two other configuration options. -.. only:: esp32 - - - If :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used. - -.. only:: esp32s2 - - - If :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used. +- If :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used. - If :doc:`Core Dump ` feature is enabled, then system state (task stacks and registers) will be dumped either to Flash or UART, for later analysis. - If :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM` is disabled (disabled by default), the panic handler code is placed in flash memory not IRAM. This means that if ESP-IDF crashes while flash cache is disabled, the panic handler will automatically re-enable flash cache before running GDB Stub or Core Dump. This adds some minor risk, if the flash cache status is also corrupted during the crash. - + If this option is enabled, the panic handler code is placed in IRAM. This allows the panic handler to run without needing to re-enable cache first. This may be necessary to debug some complex issues with crashes while flash cache is disabled (for example, when writing to SPI flash). The following diagram illustrates panic handler behavior: @@ -84,7 +72,7 @@ The following diagram illustrates panic handler behavior: :scale: 100% :caption: Panic Handler Flowchart (click to enlarge) :align: center - + blockdiag panic-handler { orientation = portrait; edge_layout = flowchart; @@ -126,15 +114,15 @@ The following diagram illustrates panic handler behavior: Register Dump and Backtrace --------------------------- -Unless ``CONFIG_ESP32_PANIC_SILENT_REBOOT`` option is enabled, panic handler prints some of the CPU registers, and the backtrace, to the console:: +Unless ``CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC_SILENT_REBOOT`` option is enabled, panic handler prints some of the CPU registers, and the backtrace, to the console:: Core 0 register dump: - PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 - A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc - A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 - A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 - A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d - EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff + PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 + A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc + A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 + A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 + A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d + EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 @@ -149,28 +137,28 @@ Backtrace line contains PC:SP pairs, where PC is the Program Counter and SP is S If :doc:`IDF Monitor ` is used, Program Counter values will be converted to code locations (function name, file name, and line number), and the output will be annotated with additional lines:: Core 0 register dump: - PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 + PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36 - A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc - A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 - A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 + A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc + A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 + A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 0x40082d1c: _calloc_r at /Users/user/esp/esp-idf/components/newlib/syscalls.c:51 - A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d - EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff + A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d + EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36 - 0x400d0802: main_task at /Users/user/esp/esp-idf/components/esp32/cpu_start.c:470 + 0x400d0802: main_task at /Users/user/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/cpu_start.c:470 To find the location where a fatal error has happened, look at the lines which follow the "Backtrace" line. Fatal error location is the top line, and subsequent lines show the call stack. GDB Stub -------- -If ``CONFIG_ESP32_PANIC_GDBSTUB`` option is enabled, panic handler will not reset the chip when fatal error happens. Instead, it will start GDB remote protocol server, commonly referred to as GDB Stub. When this happens, GDB instance running on the host computer can be instructed to connect to the ESP32 UART port. +If ``CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC_GDBSTUB`` option is enabled, panic handler will not reset the chip when fatal error happens. Instead, it will start GDB remote protocol server, commonly referred to as GDB Stub. When this happens, GDB instance running on the host computer can be instructed to connect to the {IDF_TARGET_NAME} UART port. If :doc:`IDF Monitor ` is used, GDB is started automatically when GDB Stub prompt is detected on the UART. The output would look like this:: @@ -181,7 +169,7 @@ If :doc:`IDF Monitor ` is used, GDB is started automatically This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. - This GDB was configured as "--host=x86_64-build_apple-darwin16.3.0 --target=xtensa-esp32-elf". + This GDB was configured as "--host=x86_64-build_apple-darwin16.3.0 --target=xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf". Type "show configuration" for configuration details. For bug reporting instructions, please see: . @@ -194,7 +182,7 @@ If :doc:`IDF Monitor ` is used, GDB is started automatically 0x400e1b41 in app_main () at /Users/user/esp/example/main/main.cpp:36 36 *((int*) 0) = 0; - (gdb) + (gdb) GDB prompt can be used to inspect CPU registers, local and static variables, and arbitrary locations in memory. It is not possible to set breakpoints, change PC, or continue execution. To reset the program, exit GDB and perform external reset: Ctrl-T Ctrl-R in IDF Monitor, or using external reset button on the development board. @@ -219,10 +207,10 @@ Most common reasons for this error include: - FreeRTOS task function has returned. In FreeRTOS, if task function needs to terminate, it should call :cpp:func:`vTaskDelete` function and delete itself, instead of returning. - Failure to load next instruction from SPI flash. This usually happens if: - + - Application has reconfigured SPI flash pins as some other function (GPIO, UART, etc.). Consult Hardware Design Guidelines and the Datasheet for the chip or module for details about SPI flash pins. - - - Some external device was accidentally connected to SPI flash pins, and has interfered with communication between ESP32 and SPI flash. + + - Some external device was accidentally connected to SPI flash pins, and has interfered with communication between {IDF_TARGET_NAME} and SPI flash. InstrFetchProhibited @@ -277,13 +265,7 @@ Other Fatal Errors Brownout ^^^^^^^^ -.. only:: esp32 - - ESP32 has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_ESP32_BROWNOUT_DET` and :ref:`CONFIG_ESP32_BROWNOUT_DET_LVL_SEL` options. - -.. only:: esp32s2 - - ESP32-S2 has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_ESP32S2_BROWNOUT_DET` and :ref:`CONFIG_ESP32S2_BROWNOUT_DET_LVL_SEL` options. +{IDF_TARGET_NAME} has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_BROWNOUT_DET` and :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_BROWNOUT_DET_LVL_SEL` options. When brownout detector triggers, the following message is printed:: diff --git a/docs/en/api-guides/freertos-smp.rst b/docs/en/api-guides/freertos-smp.rst index f4386ebab6..5f99a88a02 100644 --- a/docs/en/api-guides/freertos-smp.rst +++ b/docs/en/api-guides/freertos-smp.rst @@ -4,76 +4,80 @@ ESP-IDF FreeRTOS SMP Changes Overview -------- -The vanilla FreeRTOS is designed to run on a single core. However the ESP32 is -dual core containing a Protocol CPU (known as **CPU 0** or **PRO_CPU**) and an -Application CPU (known as **CPU 1** or **APP_CPU**). The two cores are -identical in practice and share the same memory. This allows the two cores to -run tasks interchangeably between them. +.. only:: esp32 -The ESP-IDF FreeRTOS is a modified version of vanilla FreeRTOS which supports -symmetric multiprocessing (SMP). ESP-IDF FreeRTOS is based on the Xtensa port -of FreeRTOS v8.2.0. This guide outlines the major differences between vanilla -FreeRTOS and ESP-IDF FreeRTOS. The API reference for vanilla FreeRTOS can be + The vanilla FreeRTOS is designed to run on a single core. However the ESP32 is + dual core containing a Protocol CPU (known as **CPU 0** or **PRO_CPU**) and an + Application CPU (known as **CPU 1** or **APP_CPU**). The two cores are + identical in practice and share the same memory. This allows the two cores to + run tasks interchangeably between them. + +The ESP-IDF FreeRTOS is a modified version of vanilla FreeRTOS which supports +symmetric multiprocessing (SMP). ESP-IDF FreeRTOS is based on the Xtensa port +of FreeRTOS v8.2.0. This guide outlines the major differences between vanilla +FreeRTOS and ESP-IDF FreeRTOS. The API reference for vanilla FreeRTOS can be found via http://www.freertos.org/a00106.html For information regarding features that are exclusive to ESP-IDF FreeRTOS, see :doc:`ESP-IDF FreeRTOS Additions<../api-reference/system/freertos_additions>`. -:ref:`backported-features`: Although ESP-IDF FreeRTOS is based on the Xtensa +:ref:`backported-features`: Although ESP-IDF FreeRTOS is based on the Xtensa port of FreeRTOS v8.2.0, a number of FreeRTOS v9.0.0 features have been backported to ESP-IDF. -:ref:`tasks-and-task-creation`: Use :cpp:func:`xTaskCreatePinnedToCore` or -:cpp:func:`xTaskCreateStaticPinnedToCore` to create tasks in ESP-IDF FreeRTOS. The -last parameter of the two functions is ``xCoreID``. This parameter specifies -which core the task is pinned to. Acceptable values are ``0`` for **PRO_CPU**, -``1`` for **APP_CPU**, or ``tskNO_AFFINITY`` which allows the task to run on -both. +.. only:: esp32 -:ref:`round-robin-scheduling`: The ESP-IDF FreeRTOS scheduler will skip tasks when -implementing Round-Robin scheduling between multiple tasks in the Ready state -that are of the same priority. To avoid this behavior, ensure that those tasks either -enter a blocked state, or are distributed across a wider range of priorities. + :ref:`tasks-and-task-creation`: Use :cpp:func:`xTaskCreatePinnedToCore` or + :cpp:func:`xTaskCreateStaticPinnedToCore` to create tasks in ESP-IDF FreeRTOS. The + last parameter of the two functions is ``xCoreID``. This parameter specifies + which core the task is pinned to. Acceptable values are ``0`` for **PRO_CPU**, + ``1`` for **APP_CPU**, or ``tskNO_AFFINITY`` which allows the task to run on + both. -:ref:`scheduler-suspension`: Suspending the scheduler in ESP-IDF FreeRTOS will only -affect the scheduler on the the calling core. In other words, calling -:cpp:func:`vTaskSuspendAll` on **PRO_CPU** will not prevent **APP_CPU** from scheduling, and -vice versa. Use critical sections or semaphores instead for simultaneous -access protection. + :ref:`round-robin-scheduling`: The ESP-IDF FreeRTOS scheduler will skip tasks when + implementing Round-Robin scheduling between multiple tasks in the Ready state + that are of the same priority. To avoid this behavior, ensure that those tasks either + enter a blocked state, or are distributed across a wider range of priorities. -:ref:`tick-interrupt-synchronicity`: Tick interrupts of **PRO_CPU** and **APP_CPU** -are not synchronized. Do not expect to use :cpp:func:`vTaskDelay` or -:cpp:func:`vTaskDelayUntil` as an accurate method of synchronizing task execution -between the two cores. Use a counting semaphore instead as their context -switches are not tied to tick interrupts due to preemption. + :ref:`scheduler-suspension`: Suspending the scheduler in ESP-IDF FreeRTOS will only + affect the scheduler on the the calling core. In other words, calling + :cpp:func:`vTaskSuspendAll` on **PRO_CPU** will not prevent **APP_CPU** from scheduling, and + vice versa. Use critical sections or semaphores instead for simultaneous + access protection. -:ref:`critical-sections`: In ESP-IDF FreeRTOS, critical sections are implemented using -mutexes. Entering critical sections involve taking a mutex, then disabling the -scheduler and interrupts of the calling core. However the other core is left -unaffected. If the other core attemps to take same mutex, it will spin until -the calling core has released the mutex by exiting the critical section. + :ref:`tick-interrupt-synchronicity`: Tick interrupts of **PRO_CPU** and **APP_CPU** + are not synchronized. Do not expect to use :cpp:func:`vTaskDelay` or + :cpp:func:`vTaskDelayUntil` as an accurate method of synchronizing task execution + between the two cores. Use a counting semaphore instead as their context + switches are not tied to tick interrupts due to preemption. -:ref:`floating-points`: The ESP32 supports hardware acceleration of single -precision floating point arithmetic (``float``). However the use of hardware -acceleration leads to some behavioral restrictions in ESP-IDF FreeRTOS. -Therefore, tasks that utilize ``float`` will automatically be pinned to a core if -not done so already. Furthermore, ``float`` cannot be used in interrupt service -routines. + :ref:`critical-sections`: In ESP-IDF FreeRTOS, critical sections are implemented using + mutexes. Entering critical sections involve taking a mutex, then disabling the + scheduler and interrupts of the calling core. However the other core is left + unaffected. If the other core attemps to take same mutex, it will spin until + the calling core has released the mutex by exiting the critical section. -:ref:`task-deletion`: Task deletion behavior has been backported from FreeRTOS -v9.0.0 and modified to be SMP compatible. Task memory will be freed immediately -when :cpp:func:`vTaskDelete` is called to delete a task that is not currently running -and not pinned to the other core. Otherwise, freeing of task memory will still + :ref:`floating-points`: The {IDF_TARGET_NAME} supports hardware acceleration of single + precision floating point arithmetic (``float``). However the use of hardware + acceleration leads to some behavioral restrictions in ESP-IDF FreeRTOS. + Therefore, tasks that utilize ``float`` will automatically be pinned to a core if + not done so already. Furthermore, ``float`` cannot be used in interrupt service + routines. + +:ref:`task-deletion`: Task deletion behavior has been backported from FreeRTOS +v9.0.0 and modified to be SMP compatible. Task memory will be freed immediately +when :cpp:func:`vTaskDelete` is called to delete a task that is not currently running +and not pinned to the other core. Otherwise, freeing of task memory will still be delegated to the Idle Task. -:ref:`deletion-callbacks`: ESP-IDF FreeRTOS has backported the Thread Local +:ref:`deletion-callbacks`: ESP-IDF FreeRTOS has backported the Thread Local Storage Pointers (TLSP) feature. However the extra feature of Deletion Callbacks has been added. Deletion callbacks are called automatically during task deletion and are -used to free memory pointed to by TLSP. Call +used to free memory pointed to by TLSP. Call :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback()` to set TLSP and Deletion Callbacks. -:ref:`esp-idf-freertos-configuration`: Several aspects of ESP-IDF FreeRTOS can be +:ref:`esp-idf-freertos-configuration`: Several aspects of ESP-IDF FreeRTOS can be set in the project configuration (``idf.py menuconfig``) such as running ESP-IDF in Unicore (single core) Mode, or configuring the number of Thread Local Storage Pointers each task will have. @@ -89,9 +93,9 @@ The following features have been backported from FreeRTOS v9.0.0 to ESP-IDF. Static Alocation ^^^^^^^^^^^^^^^^^ -This feature has been backported from FreeRTOS v9.0.0 to ESP-IDF. The +This feature has been backported from FreeRTOS v9.0.0 to ESP-IDF. The :ref:`CONFIG_FREERTOS_SUPPORT_STATIC_ALLOCATION` option must be enabled in `menuconfig` -in order for static allocation functions to be available. Once enabled, the +in order for static allocation functions to be available. Once enabled, the following functions can be called... - :cpp:func:`xTaskCreateStatic` (see :ref:`backporting-notes` below) @@ -119,32 +123,34 @@ Other Features Backporting Notes ^^^^^^^^^^^^^^^^^ -**1)** :cpp:func:`xTaskCreateStatic` has been made SMP compatible in a similar -fashion to :cpp:func:`xTaskCreate` (see :ref:`tasks-and-task-creation`). Therefore +**1)** :cpp:func:`xTaskCreateStatic` has been made SMP compatible in a similar +fashion to :cpp:func:`xTaskCreate` (see :ref:`tasks-and-task-creation`). Therefore :cpp:func:`xTaskCreateStaticPinnedToCore` can also be called. -**2)** Although vanilla FreeRTOS allows the Timer feature's daemon task to -be statically allocated, the daemon task is always dynamically allocated in -ESP-IDF. Therefore ``vApplicationGetTimerTaskMemory`` **does not** need to be +**2)** Although vanilla FreeRTOS allows the Timer feature's daemon task to +be statically allocated, the daemon task is always dynamically allocated in +ESP-IDF. Therefore ``vApplicationGetTimerTaskMemory`` **does not** need to be defined when using statically allocated timers in ESP-IDF FreeRTOS. **3)** The Thread Local Storage Pointer feature has been modified in ESP-IDF FreeRTOS to include Deletion Callbacks (see :ref:`deletion-callbacks`). Therefore -the function :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback` can also be +the function :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback` can also be called. + + .. _tasks-and-task-creation: Tasks and Task Creation ----------------------- -Tasks in ESP-IDF FreeRTOS are designed to run on a particular core, therefore -two new task creation functions have been added to ESP-IDF FreeRTOS by -appending ``PinnedToCore`` to the names of the task creation functions in +Tasks in ESP-IDF FreeRTOS are designed to run on a particular core, therefore +two new task creation functions have been added to ESP-IDF FreeRTOS by +appending ``PinnedToCore`` to the names of the task creation functions in vanilla FreeRTOS. The vanilla FreeRTOS functions of :cpp:func:`xTaskCreate` -and :cpp:func:`xTaskCreateStatic` have led to the addition of -:cpp:func:`xTaskCreatePinnedToCore` and :cpp:func:`xTaskCreateStaticPinnedToCore` in +and :cpp:func:`xTaskCreateStatic` have led to the addition of +:cpp:func:`xTaskCreatePinnedToCore` and :cpp:func:`xTaskCreateStaticPinnedToCore` in ESP-IDF FreeRTOS (see :ref:`backported-features`). For more details see :component_file:`freertos/task.c` @@ -349,15 +355,22 @@ context switches and servicing of ISRs during a critical section. Therefore, critical sections are used as a valid protection method against simultaneous access in vanilla FreeRTOS. -On the other hand, the ESP32 has no hardware method for cores to disable each -other’s interrupts. Calling ``portDISABLE_INTERRUPTS()`` will have no effect on -the interrupts of the other core. Therefore, disabling interrupts is **NOT** -a valid protection method against simultaneous access to shared data as it -leaves the other core free to access the data even if the current core has -disabled its own interrupts. +.. only:: esp32 + + On the other hand, the ESP32 has no hardware method for cores to disable each + other’s interrupts. Calling ``portDISABLE_INTERRUPTS()`` will have no effect on + the interrupts of the other core. Therefore, disabling interrupts is **NOT** + a valid protection method against simultaneous access to shared data as it + leaves the other core free to access the data even if the current core has + disabled its own interrupts. + +.. only:: esp32s2 + + ESP-IDF contains some modifications to work with dual core concurrency, + and the dual core API is used even on a single core only chip. For this reason, ESP-IDF FreeRTOS implements critical sections using special mutexes, -referred by portMUX_Type objects on top of specific ESP32 spinlock component +referred by portMUX_Type objects on top of specific spinlock component and calls to enter or exit a critical must provide a spinlock object that is associated with a shared resource requiring access protection. When entering a critical section in ESP-IDF FreeRTOS, the calling core will disable @@ -394,46 +407,42 @@ spinlock is provided upon entering and exiting, the type of call should not matter. -.. _floating-points: +.. only:: esp32 -Floating Point Aritmetic ------------------------- + .. _floating-points: -The ESP32 supports hardware acceleration of single precision floating point -arithmetic (``float``) via Floating Point Units (FPU, also known as coprocessors) -attached to each core. The use of the FPUs imposes some behavioral restrictions -on ESP-IDF FreeRTOS. + Floating Point Arithmetic + ------------------------ -ESP-IDF FreeRTOS implements Lazy Context Switching for FPUs. In other words, -the state of a core's FPU registers are not immediately saved when a context -switch occurs. Therefore, tasks that utilize ``float`` must be pinned to a -particular core upon creation. If not, ESP-IDF FreeRTOS will automatically pin -the task in question to whichever core the task was running on upon the task's -first use of ``float``. Likewise due to Lazy Context Switching, only interrupt -service routines of lowest priority (that is it the Level 1) can use ``float``, -higher priority interrupts do not support FPU usage. - -ESP32 does not support hardware acceleration for double precision floating point -arithmetic (``double``). Instead ``double`` is implemented via software hence the -behavioral restrictions with regards to ``float`` do not apply to ``double``. Note -that due to the lack of hardware acceleration, ``double`` operations may consume -significantly larger amount of CPU time in comparison to ``float``. + ESP-IDF FreeRTOS implements Lazy Context Switching for FPUs. In other words, + the state of a core's FPU registers are not immediately saved when a context + switch occurs. Therefore, tasks that utilize ``float`` must be pinned to a + particular core upon creation. If not, ESP-IDF FreeRTOS will automatically pin + the task in question to whichever core the task was running on upon the task's + first use of ``float``. Likewise due to Lazy Context Switching, only interrupt + service routines of lowest priority (that is it the Level 1) can use ``float``, + higher priority interrupts do not support FPU usage. + ESP32 does not support hardware acceleration for double precision floating point + arithmetic (``double``). Instead ``double`` is implemented via software hence the + behavioral restrictions with regards to ``float`` do not apply to ``double``. Note + that due to the lack of hardware acceleration, ``double`` operations may consume + significantly larger amount of CPU time in comparison to ``float``. .. _task-deletion: Task Deletion ------------- -FreeRTOS task deletion prior to v9.0.0 delegated the freeing of task memory +FreeRTOS task deletion prior to v9.0.0 delegated the freeing of task memory entirely to the Idle Task. Currently, the freeing of task memory will occur -immediately (within :cpp:func:`vTaskDelete`) if the task being deleted is not currently -running or is not pinned to the other core (with respect to the core +immediately (within :cpp:func:`vTaskDelete`) if the task being deleted is not currently +running or is not pinned to the other core (with respect to the core :cpp:func:`vTaskDelete` is called on). TLSP deletion callbacks will also run immediately if the same conditions are met. -However, calling :cpp:func:`vTaskDelete` to delete a task that is either currently -running or pinned to the other core will still result in the freeing of memory +However, calling :cpp:func:`vTaskDelete` to delete a task that is either currently +running or pinned to the other core will still result in the freeing of memory being delegated to the Idle Task. @@ -442,32 +451,32 @@ being delegated to the Idle Task. Thread Local Storage Pointers & Deletion Callbacks -------------------------------------------------- -Thread Local Storage Pointers (TLSP) are pointers stored directly in the TCB. -TLSP allow each task to have its own unique set of pointers to data structures. -However task deletion behavior in vanilla FreeRTOS does not automatically +Thread Local Storage Pointers (TLSP) are pointers stored directly in the TCB. +TLSP allow each task to have its own unique set of pointers to data structures. +However task deletion behavior in vanilla FreeRTOS does not automatically free the memory pointed to by TLSP. Therefore if the memory pointed to by -TLSP is not explicitly freed by the user before task deletion, memory leak will +TLSP is not explicitly freed by the user before task deletion, memory leak will occur. -ESP-IDF FreeRTOS provides the added feature of Deletion Callbacks. Deletion +ESP-IDF FreeRTOS provides the added feature of Deletion Callbacks. Deletion Callbacks are called automatically during task deletion to free memory pointed to by TLSP. Each TLSP can have its own Deletion Callback. Note that due to the -to :ref:`task-deletion` behavior, there can be instances where Deletion +to :ref:`task-deletion` behavior, there can be instances where Deletion Callbacks are called in the context of the Idle Tasks. Therefore Deletion Callbacks **should never attempt to block** and critical sections should be kept as short as possible to minimize priority inversion. Deletion callbacks are of type ``void (*TlsDeleteCallbackFunction_t)( int, void * )`` where the first parameter -is the index number of the associated TLSP, and the second parameter is the +is the index number of the associated TLSP, and the second parameter is the TLSP itself. -Deletion callbacks are set alongside TLSP by calling -:cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback`. Calling the vanilla +Deletion callbacks are set alongside TLSP by calling +:cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback`. Calling the vanilla FreeRTOS function :cpp:func:`vTaskSetThreadLocalStoragePointer` will simply set the TLSP's associated Deletion Callback to `NULL` meaning that no callback will be called for that TLSP during task deletion. If a deletion callback is `NULL`, -users should manually free the memory pointed to by the associated TLSP before +users should manually free the memory pointed to by the associated TLSP before task deletion in order to avoid memory leak. :ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` in menuconfig can be used @@ -487,27 +496,27 @@ highlights some of the ESP-IDF FreeRTOS configuration options. For a full list o ESP-IDF FreeRTOS configurations, see :doc:`FreeRTOS <../api-reference/kconfig>` :ref:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF FreeRTOS only -on **PRO_CPU**. Note that this is **not equivalent to running vanilla -FreeRTOS**. Behaviors of multiple components in ESP-IDF will be modified such -as :component_file:`esp32/cpu_start.c`. For more details regarding the -effects of running ESP-IDF FreeRTOS on a single core, search for +on **PRO_CPU**. Note that this is **not equivalent to running vanilla +FreeRTOS**. Behaviors of multiple components in ESP-IDF will be modified such +as :component_file:`{IDF_TARGET_PATH_NAME}/cpu_start.c`. For more details regarding the +effects of running ESP-IDF FreeRTOS on a single core, search for occurences of ``CONFIG_FREERTOS_UNICORE`` in the ESP-IDF components. - -:ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` will define the -number of Thread Local Storage Pointers each task will have in ESP-IDF + +:ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` will define the +number of Thread Local Storage Pointers each task will have in ESP-IDF FreeRTOS. :ref:`CONFIG_FREERTOS_SUPPORT_STATIC_ALLOCATION` will enable the backported functionality of :cpp:func:`xTaskCreateStaticPinnedToCore` in ESP-IDF FreeRTOS - + :ref:`CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION` will trigger a halt in particular functions in ESP-IDF FreeRTOS which have not been fully tested in an SMP context. -:ref:`CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER` will enclose all task functions -within a wrapper function. In the case that a task function mistakenly returns -(i.e. does not call :cpp:func:`vTaskDelete`), the call flow will return to the -wrapper function. The wrapper function will then log an error and abort the +:ref:`CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER` will enclose all task functions +within a wrapper function. In the case that a task function mistakenly returns +(i.e. does not call :cpp:func:`vTaskDelete`), the call flow will return to the +wrapper function. The wrapper function will then log an error and abort the application, as illustrated below:: E (25) FreeRTOS: FreeRTOS task should not return. Aborting now! diff --git a/docs/en/api-guides/general-notes.rst b/docs/en/api-guides/general-notes.rst index b3860332fb..84fa489a51 100644 --- a/docs/en/api-guides/general-notes.rst +++ b/docs/en/api-guides/general-notes.rst @@ -18,7 +18,7 @@ This process is explained in detail in the following sections. First stage bootloader ^^^^^^^^^^^^^^^^^^^^^^ -After SoC reset, PRO CPU will start running immediately, executing reset vector code, while APP CPU will be held in reset. During startup process, PRO CPU does all the initialization. APP CPU reset is de-asserted in the ``call_start_cpu0`` function of application startup code. Reset vector code is located at address 0x40000400 in the mask ROM of the ESP32 chip and can not be modified. +After SoC reset, PRO CPU will start running immediately, executing reset vector code, while APP CPU will be held in reset. During startup process, PRO CPU does all the initialization. APP CPU reset is de-asserted in the ``call_start_cpu0`` function of application startup code. Reset vector code is located at address 0x40000400 in the mask ROM of the {IDF_TARGET_NAME} chip and can not be modified. Startup code called from the reset vector determines the boot mode by checking ``GPIO_STRAP_REG`` register for bootstrap pin states. Depending on the reset reason, the following takes place: @@ -28,18 +28,18 @@ Startup code called from the reset vector determines the boot mode by checking ` 3. For software CPU reset and watchdog CPU reset: configure SPI flash based on EFUSE values, and attempt to load the code from flash. This step is described in more detail in the next paragraphs. If loading code from flash fails, unpack BASIC interpreter into the RAM and start it. Note that RTC watchdog is still enabled when this happens, so unless any input is received by the interpreter, watchdog will reset the SOC in a few hundred milliseconds, repeating the whole process. If the interpreter receives any input from the UART, it disables the watchdog. -Application binary image is loaded from flash starting at address 0x1000. First 4kB sector of flash is used to store secure boot IV and signature of the application image. Please check secure boot documentation for details about this. +Application binary image is loaded from flash starting at address 0x1000. First 4kB sector of flash is used to store secure boot IV and signature of the application image. Please check secure boot documentation for details about this. .. TODO: describe application binary image format, describe optional flash configuration commands. Second stage bootloader ^^^^^^^^^^^^^^^^^^^^^^^ -In ESP-IDF, the binary image which resides at offset 0x1000 in flash is the second stage bootloader. Second stage bootloader source code is available in components/bootloader directory of ESP-IDF. Note that this arrangement is not the only one possible with the ESP32 chip. It is possible to write a fully featured application which would work when flashed to offset 0x1000, but this is out of scope of this document. Second stage bootloader is used in ESP-IDF to add flexibility to flash layout (using partition tables), and allow for various flows associated with flash encryption, secure boot, and over-the-air updates (OTA) to take place. +In ESP-IDF, the binary image which resides at offset 0x1000 in flash is the second stage bootloader. Second stage bootloader source code is available in components/bootloader directory of ESP-IDF. Note that this arrangement is not the only one possible with the {IDF_TARGET_NAME} chip. It is possible to write a fully featured application which would work when flashed to offset 0x1000, but this is out of scope of this document. Second stage bootloader is used in ESP-IDF to add flexibility to flash layout (using partition tables), and allow for various flows associated with flash encryption, secure boot, and over-the-air updates (OTA) to take place. When the first stage bootloader is finished checking and loading the second stage bootloader, it jumps to the second stage bootloader entry point found in the binary image header. -Second stage bootloader reads the partition table found at offset 0x8000. See :doc:`partition tables ` documentation for more information. The bootloader finds factory and OTA partitions, and decides which one to boot based on data found in *OTA info* partition. +Second stage bootloader reads the partition table found at offset 0x8000. See :doc:`partition tables ` documentation for more information. The bootloader finds factory and OTA partitions, and decides which one to boot based on data found in *OTA info* partition. For the selected partition, second stage bootloader copies data and code sections which are mapped into IRAM and DRAM to their load addresses. For sections which have load addresses in DROM and IROM regions, flash MMU is configured to provide the correct mapping. Note that the second stage bootloader configures flash MMU for both PRO and APP CPUs, but it only enables flash MMU for PRO CPU. Reason for this is that second stage bootloader code is loaded into the memory region used by APP CPU cache. The duty of enabling cache for APP CPU is passed on to the application. Once code is loaded and flash MMU is set up, second stage bootloader jumps to the application entry point found in the binary image header. @@ -48,9 +48,9 @@ Currently it is not possible to add application-defined hooks to the bootloader Application startup ^^^^^^^^^^^^^^^^^^^ -ESP-IDF application entry point is ``call_start_cpu0`` function found in ``components/esp32/cpu_start.c``. Two main things this function does are to enable heap allocator and to make APP CPU jump to its entry point, ``call_start_cpu1``. The code on PRO CPU sets the entry point for APP CPU, de-asserts APP CPU reset, and waits for a global flag to be set by the code running on APP CPU, indicating that it has started. Once this is done, PRO CPU jumps to ``start_cpu0`` function, and APP CPU jumps to ``start_cpu1`` function. +ESP-IDF application entry point is ``call_start_cpu0`` function found in ``components/{IDF_TARGET_PATH_NAME}/cpu_start.c``. Two main things this function does are to enable heap allocator and to make APP CPU jump to its entry point, ``call_start_cpu1``. The code on PRO CPU sets the entry point for APP CPU, de-asserts APP CPU reset, and waits for a global flag to be set by the code running on APP CPU, indicating that it has started. Once this is done, PRO CPU jumps to ``start_cpu0`` function, and APP CPU jumps to ``start_cpu1`` function. -Both ``start_cpu0`` and ``start_cpu1`` are weak functions, meaning that they can be overridden in the application, if some application-specific change to initialization sequence is needed. Default implementation of ``start_cpu0`` enables or initializes components depending on choices made in ``menuconfig``. Please see source code of this function in ``components/esp32/cpu_start.c`` for an up to date list of steps performed. Note that any C++ global constructors present in the application will be called at this stage. Once all essential components are initialized, *main task* is created and FreeRTOS scheduler is started. +Both ``start_cpu0`` and ``start_cpu1`` are weak functions, meaning that they can be overridden in the application, if some application-specific change to initialization sequence is needed. Default implementation of ``start_cpu0`` enables or initializes components depending on choices made in ``menuconfig``. Please see source code of this function in ``components/{IDF_TARGET_PATH_NAME}/cpu_start.c`` for an up to date list of steps performed. Note that any C++ global constructors present in the application will be called at this stage. Once all essential components are initialized, *main task* is created and FreeRTOS scheduler is started. While PRO CPU does initialization in ``start_cpu0`` function, APP CPU spins in ``start_cpu1`` function, waiting for the scheduler to be started on the PRO CPU. Once the scheduler is started on the PRO CPU, code on the APP CPU starts the scheduler as well. @@ -61,7 +61,7 @@ Main task is the task which runs ``app_main`` function. Main task stack size and Application memory layout ------------------------- -ESP32 chip has flexible memory mapping features. This section describes how ESP-IDF uses these features by default. +{IDF_TARGET_NAME} chip has flexible memory mapping features. This section describes how ESP-IDF uses these features by default. Application code in ESP-IDF can be placed into one of the following memory regions. @@ -75,17 +75,17 @@ A few components of ESP-IDF and parts of WiFi stack are placed into this region If some application code needs to be placed into IRAM, it can be done using ``IRAM_ATTR`` define:: #include "esp_attr.h" - + void IRAM_ATTR gpio_isr_handler(void* arg) { - // ... + // ... } Here are the cases when parts of application may or should be placed into IRAM. - Interrupt handlers must be placed into IRAM if ``ESP_INTR_FLAG_IRAM`` is used when registering the interrupt handler. In this case, ISR may only call functions placed into IRAM or functions present in ROM. *Note 1:* all FreeRTOS APIs are currently placed into IRAM, so are safe to call from interrupt handlers. If the ISR is placed into IRAM, all constant data used by the ISR and functions called from ISR (including, but not limited to, ``const char`` arrays), must be placed into DRAM using ``DRAM_ATTR``. -- Some timing critical code may be placed into IRAM to reduce the penalty associated with loading the code from flash. ESP32 reads code and data from flash via a 32 kB cache. In some cases, placing a function into IRAM may reduce delays caused by a cache miss. +- Some timing critical code may be placed into IRAM to reduce the penalty associated with loading the code from flash. {IDF_TARGET_NAME} reads code and data from flash via a 32 kB cache. In some cases, placing a function into IRAM may reduce delays caused by a cache miss. IROM (code executed from Flash) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -140,7 +140,7 @@ DMA Capable Requirement Most DMA controllers (e.g. SPI, sdmmc, etc.) have requirements that sending/receiving buffers should be placed in DRAM and word-aligned. We suggest to place DMA buffers in static variables rather than in the stack. Use macro ``DMA_ATTR`` to declare global/local static variables like:: - + DMA_ATTR uint8_t buffer[]="I want to send something"; void app_main() diff --git a/docs/en/api-guides/hlinterrupts.rst b/docs/en/api-guides/hlinterrupts.rst index 2d094bc331..42dfda7997 100644 --- a/docs/en/api-guides/hlinterrupts.rst +++ b/docs/en/api-guides/hlinterrupts.rst @@ -4,7 +4,7 @@ High-Level Interrupts .. toctree:: :maxdepth: 1 -The Xtensa architecture has support for 32 interrupts, divided over 8 levels, plus an assortment of exceptions. On the ESP32, the interrupt mux allows most interrupt sources to be routed to these interrupts using the :doc:`interrupt allocator <../api-reference/system/intr_alloc>`. Normally, interrupts will be written in C, but ESP-IDF allows high-level interrupts to be written in assembly as well, allowing for very low interrupt latencies. +The Xtensa architecture has support for 32 interrupts, divided over 8 levels, plus an assortment of exceptions. On the {IDF_TARGET_NAME}, the interrupt mux allows most interrupt sources to be routed to these interrupts using the :doc:`interrupt allocator <../api-reference/system/intr_alloc>`. Normally, interrupts will be written in C, but ESP-IDF allows high-level interrupts to be written in assembly as well, allowing for very low interrupt latencies. Interrupt Levels ---------------- @@ -28,11 +28,11 @@ Using these symbols is done by creating an assembly file (suffix .S) and definin .align 4 xt_highint5: ... your code here - rsr a0, EXCSAVE_5 + rsr a0, EXCSAVE_5 rfi 5 + For a real-life example, see the :component_file:`{IDF_TARGET_PATH_NAME}/dport_panic_highint_hdl.S` file; the panic handler interrupt is implemented there. -For a real-life example, see the :component_file:`esp32/dport_panic_highint_hdl.S` file; the panic handler interrupt is implemented there. Notes ----- @@ -49,7 +49,7 @@ Notes ld_include_my_isr_file: -(The symbol is called ``ld_include_my_isr_file`` here but can have any arbitrary name not defined anywhere else.) +(The symbol is called ``ld_include_my_isr_file`` here but can have any arbitrary name not defined anywhere else.) Then, in the component.mk, add this file as an unresolved symbol to the ld command line arguments:: COMPONENT_ADD_LDFLAGS := -u ld_include_my_isr_file diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index bd6e61eaac..d71d81ed89 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -15,7 +15,7 @@ API Guides Error Handling :esp32: ESP-BLE-MESH ESP-MESH (Wi-Fi) - ESP32 Core Dump + {IDF_TARGET_NAME} Core Dump Event Handling External SPI-connected RAM Fatal Errors diff --git a/docs/en/api-guides/jtag-debugging/building-openocd-linux.rst b/docs/en/api-guides/jtag-debugging/building-openocd-linux.rst index 846161881c..5dc2c59301 100644 --- a/docs/en/api-guides/jtag-debugging/building-openocd-linux.rst +++ b/docs/en/api-guides/jtag-debugging/building-openocd-linux.rst @@ -11,7 +11,7 @@ The following instructions are alternative to downloading binary OpenOCD from `E Download Sources of OpenOCD =========================== -The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:: +The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:: cd ~/esp git clone --recursive https://github.com/espressif/openocd-esp32.git @@ -61,9 +61,9 @@ Optionally you can add ``sudo make install`` step at the end. Skip it, if you ha .. note:: - * Should an error occur, resolve it and try again until the command ``make`` works. + * Should an error occur, resolve it and try again until the command ``make`` works. * If there is a submodule problem from OpenOCD, please ``cd`` to the ``openocd-esp32`` directory and input ``git submodule update --init``. - * If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``. + * If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``. * If the information of your device is not shown in the log, use ``./configure`` to enable it as described in ``../openocd-esp32/doc/INSTALL.txt``. * For details concerning compiling OpenOCD, please refer to ``openocd-esp32/README``. @@ -73,4 +73,4 @@ Once ``make`` process is successfully completed, the executable of OpenOCD will Next Steps ========== -To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`. +To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`. diff --git a/docs/en/api-guides/jtag-debugging/building-openocd-macos.rst b/docs/en/api-guides/jtag-debugging/building-openocd-macos.rst index 0edb05149d..860db3239d 100644 --- a/docs/en/api-guides/jtag-debugging/building-openocd-macos.rst +++ b/docs/en/api-guides/jtag-debugging/building-openocd-macos.rst @@ -10,7 +10,7 @@ The following instructions are alternative to downloading binary OpenOCD from `E Download Sources of OpenOCD =========================== -The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:: +The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:: cd ~/esp git clone --recursive https://github.com/espressif/openocd-esp32.git @@ -39,9 +39,9 @@ Optionally you can add ``sudo make install`` step at the end. Skip it, if you ha .. note:: - * Should an error occur, resolve it and try again until the command ``make`` works. + * Should an error occur, resolve it and try again until the command ``make`` works. * If there is a submodule problem from OpenOCD, please ``cd`` to the ``openocd-esp32`` directory and input ``git submodule update --init``. - * If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``. + * If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``. * If the information of your device is not shown in the log, use ``./configure`` to enable it as described in ``../openocd-esp32/doc/INSTALL.txt``. * For details concerning compiling OpenOCD, please refer to ``openocd-esp32/README.OSX``. @@ -50,6 +50,5 @@ Once ``make`` process is successfully completed, the executable of OpenOCD will Next Steps ========== -To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`. +To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`. - \ No newline at end of file diff --git a/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst b/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst index 3163c640f8..423a177dc1 100644 --- a/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst +++ b/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst @@ -29,7 +29,7 @@ Install packages that are required to compile OpenOCD:: Download Sources of OpenOCD =========================== -The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:: +The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:: cd ~/esp git clone --recursive https://github.com/espressif/openocd-esp32.git @@ -62,18 +62,18 @@ Proceed with configuring and building OpenOCD:: make cp ../libusb/MinGW32/dll/libusb-1.0.dll ./src cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src - + Optionally you can add ``make install`` step at the end. Skip it, if you have an existing OpenOCD (from e.g. another development platform), as it may get overwritten. Also you could use ``export DESTDIR="/custom/install/dir"; make install``. .. note:: - * Should an error occur, resolve it and try again until the command ``make`` works. + * Should an error occur, resolve it and try again until the command ``make`` works. * If there is a submodule problem from OpenOCD, please ``cd`` to the ``openocd-esp32`` directory and input ``git submodule update --init``. - * If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``. + * If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``. * If the information of your device is not shown in the log, use ``./configure`` to enable it as described in ``../openocd-esp32/doc/INSTALL.txt``. * For details concerning compiling OpenOCD, please refer to ``openocd-esp32/README.Windows``. - * Don't forget to copy `libusb-1.0.dll` and `libwinpthread-1.dll` into `OOCD_INSTALLDIR/bin` from ``~/esp/openocd-esp32/src``. + * Don't forget to copy `libusb-1.0.dll` and `libwinpthread-1.dll` into `OOCD_INSTALLDIR/bin` from ``~/esp/openocd-esp32/src``. Once ``make`` process is successfully completed, the executable of OpenOCD will be saved in ``~/esp/openocd-esp32/src`` directory. @@ -110,4 +110,4 @@ A complete described previously process is provided below for the faster executi Next Steps ========== -To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`. +To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`. diff --git a/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst b/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst index 8c199de6bf..9edb50fbc0 100644 --- a/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst +++ b/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst @@ -2,44 +2,64 @@ Configure Other JTAG Interface ============================== :link_to_translation:`zh_CN:[中文]` -Refer to section :ref:`jtag-debugging-selecting-jtag-adapter` for guidance what JTAG interface to select, so it is able to operate with OpenOCD and ESP32. Then follow three configuration steps below to get it working. +Refer to section :ref:`jtag-debugging-selecting-jtag-adapter` for guidance what JTAG interface to select, so it is able to operate with OpenOCD and {IDF_TARGET_NAME}. Then follow three configuration steps below to get it working. Configure Hardware ^^^^^^^^^^^^^^^^^^ -1. Identify all pins / signals on JTAG interface and ESP32 board, that should be connected to establish communication. +1. Identify all pins / signals on JTAG interface and {IDF_TARGET_NAME} board, that should be connected to establish communication. - +---+---------------+-------------+ - | | ESP32 Pin | JTAG Signal | - +===+===============+=============+ - | 1 | CHIP_PU | TRST_N | - +---+---------------+-------------+ - | 2 | MTDO / GPIO15 | TDO | - +---+---------------+-------------+ - | 3 | MTDI / GPIO12 | TDI | - +---+---------------+-------------+ - | 4 | MTCK / GPIO13 | TCK | - +---+---------------+-------------+ - | 5 | MTMS / GPIO14 | TMS | - +---+---------------+-------------+ - | 6 | GND | GND | - +---+---------------+-------------+ +.. only:: esp32 -2. Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation. + +---+-----------------------+-------------+ + | | ESP32 Pin | JTAG Signal | + +===+=======================+=============+ + | 1 | CHIP_PU | TRST_N | + +---+-----------------------+-------------+ + | 2 | MTDO / GPIO15 | TDO | + +---+-----------------------+-------------+ + | 3 | MTDI / GPIO12 | TDI | + +---+-----------------------+-------------+ + | 4 | MTCK / GPIO13 | TCK | + +---+-----------------------+-------------+ + | 5 | MTMS / GPIO14 | TMS | + +---+-----------------------+-------------+ + | 6 | GND | GND | + +---+-----------------------+-------------+ -3. Connect identified pin / signals of ESP32 and JTAG interface. +.. only:: esp32s2 + + +---+-----------------------+-------------+ + | | ESP32-S2 Pin | JTAG Signal | + +===+=======================+=============+ + | 1 | CHIP_PU | TRST_N | + +---+-----------------------+-------------+ + | 2 | MTDO / GPIO40 | TDO | + +---+-----------------------+-------------+ + | 3 | MTDI / GPIO41 | TDI | + +---+-----------------------+-------------+ + | 4 | MTCK / GPIO39 | TCK | + +---+-----------------------+-------------+ + | 5 | MTMS / GPIO42 | TMS | + +---+-----------------------+-------------+ + | 6 | GND | GND | + +---+-----------------------+-------------+ + +2. Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation. + +3. Connect identified pin / signals of {IDF_TARGET_NAME} and JTAG interface. Configure Drivers ^^^^^^^^^^^^^^^^^ -You may need to install driver s/w to make JTAG work with computer. Refer to documentation of JTAG adapter, that should provide related details. +You may need to install driver s/w to make JTAG work with computer. Refer to documentation of JTAG adapter, that should provide related details. Connect ^^^^^^^ -Connect JTAG interface to the computer. Power on ESP32 and JTAG interface boards. Check if JTAG interface is visible by computer. +Connect JTAG interface to the computer. Power on {IDF_TARGET_NAME} and JTAG interface boards. Check if JTAG interface is visible by computer. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`. diff --git a/docs/en/api-guides/jtag-debugging/debugging-examples.rst b/docs/en/api-guides/jtag-debugging/debugging-examples.rst index a8d3d2a29d..8f2954bee7 100644 --- a/docs/en/api-guides/jtag-debugging/debugging-examples.rst +++ b/docs/en/api-guides/jtag-debugging/debugging-examples.rst @@ -38,7 +38,7 @@ Examples in this section Navigating through the code, call stack and threads ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When the target is halted, debugger shows the list of threads in "Debug" window. The line of code where program halted is highlighted in another window below, as shown on the following picture. The LED stops blinking. +When the target is halted, debugger shows the list of threads in "Debug" window. The line of code where program halted is highlighted in another window below, as shown on the following picture. The LED stops blinking. .. figure:: ../../../_static/debugging-target-halted.jpg :align: center @@ -47,7 +47,7 @@ When the target is halted, debugger shows the list of threads in "Debug" window. Target halted during debugging -Specific thread where the program halted is expanded showing the call stack. It represents function calls that lead up to the highlighted line of code, where the target halted. The first line of call stack under Thread #1 contains the last called function ``app_main()``, that in turn was called from function ``main_task()`` shown in a line below. Each line of the stack also contains the file name and line number where the function was called. By clicking / highlighting the stack entries, in window below, you will see contents of this file. +Specific thread where the program halted is expanded showing the call stack. It represents function calls that lead up to the highlighted line of code, where the target halted. The first line of call stack under Thread #1 contains the last called function ``app_main()``, that in turn was called from function ``main_task()`` shown in a line below. Each line of the stack also contains the file name and line number where the function was called. By clicking / highlighting the stack entries, in window below, you will see contents of this file. By expanding threads you can navigate throughout the application. Expand Thread #5 that contains much longer call stack. You will see there, besides function calls, numbers like ``0x4000000c``. They represent addresses of binary code not provided in source form. @@ -70,7 +70,7 @@ Setting and clearing breakpoints When debugging, we would like to be able to stop the application at critical lines of code and then examine the state of specific variables, memory and registers / peripherals. To do so we are using breakpoints. They provide a convenient way to quickly get to and halt the application at specific line. -Let's establish two breakpoints when the state of LED changes. Basing on code listing above, this happens at lines 33 and 36. To do so, hold the "Control" on the keyboard and double clink on number ``33`` in file ``blink.c`` file. A dialog will open where you can confirm your selection by pressing "OK" button. If you do not like to see the dialog just double click the line number. Set another breakpoint in line 36. +Let's establish two breakpoints when the state of LED changes. Basing on code listing above, this happens at lines 33 and 36. To do so, hold the "Control" on the keyboard and double clink on number ``33`` in file ``blink.c`` file. A dialog will open where you can confirm your selection by pressing "OK" button. If you do not like to see the dialog just double click the line number. Set another breakpoint in line 36. .. figure:: ../../../_static/debugging-setting-breakpoint.jpg :align: center @@ -141,7 +141,7 @@ If you press "Step Into (F5)" instead, then debugger will step inside subroutine Stepping through the code with "Step Into (F5)" -In this particular case debugger stepped inside ``gpio_set_level(BLINK_GPIO, 0)`` and effectively moved to ``gpio.c`` driver code. +In this particular case debugger stepped inside ``gpio_set_level(BLINK_GPIO, 0)`` and effectively moved to ``gpio.c`` driver code. See :ref:`jtag-debugging-tip-why-next-works-as-step` for potential limitation of using ``next`` command. @@ -150,10 +150,17 @@ See :ref:`jtag-debugging-tip-why-next-works-as-step` for potential limitation of Checking and setting memory ^^^^^^^^^^^^^^^^^^^^^^^^^^^ - To display or set contents of memory use "Memory" tab at the bottom of "Debug" perspective. -With the "Memory" tab, we will read from and write to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's. For more information please refer to `ESP32 Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. +With the "Memory" tab, we will read from and write to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's. + +.. only:: esp32 + + For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. + +.. only:: esp32s2beta + + For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. Being in the same ``blink.c`` project as before, set two breakpoints right after ``gpio_set_level`` instruction. Click "Memory" tab and then "Add Memory Monitor" button. Enter ``0x3FF44004`` in provided dialog. @@ -175,7 +182,7 @@ You should see one bit being flipped over at memory location ``0x3FF44004`` (and Observing memory location 0x3FF44004 changing one bit to "OFF" -To set memory use the same "Monitor" tab and the same memory location. Type in alternate bit pattern as previously observed. Immediately after pressing enter you will see LED changing the state. +To set memory use the same "Monitor" tab and the same memory location. Type in alternate bit pattern as previously observed. Immediately after pressing enter you will see LED changing the state. .. _jtag-debugging-examples-eclipse-06: @@ -209,7 +216,7 @@ To modify ``i`` enter a new number in "Value" column. After pressing "Resume (F8 Setting conditional breakpoints ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Here comes more interesting part. You may set a breakpoint to halt the program execution, if certain condition is satisfied. Right click on the breakpoint to open a context menu and select "Breakpoint Properties". Change the selection under "Type:" to "Hardware" and enter a "Condition:" like ``i == 2``. +Here comes more interesting part. You may set a breakpoint to halt the program execution, if certain condition is satisfied. Right click on the breakpoint to open a context menu and select "Breakpoint Properties". Change the selection under "Type:" to "Hardware" and enter a "Condition:" like ``i == 2``. .. figure:: ../../../_static/debugging-setting-conditional-breakpoint.jpg :align: center @@ -230,7 +237,7 @@ Verify if your target is ready and loaded with :example:`get-started/blink` exam Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink.c:43 43 xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5, NULL); - (gdb) + (gdb) @@ -251,19 +258,19 @@ Examples in this section Navigating through the code, call stack and threads ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When you see the ``(gdb)`` prompt, the application is halted. LED should not be blinking. +When you see the ``(gdb)`` prompt, the application is halted. LED should not be blinking. To find out where exactly the code is halted, enter ``l`` or ``list``, and debugger will show couple of lines of code around the halt point (line 43 of code in file ``blink.c``) :: (gdb) l 38 } 39 } - 40 + 40 41 void app_main() 42 { 43 xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5, NULL); 44 } - (gdb) + (gdb) Check how code listing works by entering, e.g. ``l 30, 40`` to see particular range of lines of code. @@ -272,15 +279,15 @@ You can use ``bt`` or ``backtrace`` to see what function calls lead up to this c (gdb) bt #0 app_main () at /home/user-name/esp/blink/main/./blink.c:43 - #1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/esp32/./cpu_start.c:339 - (gdb) + #1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:339 + (gdb) -Line #0 of output provides the last function call before the application halted, i.e. ``app_main ()`` we have listed previously. The ``app_main ()`` was in turn called by function ``main_task`` from line 339 of code located in file ``cpu_start.c``. +Line #0 of output provides the last function call before the application halted, i.e. ``app_main ()`` we have listed previously. The ``app_main ()`` was in turn called by function ``main_task`` from line 339 of code located in file ``cpu_start.c``. To get to the context of ``main_task`` in file ``cpu_start.c``, enter ``frame N``, where N = 1, because the ``main_task`` is listed under #1):: (gdb) frame 1 - #1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/esp32/./cpu_start.c:339 + #1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:339 339 app_main(); (gdb) @@ -295,8 +302,8 @@ Enter ``l`` and this will reveal the piece of code that called ``app_main()`` (i 339 app_main(); 340 vTaskDelete(NULL); 341 } - 342 - (gdb) + 342 + (gdb) By listing some lines before, you will see the function name ``main_task`` we have been looking for:: @@ -317,27 +324,27 @@ By listing some lines before, you will see the function name ``main_task`` we ha 339 app_main(); 340 vTaskDelete(NULL); 341 } - (gdb) + (gdb) To see the other code, enter ``i threads``. This will show the list of threads running on target:: (gdb) i threads - Id Target Id Frame + Id Target Id Frame 8 Thread 1073411336 (dport) 0x400d0848 in dport_access_init_core (arg=) - at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:170 - 7 Thread 1073408744 (ipc0) xQueueGenericReceive (xQueue=0x3ffae694, pvBuffer=0x0, xTicksToWait=1644638200, + at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./dport_access.c:170 + 7 Thread 1073408744 (ipc0) xQueueGenericReceive (xQueue=0x3ffae694, pvBuffer=0x0, xTicksToWait=1644638200, xJustPeeking=0) at /home/user-name/esp/esp-idf/components/freertos/./queue.c:1452 6 Thread 1073431096 (Tmr Svc) prvTimerTask (pvParameters=0x0) at /home/user-name/esp/esp-idf/components/freertos/./timers.c:445 5 Thread 1073410208 (ipc1 : Running) 0x4000bfea in ?? () 4 Thread 1073432224 (dport) dport_access_init_core (arg=0x0) - at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:150 + at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./dport_access.c:150 3 Thread 1073413156 (IDLE) prvIdleTask (pvParameters=0x0) at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282 2 Thread 1073413512 (IDLE) prvIdleTask (pvParameters=0x0) at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282 * 1 Thread 1073411772 (main : Running) app_main () at /home/user-name/esp/blink/main/./blink.c:43 - (gdb) + (gdb) The thread list shows the last function calls per each thread together with the name of C source file if available. @@ -360,7 +367,7 @@ Then check the backtrace:: #6 0x4000000c in ?? () #7 0x4000000c in ?? () #8 0x4000000c in ?? () - (gdb) + (gdb) As you see, the backtrace may contain several entries. This will let you check what exact sequence of function calls lead to the code where the target halted. Question marks ``??`` instead of a function name indicate that application is available only in binary format, without any source file in C language. The value like ``0x4000bfea`` is the memory address of the function call. @@ -385,18 +392,18 @@ If you new enter ``c``, the processor will run and halt at a breakpoint. Enterin (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB6F6 (active) APP_CPU: PC=0x400D10D8 + Target halted. PRO_CPU: PC=0x400DB6F6 (active) APP_CPU: PC=0x400D10D8 Breakpoint 2, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:33 33 gpio_set_level(BLINK_GPIO, 0); (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB6F8 (active) APP_CPU: PC=0x400D10D8 - Target halted. PRO_CPU: PC=0x400DB704 (active) APP_CPU: PC=0x400D10D8 + Target halted. PRO_CPU: PC=0x400DB6F8 (active) APP_CPU: PC=0x400D10D8 + Target halted. PRO_CPU: PC=0x400DB704 (active) APP_CPU: PC=0x400D10D8 Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:36 36 gpio_set_level(BLINK_GPIO, 1); - (gdb) + (gdb) You will be also able to see that LED is changing the state only if you resume program execution by entering ``c``. @@ -408,16 +415,16 @@ To examine how many breakpoints are set and where, use command ``info break``:: breakpoint already hit 1 time 3 breakpoint keep y 0x400db704 in blink_task at /home/user-name/esp/blink/main/./blink.c:36 breakpoint already hit 1 time - (gdb) + (gdb) Please note that breakpoint numbers (listed under ``Num``) start with ``2``. This is because first breakpoint has been already established at function ``app_main()`` by running command ``thb app_main`` on debugger launch. As it was a temporary breakpoint, it has been automatically deleted and now is not listed anymore. -To remove breakpoints enter ``delete N`` command (in short ``d N``), where ``N`` is the breakpoint number:: +To remove breakpoints enter ``delete N`` command (in short ``d N``), where ``N`` is the breakpoint number:: (gdb) delete 1 No breakpoint number 1. (gdb) delete 2 - (gdb) + (gdb) Read more about breakpoints under :ref:`jtag-debugging-tip-breakpoints` and :ref:`jtag-debugging-tip-where-breakpoints` @@ -438,9 +445,9 @@ To check it delete all breakpoints and enter ``c`` to resume application. Then e Program received signal SIGINT, Interrupt. [Switching to Thread 1073413512] - 0x400d0c00 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/esp32/./freertos_hooks.c:52 + 0x400d0c00 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./freertos_hooks.c:52 52 asm("waiti 0"); - (gdb) + (gdb) In particular case above, the application has been halted in line 52 of code in file ``freertos_hooks.c``. Now you can resume it again by enter ``c`` or do some debugging as discussed below. @@ -462,46 +469,46 @@ To demonstrate this functionality, using command ``break`` and ``delete`` discus Num Type Disp Enb Address What 3 breakpoint keep y 0x400db704 in blink_task at /home/user-name/esp/blink/main/./blink.c:36 breakpoint already hit 1 time - (gdb) + (gdb) Resume program by entering ``c`` and let it halt:: (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB754 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB754 (active) APP_CPU: PC=0x400D1128 Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:36 36 gpio_set_level(BLINK_GPIO, 1); - (gdb) + (gdb) Then enter ``n`` couple of times to see how debugger is stepping one program line at a time:: (gdb) n - Target halted. PRO_CPU: PC=0x400DB756 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB758 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB756 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB758 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128 37 vTaskDelay(1000 / portTICK_PERIOD_MS); (gdb) n - Target halted. PRO_CPU: PC=0x400DB75E (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400846FC (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB761 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB746 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB75E (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400846FC (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB761 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB746 (active) APP_CPU: PC=0x400D1128 33 gpio_set_level(BLINK_GPIO, 0); - (gdb) + (gdb) If you enter ``s`` instead, then debugger will step inside subroutine calls:: (gdb) s - Target halted. PRO_CPU: PC=0x400DB748 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB74B (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DC04F (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB748 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB74B (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DC04F (active) APP_CPU: PC=0x400D1128 gpio_set_level (gpio_num=GPIO_NUM_4, level=0) at /home/user-name/esp/esp-idf/components/driver/./gpio.c:183 183 GPIO_CHECK(GPIO_IS_VALID_OUTPUT_GPIO(gpio_num), "GPIO output gpio_num error", ESP_ERR_INVALID_ARG); - (gdb) + (gdb) -In this particular case debugger stepped inside ``gpio_set_level(BLINK_GPIO, 0)`` and effectively moved to ``gpio.c`` driver code. +In this particular case debugger stepped inside ``gpio_set_level(BLINK_GPIO, 0)`` and effectively moved to ``gpio.c`` driver code. See :ref:`jtag-debugging-tip-why-next-works-as-step` for potential limitation of using ``next`` command. @@ -513,14 +520,22 @@ Checking and setting memory Displaying the contents of memory is done with command ``x``. With additional parameters you may vary the format and count of memory locations displayed. Run ``help x`` to see more details. Companion command to ``x`` is ``set`` that let you write values to the memory. -We will demonstrate how ``x`` and ``set`` work by reading from and writing to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's. For more information please refer to `ESP32 Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. +We will demonstrate how ``x`` and ``set`` work by reading from and writing to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's. + +.. only:: esp32 + + For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. + +.. only:: esp32s2beta + + For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. Being in the same ``blink.c`` project as before, set two breakpoints right after ``gpio_set_level`` instruction. Enter two times ``c`` to get to the break point followed by ``x /1wx 0x3FF44004`` to display contents of ``GPIO_OUT_REG`` memory location:: (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB75E (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB74E (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB75E (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB74E (active) APP_CPU: PC=0x400D1128 Breakpoint 2, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:34 34 vTaskDelay(1000 / portTICK_PERIOD_MS); @@ -528,14 +543,14 @@ Being in the same ``blink.c`` project as before, set two breakpoints right after 0x3ff44004: 0x00000000 (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB751 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB751 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128 Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:37 37 vTaskDelay(1000 / portTICK_PERIOD_MS); (gdb) x /1wx 0x3FF44004 0x3ff44004: 0x00000010 - (gdb) + (gdb) If your are blinking LED connected to GPIO4, then you should see fourth bit being flipped each time the LED changes the state:: @@ -571,7 +586,7 @@ This will insert so called "watchpoint" in each place of code where variable ``i (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB751 (active) APP_CPU: PC=0x400D0811 + Target halted. PRO_CPU: PC=0x400DB751 (active) APP_CPU: PC=0x400D0811 [New Thread 1073432196] Program received signal SIGTRAP, Trace/breakpoint trap. @@ -584,14 +599,14 @@ Resume application couple more times so ``i`` gets incremented. Now you can ente (gdb) p i $1 = 3 - (gdb) + (gdb) To modify the value of ``i`` use ``set`` command as below (you can then print it out to check if it has been indeed changed):: (gdb) set var i = 0 (gdb) p i $3 = 0 - (gdb) + (gdb) You may have up to two watchpoints, see :ref:`jtag-debugging-tip-breakpoints`. @@ -607,21 +622,21 @@ Here comes more interesting part. You may set a breakpoint to halt the program e Breakpoint 3 at 0x400db753: file /home/user-name/esp/blink/main/./blink.c, line 34. (gdb) -Above command sets conditional breakpoint to halt program execution in line ``34`` of ``blink.c`` if ``i == 2``. +Above command sets conditional breakpoint to halt program execution in line ``34`` of ``blink.c`` if ``i == 2``. If current value of ``i`` is less than ``2`` and program is resumed, it will blink LED in a loop until condition ``i == 2`` gets true and then finally halt:: (gdb) set var i = 0 (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB755 (active) APP_CPU: PC=0x400D112C - Target halted. PRO_CPU: PC=0x400DB753 (active) APP_CPU: PC=0x400D112C - Target halted. PRO_CPU: PC=0x400DB755 (active) APP_CPU: PC=0x400D112C - Target halted. PRO_CPU: PC=0x400DB753 (active) APP_CPU: PC=0x400D112C + Target halted. PRO_CPU: PC=0x400DB755 (active) APP_CPU: PC=0x400D112C + Target halted. PRO_CPU: PC=0x400DB753 (active) APP_CPU: PC=0x400D112C + Target halted. PRO_CPU: PC=0x400DB755 (active) APP_CPU: PC=0x400D112C + Target halted. PRO_CPU: PC=0x400DB753 (active) APP_CPU: PC=0x400D112C Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:34 34 gpio_set_level(BLINK_GPIO, 0); - (gdb) + (gdb) Obtaining help on commands @@ -635,7 +650,7 @@ Commands presented so for should provide are very basis and intended to let you Unlike "step", if the current source line calls a subroutine, this command does not enter the subroutine, but instead steps over the call, in effect treating it as a single source line. - (gdb) + (gdb) By typing just ``help``, you will get top level list of command classes, to aid you drilling down to more details. Optionally refer to available GDB cheat sheets, for instance http://darkdust.net/files/GDB%20Cheat%20Sheet.pdf. Good to have as a reference (even if not all commands are applicable in an embedded environment). @@ -643,7 +658,7 @@ By typing just ``help``, you will get top level list of command classes, to aid Ending debugger session ^^^^^^^^^^^^^^^^^^^^^^^ -To quit debugger enter ``q``:: +To quit debugger enter ``q``:: (gdb) q A debugging session is active. @@ -653,4 +668,4 @@ To quit debugger enter ``q``:: Quit anyway? (y or n) y Detaching from program: /home/user-name/esp/blink/build/blink.elf, Remote target Ending remote debugging. - user-name@computer-name:~/esp/blink$ + user-name@computer-name:~/esp/blink$ diff --git a/docs/en/api-guides/jtag-debugging/index.rst b/docs/en/api-guides/jtag-debugging/index.rst index 736c8c71e5..8e32b02467 100644 --- a/docs/en/api-guides/jtag-debugging/index.rst +++ b/docs/en/api-guides/jtag-debugging/index.rst @@ -2,18 +2,18 @@ JTAG Debugging ============== :link_to_translation:`zh_CN:[中文]` -This document provides a guide to installing OpenOCD for ESP32 and debugging using +This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and debugging using GDB. The document is structured as follows: :ref:`jtag-debugging-introduction` Introduction to the purpose of this guide. :ref:`jtag-debugging-how-it-works` - Description how ESP32, JTAG interface, OpenOCD and GDB are interconnected and working together to enable debugging of ESP32. + Description how {IDF_TARGET_NAME}, JTAG interface, OpenOCD and GDB are interconnected and working together to enable debugging of {IDF_TARGET_NAME}. :ref:`jtag-debugging-selecting-jtag-adapter` What are the criteria and options to select JTAG adapter hardware. :ref:`jtag-debugging-setup-openocd` Procedure to install OpenOCD and verify that it is installed. -:ref:`jtag-debugging-configuring-esp32-target` +:ref:`jtag-debugging-configuring-target` Configuration of OpenOCD software and set up JTAG adapter hardware that will make together a debugging target. :ref:`jtag-debugging-launching-debugger` Steps to start up a debug session with GDB from :ref:`jtag-debugging-using-debugger-eclipse` and from :ref:`jtag-debugging-using-debugger-command-line`. @@ -22,7 +22,7 @@ GDB. The document is structured as follows: :ref:`jtag-debugging-building-openocd` Procedure to build OpenOCD from sources for :doc:`Windows `, :doc:`Linux ` and :doc:`MacOS ` operating systems. :ref:`jtag-debugging-tips-and-quirks` - This section provides collection of tips and quirks related JTAG debugging of ESP32 with OpenOCD and GDB. + This section provides collection of tips and quirks related JTAG debugging of {IDF_TARGET_NAME} with OpenOCD and GDB. .. _jtag-debugging-introduction: @@ -30,13 +30,15 @@ GDB. The document is structured as follows: Introduction ------------ -The ESP32 has two powerful Xtensa cores, allowing for a great deal of variety of program architectures. The FreeRTOS OS that comes with ESP-IDF is capable of multi-core preemptive multithreading, allowing for an intuitive way of writing software. +.. only:: esp32 -The downside of the ease of programming is that debugging without the right tools is harder: figuring out a bug that is caused by two threads, running even simultaneously on two different CPU cores, can take a long time when all you have are printf statements. A better and in many cases quicker way to debug such problems is by using a debugger, connected to the processors over a debug port. + The ESP32 has two powerful Xtensa cores, allowing for a great deal of variety of program architectures. The FreeRTOS OS that comes with ESP-IDF is capable of multi-core preemptive multithreading, allowing for an intuitive way of writing software. -Espressif has ported OpenOCD to support the ESP32 processor and the multicore FreeRTOS, which will be the foundation of most ESP32 apps, and has written some tools to help with features OpenOCD does not support natively. + The downside of the ease of programming is that debugging without the right tools is harder: figuring out a bug that is caused by two threads, running even simultaneously on two different CPU cores, can take a long time when all you have are printf statements. A better and in many cases quicker way to debug such problems is by using a debugger, connected to the processors over a debug port. -This document provides a guide to installing OpenOCD for ESP32 and debugging using GDB under Linux, Windows and MacOS. Except for OS specific installation procedures, the s/w user interface and use procedures are the same across all supported operating systems. +Espressif has ported OpenOCD to support the {IDF_TARGET_NAME} processor and the multicore FreeRTOS, which will be the foundation of most {IDF_TARGET_NAME} apps, and has written some tools to help with features OpenOCD does not support natively. + +This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and debugging using GDB under Linux, Windows and MacOS. Except for OS specific installation procedures, the s/w user interface and use procedures are the same across all supported operating systems. .. note:: @@ -47,20 +49,22 @@ This document provides a guide to installing OpenOCD for ESP32 and debugging usi How it Works? ------------- -The key software and hardware to perform debugging of ESP32 with OpenOCD over JTAG (Joint Test Action Group) interface is presented below and includes **xtensa-esp32-elf-gdb debugger**, **OpenOCD on chip debugger** and **JTAG adapter** connected to **ESP32** target. +The key software and hardware to perform debugging of {IDF_TARGET_NAME} with OpenOCD over JTAG (Joint Test Action Group) interface is presented below and includes xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb debugger, OpenOCD on chip debugger and JTAG adapter connected to {IDF_TARGET_NAME} target. .. figure:: ../../../_static/jtag-debugging-overview.jpg :align: center - :alt: JTAG debugging - overview diagram + :alt: JTAG debugging - overview diagram :figclass: align-center - JTAG debugging - overview diagram + JTAG debugging - overview diagram -Under "Application Loading and Monitoring" there is another software and hardware to compile, build and flash application to ESP32, as well as to provide means to monitor diagnostic messages from ESP32. +Under "Application Loading and Monitoring" there is another software and hardware to compile, build and flash application to {IDF_TARGET_NAME}, as well as to provide means to monitor diagnostic messages from {IDF_TARGET_NAME}. Debugging using JTAG and application loading / monitoring is integrated under the `Eclipse `_ environment, to provide quick and easy transition from writing, compiling and loading the code to debugging, back to writing the code, and so on. All the software is available for Windows, Linux and MacOS platforms. -If the :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>` is used, then connection from PC to ESP32 is done effectively with a single USB cable thanks to FT2232H chip installed on WROVER, which provides two USB channels, one for JTAG and the second for UART connection. +.. only:: esp32 + + If the :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>` is used, then connection from PC to ESP32 is done effectively with a single USB cable thanks to FT2232H chip installed on WROVER, which provides two USB channels, one for JTAG and the second for UART connection. Depending on user preferences, both `debugger` and `idf.py build` can be operated directly from terminal/command line, instead from Eclipse. @@ -70,13 +74,13 @@ Depending on user preferences, both `debugger` and `idf.py build` can be operate Selecting JTAG Adapter ---------------------- -The quickest and most convenient way to start with JTAG debugging is by using :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>`. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to ESP32. WROVER KIT is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter. +The quickest and most convenient way to start with JTAG debugging is by using :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>`. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. WROVER KIT is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter. -If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the ESP32 as well as with the OpenOCD software. The JTAG port on the ESP32 is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range. +If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the {IDF_TARGET_NAME} as well as with the OpenOCD software. The JTAG port on the {IDF_TARGET_NAME} is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range. -On the software side, OpenOCD supports a fair amount of JTAG adapters. See http://openocd.org/doc/html/Debug-Adapter-Hardware.html for an (unfortunately slightly incomplete) list of the adapters OpenOCD works with. This page lists SWD-compatible adapters as well; take note that the ESP32 does not support SWD. JTAG adapters that are hardcoded to a specific product line, e.g. ST-LINK debugging adapters for STM32 families, will not work. +On the software side, OpenOCD supports a fair amount of JTAG adapters. See http://openocd.org/doc/html/Debug-Adapter-Hardware.html for an (unfortunately slightly incomplete) list of the adapters OpenOCD works with. This page lists SWD-compatible adapters as well; take note that the {IDF_TARGET_NAME} does not support SWD. JTAG adapters that are hardcoded to a specific product line, e.g. ST-LINK debugging adapters for STM32 families, will not work. -The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and GND. Some JTAG debuggers also need a connection from the ESP32 power line to a line called e.g. Vtar to set the working voltage. SRST can optionally be connected to the CH_PD of the ESP32, although for now, support in OpenOCD for that line is pretty minimal. +The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and GND. Some JTAG debuggers also need a connection from the {IDF_TARGET_NAME} power line to a line called e.g. Vtar to set the working voltage. SRST can optionally be connected to the CH_PD of the {IDF_TARGET_NAME}, although for now, support in OpenOCD for that line is pretty minimal. .. _jtag-debugging-setup-openocd: @@ -94,7 +98,7 @@ If you have already set up ESP-IDF with CMake build system according to the :doc The output should be as follows (although the version may be more recent than listed here):: - Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04) + Open On-Chip Debugger v0.10.0-{IDF_TARGET_TOOLCHAIN_NAME}-20190708 (2019-07-08-11:04) Licensed under GNU GPL v2 For bug reports, read http://openocd.org/doc/doxygen/bugs.html @@ -107,12 +111,12 @@ If any of these steps do not work, please go back to the :ref:`setting up the to It is also possible to build OpenOCD from source. Please refer to :ref:`jtag-debugging-building-openocd` section for details. -.. _jtag-debugging-configuring-esp32-target: +.. _jtag-debugging-configuring-target: -Configuring ESP32 Target ------------------------- +Configuring {IDF_TARGET_NAME} Target +------------------------------------- -Once OpenOCD is installed, move to configuring ESP32 target (i.e ESP32 board with JTAG interface). You will do it in the following three steps: +Once OpenOCD is installed, move to configuring {IDF_TARGET_NAME} target (i.e {IDF_TARGET_NAME} board with JTAG interface). You will do it in the following three steps: * Configure and connect JTAG interface * Run OpenOCD @@ -122,12 +126,12 @@ Once OpenOCD is installed, move to configuring ESP32 target (i.e ESP32 board wit Configure and connect JTAG interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This step depends on JTAG and ESP32 board you are using - see the two cases described below. +This step depends on JTAG and {IDF_TARGET_NAME} board you are using - see the two cases described below. .. toctree:: :maxdepth: 1 - configure-wrover + :esp32: configure-wrover configure-other-jtag @@ -168,8 +172,8 @@ You should now see similar output (this log is for ESP-WROVER-KIT):: Info : esp32: Core was reset (pwrstat=0x5F, after clear 0x0F). * If there is an error indicating permission problems, please see the "Permissions delegation" bit in the OpenOCD README file in ``~/esp/openocd-esp32`` directory. -* In case there is an error finding configuration files, e.g. ``Can't find board/esp32-wrover-kit-3.3v.cfg``, check the path after ``-s``. This path is used by OpenOCD to look for the files specified after ``-f``. Also check if the file is indeed under provided path. -* If you see JTAG errors (...all ones/...all zeroes) please check your connections, whether no other signals are connected to JTAG besides ESP32's pins, and see if everything is powered on. +* In case there is an error finding configuration files, e.g. ``Can't find board/esp32-wrover-kit-3.3v.cfg``, check the path after ``-s``. This path is used by OpenOCD to look for the files specified after ``-f``. Also check if the file is indeed under provided path. +* If you see JTAG errors (...all ones/...all zeroes) please check your connections, whether no other signals are connected to JTAG besides {IDF_TARGET_NAME}'s pins, and see if everything is powered on. .. _jtag-upload-app-debug: @@ -177,7 +181,7 @@ You should now see similar output (this log is for ESP-WROVER-KIT):: Upload application for debugging ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Build and upload your application to ESP32 as usual, see :ref:`get-started-build`. +Build and upload your application to {IDF_TARGET_NAME} as usual, see :ref:`get-started-build`. Another option is to write application image to flash using OpenOCD via JTAG with commands like this:: @@ -201,9 +205,9 @@ You are now ready to start application debugging. Follow steps described in sect Launching Debugger ------------------ -The toolchain for ESP32 features GNU Debugger, in short GDB. It is available with other toolchain programs under filename ``xtensa-esp32-elf-gdb``. GDB can be called and operated directly from command line in a terminal. Another option is to call it from within IDE (like Eclipse, Visual Studio Code, etc.) and operate indirectly with help of GUI instead of typing commands in a terminal. +The toolchain for {IDF_TARGET_NAME} features GNU Debugger, in short GDB. It is available with other toolchain programs under filename: xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb. GDB can be called and operated directly from command line in a terminal. Another option is to call it from within IDE (like Eclipse, Visual Studio Code, etc.) and operate indirectly with help of GUI instead of typing commands in a terminal. -Both options of using debugger are discussed under links below. +Both options of using debugger are discussed under links below. * :ref:`jtag-debugging-using-debugger-eclipse` * :ref:`jtag-debugging-using-debugger-command-line` @@ -226,9 +230,9 @@ This section is intended for users not familiar with GDB. It presents example de 6. :ref:`jtag-debugging-examples-eclipse-06` 7. :ref:`jtag-debugging-examples-eclipse-07` -Similar debugging actions are provided using GDB from :ref:`jtag-debugging-examples-command-line`. +Similar debugging actions are provided using GDB from :ref:`jtag-debugging-examples-command-line`. -Before proceeding to examples, set up your ESP32 target and load it with :example:`get-started/blink`. +Before proceeding to examples, set up your {IDF_TARGET_NAME} target and load it with :example:`get-started/blink`. .. _jtag-debugging-building-openocd: diff --git a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst index 866977c5bd..88a56e75d0 100644 --- a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst @@ -10,7 +10,7 @@ This section provides collection of all tips and quirks referred to from various Breakpoints and watchpoints available ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -ESP32 debugger supports 2 hardware implemented breakpoints and 64 software ones. Hardware breakpoints are implemented by ESP32 chip's logic and can be set anywhere in the code: either in flash or IRAM program's regions. Additionally there are 2 types of software breakpoints implemented by OpenOCD: flash (up to 32) and IRAM (up to 32) breakpoints. Currently GDB can not set software breakpoints in flash. So until this limitation is removed those breakpoints have to be emulated by OpenOCD as hardware ones (see :ref:`below ` for details). ESP32 also supports two watchpoints, so two variables can be watched for change or read by the GDB command ``watch myVariable``. Note that menuconfig option :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` uses the 2nd watchpoint and will not provide expected results, if you also try to use it within OpenOCD / GDB. See menuconfig's help for detailed description. +{IDF_TARGET_NAME} debugger supports 2 hardware implemented breakpoints and 64 software ones. Hardware breakpoints are implemented by {IDF_TARGET_NAME} chip's logic and can be set anywhere in the code: either in flash or IRAM program's regions. Additionally there are 2 types of software breakpoints implemented by OpenOCD: flash (up to 32) and IRAM (up to 32) breakpoints. Currently GDB can not set software breakpoints in flash. So until this limitation is removed those breakpoints have to be emulated by OpenOCD as hardware ones (see :ref:`below ` for details). {IDF_TARGET_NAME} also supports two watchpoints, so two variables can be watched for change or read by the GDB command ``watch myVariable``. Note that menuconfig option :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` uses the 2nd watchpoint and will not provide expected results, if you also try to use it within OpenOCD / GDB. See menuconfig's help for detailed description. .. _jtag-debugging-tip-where-breakpoints: @@ -26,9 +26,9 @@ Emulating part of hardware breakpoints using software flash ones means that the Flash Mappings vs SW Flash Breakpoints ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In order to set/clear software breakpoints in flash, OpenOCD needs to know their flash addresses. To accomplish conversion from the ESP32 address space to the flash one, OpenOCD uses mappings of program's code regions resided in flash. Those mappings are kept in the image header which is prepended to program binary data (code and data segments) and is specific to every application image written to the flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found application image, but there can be the cases when it will not work, e.g. partition table is not at standard flash location or even there can be multiple images: one factory and two OTA and you may want to debbug any of them. To cover all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of application image to debug. The command has the following format: +In order to set/clear software breakpoints in flash, OpenOCD needs to know their flash addresses. To accomplish conversion from the {IDF_TARGET_NAME} address space to the flash one, OpenOCD uses mappings of program's code regions resided in flash. Those mappings are kept in the image header which is prepended to program binary data (code and data segments) and is specific to every application image written to the flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found application image, but there can be the cases when it will not work, e.g. partition table is not at standard flash location or even there can be multiple images: one factory and two OTA and you may want to debbug any of them. To cover all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of application image to debug. The command has the following format: -``esp32 appimage_offset `` +``esp32 appimage_offset `` Offset should be in hex format. To reset to the default behaviour you can specify ``-1`` as offset. @@ -55,13 +55,7 @@ Support options for OpenOCD at compile time ESP-IDF has some support options for OpenOCD debugging which can be set at compile time: -.. only:: esp32 - - * :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger. - -.. only:: esp32s2 - - * :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger. +* :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger. * :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` (disabled by default) sets watchpoint index 1 (the second of two) at the end of any task stack. This is the most accurate way to debug task stack overflows. Click the link for more details. @@ -77,14 +71,16 @@ OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS task .. _jtag-debugging-tip-code-flash-voltage: -Why to set SPI flash voltage in OpenOCD configuration? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. only:: esp33 -The MTDI pin of ESP32, being among four pins used for JTAG communication, is also one of ESP32's bootstrapping pins. On power up ESP32 is sampling binary level on MTDI to set it's internal voltage regulator used to supply power to external SPI flash chip. If binary level on MDTI pin on power up is low, the voltage regulator is set to deliver 3.3 V, if it is high, then the voltage is set to 1.8 V. The MTDI pin should have a pull-up or may rely on internal weak pull down resistor (see `ESP32 Series Datasheet `_ for details), depending on the type of SPI chip used. Once JTAG is connected, it overrides the pull-up or pull-down resistor that is supposed to do the bootstrapping. + Why to set SPI flash voltage in OpenOCD configuration? + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To handle this issue OpenOCD's board configuration file (e.g. ``boards\esp-wroom-32.cfg`` for ESP32-WROOM-32 module) provides ``ESP32_FLASH_VOLTAGE`` parameter to set the idle state of the ``TDO`` line to a specified binary level, therefore reducing the chance of a bad bootup of application due to incorrect flash voltage. + The MTDI pin of ESP32, being among four pins used for JTAG communication, is also one of ESP32's bootstrapping pins. On power up ESP32 is sampling binary level on MTDI to set it's internal voltage regulator used to supply power to external SPI flash chip. If binary level on MDTI pin on power up is low, the voltage regulator is set to deliver 3.3 V, if it is high, then the voltage is set to 1.8 V. The MTDI pin should have a pull-up or may rely on internal weak pull down resistor (see `ESP32 Series Datasheet `_ for details), depending on the type of SPI chip used. Once JTAG is connected, it overrides the pull-up or pull-down resistor that is supposed to do the bootstrapping. -Check specification of ESP32 module connected to JTAG, what is the power supply voltage of SPI flash chip. Then set ``ESP32_FLASH_VOLTAGE`` accordingly. Most WROOM modules use 3.3 V flash, while WROVER modules use 1.8 V flash. + To handle this issue OpenOCD's board configuration file (e.g. ``boards\esp-wroom-32.cfg`` for ESP32-WROOM-32 module) provides ``ESP32_FLASH_VOLTAGE`` parameter to set the idle state of the ``TDO`` line to a specified binary level, therefore reducing the chance of a bad bootup of application due to incorrect flash voltage. + + Check specification of ESP32 module connected to JTAG, what is the power supply voltage of SPI flash chip. Then set ``ESP32_FLASH_VOLTAGE`` accordingly. Most WROOM modules use 3.3 V flash, while WROVER modules use 1.8 V flash. .. _jtag-debugging-tip-optimize-jtag-speed: @@ -105,9 +101,9 @@ In order to achieve higher data rates and minimize number of dropped packets it What is the meaning of debugger's startup commands? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -On startup, debugger is issuing sequence of commands to reset the chip and halt it at specific line of code. This sequence (shown below) is user defined to pick up at most convenient / appropriate line and start debugging. +On startup, debugger is issuing sequence of commands to reset the chip and halt it at specific line of code. This sequence (shown below) is user defined to pick up at most convenient / appropriate line and start debugging. -* ``set remote hardware-watchpoint-limit 2`` — Restrict GDB to using two hardware watchpoints supported by ESP32. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html. +* ``set remote hardware-watchpoint-limit 2`` — Restrict GDB to using two hardware watchpoints supported by the chip, 2 for ESP32. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html. * ``mon reset halt`` — reset the chip and keep the CPUs halted * ``flushregs`` — monitor (``mon``) command can not inform GDB that the target state has changed. GDB will assume that whatever stack the target had before ``mon reset halt`` will still be valid. In fact, after reset the target state will change, and executing ``flushregs`` is a way to force GDB to get new state from the target. * ``thb app_main`` — insert a temporary hardware breakpoint at ``app_main``, put here another function name if required @@ -170,40 +166,42 @@ Power supply voltage of ESP32's SPI flash chip Comment out this line to set 3.3 V, ref: :ref:`jtag-debugging-tip-code-flash-voltage` -Configuration file for ESP32 targets -"""""""""""""""""""""""""""""""""""" +.. only:: esp32 -:: + Configuration file for ESP32 targets + """""""""""""""""""""""""""""""""""" - source [find target/esp32.cfg] + :: -.. note:: + source [find target/esp32.cfg] - Do not change ``source [find target/esp32.cfg]`` line unless you are familiar with OpenOCD internals. + .. note:: -Currently ``target/esp32.cfg`` remains the only configuration file for ESP32 targets (esp108 and esp32). The matrix of supported configurations is as follows: + Do not change ``source [find target/esp32.cfg]`` line unless you are familiar with OpenOCD internals. - +---------------+---------------+---------------+ - | Dual/single | RTOS | Target used | - +===============+===============+===============+ - | dual | FreeRTOS | esp32 | - +---------------+---------------+---------------+ - | single | FreeRTOS | esp108 (*) | - +---------------+---------------+---------------+ - | dual | none | esp108 | - +---------------+---------------+---------------+ - | single | none | esp108 | - +---------------+---------------+---------------+ + Currently ``target/esp32.cfg`` remains the only configuration file for ESP32 targets (esp108 and esp32). The matrix of supported configurations is as follows: - (*) — we plan to fix this and add support for single core debugging with esp32 target in a subsequent commits. + +---------------+---------------+---------------+ + | Dual/single | RTOS | Target used | + +===============+===============+===============+ + | dual | FreeRTOS | esp32 | + +---------------+---------------+---------------+ + | single | FreeRTOS | esp108 (*) | + +---------------+---------------+---------------+ + | dual | none | esp108 | + +---------------+---------------+---------------+ + | single | none | esp108 | + +---------------+---------------+---------------+ -Look inside ``board/esp-wroom-32.cfg`` for additional information provided in comments besides each configuration parameter. + (*) — we plan to fix this and add support for single core debugging with esp32 target in a subsequent commits. + + Look inside ``board/esp-wroom-32.cfg`` for additional information provided in comments besides each configuration parameter. .. _jtag-debugging-tip-reset-by-debugger: -How debugger resets ESP32? -^^^^^^^^^^^^^^^^^^^^^^^^^^ +How debugger resets {IDF_TARGET_NAME}? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The board can be reset by entering ``mon reset`` or ``mon reset halt`` into GDB. @@ -213,21 +211,37 @@ The board can be reset by entering ``mon reset`` or ``mon reset halt`` into GDB. Do not use JTAG pins for something else ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides ESP32 module and JTAG adapter. ESP32 JTAG us using the following pins: +Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides {IDF_TARGET_NAME} module and JTAG adapter. {IDF_TARGET_NAME} JTAG us using the following pins: - +---+----------------+-------------+ - | | ESP32 JTAG Pin | JTAG Signal | - +===+================+=============+ - | 1 | MTDO / GPIO15 | TDO | - +---+----------------+-------------+ - | 2 | MTDI / GPIO12 | TDI | - +---+----------------+-------------+ - | 3 | MTCK / GPIO13 | TCK | - +---+----------------+-------------+ - | 4 | MTMS / GPIO14 | TMS | - +---+----------------+-------------+ +.. only:: esp32 -JTAG communication will likely fail, if configuration of JTAG pins is changed by user application. If OpenOCD initializes correctly (detects the two Tensilica cores), but loses sync and spews out a lot of DTR/DIR errors when the program is ran, it is likely that the application reconfigures the JTAG pins to something else, or the user forgot to connect Vtar to a JTAG adapter that needed it. + +---+-----------------------+-------------+ + | | ESP32 Pin | JTAG Signal | + +===+=======================+=============+ + | 1 | MTDO / GPIO15 | TDO | + +---+-----------------------+-------------+ + | 2 | MTDI / GPIO12 | TDI | + +---+-----------------------+-------------+ + | 3 | MTCK / GPIO13 | TCK | + +---+-----------------------+-------------+ + | 4 | MTMS / GPIO14 | TMS | + +---+-----------------------+-------------+ + +.. only:: esp32s2 + + +---+-----------------------+-------------+ + | | ESP32-S2 Pin | JTAG Signal | + +===+=======================+=============+ + | 1 | MTDO / GPIO40 | TDO | + +---+-----------------------+-------------+ + | 2 | MTDI / GPIO41 | TDI | + +---+-----------------------+-------------+ + | 3 | MTCK / GPIO39 | TCK | + +---+-----------------------+-------------+ + | 4 | MTMS / GPIO42 | TMS | + +---+-----------------------+-------------+ + +JTAG communication will likely fail, if configuration of JTAG pins is changed by user application. If OpenOCD initializes correctly (detects the two Tensilica cores), but loses sync and spews out a lot of DTR/DIR errors when the program is ran, it is likely that the application reconfigures the JTAG pins to something else, or the user forgot to connect Vtar to a JTAG adapter that needed it. .. highlight:: none @@ -243,12 +257,14 @@ Below is an excerpt from series of errors reported by GDB after the application .. _jtag-debugging-tip-at-firmware-issue: -JTAG and ESP32-WROOM-32 AT firmware Compatibility Issue -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. only:: esp32 -The ESP32-WROOM series of modules come pre-flashed with AT firmware. This firmware configures the pins GPIO12 to GPIO15 as SPI slave interface, which makes using JTAG impossible. + JTAG and ESP32-WROOM-32 AT firmware Compatibility Issue + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To make JTAG available, build new firmware that is not using pins GPIO12 to GPIO15 dedicated to JTAG communication. After that, flash the firmware onto your module. See also :ref:`jtag-debugging-tip-jtag-pins-reconfigured`. + The ESP32-WROOM series of modules come pre-flashed with AT firmware. This firmware configures the pins GPIO12 to GPIO15 as SPI slave interface, which makes using JTAG impossible. + + To make JTAG available, build new firmware that is not using pins GPIO12 to GPIO15 dedicated to JTAG communication. After that, flash the firmware onto your module. See also :ref:`jtag-debugging-tip-jtag-pins-reconfigured`. .. _jtag-debugging-tip-reporting-issues: @@ -256,7 +272,7 @@ To make JTAG available, build new firmware that is not using pins GPIO12 to GPIO Reporting issues with OpenOCD / GDB ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In case you encounter a problem with OpenOCD or GDB programs itself and do not find a solution searching available resources on the web, open an issue in the OpenOCD issue tracker under https://github.com/espressif/openocd-esp32/issues. +In case you encounter a problem with OpenOCD or GDB programs itself and do not find a solution searching available resources on the web, open an issue in the OpenOCD issue tracker under https://github.com/espressif/openocd-esp32/issues. 1. In issue report provide details of your configuration: diff --git a/docs/en/api-guides/jtag-debugging/using-debugger.rst b/docs/en/api-guides/jtag-debugging/using-debugger.rst index e537f57d05..4e8644593f 100644 --- a/docs/en/api-guides/jtag-debugging/using-debugger.rst +++ b/docs/en/api-guides/jtag-debugging/using-debugger.rst @@ -36,9 +36,9 @@ Once installation is complete, configure debugging session following steps below Configuration of GDB Hardware Debugging - Main tab -6. Click "Debugger" tab. In field "GDB Command" enter ``xtensa-esp32-elf-gdb`` to invoke debugger. +6. Click "Debugger" tab. In field "GDB Command" enter ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb`` to invoke debugger. -7. Change default configuration of "Remote host" by entering ``3333`` under the "Port number". +7. Change default configuration of "Remote host" by entering ``3333`` under the "Port number". Configuration entered in points 6 and 7 is shown on the following picture. @@ -65,7 +65,7 @@ Once installation is complete, configure debugging session following steps below For description of ``program_esp`` command see :ref:`jtag-upload-app-debug`. -9. Under "Load Image and Symbols" uncheck "Load image" option. +9. Under "Load Image and Symbols" uncheck "Load image" option. 10. Further down on the same tab, establish an initial breakpoint to halt CPUs after they are reset by debugger. The plugin will set this breakpoint at the beginning of the function entered under "Set break point at:". Checkout this option and enter ``app_main`` in provided field. @@ -82,9 +82,9 @@ Once installation is complete, configure debugging session following steps below If the "Startup" sequence looks convoluted and respective "Initialization Commands" are not clear to you, check :ref:`jtag-debugging-tip-debugger-startup-commands` for additional explanation. -12. If you previously completed :ref:`jtag-debugging-configuring-esp32-target` steps described above, so the target is running and ready to talk to debugger, go right to debugging by pressing "Debug" button. Otherwise press "Apply" to save changes, go back to :ref:`jtag-debugging-configuring-esp32-target` and return here to start debugging. +12. If you previously completed :ref:`jtag-debugging-configuring-target` steps described above, so the target is running and ready to talk to debugger, go right to debugging by pressing "Debug" button. Otherwise press "Apply" to save changes, go back to :ref:`jtag-debugging-configuring-target` and return here to start debugging. -Once all 1 - 12 configuration steps are satisfied, the new Eclipse perspective called "Debug" will open as shown on example picture below. +Once all 1 - 12 configuration steps are satisfied, the new Eclipse perspective called "Debug" will open as shown on example picture below. .. figure:: ../../../_static/debug-perspective.jpg :align: center @@ -101,7 +101,7 @@ If you are not quite sure how to use GDB, check :ref:`jtag-debugging-examples-ec Command Line ^^^^^^^^^^^^ -1. Begin with completing steps described under :ref:`jtag-debugging-configuring-esp32-target`. This is prerequisite to start a debugging session. +1. Begin with completing steps described under :ref:`jtag-debugging-configuring-target`. This is prerequisite to start a debugging session. .. highlight:: bash @@ -124,7 +124,7 @@ Command Line thb app_main c - Save this file in current directory. + Save this file in current directory. For more details what's inside ``gdbinit`` file, see :ref:`jtag-debugging-tip-debugger-startup-commands` @@ -134,7 +134,7 @@ Command Line :: - xtensa-esp32-elf-gdb -x gdbinit build/blink.elf + xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit build/blink.elf .. highlight:: none @@ -142,14 +142,14 @@ Command Line :: - user-name@computer-name:~/esp/blink$ xtensa-esp32-elf-gdb -x gdbinit build/blink.elf + user-name@computer-name:~/esp/blink$ xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit build/blink.elf GNU gdb (crosstool-NG crosstool-ng-1.22.0-61-gab8375a) 7.10 Copyright (C) 2015 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. - This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=xtensa-esp32-elf". + This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf". Type "show configuration" for configuration details. For bug reporting instructions, please see: . @@ -158,20 +158,20 @@ Command Line For help, type "help". Type "apropos word" to search for commands related to "word"... Reading symbols from build/blink.elf...done. - 0x400d10d8 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/esp32/./freertos_hooks.c:52 + 0x400d10d8 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./freertos_hooks.c:52 52 asm("waiti 0"); - JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - JTAG tap: esp32.slave tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F). - esp32: Core was reset (pwrstat=0x5F, after clear 0x0F). - Target halted. PRO_CPU: PC=0x5000004B (active) APP_CPU: PC=0x00000000 - esp32: target state: halted - esp32: Core was reset (pwrstat=0x1F, after clear 0x0F). - Target halted. PRO_CPU: PC=0x40000400 (active) APP_CPU: PC=0x40000400 - esp32: target state: halted + JTAG tap: {IDF_TARGET_PATH_NAME}.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) + JTAG tap: {IDF_TARGET_PATH_NAME}.slave tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) + {IDF_TARGET_PATH_NAME}: Debug controller was reset (pwrstat=0x5F, after clear 0x0F). + {IDF_TARGET_PATH_NAME}: Core was reset (pwrstat=0x5F, after clear 0x0F). + Target halted. PRO_CPU: PC=0x5000004B (active) APP_CPU: PC=0x00000000 + {IDF_TARGET_PATH_NAME}: target state: halted + {IDF_TARGET_PATH_NAME}: Core was reset (pwrstat=0x1F, after clear 0x0F). + Target halted. PRO_CPU: PC=0x40000400 (active) APP_CPU: PC=0x40000400 + {IDF_TARGET_PATH_NAME}: target state: halted Hardware assisted breakpoint 1 at 0x400db717: file /home/user-name/esp/blink/main/./blink.c, line 43. 0x0: 0x00000000 - Target halted. PRO_CPU: PC=0x400DB717 (active) APP_CPU: PC=0x400D10D8 + Target halted. PRO_CPU: PC=0x400DB717 (active) APP_CPU: PC=0x400D10D8 [New Thread 1073428656] [New Thread 1073413708] [New Thread 1073431316] @@ -180,10 +180,10 @@ Command Line [New Thread 1073432196] [New Thread 1073411552] [Switching to Thread 1073411996] - + Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink.c:43 43 xTaskCreate(&blink_task, "blink_task", 512, NULL, 5, NULL); - (gdb) + (gdb) Note the third line from bottom that shows debugger halting at breakpoint established in ``gdbinit`` file at function ``app_main()``. Since the processor is halted, the LED should not be blinking. If this is what you see as well, you are ready to start debugging. diff --git a/docs/en/api-guides/linker-script-generation.rst b/docs/en/api-guides/linker-script-generation.rst index 258a249942..3c377aef37 100644 --- a/docs/en/api-guides/linker-script-generation.rst +++ b/docs/en/api-guides/linker-script-generation.rst @@ -21,15 +21,15 @@ This section presents a guide for quickly placing code/data to RAM and RTC memor For this guide, suppose we have the following:: - components/ - - my_component/ + - my_component/ - CMakeLists.txt - component.mk - - Kconfig + - Kconfig - src/ - - my_src1.c - - my_src2.c - - my_src3.c - - my_linker_fragment_file.lf + - my_src1.c + - my_src2.c + - my_src3.c + - my_linker_fragment_file.lf - a component named ``my_component`` that is archived as library ``libmy_component.a`` during build @@ -65,7 +65,7 @@ created linker fragment file. .. code-block:: cmake - # file paths relative to CMakeLists.txt + # file paths relative to CMakeLists.txt idf_component_register(... LDFRAGMENTS "path/to/linker_fragment_file.lf" "path/to/another_linker_fragment_file.lf" ... @@ -86,7 +86,7 @@ It is possible to specify placements at the following levels of granularity: Placing object files """""""""""""""""""" -Suppose the entirety of ``my_src1.o`` is performance-critical, so it is desirable to place it in RAM. +Suppose the entirety of ``my_src1.o`` is performance-critical, so it is desirable to place it in RAM. On the other hand, the entirety of ``my_src2.o`` contains symbols needed coming out of deep sleep, so it needs to be put under RTC memory. In the the linker fragment file, we can write: @@ -99,7 +99,7 @@ In the the linker fragment file, we can write: my_src2 (rtc) # places all my_src2 code/ data and read-only data under RTC fast memory/RTC slow memory What happens to ``my_src3.o``? Since it is not specified, default placements are used for ``my_src3.o``. More on default placements -:ref:`here`. +:ref:`here`. Placing symbols """""""""""""""" @@ -215,7 +215,7 @@ As the name suggests, it is where code and data are usually placed, i.e. code/co placed in RAM, etc. More on the default scheme :ref:`here`. .. note:: - For an example of an ESP-IDF component using the linker script generation mechanism, see :component_file:`freertos/CMakeLists.txt`. + For an example of an ESP-IDF component using the linker script generation mechanism, see :component_file:`freertos/CMakeLists.txt`. ``freertos`` uses this to place its object files to the instruction RAM for performance reasons. This marks the end of the quick start guide. The following text discusses the internals of the mechanism in a little bit more detail. @@ -226,7 +226,7 @@ Linker Script Generation Internals Linking is the last step in the process of turning C/C++ source files into an executable. It is performed by the toolchain's linker, and accepts linker scripts which specify code/data placements, among other things. With the linker script generation mechanism, this process is no different, except -that the linker script passed to the linker is dynamically generated from: (1) the collected :ref:`linker fragment files` and +that the linker script passed to the linker is dynamically generated from: (1) the collected :ref:`linker fragment files` and (2) :ref:`linker script template`. .. note:: @@ -240,7 +240,7 @@ Linker Fragment Files As mentioned in the quick start guide, fragment files are simple text files with the ``.lf`` extension containing the desired placements. This is a simplified description of what fragment files contain, however. What fragment files actually contain are 'fragments'. Fragments are entities which contain pieces of information which, when put together, form -placement rules that tell where to place sections of object files in the output binary. There are three types of fragments: :ref:`sections`, +placement rules that tell where to place sections of object files in the output binary. There are three types of fragments: :ref:`sections`, :ref:`scheme` and :ref:`mapping`. Grammar @@ -276,7 +276,7 @@ The three fragment types share a common grammar: **Condition Checking** Condition checking enable the linker script generation to be configuration-aware. Depending on whether expressions involving configuration values -are true or not, a particular set of values for a key can be used. The evaluation uses ``eval_string`` from :idf_file:`tools/kconfig_new/kconfiglib.py` +are true or not, a particular set of values for a key can be used. The evaluation uses ``eval_string`` from :idf_file:`tools/kconfig_new/kconfiglib.py` and adheres to its required syntax and limitations. Supported operators are as follows: - comparison @@ -331,7 +331,7 @@ for both key values and entire fragments. The two sample fragments below are equ **Comments** Comment in linker fragment files begin with ``#``. Like in other languages, comment are used to provide helpful descriptions and documentation -and are ignored during processing. +and are ignored during processing. Compatibility with ESP-IDF v3.x Linker Script Fragment Files """""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -426,10 +426,10 @@ will be generated for the target ``flash_text``. These catch-all rules then effectively serve as fallback rules for those whose mappings were not specified. -.. note:: - The ``default scheme`` is defined in :component:`esp32/ld/esp32_fragments.lf`. The ``noflash`` and ``rtc`` scheme fragments which are - built-in schemes referenced in the quick start guide are also defined in this file. +The ``default scheme`` is defined in :component:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}_fragments.lf`. The ``noflash`` and ``rtc`` scheme fragments which are +built-in schemes referenced in the quick start guide are also defined in this file. + .. _ldgen-mapping-fragment : @@ -589,9 +589,5 @@ Then the corresponding excerpt from the generated linker script will be as follo it too is placed wherever ``iram0_text`` is referenced by a marker. Since it is a rule generated from the default scheme, it comes first among all other rules collected under the same target name. -.. note:: - - The linker script template currently used is :component:`esp32/ld/esp32.project.ld.in`, specified by the ``esp32`` component; the + The linker script template currently used is :component:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}.project.ld.in`, specified by the ``{IDF_TARGET_PATH_NAME}`` component; the generated output script is put under its build directory. - - diff --git a/docs/en/api-guides/partition-tables.rst b/docs/en/api-guides/partition-tables.rst index 91fe17e0e3..c0cdea82a4 100644 --- a/docs/en/api-guides/partition-tables.rst +++ b/docs/en/api-guides/partition-tables.rst @@ -5,7 +5,7 @@ Partition Tables Overview -------- -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 (:ref:`default offset `) 0x8000 in the flash. +A single {IDF_TARGET_NAME}'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 (:ref:`default offset `) 0x8000 in the flash. Partition table length is 0xC00 bytes (maximum 95 partition table entries). An MD5 checksum, which is used for checking the integrity of the partition table, is appended after the table data. If the partition table is signed due to `secure boot`, the signature is appended after the partition table. @@ -23,7 +23,7 @@ Built-in Partition Tables Here is the summary printed for the "Single factory app, no OTA" configuration:: - # Espressif ESP32 Partition Table + # Espressif ESP Partition Table # Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x6000, phy_init, data, phy, 0xf000, 0x1000, @@ -34,7 +34,7 @@ Here is the summary printed for the "Single factory app, no OTA" configuration:: Here is the summary printed for the "Factory app, two OTA definitions" configuration:: - # Espressif ESP32 Partition Table + # Espressif ESP Partition Table # Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x4000, otadata, data, ota, 0xd000, 0x2000, @@ -69,7 +69,7 @@ The CSV format is the same format as printed in the summaries shown above. Howev Name field ~~~~~~~~~~ -Name field can be any meaningful name. It is not significant to the ESP32. Names longer than 16 characters will be truncated. +Name field can be any meaningful name. It is not significant to the {IDF_TARGET_NAME}. Names longer than 16 characters will be truncated. Type field ~~~~~~~~~~ @@ -136,7 +136,7 @@ Only one flag is currently supported, ``encrypted``. If this field is set to ``e Generating Binary Partition Table --------------------------------- -The partition table which is flashed to the ESP32 is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats. +The partition table which is flashed to the {IDF_TARGET_NAME} is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats. If you configure the partition table CSV name in the project configuration (``idf.py menuconfig``) and then build the project or run ``idf.py partition_table``, this conversion is done as part of the build process. diff --git a/docs/en/api-guides/romconsole.rst b/docs/en/api-guides/romconsole.rst index d33ca00005..e34d8ca9db 100644 --- a/docs/en/api-guides/romconsole.rst +++ b/docs/en/api-guides/romconsole.rst @@ -1,9 +1,9 @@ -***************** -ESP32 ROM console -***************** +***************************** +{IDF_TARGET_NAME} ROM console +***************************** -When an ESP32 is unable to boot from flash ROM (and the fuse disabling it hasn't been blown), it boots into a rom console. The console -is based on TinyBasic, and statements entered should be in the form of BASIC statements. As is common in the BASIC language, without a +When an {IDF_TARGET_NAME} is unable to boot from flash ROM (and the fuse disabling it hasn't been blown), it boots into a rom console. The console +is based on TinyBasic, and statements entered should be in the form of BASIC statements. As is common in the BASIC language, without a preceeding line number, commands entered are executed immediately; lines with a prefixed line number are stored as part of a program. Full list of supported statements and functions @@ -12,7 +12,7 @@ Full list of supported statements and functions System ------ -- BYE - *exits Basic, reboots ESP32, retries booting from flash* +- BYE - *exits Basic, reboots and retries booting from flash* - END - *stops execution from the program, also "STOP"* - MEM - *displays memory usage statistics* - NEW - *clears the current program* diff --git a/docs/en/api-guides/tools/idf-monitor.rst b/docs/en/api-guides/tools/idf-monitor.rst index 2a5022ef04..b5cd8bb4ef 100644 --- a/docs/en/api-guides/tools/idf-monitor.rst +++ b/docs/en/api-guides/tools/idf-monitor.rst @@ -89,11 +89,11 @@ IDF Monitor adds more details to the dump:: 0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:47 0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:42 0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:33 - 0x400d071d: main_task at /home/gus/esp/32/idf/components/esp32/./cpu_start.c:254 + 0x400d071d: main_task at /home/gus/esp/32/idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:254 To decode each address, IDF Monitor runs the following command in the background:: - xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS + xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS Launching GDB with GDBStub @@ -103,19 +103,13 @@ By default, if esp-idf crashes, the panic handler prints relevant registers and Optionally, the panic handler can be configured to run GDBStub, the tool which can communicate with GDB_ project debugger. GDBStub allows to read memory, examine call stack frames and variables, etc. It is not as versatile as JTAG debugging, but this method does not require any special hardware. -.. only:: esp32 - - To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32_PANIC` to ``Invoke GDBStub``. - -.. only:: esp32s2 - - To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32S2_PANIC` to ``Invoke GDBStub``. +To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC` to ``Invoke GDBStub``. In this case, if the panic handler is triggered, as soon as IDF Monitor sees that GDBStub has loaded, it automatically pauses serial monitoring and runs GDB with necessary arguments. After GDB exits, the board is reset via the RTS serial line. If this line is not connected, please reset the board manually by pressing its Reset button. In the background, IDF Monitor runs the following command:: - xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf + xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf :idf_target:`Hello NAME chip` Output Filtering @@ -134,7 +128,7 @@ For example, ``PRINT_FILTER="tag1:W"`` matches and prints only the outputs writt which can be useful for adjusting the filtering options without recompiling the application. -Your app tags must not contain spaces, asterisks ``*``, +Your app tags must not contain spaces, asterisks ``*``, and semicolons ``:`` to be compatible with the output filtering feature. If the last line of the output in your app is not followed by a carriage return, the output filtering might get confused, i.e., the monitor starts to print the line and later finds out that the line should not have been written. This is a known issue and can be avoided by always adding a carriage return (especially when no output follows immediately afterwards). diff --git a/docs/en/api-guides/ulp.rst b/docs/en/api-guides/ulp.rst index 5de0e49f95..a9197465f6 100644 --- a/docs/en/api-guides/ulp.rst +++ b/docs/en/api-guides/ulp.rst @@ -6,8 +6,8 @@ ULP Coprocessor programming .. toctree:: :maxdepth: 1 - Instruction set reference for ESP32 ULP - Instruction set reference for ESP32-S2 ULP + :esp32: Instruction set reference for ESP32 ULP + :esp32s2: Instruction set reference for ESP32-S2 ULP Programming using macros (legacy) @@ -31,7 +31,7 @@ To compile the ULP code as part of the component, the following steps must be ta 1. The ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside the component directory, for instance `ulp/`. -.. note: When registering the component (via ``idf_component_register``), this directory should not be added to the ``SRC_DIRS`` argument. The logic behind this is that the ESP-IDF build system will compile files found in ``SRC_DIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files. +.. note: When registering the component (via ``idf_component_register``), this directory should not be added to the ``SRC_DIRS`` argument. The logic behind this is that the ESP-IDF build system will compile files found in ``SRC_DIRS`` based on their extensions. For ``.S`` files, ``xtensa-{IDF_TARGET_NAME}-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files. 2. Call ``ulp_embed_binary`` from the component CMakeLists.txt after registration. For example:: @@ -44,11 +44,11 @@ To compile the ULP code as part of the component, the following steps must be ta ulp_embed_binary(${ulp_app_name} ${ulp_s_sources} ${ulp_exp_dep_srcs}) - The first argument to ``ulp_embed_binary`` specifies the ULP binary name. The name specified here will also be used by other generated artifacts - such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP assembly source files. - Finally, the third argument specifies the list of component source files which include the header file to be generated. - This list is needed to build the dependencies correctly and ensure that the generated header file will be created before any of these files are compiled. - See section below for the concept of generated header files for ULP applications. + The first argument to ``ulp_embed_binary`` specifies the ULP binary name. The name specified here will also be used by other generated artifacts + such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP assembly source files. + Finally, the third argument specifies the list of component source files which include the header file to be generated. + This list is needed to build the dependencies correctly and ensure that the generated header file will be created before any of these files are compiled. + See section below for the concept of generated header files for ULP applications. 3. Build the application as usual (e.g. `idf.py app`) diff --git a/docs/en/api-guides/ulp_instruction_set.rst b/docs/en/api-guides/ulp_instruction_set.rst index 6eec2f4b53..fee3a76db5 100644 --- a/docs/en/api-guides/ulp_instruction_set.rst +++ b/docs/en/api-guides/ulp_instruction_set.rst @@ -1,7 +1,7 @@ ESP32 ULP coprocessor instruction set ===================================== -This document provides details about the instructions used by ESP32 ULP coprocessor assembler. +This document provides details about the instructions used by {IDF_TARGET_NAME} ULP coprocessor assembler. ULP coprocessor has 4 16-bit general purpose registers, labeled R0, R1, R2, R3. It also has an 8-bit counter register (stage_cnt) which can be used to implement loops. Stage count regiter is accessed using special instructions. @@ -13,7 +13,7 @@ The instruction syntax is case insensitive. Upper and lower case letters can be Note about addressing --------------------- -ESP32 ULP coprocessor's JUMP, ST, LD instructions which take register as an argument (jump address, store/load base address) expect the argument to be expressed in 32-bit words. +{IDF_TARGET_NAME} ULP coprocessor's JUMP, ST, LD instructions which take register as an argument (jump address, store/load base address) expect the argument to be expressed in 32-bit words. Consider the following example program:: @@ -160,9 +160,9 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low **Examples**:: 1: SUB R1, R2, R3 //R1 = R2 - R3 - + 2: sub R1, R2, 0x1234 //R1 = R2 - 0x1234 - + 3: .set value1, 0x03 //constant value1=0x03 SUB R1, R2, value1 //R1 = R2 - value1 4: .global label //declaration of variable label @@ -211,7 +211,7 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low **Syntax** **OR** *Rdst, Rsrc1, Rsrc2* - + **OR** *Rdst, Rsrc1, imm* **Operands** @@ -222,12 +222,12 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low **Cycles** 2 cycles to execute, 4 cycles to fetch next instruction - + **Description** The instruction does logical OR of a source register and another source register or 16-bit signed value and stores result to the destination register. **Examples**:: - + 1: OR R1, R2, R3 //R1 = R2 \| R3 2: OR R1, R2, 0x1234 //R1 = R2 \| 0x1234 @@ -255,7 +255,7 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low - *Rsrc1* - Register R[0..3] - *Rsrc2* - Register R[0..3] - *Imm* - 16-bit signed value - + **Cycles** 2 cycles to execute, 4 cycles to fetch next instruction @@ -373,7 +373,7 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low **Examples**:: 1: ST R1, R2, 0x12 //MEM[R2+0x12] = R1 - + 2: .data //Data section definition Addr1: .word 123 // Define label Addr1 16 bit .set offs, 0x00 // Define constant offs @@ -392,9 +392,9 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low **Operands** *Rdst* – Register R[0..3], destination - + *Rsrc* – Register R[0..3], holds address of destination, in 32-bit words - + *Offset* – 10-bit signed value, offset in bytes **Cycles** @@ -481,8 +481,8 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low - *EQ* (equal) – jump if value in R0 == threshold - *LT* (less than) – jump if value in R0 < threshold - *LE* (less or equal) – jump if value in R0 <= threshold - - *GT* (greater than) – jump if value in R0 > threshold - - *GE* (greater or equal) – jump if value in R0 >= threshold + - *GT* (greater than) – jump if value in R0 > threshold + - *GE* (greater or equal) – jump if value in R0 >= threshold **Cycles** @@ -551,7 +551,7 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low next: // JUMPS target, threshold, GT is implemented as: - + JUMPS next, threshold, LE JUMPS target, threshold, GE next: diff --git a/docs/en/api-guides/unit-tests.rst b/docs/en/api-guides/unit-tests.rst index 7eea5a4e31..bfc1000e39 100644 --- a/docs/en/api-guides/unit-tests.rst +++ b/docs/en/api-guides/unit-tests.rst @@ -1,5 +1,5 @@ -Unit Testing in ESP32 -============================= +Unit Testing in {IDF_TARGET_NAME} +================================= :link_to_translation:`zh_CN:[中文]` ESP-IDF comes with a unit test application that is based on the Unity - unit test framework. Unit tests are integrated in the ESP-IDF repository and are placed in the ``test`` subdirectories of each component respectively. @@ -98,7 +98,7 @@ Once the signal is sent from DUT2, you need to press "Enter" on DUT1, then DUT1 Multi-stage Test Cases ----------------------- -The normal test cases are expected to finish without reset (or only need to check if reset happens). Sometimes we expect to run some specific tests after certain kinds of reset. +The normal test cases are expected to finish without reset (or only need to check if reset happens). Sometimes we expect to run some specific tests after certain kinds of reset. For example, we expect to test if the reset reason is correct after a wakeup from deep sleep. We need to create a deep-sleep reset first and then check the reset reason. To support this, we can define multi-stage test cases, to group a set of test functions:: @@ -114,7 +114,7 @@ To support this, we can define multi-stage test cases, to group a set of test fu TEST_ASSERT(reason == DEEPSLEEP_RESET); } - TEST_CASE_MULTIPLE_STAGES("reset reason check for deepsleep", "[esp32]", trigger_deepsleep, check_deepsleep_reset_reason); + TEST_CASE_MULTIPLE_STAGES("reset reason check for deepsleep", "[{IDF_TARGET_PATH_NAME}]", trigger_deepsleep, check_deepsleep_reset_reason); Multi-stage test cases present a group of test functions to users. It needs user interactions (select cases and select different stages) to run the case. @@ -130,19 +130,19 @@ Change into ``tools/unit-test-app`` directory to configure and build it: * ``idf.py menuconfig`` - configure unit test app. * ``idf.py -T all build`` - build unit test app with tests for each component having tests in the ``test`` subdirectory. -* ``idf.py -T xxx build`` - build unit test app with tests for specific components. +* ``idf.py -T xxx build`` - build unit test app with tests for specific components. * ``idf.py -T all -E xxxbuild`` - build unit test app with all unit tests, except for unit tests of some components. (For instance: ``idf.py -T all -E ulp mbedtls build`` - build all unit tests exludes ``ulp`` and ``mbedtls`` components). When the build finishes, it will print instructions for flashing the chip. You can simply run ``idf.py flash`` to flash all build output. -You can also run ``idf.py -T all flash`` or ``idf.py -T xxx flash`` to build and flash. Everything needed will be rebuilt automatically before flashing. +You can also run ``idf.py -T all flash`` or ``idf.py -T xxx flash`` to build and flash. Everything needed will be rebuilt automatically before flashing. Use menuconfig to set the serial port for flashing. Running Unit Tests ------------------ -After flashing reset the ESP32 and it will boot the unit test app. +After flashing reset the {IDF_TARGET_NAME} and it will boot the unit test app. When unit test app is idle, press "Enter" will make it print test menu with all available tests:: @@ -168,7 +168,7 @@ When unit test app is idle, press "Enter" will make it print test menu with all (17) "SPI Master no response when switch from host1 (HSPI) to host2 (VSPI)" [spi] (18) "SPI Master DMA test, TX and RX in different regions" [spi] (19) "SPI Master DMA test: length, start, not aligned" [spi] - (20) "reset reason check for deepsleep" [esp32][test_env=UT_T2_1][multi_stage] + (20) "reset reason check for deepsleep" [{IDF_TARGET_PATH_NAME}][test_env=UT_T2_1][multi_stage] (1) "trigger_deepsleep" (2) "check_deepsleep_reset_reason" @@ -176,7 +176,7 @@ The normal case will print the case name and description. Master-slave cases wil Test cases can be run by inputting one of the following: -- Test case name in quotation marks to run a single test case +- Test case name in quotation marks to run a single test case - Test case index to run a single test case @@ -223,8 +223,8 @@ between runs and between different builds. A technique for eliminating for some variability is to place code and data in instruction or data RAM (IRAM/DRAM), respectively. The CPU can access IRAM and DRAM directly, eliminating the cache out of the equation. However, this might not always be viable as the size of IRAM and DRAM is limited. -The cache compensated timer is an alternative to placing the code/data to be benchmarked in IRAM/DRAM. This timer uses the processor's internal event counters in order to determine the amount -of time spent on waiting for code/data in case of a cache miss, then subtract that from the recorded wall time. +The cache compensated timer is an alternative to placing the code/data to be benchmarked in IRAM/DRAM. This timer uses the processor's internal event counters in order to determine the amount +of time spent on waiting for code/data in case of a cache miss, then subtract that from the recorded wall time. .. code-block:: c diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index b4f755baca..140c61b69b 100644 --- a/docs/en/api-guides/wifi.rst +++ b/docs/en/api-guides/wifi.rst @@ -1,8 +1,8 @@ Wi-Fi Driver ============= -ESP32 Wi-Fi Feature List -------------------------- +{IDF_TARGET_NAME} Wi-Fi Feature List +------------------------------------ - Support Station-only mode, AP-only mode, Station/AP-coexistence mode - Support IEEE-802.11B, IEEE-802.11G, IEEE802.11N and APIs to configure the protocol mode - Support WPA/WPA2/WPA2-Enterprise and WPS @@ -21,7 +21,7 @@ How To Write a Wi-Fi Application Preparation +++++++++++ -Generally, the most effective way to begin your own Wi-Fi application is to select an example which is similar to your own application, and port the useful part into your project. It is not a MUST but it is strongly recommended that you take some time to read this article first, especially if you want to program a robust Wi-Fi application. This article is supplementary to the Wi-Fi APIs/Examples. It describes the principles of using the Wi-Fi APIs, the limitations of the current Wi-Fi API implementation, and the most common pitfalls in using Wi-Fi. This article also reveals some design details of the Wi-Fi driver. We recommend that you become familiar at least with the following sections: <`ESP32 Wi-Fi API Error Code`_>, <`ESP32 Wi-Fi Programming Model`_>, and <`ESP32 Wi-Fi Event Description`_>. +Generally, the most effective way to begin your own Wi-Fi application is to select an example which is similar to your own application, and port the useful part into your project. It is not a MUST but it is strongly recommended that you take some time to read this article first, especially if you want to program a robust Wi-Fi application. This article is supplementary to the Wi-Fi APIs/Examples. It describes the principles of using the Wi-Fi APIs, the limitations of the current Wi-Fi API implementation, and the most common pitfalls in using Wi-Fi. This article also reveals some design details of the Wi-Fi driver. We recommend that you become familiar at least with the following sections: <`{IDF_TARGET_NAME} Wi-Fi API Error Code`_>, <`{IDF_TARGET_NAME} Wi-Fi Programming Model`_>, and <`{IDF_TARGET_NAME} Wi-Fi Event Description`_>. Setting Wi-Fi Compile-time Options ++++++++++++++++++++++++++++++++++++ @@ -29,28 +29,28 @@ Refer to <`Wi-Fi Menuconfig`_> Init Wi-Fi +++++++++++ -Refer to <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_>. +Refer to <`{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_>, <`{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_>. Start/Connect Wi-Fi ++++++++++++++++++++ -Refer to <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_>. +Refer to <`{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_>, <`{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_>. Event-Handling ++++++++++++++ -Generally, it is easy to write code in "sunny-day" scenarios, such as <`WIFI_EVENT_STA_START`_>, <`WIFI_EVENT_STA_CONNECTED`_> etc. The hard part is to write routines in "rainy-day" scenarios, such as <`WIFI_EVENT_STA_DISCONNECTED`_> etc. Good handling of "rainy-day" scenarios is fundamental to robust Wi-Fi applications. Refer to <`ESP32 Wi-Fi Event Description`_>, <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_>. See also :doc:`an overview of event handling in ESP-IDF`. +Generally, it is easy to write code in "sunny-day" scenarios, such as <`WIFI_EVENT_STA_START`_>, <`WIFI_EVENT_STA_CONNECTED`_> etc. The hard part is to write routines in "rainy-day" scenarios, such as <`WIFI_EVENT_STA_DISCONNECTED`_> etc. Good handling of "rainy-day" scenarios is fundamental to robust Wi-Fi applications. Refer to <`{IDF_TARGET_NAME} Wi-Fi Event Description`_>, <`{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_>, <`{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_>. See also :doc:`an overview of event handling in ESP-IDF`. -Write Error-Recovery Routines Correctly at All Times +Write Error-Recovery Routines Correctly at All Times ++++++++++++++++++++++++++++++++++++++++++++++++++++ -Just like the handling of "rainy-day" scenarios, a good error-recovery routine is also fundamental to robust Wi-Fi applications. Refer to <`ESP32 Wi-Fi API Error Code`_> +Just like the handling of "rainy-day" scenarios, a good error-recovery routine is also fundamental to robust Wi-Fi applications. Refer to <`{IDF_TARGET_NAME} Wi-Fi API Error Code`_> -ESP32 Wi-Fi API Error Code ---------------------------- -All of the ESP32 Wi-Fi APIs have well-defined return values, namely, the error code. The error code can be categorized into: +{IDF_TARGET_NAME} Wi-Fi API Error Code +-------------------------------------- +All of the {IDF_TARGET_NAME} Wi-Fi APIs have well-defined return values, namely, the error code. The error code can be categorized into: - No errors, e.g. ESP_OK means that the API returns successfully - Recoverable errors, such as ESP_ERR_NO_MEM, etc. - - Non-recoverable, non-critical errors - - Non-recoverable, critical errors + - Non-recoverable, non-critical errors + - Non-recoverable, critical errors Whether the error is critical or not depends on the API and the application scenario, and it is defined by the API user. @@ -63,8 +63,8 @@ Whether the error is critical or not depends on the API and the application scen In esp_err.h, ESP_ERROR_CHECK checks the return values. It is a rather commonplace error-handling code and can be used as the default error-handling code in the application development phase. However, we strongly recommend that API users write their own error-handling code. -ESP32 Wi-Fi API Parameter Initialization ------------------------------------------- +{IDF_TARGET_NAME} Wi-Fi API Parameter Initialization +---------------------------------------------------- When initializing struct parameters for the API, one of two approaches should be followed: - explicitly set all fields of the parameter or @@ -74,9 +74,9 @@ Initializing or getting the entire structure is very important because most of t .. _wifi-programming-model: -ESP32 Wi-Fi Programming Model ------------------------------ -The ESP32 Wi-Fi programming model is depicted as follows: +{IDF_TARGET_NAME} Wi-Fi Programming Model +----------------------------------------- +The {IDF_TARGET_NAME} Wi-Fi programming model is depicted as follows: .. blockdiag:: :caption: Wi-Fi Programming Model @@ -124,8 +124,8 @@ The Wi-Fi driver can be considered a black box that knows nothing about high-lay Wi-Fi event handling is based on the :doc:`esp_event library <../api-reference/system/esp_event>`. Events are sent by the Wi-Fi driver to the :ref:`default event loop `. Application may handle these events in callbacks registered using :cpp:func:`esp_event_handler_register`. Wi-Fi events are also handled by :doc:`esp_netif component <../api-reference/network/esp_netif>` to provide a set of default behaviors. For example, when Wi-Fi station connects to an AP, esp_netif will automatically start the DHCP client (by default). -ESP32 Wi-Fi Event Description ------------------------------------- +{IDF_TARGET_NAME} Wi-Fi Event Description +----------------------------------------- WIFI_EVENT_WIFI_READY ++++++++++++++++++++++++++++++++++++ @@ -137,15 +137,15 @@ The scan-done event is triggered by esp_wifi_scan_start() and will arise in the - The scan is completed, e.g., the target AP is found successfully, or all channels have been scanned. - The scan is stopped by esp_wifi_scan_stop(). - - The esp_wifi_scan_start() is called before the scan is completed. A new scan will override the current scan and a scan-done event will be generated. + - The esp_wifi_scan_start() is called before the scan is completed. A new scan will override the current scan and a scan-done event will be generated. The scan-done event will not arise in the following scenarios: - It is a blocked scan. - The scan is caused by esp_wifi_connect(). -Upon receiving this event, the event task does nothing. The application event callback needs to call esp_wifi_scan_get_ap_num() and esp_wifi_scan_get_ap_records() to fetch the scanned AP list and trigger the Wi-Fi driver to free the internal memory which is allocated during the scan **(do not forget to do this)**! -Refer to 'ESP32 Wi-Fi Scan' for a more detailed description. +Upon receiving this event, the event task does nothing. The application event callback needs to call esp_wifi_scan_get_ap_num() and esp_wifi_scan_get_ap_records() to fetch the scanned AP list and trigger the Wi-Fi driver to free the internal memory which is allocated during the scan **(do not forget to do this)**! +Refer to '{IDF_TARGET_NAME} Wi-Fi Scan' for a more detailed description. WIFI_EVENT_STA_START ++++++++++++++++++++++++++++++++++++ @@ -158,14 +158,14 @@ If esp_wifi_stop() returns ESP_OK and the current Wi-Fi mode is Station or AP+St WIFI_EVENT_STA_CONNECTED ++++++++++++++++++++++++++++++++++++ If esp_wifi_connect() returns ESP_OK and the station successfully connects to the target AP, the connection event will arise. Upon receiving this event, the event task starts the DHCP client and begins the DHCP process of getting the IP address. Then, the Wi-Fi driver is ready for sending and receiving data. This moment is good for beginning the application work, provided that the application does not depend on LwIP, namely the IP address. However, if the application is LwIP-based, then you need to wait until the *got ip* event comes in. - + WIFI_EVENT_STA_DISCONNECTED ++++++++++++++++++++++++++++++++++++ This event can be generated in the following scenarios: - When esp_wifi_disconnect(), or esp_wifi_stop(), or esp_wifi_deinit(), or esp_wifi_restart() is called and the station is already connected to the AP. - When esp_wifi_connect() is called, but the Wi-Fi driver fails to set up a connection with the AP due to certain reasons, e.g. the scan fails to find the target AP, authentication times out, etc. If there are more than one AP with the same SSID, the disconnected event is raised after the station fails to connect all of the found APs. - - When the Wi-Fi connection is disrupted because of specific reasons, e.g., the station continuously loses N beacons, the AP kicks off the station, the AP's authentication mode is changed, etc. + - When the Wi-Fi connection is disrupted because of specific reasons, e.g., the station continuously loses N beacons, the AP kicks off the station, the AP's authentication mode is changed, etc. Upon receiving this event, the default behavior of the event task is: - Shuts down the station's LwIP netif. @@ -180,7 +180,7 @@ Another thing deserves our attention is that the default behavior of LwIP is to - Five seconds later, the Wi-Fi connection is restored because esp_wifi_connect() is called in the application event callback function. **Moreover, the station connects to the same AP and gets the same IPV4 address as before**. - Sixty seconds later, when the application sends out data with the keep-alive socket, the socket returns an error and the application closes the socket and re-creates it when necessary. -In above scenario, ideally, the application sockets and the network layer should not be affected, since the Wi-Fi connection only fails temporarily and recovers very quickly. The application can enable "Keep TCP connections when IP changed" via LwIP menuconfig. +In above scenario, ideally, the application sockets and the network layer should not be affected, since the Wi-Fi connection only fails temporarily and recovers very quickly. The application can enable "Keep TCP connections when IP changed" via LwIP menuconfig. WIFI_EVENT_STA_AUTHMODE_CHANGE ++++++++++++++++++++++++++++++++++++ @@ -202,13 +202,13 @@ The socket is based on the IPV4 address, which means that, if the IPV4 changes, IP_EVENT_GOT_IP6 ++++++++++++++++++++++++++++++++++++ -This event arises when the IPV6 SLAAC support auto-configures an address for the ESP32, or when this address changes. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets). +This event arises when the IPV6 SLAAC support auto-configures an address for the {IDF_TARGET_NAME}, or when this address changes. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets). IP_STA_LOST_IP ++++++++++++++++++++++++++++++++++++ This event arises when the IPV4 address become invalid. -IP_STA_LOST_IP doesn't arise immediately after the WiFi disconnects, instead it starts an IPV4 address lost timer, if the IPV4 address is got before ip lost timer expires, IP_EVENT_STA_LOST_IP doesn't happen. Otherwise, the event arises when IPV4 address lost timer expires. +IP_STA_LOST_IP doesn't arise immediately after the WiFi disconnects, instead it starts an IPV4 address lost timer, if the IPV4 address is got before ip lost timer expires, IP_EVENT_STA_LOST_IP doesn't happen. Otherwise, the event arises when IPV4 address lost timer expires. Generally the application don't need to care about this event, it is just a debug event to let the application know that the IPV4 address is lost. @@ -222,7 +222,7 @@ Similar to <`WIFI_EVENT_STA_STOP`_>. WIFI_EVENT_AP_STACONNECTED ++++++++++++++++++++++++++++++++++++ -Every time a station is connected to ESP32 AP, the <`WIFI_EVENT_AP_STACONNECTED`_> will arise. Upon receiving this event, the event task will do nothing, and the application callback can also ignore it. However, you may want to do something, for example, to get the info of the connected STA, etc. +Every time a station is connected to {IDF_TARGET_NAME} AP, the <`WIFI_EVENT_AP_STACONNECTED`_> will arise. Upon receiving this event, the event task will do nothing, and the application callback can also ignore it. However, you may want to do something, for example, to get the info of the connected STA, etc. WIFI_EVENT_AP_STADISCONNECTED ++++++++++++++++++++++++++++++++++++ @@ -240,8 +240,8 @@ WIFI_EVENT_AP_PROBEREQRECVED This event is disabled by default. The application can enable it via API esp_wifi_set_event_mask(). When this event is enabled, it will be raised each time the AP receives a probe request. -ESP32 Wi-Fi Station General Scenario ---------------------------------------- +{IDF_TARGET_NAME} Wi-Fi Station General Scenario +------------------------------------------------ Below is a "big scenario" which describes some small scenarios in Station mode: .. seqdiag:: @@ -255,9 +255,9 @@ Below is a "big scenario" which describes some small scenarios in Station mode: edge_length = 140; span_height = 5; default_shape = roundedbox; - default_fontsize = 12; + default_fontsize = 12; - MAIN_TASK [label = "Main\ntask"]; + MAIN_TASK [label = "Main\ntask"]; APP_TASK [label = "App\ntask"]; EVENT_TASK [label = "Event\ntask"]; LwIP_TASK [label = "LwIP\ntask"]; @@ -302,7 +302,7 @@ Below is a "big scenario" which describes some small scenarios in Station mode: ++++++++++++++++++++++++++++++ - s1.1: The main task calls esp_netif_init() to create an LwIP core task and initialize LwIP-related work. - - s1.2: The main task calls esp_event_loop_init() to create a system Event task and initialize an application event's callback function. In the scenario above, the application event's callback function does nothing but relaying the event to the application task. + - s1.2: The main task calls esp_event_loop_init() to create a system Event task and initialize an application event's callback function. In the scenario above, the application event's callback function does nothing but relaying the event to the application task. - s1.3: The main task calls esp_netif_create_default_wifi_ap() or esp_netif_create_default_wifi_sta() to create default network interface instance binding station or AP with TCP/IP stack. @@ -314,7 +314,7 @@ Step 1.1~1.5 is a recommended sequence that initializes a Wi-Fi-/LwIP-based appl 2. Wi-Fi Configuration Phase +++++++++++++++++++++++++++++++ -Once the Wi-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode is Station, so you may need to call esp_wifi_set_mode(WIFI_MODE_STA) to configure the Wi-Fi mode as Station. You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, country code, bandwidth, etc. Refer to <`ESP32 Wi-Fi Configuration`_>. +Once the Wi-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode is Station, so you may need to call esp_wifi_set_mode(WIFI_MODE_STA) to configure the Wi-Fi mode as Station. You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, country code, bandwidth, etc. Refer to <`{IDF_TARGET_NAME} Wi-Fi Configuration`_>. Generally, we configure the Wi-Fi driver before setting up the Wi-Fi connection, but this is **NOT** mandatory, which means that you can configure the Wi-Fi connection anytime, provided that the Wi-Fi driver is initialized successfully. However, if the configuration does not need to change after the Wi-Fi connection is set up, you should configure the Wi-Fi driver at this stage, because the configuration APIs (such as esp_wifi_set_protocol) will cause the Wi-Fi to reconnect, which may not be desirable. @@ -325,12 +325,12 @@ If the Wi-Fi NVS flash is enabled by menuconfig, all Wi-Fi configuration in this - s3.1: Call esp_wifi_start to start the Wi-Fi driver. - s3.2: The Wi-Fi driver posts <`WIFI_EVENT_STA_START`_> to the event task; then, the event task will do some common things and will call the application event callback function. - s3.3: The application event callback function relays the <`WIFI_EVENT_STA_START`_> to the application task. We recommend that you call esp_wifi_connect(). However, you can also call esp_wifi_connect() in other phrases after the <`WIFI_EVENT_STA_START`_> arises. - + 4. Wi-Fi Connect Phase +++++++++++++++++++++++++++++++++ - s4.1: Once esp_wifi_connect() is called, the Wi-Fi driver will start the internal scan/connection process. - - s4.2: If the internal scan/connection process is successful, the <`WIFI_EVENT_STA_CONNECTED`_> will be generated. In the event task, it starts the DHCP client, which will finally trigger the DHCP process. + - s4.2: If the internal scan/connection process is successful, the <`WIFI_EVENT_STA_CONNECTED`_> will be generated. In the event task, it starts the DHCP client, which will finally trigger the DHCP process. - s4.3: In the above-mentioned scenario, the application event callback will relay the event to the application task. Generally, the application needs to do nothing, and you can do whatever you want, e.g., print a log, etc. @@ -347,7 +347,7 @@ In step 4.2, the Wi-Fi connection may fail because, for example, the password is +++++++++++++++++++++++++++++++++ - s6.1: When the Wi-Fi connection is disrupted, e.g. because the AP is powered off, the RSSI is poor, etc., <`WIFI_EVENT_STA_DISCONNECTED`_> will arise. This event may also arise in phase 3. Here, the event task will notify the LwIP task to clear/remove all UDP/TCP connections. Then, all application sockets will be in a wrong status. In other words, no socket can work properly when this event happens. - s6.2: In the scenario described above, the application event callback function relays <`WIFI_EVENT_STA_DISCONNECTED`_> to the application task. We recommend that esp_wifi_connect() be called to reconnect the Wi-Fi, close all sockets and re-create them if necessary. Refer to <`WIFI_EVENT_STA_DISCONNECTED`_>. - + 7. Wi-Fi IP Change Phase ++++++++++++++++++++++++++++++++++ @@ -363,7 +363,7 @@ In step 4.2, the Wi-Fi connection may fail because, for example, the password is - s8.3: Call esp_wifi_deinit() to unload the Wi-Fi driver. -ESP32 Wi-Fi AP General Scenario +{IDF_TARGET_NAME} Wi-Fi AP General Scenario --------------------------------------------- Below is a "big scenario" which describes some small scenarios in AP mode: @@ -378,9 +378,9 @@ Below is a "big scenario" which describes some small scenarios in AP mode: edge_length = 140; span_height = 5; default_shape = roundedbox; - default_fontsize = 12; + default_fontsize = 12; - MAIN_TASK [label = "Main\ntask"]; + MAIN_TASK [label = "Main\ntask"]; APP_TASK [label = "App\ntask"]; EVENT_TASK [label = "Event\ntask"]; LwIP_TASK [label = "LwIP\ntask"]; @@ -411,46 +411,46 @@ Below is a "big scenario" which describes some small scenarios in AP mode: } -ESP32 Wi-Fi Scan +{IDF_TARGET_NAME} Wi-Fi Scan ------------------------ Currently, the esp_wifi_scan_start() API is supported only in Station or Station+AP mode. -Scan Type +Scan Type +++++++++++++++++++++++++ +------------------+--------------------------------------------------------------+ -| Mode | Description | +| Mode | Description | +==================+==============================================================+ | Active Scan | Scan by sending a probe request. | -| | The default scan is an active scan. | -| | | +| | The default scan is an active scan. | +| | | +------------------+--------------------------------------------------------------+ | Passive Scan | No probe request is sent out. Just switch to the specific | -| | channel and wait for a beacon. | +| | channel and wait for a beacon. | | | Application can enable it via the scan_type field of | -| | wifi_scan_config_t. | -| | | +| | wifi_scan_config_t. | +| | | +------------------+--------------------------------------------------------------+ | Foreground Scan | This scan is applicable when there is no Wi-Fi connection | | | in Station mode. Foreground or background scanning is | -| | controlled by the Wi-Fi driver and cannot be configured by | -| | the application. | +| | controlled by the Wi-Fi driver and cannot be configured by | +| | the application. | +------------------+--------------------------------------------------------------+ | Background Scan | This scan is applicable when there is a Wi-Fi connection in | -| | Station mode or in Station+AP mode. | +| | Station mode or in Station+AP mode. | | | Whether it is a foreground scan or background scan depends on| -| | the Wi-Fi driver and cannot be configured by the application.| -| | | +| | the Wi-Fi driver and cannot be configured by the application.| +| | | +------------------+--------------------------------------------------------------+ -| All-Channel Scan | It scans all of the channels. | +| All-Channel Scan | It scans all of the channels. | | | If the channel field of wifi_scan_config_t is set to 0, it is| | | an all-channel scan. | | | | +------------------+--------------------------------------------------------------+ | Specific Channel | It scans specific channels only. | | Scan | If the channel field of wifi_scan_config_t set to 1, it is a | -| | specific-channel scan. | +| | specific-channel scan. | | | | +------------------+--------------------------------------------------------------+ @@ -533,7 +533,7 @@ Scenario: edge_length = 160; span_height = 5; default_shape = roundedbox; - default_fontsize = 12; + default_fontsize = 12; APP_TASK [label = "App\ntask"]; EVENT_TASK [label = "Event\ntask"]; @@ -550,7 +550,7 @@ Scenario: } -The scenario above describes an all-channel, foreground scan. The foreground scan can only occur in Station mode where the station does not connect to any AP. Whether it is a foreground or background scan is totally determined by the Wi-Fi driver, and cannot be configured by the application. +The scenario above describes an all-channel, foreground scan. The foreground scan can only occur in Station mode where the station does not connect to any AP. Whether it is a foreground or background scan is totally determined by the Wi-Fi driver, and cannot be configured by the application. Detailed scenario description: @@ -589,7 +589,7 @@ Scenario: edge_length = 160; span_height = 5; default_shape = roundedbox; - default_fontsize = 12; + default_fontsize = 12; APP_TASK [label = "App\ntask"]; EVENT_TASK [label = "Event\ntask"]; @@ -625,7 +625,7 @@ Scenario: edge_length = 160; span_height = 5; default_shape = roundedbox; - default_fontsize = 12; + default_fontsize = 12; APP_TASK [label = "App\ntask"]; EVENT_TASK [label = "Event\ntask"]; @@ -662,7 +662,7 @@ If the block parameter of esp_wifi_scan_start() is true, then the scan is a bloc Parallel Scan +++++++++++++ -Two application tasks may call esp_wifi_scan_start() at the same time, or the same application task calls esp_wifi_scan_start() before it gets a scan-done event. Both scenarios can happen. **However, the Wi-Fi driver does not support multiple concurrent scans adequately. As a result, concurrent scans should be avoided.** Support for concurrent scan will be enhanced in future releases, as the ESP32's Wi-Fi functionality improves continuously. +Two application tasks may call esp_wifi_scan_start() at the same time, or the same application task calls esp_wifi_scan_start() before it gets a scan-done event. Both scenarios can happen. **However, the Wi-Fi driver does not support multiple concurrent scans adequately. As a result, concurrent scans should be avoided.** Support for concurrent scan will be enhanced in future releases, as the {IDF_TARGET_NAME}'s Wi-Fi functionality improves continuously. Scan When Wi-Fi Is Connecting +++++++++++++++++++++++++++++++ @@ -681,10 +681,10 @@ In above scenario the scan will never succeed because the connecting is in proce The application can define its own reconnect strategy to avoid the scan starve to death. Refer to <`Wi-Fi Reconnect`_>. -ESP32 Wi-Fi Station Connecting Scenario ----------------------------------------- +{IDF_TARGET_NAME} Wi-Fi Station Connecting Scenario +--------------------------------------------------- -This scenario only depicts the case when there is only one target AP are found in scan phase, for the scenario that more than one AP with the same SSID are found, refer to <`ESP32 Wi-Fi Station Connecting When Multiple APs Are Found`_>. +This scenario only depicts the case when there is only one target AP are found in scan phase, for the scenario that more than one AP with the same SSID are found, refer to <`{IDF_TARGET_NAME} Wi-Fi Station Connecting When Multiple APs Are Found`_>. Generally, the application does not need to care about the connecting process. Below is a brief introduction to the process for those who are really interested. @@ -701,7 +701,7 @@ Scenario: edge_length = 160; span_height = 5; default_shape = roundedbox; - default_fontsize = 12; + default_fontsize = 12; EVENT_TASK [label = "Event\ntask"]; WIFI_TASK [label = "Wi-Fi\ntask"]; @@ -737,13 +737,13 @@ Scan Phase +++++++++++++++++++++ - s1.1, The Wi-Fi driver begins scanning in "Wi-Fi Connect". Refer to <`Scan in Wi-Fi Connect`_> for more details. - - s1.2, If the scan fails to find the target AP, <`WIFI_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_NO_AP_FOUND. Refer to <`Wi-Fi Reason Code`_>. + - s1.2, If the scan fails to find the target AP, <`WIFI_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_NO_AP_FOUND. Refer to <`Wi-Fi Reason Code`_>. Auth Phase +++++++++++++++++++++ - s2.1, The authentication request packet is sent and the auth timer is enabled. - - s2.2, If the authentication response packet is not received before the authentication timer times out, <`WIFI_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_AUTH_EXPIRE. Refer to <`Wi-Fi Reason Code`_>. + - s2.2, If the authentication response packet is not received before the authentication timer times out, <`WIFI_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_AUTH_EXPIRE. Refer to <`Wi-Fi Reason Code`_>. - s2.3, The auth-response packet is received and the auth-timer is stopped. - s2.4, The AP rejects authentication in the response and <`WIFI_EVENT_STA_DISCONNECTED`_> arises, while the reason-code is WIFI_REASON_AUTH_FAIL or the reasons specified by the AP. Refer to <`Wi-Fi Reason Code`_>. @@ -753,22 +753,22 @@ Association Phase - s3.1, The association request is sent and the association timer is enabled. - s3.2, If the association response is not received before the association timer times out, <`WIFI_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_ASSOC_EXPIRE. Refer to <`Wi-Fi Reason Code`_>. - s3.3, The association response is received and the association timer is stopped. - - s3.4, The AP rejects the association in the response and <`WIFI_EVENT_STA_DISCONNECTED`_> arises, while the reason-code is the one specified in the association response. Refer to <`Wi-Fi Reason Code`_>. + - s3.4, The AP rejects the association in the response and <`WIFI_EVENT_STA_DISCONNECTED`_> arises, while the reason-code is the one specified in the association response. Refer to <`Wi-Fi Reason Code`_>. Four-way Handshake Phase ++++++++++++++++++++++++++ - s4.1, The four-way handshake is sent out and the association timer is enabled. - - s4.2, If the association response is not received before the association timer times out, <`WIFI_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_ASSOC_EXPIRE. Refer to <`Wi-Fi Reason Code`_>. + - s4.2, If the association response is not received before the association timer times out, <`WIFI_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_ASSOC_EXPIRE. Refer to <`Wi-Fi Reason Code`_>. - s4.3, The association response is received and the association timer is stopped. - - s4.4, The AP rejects the association in the response and <`WIFI_EVENT_STA_DISCONNECTED`_> arises and the reason-code will be the one specified in the association response. Refer to <`Wi-Fi Reason Code`_>. + - s4.4, The AP rejects the association in the response and <`WIFI_EVENT_STA_DISCONNECTED`_> arises and the reason-code will be the one specified in the association response. Refer to <`Wi-Fi Reason Code`_>. Wi-Fi Reason Code +++++++++++++++++++++ -The table below shows the reason-code defined in ESP32. The first column is the macro name defined in esp_wifi_types.h. The common prefix *WIFI_REASON* is removed, which means that *UNSPECIFIED* actually stands for *WIFI_REASON_UNSPECIFIED* and so on. The second column is the value of the reason. The third column is the standard value to which this reason is mapped in section 8.4.1.7 of ieee802.11-2012. (For more information, refer to the standard mentioned above.) The last column is a description of the reason. +The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first column is the macro name defined in esp_wifi_types.h. The common prefix *WIFI_REASON* is removed, which means that *UNSPECIFIED* actually stands for *WIFI_REASON_UNSPECIFIED* and so on. The second column is the value of the reason. The third column is the standard value to which this reason is mapped in section 8.4.1.7 of ieee802.11-2012. (For more information, refer to the standard mentioned above.) The last column is a description of the reason. +---------------------------+-------+---------+-------------------------------------------------------------+ | Reason code | Value |Mapped To| Description | @@ -779,12 +779,12 @@ The table below shows the reason-code defined in ESP32. The first column is the +---------------------------+-------+---------+-------------------------------------------------------------+ | AUTH_EXPIRE | 2 | 2 | The previous authentication is no longer valid. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - auth is timed out | | | | | - the reason is received from the AP. | | | | | | -| | | | For the ESP32 AP, this reason is reported when: | +| | | | For the ESP AP, this reason is reported when: | | | | | | | | | | - the AP has not received any packets from the station | | | | | in the past five minutes. | @@ -795,18 +795,18 @@ The table below shows the reason-code defined in ESP32. The first column is the | AUTH_LEAVE | 3 | 3 | De-authenticated, because the sending STA is | | | | | leaving (or has left). | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | ASSOC_EXPIRE | 4 | 4 | Disassociated due to inactivity. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | -| | | | | -| | | | For the ESP32 AP, this reason is reported when: | +| | | | | +| | | | For the ESP AP, this reason is reported when: | | | | | | | | | | - the AP has not received any packets from the | | | | | station in the past five minutes. | @@ -817,111 +817,111 @@ The table below shows the reason-code defined in ESP32. The first column is the | ASSOC_TOOMANY | 5 | 5 | Disassociated, because the AP is unable to handle | | | | | all currently associated STAs at the same time. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | -| | | | | -| | | | For the ESP32 AP, this reason is reported when: | +| | | | | +| | | | For the ESP AP, this reason is reported when: | | | | | | | | | | - the stations associated with the AP reach the | | | | | maximum number that the AP can support. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | NOT_AUTHED | 6 | 6 | Class-2 frame received from a non-authenticated STA. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | | | | | | -| | | | For the ESP32 AP, this reason is reported when: | -| | | | | +| | | | For the ESP AP, this reason is reported when: | +| | | | | | | | | - the AP receives a packet with data from a | | | | | non-authenticated station. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | NOT_ASSOCED | 7 | 7 | Class-3 frame received from a non-associated STA. | -| | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | -| | | | | -| | | | For the ESP32 AP, this reason is reported when: | -| | | | | +| | | | | +| | | | For the ESP AP, this reason is reported when: | +| | | | | | | | | - the AP receives a packet with data from a | | | | | non-associated station. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | ASSOC_LEAVE | 8 | 8 | Disassociated, because the sending STA is leaving (or has | | | | | left) BSS. | -| | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | | | | | - the station is disconnected by esp_wifi_disconnect() and | | | | | other APIs. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | ASSOC_NOT_AUTHED | 9 | 9 | STA requesting (re)association is not authenticated by the | | | | | responding STA. | -| | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | -| | | | | -| | | | For the ESP32 AP, this reason is reported when: | -| | | | | +| | | | | +| | | | For the ESP AP, this reason is reported when: | +| | | | | | | | | - the AP receives packets with data from an | | | | | associated, yet not authenticated, station. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | DISASSOC_PWRCAP_BAD | 10 | 10 | Disassociated, because the information in the Power | | | | | Capability element is unacceptable. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | DISASSOC_SUPCHAN_BAD | 11 | 11 | Disassociated, because the information in the Supported | | | | | Channels element is unacceptable. | -| | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | IE_INVALID | 13 | 13 | Invalid element, i.e. an element whose content does not meet| | | | | the specifications of the Standard in Clause 8. | -| | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP | | | | | | -| | | | For the ESP32 AP, this reason is reported when: | -| | | | | +| | | | For the ESP AP, this reason is reported when: | +| | | | | | | | | - the AP parses a wrong WPA or RSN IE. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | MIC_FAILURE | 14 | 14 | Message integrity code (MIC) failure. | -| | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ -| 4WAY_HANDSHAKE_TIMEOUT | 15 | 15 | Four-way handshake times out. For legacy reasons, in ESP32 | +| 4WAY_HANDSHAKE_TIMEOUT | 15 | 15 | Four-way handshake times out. For legacy reasons, in ESP | | | | | this reason-code is replaced with | | | | | WIFI_REASON_HANDSHAKE_TIMEOUT. | -| | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - the handshake times out | | | | | - it is received from the AP. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | GROUP_KEY_UPDATE_TIMEOUT | 16 | 16 | Group-Key Handshake times out. | -| | | | | -| | | | For the ESP32 station, this reason is reported when: | +| | | | | +| | | | For the ESP station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | | | | | | @@ -929,7 +929,7 @@ The table below shows the reason-code defined in ESP32. The first column is the | IE_IN_4WAY_DIFFERS | 17 | 17 | The element in the four-way handshake is different from the | | | | | (Re-)Association Request/Probe and Response/Beacon frame. | | | | | | -| | | | For the ESP32 station, this reason is reported when: | +| | | | For the ESP station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | | | | | - the station finds that the four-way handshake IE differs | @@ -939,59 +939,59 @@ The table below shows the reason-code defined in ESP32. The first column is the +---------------------------+-------+---------+-------------------------------------------------------------+ | GROUP_CIPHER_INVALID | 18 | 18 | Invalid group cipher. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | PAIRWISE_CIPHER_INVALID | 19 | 19 | Invalid pairwise cipher. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | AKMP_INVALID | 20 | 20 | Invalid AKMP. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | UNSUPP_RSN_IE_VERSION | 21 | 21 | Unsupported RSNE version. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | INVALID_RSN_IE_CAP | 22 | 22 | Invalid RSNE capabilities. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | 802_1X_AUTH_FAILED | 23 | 23 | IEEE 802.1X. authentication failed. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | | | | | | -| | | | For the ESP32 AP, this reason is reported when: | -| | | | | +| | | | For the ESP AP, this reason is reported when: | +| | | | | | | | | - 802.1 x authentication fails. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | CIPHER_SUITE_REJECTED | 24 | 24 | Cipher suite rejected due to security policies. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | BEACON_TIMEOUT | 200 |reserved | Espressif-specific Wi-Fi reason-code: when the station | -| | | | loses N beacons continuously, it will disrupt the connection| +| | | | loses N beacons continuously, it will disrupt the connection| | | | | and report this reason. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ @@ -1005,7 +1005,7 @@ The table below shows the reason-code defined in ESP32. The first column is the +---------------------------+-------+---------+-------------------------------------------------------------+ | ASSOC_FAIL | 203 |reserved | Espressif-specific Wi-Fi reason-code: the association | | | | | fails, but not because of ASSOC_EXPIRE or ASSOC_TOOMANY. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | HANDSHAKE_TIMEOUT | 204 |reserved | Espressif-specific Wi-Fi reason-code: the | | | | | handshake fails for the same reason as that in | @@ -1013,10 +1013,10 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ -ESP32 Wi-Fi Station Connecting When Multiple APs Are Found ---------------------------------------------------------------- +{IDF_TARGET_NAME} Wi-Fi Station Connecting When Multiple APs Are Found +---------------------------------------------------------------------- -This scenario is similar as <`ESP32 Wi-Fi Station Connecting Scenario`_>, the difference is the station will not raise the event <`WIFI_EVENT_STA_DISCONNECTED`_> unless it fails to connect all of the found APs. +This scenario is similar as <`{IDF_TARGET_NAME} Wi-Fi Station Connecting Scenario`_>, the difference is the station will not raise the event <`WIFI_EVENT_STA_DISCONNECTED`_> unless it fails to connect all of the found APs. Wi-Fi Reconnect @@ -1033,12 +1033,12 @@ Another thing we need to consider is the reconnect may not connect the same AP i Wi-Fi Beacon Timeout --------------------------- -The beacon timeout mechanism is used by ESP32 station to detect whether the AP is alive or not. If the station continuously loses 60 beacons of the connected AP, the beacon timeout happens. +The beacon timeout mechanism is used by {IDF_TARGET_NAME} station to detect whether the AP is alive or not. If the station continuously loses 60 beacons of the connected AP, the beacon timeout happens. After the beacon timeout happens, the station sends 5 probe requests to AP, it disconnects the AP and raises the event <`WIFI_EVENT_STA_DISCONNECTED`_> if still no probe response or beacon is received from AP. -ESP32 Wi-Fi Configuration ---------------------------- +{IDF_TARGET_NAME} Wi-Fi Configuration +------------------------------------- All configurations will be stored into flash when the Wi-Fi NVS is enabled; otherwise, refer to <`Wi-Fi NVS Flash`_>. @@ -1054,7 +1054,7 @@ Call esp_wifi_set_mode() to set the Wi-Fi mode. | | station and AP interfaces are not initialized for | | | RX/TX Wi-Fi data. Generally, this mode is used for Sniffer, | | | or when you only want to stop both the STA and the AP | -| | without calling esp_wifi_deinit() to unload the whole Wi-Fi | +| | without calling esp_wifi_deinit() to unload the whole Wi-Fi | | | driver. | +------------------+--------------------------------------------------------------+ | WIFI_MODE_STA | Station mode: in this mode, esp_wifi_start() will init the | @@ -1071,8 +1071,8 @@ Call esp_wifi_set_mode() to set the Wi-Fi mode. | WIFI_MODE_APSTA | Station-AP coexistence mode: in this mode, esp_wifi_start() | | | will simultaneously init both the station and the AP. | | | This is done in station mode and AP mode. Please note | -| | that the channel of the external AP, which the ESP32 Station | -| | is connected to, has higher priority over the ESP32 AP | +| | that the channel of the external AP, which the ESP Station | +| | is connected to, has higher priority over the ESP AP | | | channel. | +------------------+--------------------------------------------------------------+ @@ -1169,7 +1169,7 @@ API esp_wifi_set_config() can be used to configure the AP. The table below descr | | sure the channel is within the required range. | | | For more details, refer to <`Wi-Fi Country Code`_>. | +------------------+--------------------------------------------------------------+ -| authmode | Auth mode of ESP32 AP; currently, ESP32 Wi-Fi does not | +| authmode | Auth mode of ESP AP; currently, ESP Wi-Fi does not | | | support AUTH_WEP. If the authmode is an invalid value, | | | AP defaults the value to WIFI_AUTH_OPEN. | | | | @@ -1178,7 +1178,7 @@ API esp_wifi_set_config() can be used to configure the AP. The table below descr | | otherwise, it does broadcast the SSID. | | | | +------------------+--------------------------------------------------------------+ -| max_connection | Currently, ESP32 Wi-Fi supports up to 10 Wi-Fi connections. | +| max_connection | Currently, ESP Wi-Fi supports up to 10 Wi-Fi connections. | | | If max_connection > 10, AP defaults the value to 10. | | | | +------------------+--------------------------------------------------------------+ @@ -1219,18 +1219,18 @@ Currently, the IDF supports the following protocol modes: | | **This mode is an Espressif-patented mode which can achieve| | | a one-kilometer line of sight range. Please, make sure both| | | the station and the AP are connected to an | -| | ESP32 device** | +| | ESP device** | +--------------------+------------------------------------------------------------+ Long Range (LR) +++++++++++++++++++++++++ -Long Range (LR) mode is an Espressif-patented Wi-Fi mode which can achieve a one-kilometer line of sight range. It has better reception sensitivity, stronger anti-interference ability and longer transmission distance than the traditional 802.11B mode. +Long Range (LR) mode is an Espressif-patented Wi-Fi mode which can achieve a one-kilometer line of sight range. It has better reception sensitivity, stronger anti-interference ability and longer transmission distance than the traditional 802.11B mode. LR Compitability ************************* -Since LR is Espressif unique Wi-Fi mode, only ESP32 devices can transmit and receive the LR data. In other words, the ESP32 device should NOT transmit the data in LR data rate if the connected device doesn't support LR. The application can achieve this by configuring suitable Wi-Fi mode. If the negotiated mode supports LR, the ESP32 may transmit data in LR rate, otherwise, ESP32 will transmit all data in traditional Wi-Fi data rate. +Since LR is Espressif unique Wi-Fi mode, only {IDF_TARGET_NAME} devices can transmit and receive the LR data. In other words, the {IDF_TARGET_NAME} device should NOT transmit the data in LR data rate if the connected device doesn't support LR. The application can achieve this by configuring suitable Wi-Fi mode. If the negotiated mode supports LR, the {IDF_TARGET_NAME} may transmit data in LR rate, otherwise, {IDF_TARGET_NAME} will transmit all data in traditional Wi-Fi data rate. Following table depicts the Wi-Fi mode negotiation: @@ -1255,11 +1255,11 @@ Following table depicts the Wi-Fi mode negotiation: In above table, the row is the Wi-Fi mode of AP and the column is the Wi-Fi mode of station. The "-" indicates Wi-Fi mode of the AP and station are not compatible. According to the table, we can conclude that: - - For LR enabled in ESP32 AP, it's incompatible with traditional 802.11 mode because the beacon is sent in LR mode. - - For LR enabled in ESP32 station and the mode is NOT LR only mode, it's compatible with traditional 802.11 mode. - - If both station and AP are ESP32 devices and both of them enable LR mode, the negotiated mode supports LR. + - For LR enabled in {IDF_TARGET_NAME} AP, it's incompatible with traditional 802.11 mode because the beacon is sent in LR mode. + - For LR enabled in {IDF_TARGET_NAME} station and the mode is NOT LR only mode, it's compatible with traditional 802.11 mode. + - If both station and AP are {IDF_TARGET_NAME} devices and both of them enable LR mode, the negotiated mode supports LR. -If the negotiated Wi-Fi mode supports both traditional 802.11 mode and LR mode, it's the WiFi driver's responsibility to automatically select the best data rate in different Wi-Fi mode and the application don't need to care about it. +If the negotiated Wi-Fi mode supports both traditional 802.11 mode and LR mode, it's the WiFi driver's responsibility to automatically select the best data rate in different Wi-Fi mode and the application don't need to care about it. LR Impacts to Traditional Wi-Fi device *************************************** @@ -1284,7 +1284,7 @@ When to Use LR ************************* The general conditions for using LR are: - - Both the AP and station are ESP32 devices. + - Both the AP and station are devices. - Long distance WiFi connection and data transmission is required. - Data throughput requirements are very small, such as remote device control, etc. @@ -1387,23 +1387,23 @@ Following table depicts which country info is used in different WiFi Mode and di Home Channel ************************* -In AP mode, the home channel is defined as that of the AP channel. In Station mode, the home channel is defined as the channel of the AP to which the station is connected. In Station+AP mode, the home channel of AP and station must be the same. If the home channels of Station and AP are different, the station's home channel is always in priority. Take the following as an example: at the beginning, the AP is on channel 6, then the station connects to an AP whose channel is 9. Since the station's home channel has a higher priority, the AP needs to switch its channel from 6 to 9 to make sure that both station and AP have the same home channel. While switching channel, the ESP32 in SoftAP mode will notify the connected stations about the channel migration using a Channel Switch Announcement (CSA). Stations that support channel switching will transition smoothly whereas stations who do not will disconnect and reconnect to the SoftAP. +In AP mode, the home channel is defined as that of the AP channel. In Station mode, the home channel is defined as the channel of the AP to which the station is connected. In Station+AP mode, the home channel of AP and station must be the same. If the home channels of Station and AP are different, the station's home channel is always in priority. Take the following as an example: at the beginning, the AP is on channel 6, then the station connects to an AP whose channel is 9. Since the station's home channel has a higher priority, the AP needs to switch its channel from 6 to 9 to make sure that both station and AP have the same home channel. While switching channel, the {IDF_TARGET_NAME} in SoftAP mode will notify the connected stations about the channel migration using a Channel Switch Announcement (CSA). Stations that support channel switching will transition smoothly whereas stations who do not will disconnect and reconnect to the SoftAP. Wi-Fi Vendor IE Configuration +++++++++++++++++++++++++++++++++++ -By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and the application does not need to care about them. Some applications, however, may have to handle the beacon, probe request, probe response and other management frames. For example, if you insert some vendor-specific IE into the management frames, it is only the management frames which contain this vendor-specific IE that will be processed. In ESP32, esp_wifi_set_vendor_ie() and esp_wifi_set_vendor_ie_cb() are responsible for this kind of tasks. +By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and the application does not need to care about them. Some applications, however, may have to handle the beacon, probe request, probe response and other management frames. For example, if you insert some vendor-specific IE into the management frames, it is only the management frames which contain this vendor-specific IE that will be processed. In {IDF_TARGET_NAME}, esp_wifi_set_vendor_ie() and esp_wifi_set_vendor_ie_cb() are responsible for this kind of tasks. Wi-Fi Security ------------------------------- -In addition to traditional security methods (WEP/WPA-TKIP/WPA2-CCMP), ESP32 Wi-Fi now supports state-of-the-art security protocols, namely Protected Management Frames based on 802.11w standard and Wi-Fi Protected Access 3 (WPA3-Personal). Together, PMF and WPA3 provide better privacy and robustness against known attacks in traditional modes. +In addition to traditional security methods (WEP/WPA-TKIP/WPA2-CCMP), {IDF_TARGET_NAME} Wi-Fi now supports state-of-the-art security protocols, namely Protected Management Frames based on 802.11w standard and Wi-Fi Protected Access 3 (WPA3-Personal). Together, PMF and WPA3 provide better privacy and robustness against known attacks in traditional modes. Protected Management Frames (PMF) ++++++++++++++++++++++++++++++++++ -In Wi-Fi, management frames such as beacons, probes, (de)authentication, (dis)association are used by non-AP stations to scan and connect to an AP. Unlike data frames, these frames are sent unencrypted. +In Wi-Fi, management frames such as beacons, probes, (de)authentication, (dis)association are used by non-AP stations to scan and connect to an AP. Unlike data frames, these frames are sent unencrypted. An attacker can use eavesdropping and packet injection to send spoofed (de)authentication/(dis)association frames at the right time, leading to following attacks in case of unprotected management frame exchanges. - DOS attack on one or all clients in the range of the attacker. @@ -1414,11 +1414,11 @@ An attacker can use eavesdropping and packet injection to send spoofed (de)authe PMF provides protection against these attacks by encrypting unicast management frames and providing integrity checks for broadcast management frames. These include deauthentication, disassociation and robust management frames. It also provides Secure Association (SA) teardown mechanism to prevent spoofed association/authentication frames from disconnecting already connected clients. -ESP32 supports the following three modes of operation with respect to PMF. +{IDF_TARGET_NAME} supports the following three modes of operation with respect to PMF. - - PMF not supported: In this mode, ESP32 indicates to AP that it is not capable of supporting management protection during association. In effect, security in this mode will be equivalent to that in traditional mode. - - PMF capable, but not required: In this mode, ESP32 indicates to AP that it is capable of supporting PMF. The management protection will be used if AP mandates PMF or is at least capable of supporting PMF. - - PMF capable and required: In this mode, ESP32 will only connect to AP, if AP supports PMF. If not, ESP32 will refuse to connect to the AP. + - PMF not supported: In this mode, {IDF_TARGET_NAME} indicates to AP that it is not capable of supporting management protection during association. In effect, security in this mode will be equivalent to that in traditional mode. + - PMF capable, but not required: In this mode, {IDF_TARGET_NAME} indicates to AP that it is capable of supporting PMF. The management protection will be used if AP mandates PMF or is at least capable of supporting PMF. + - PMF capable and required: In this mode, {IDF_TARGET_NAME} will only connect to AP, if AP supports PMF. If not, {IDF_TARGET_NAME} will refuse to connect to the AP. :cpp:func:`esp_wifi_set_config` can be used to configure PMF mode by setting appropriate flags in `pmf_cfg` parameter. Currently, PMF is supported only in Station mode. @@ -1428,17 +1428,17 @@ WPA3-Personal Wi-Fi Protected Access-3 (WPA3) is a set of enhancements to Wi-Fi access security intended to replace the current WPA2 standard. In order to provide more robust authentication, WPA3 uses Simultaneous Authentication of Equals (SAE), which is password-authenticated key agreement method based on Diffie-Hellman key exchange. Unlike WPA2, the technology is resistant to offline-dictionary attack, where the attacker attempts to determine shared password based on captured 4-way handshake without any further network interaction. WPA3 also provides forward secrecy, which means the captured data cannot be decrypted even if password is compromised after data transmission. Please refer to `Security `_ section of Wi-Fi Alliance's official website for further details. -In order to enable WPA3-Personal, "Enable WPA3-Personal" should be selected in menuconfig. If enabled, ESP32 uses SAE for authentication if supported by the AP. Since PMF is a mandatory requirement for WPA3, PMF capability should be at least set to "PMF capable, but not required" for ESP32 to use WPA3 mode. Application developers need not worry about the underlying security mode as highest available is chosen from security standpoint. Note that Wi-Fi stack size requirement will increase approximately by 3k when WPA3 is used. Currently, WPA3 is supported only in Station mode. +In order to enable WPA3-Personal, "Enable WPA3-Personal" should be selected in menuconfig. If enabled, {IDF_TARGET_NAME} uses SAE for authentication if supported by the AP. Since PMF is a mandatory requirement for WPA3, PMF capability should be at least set to "PMF capable, but not required" for {IDF_TARGET_NAME} to use WPA3 mode. Application developers need not worry about the underlying security mode as highest available is chosen from security standpoint. Note that Wi-Fi stack size requirement will increase approximately by 3k when WPA3 is used. Currently, WPA3 is supported only in Station mode. -ESP32 Wi-Fi Power-saving Mode ------------------------------------ +{IDF_TARGET_NAME} Wi-Fi Power-saving Mode +----------------------------------------- Station Sleep ++++++++++++++++++++++ -Currently, ESP32 Wi-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 protocol. Modem-sleep mode works in Station-only mode and the station must connect to the AP first. If the Modem-sleep mode is enabled, station will switch between active and sleep state periodically. In sleep state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem-sleep mode. +Currently, {IDF_TARGET_NAME} Wi-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 protocol. Modem-sleep mode works in Station-only mode and the station must connect to the AP first. If the Modem-sleep mode is enabled, station will switch between active and sleep state periodically. In sleep state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem-sleep mode. -Modem-sleep mode includes minimum and maximum power save modes. In minimum power save mode, station wakes up every DTIM to receive beacon. Broadcast data will not be lost because it is transmitted after DTIM. However, it can not save much more power if DTIM is short for DTIM is determined by AP. +Modem-sleep mode includes minimum and maximum power save modes. In minimum power save mode, station wakes up every DTIM to receive beacon. Broadcast data will not be lost because it is transmitted after DTIM. However, it can not save much more power if DTIM is short for DTIM is determined by AP. In maximum power save mode, station wakes up every listen interval to receive beacon. This listen interval can be set longer than the AP DTIM period. Broadcast data may be lost because station may be in sleep state at DTIM time. If listen interval is longer, more power is saved but broadcast data is more easy to lose. Listen interval can be configured by calling API :cpp:func:`esp_wifi_set_config` before connecting to AP. @@ -1451,20 +1451,20 @@ The default Modem-sleep mode is WIFI_PS_MIN_MODEM. AP Sleep +++++++++++++++++++++++++++++++ -Currently ESP32 AP doesn't support all of the power save feature defined in Wi-Fi specification. To be specific, the AP only caches unicast data for the stations connect to this AP, but doesn't cache the multicast data for the stations. If stations connected to the ESP32 AP are power save enabled, they may experience multicast packet loss. +Currently {IDF_TARGET_NAME} AP doesn't support all of the power save feature defined in Wi-Fi specification. To be specific, the AP only caches unicast data for the stations connect to this AP, but doesn't cache the multicast data for the stations. If stations connected to the {IDF_TARGET_NAME} AP are power save enabled, they may experience multicast packet loss. -In future, all power save features will be supported on ESP32 AP. +In future, all power save features will be supported on {IDF_TARGET_NAME} AP. -ESP32 Wi-Fi Connect Crypto ------------------------------------ -Now ESP32 have two group crypto functions can be used when do wifi connect, one is the original functions, the other is optimized by ESP hardware: +{IDF_TARGET_NAME} Wi-Fi Connect Crypto +-------------------------------------- +Now {IDF_TARGET_NAME} have two group crypto functions can be used when do wifi connect, one is the original functions, the other is optimized by ESP hardware: 1. Original functions which is the source code used in the folder components/wpa_supplicant/src/crypto function; 2. The optimized functions is in the folder components/wpa_supplicant/src/fast_crypto, these function used the hardware crypto to make it faster than origin one, the type of function's name add `fast_` to distinguish with the original one. For example, the API aes_wrap() is used to encrypt frame information when do 4 way handshake, the fast_aes_wrap() has the same result but can be faster. -Two groups of crypto function can be used when register in the wpa_crypto_funcs_t, wpa2_crypto_funcs_t and wps_crypto_funcs_t structure, also we have given the recommend functions to register in the -fast_crypto_ops.c, you can register the function as the way you need, however what should make action is that the crypto_hash_xxx function and crypto_cipher_xxx function need to register with the same function to operation. For example, if you register crypto_hash_init() function to initialize the esp_crypto_hash structure, you need use the crypto_hash_update() and crypto_hash_finish() function to finish the operation, rather than fast_crypto_hash_update() or fast_crypto_hash_finish(). +Two groups of crypto function can be used when register in the wpa_crypto_funcs_t, wpa2_crypto_funcs_t and wps_crypto_funcs_t structure, also we have given the recommend functions to register in the +fast_crypto_ops.c, you can register the function as the way you need, however what should make action is that the crypto_hash_xxx function and crypto_cipher_xxx function need to register with the same function to operation. For example, if you register crypto_hash_init() function to initialize the esp_crypto_hash structure, you need use the crypto_hash_update() and crypto_hash_finish() function to finish the operation, rather than fast_crypto_hash_update() or fast_crypto_hash_finish(). -ESP32 Wi-Fi Throughput +{IDF_TARGET_NAME} Wi-Fi Throughput ----------------------------------- The table below shows the best throughput results we got in Espressif's lab and in a shield box. @@ -1504,7 +1504,7 @@ Preconditions of Using esp_wifi_80211_tx ++++++++++++++++++++++++++++++++++++++++++++ - The Wi-Fi mode is Station, or AP, or Station+AP. - - Either esp_wifi_set_promiscuous(true), or esp_wifi_start(), or both of these APIs return ESP_OK. This is because we need to make sure that Wi-Fi hardware is initialized before esp_wifi_80211_tx() is called. In ESP32, both esp_wifi_set_promiscuous(true) and esp_wifi_start() can trigger the initialization of Wi-Fi hardware. + - Either esp_wifi_set_promiscuous(true), or esp_wifi_start(), or both of these APIs return ESP_OK. This is because we need to make sure that Wi-Fi hardware is initialized before esp_wifi_80211_tx() is called. In {IDF_TARGET_NAME}, both esp_wifi_set_promiscuous(true) and esp_wifi_start() can trigger the initialization of Wi-Fi hardware. - The parameters of esp_wifi_80211_tx are hereby correctly provided. Data rate @@ -1533,7 +1533,7 @@ Theoretically, if we do not consider the side-effects the API imposes on the Wi- | | with the same MAC/BSSID. | | | | | | Side-effect example#1 | -| | The application calls esp_wifi_80211_tx to send | +| | The application calls esp_wifi_80211_tx to send | | | a beacon with BSSID == mac_x in AP mode, but | | | the mac_x is not the MAC of the AP interface. | | | Moreover, there is another AP, say | @@ -1636,9 +1636,9 @@ The Wi-Fi multiple antennas selecting can be depicted as following picture:: |__________| -ESP32 supports up to sixteen antennas through external antenna switch. The antenna switch can be controlled by up to four address pins - antenna_select[0:3]. Different input value of antenna_select[0:3] means selecting different antenna. E.g. the value '0b1011' means the antenna 11 is selected. The default value of antenna_select[3:0] is '0b0000', it means the antenna 0 is selected by default. +{IDF_TARGET_NAME} supports up to sixteen antennas through external antenna switch. The antenna switch can be controlled by up to four address pins - antenna_select[0:3]. Different input value of antenna_select[0:3] means selecting different antenna. E.g. the value '0b1011' means the antenna 11 is selected. The default value of antenna_select[3:0] is '0b0000', it means the antenna 0 is selected by default. -Up to four GPIOs are connected to the four active high antenna_select pins. ESP32 can select the antenna by control the GPIO[0:3]. The API :cpp:func:`esp_wifi_set_ant_gpio()` is used to configure which GPIOs are connected to antenna_selects. If GPIO[x] is connected to antenna_select[x], then gpio_config->gpio_cfg[x].gpio_select should be set to 1 and gpio_config->gpio_cfg[x].gpio_num should be provided. +Up to four GPIOs are connected to the four active high antenna_select pins. {IDF_TARGET_NAME} can select the antenna by control the GPIO[0:3]. The API :cpp:func:`esp_wifi_set_ant_gpio()` is used to configure which GPIOs are connected to antenna_selects. If GPIO[x] is connected to antenna_select[x], then gpio_config->gpio_cfg[x].gpio_select should be set to 1 and gpio_config->gpio_cfg[x].gpio_num should be provided. Although up to sixteen anteenas are supported, only one or two antennas can be simultaneously enabled for RX/TX. The API :cpp:func:`esp_wifi_set_ant()` is used to configure which antennas are enabled. @@ -1679,7 +1679,7 @@ Generally, following steps can be taken to configure the multiple antennas: Wi-Fi Channel State Information ------------------------------------ -Channel state information (CSI) refers to the channel information of a Wi-Fi connection. In ESP32, this information consists of channel frequency responses of sub-carriers and is estimated when packets are received from the transmitter. Each channel frequency response of sub-carrier is recorded by two bytes of signed characters. The first one is imaginary part and the second one is real part. There are up to three fields of channel frequency responses according to the type of received packet. They are legacy long training field (LLTF), high throughput LTF (HT-LTF) and space time block code HT-LTF (STBC-HT-LTF). For different types of packets which are received on channels with different state, the sub-carrier index and total bytes of signed characters of CSI is shown in the following table. +Channel state information (CSI) refers to the channel information of a Wi-Fi connection. In {IDF_TARGET_NAME}, this information consists of channel frequency responses of sub-carriers and is estimated when packets are received from the transmitter. Each channel frequency response of sub-carrier is recorded by two bytes of signed characters. The first one is imaginary part and the second one is real part. There are up to three fields of channel frequency responses according to the type of received packet. They are legacy long training field (LLTF), high throughput LTF (HT-LTF) and space time block code HT-LTF (STBC-HT-LTF). For different types of packets which are received on channels with different state, the sub-carrier index and total bytes of signed characters of CSI is shown in the following table. +-------------+--------------------+-----------------------------------------+--------------------------------------------------------+----------------------------------------------------------+ | channel | secondary channel | none | below | above | @@ -1699,21 +1699,21 @@ Channel state information (CSI) refers to the channel information of a Wi-Fi con | total bytes | 128 | 256 | 384 | 128 | 256 | 380 | 384 | 612 | 128 | 256 | 376 | 384 | 612 | +----------------------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+ -All of the information in the table can be found in the structure wifi_csi_info_t. +All of the information in the table can be found in the structure wifi_csi_info_t. - - Secondary channel refers to secondary_channel field of rx_ctrl field. - - Signal mode of packet refers to sig_mode field of rx_ctrl field. - - Channel bandwidth refers to cwb field of rx_ctrl field. - - STBC refers to stbc field of rx_ctrl field. - - Total bytes refers to len field. - - The CSI data corresponding to each Long Training Field(LTF) type is stored in a buffer starting from the buf field. Each item is stored as two bytes: imaginary part followed by real part. The order of each item is the same as the sub-carrier in the table. The order of LTF is: LLTF, HT-LTF, STBC-HT-LTF. However all 3 LTFs may not be present, depending on the channel and packet information (see above). - - If first_word_invalid field of wifi_csi_info_t is true, it means that the first four bytes of CSI data is invalid due to a hardware limitation in ESP32. + - Secondary channel refers to secondary_channel field of rx_ctrl field. + - Signal mode of packet refers to sig_mode field of rx_ctrl field. + - Channel bandwidth refers to cwb field of rx_ctrl field. + - STBC refers to stbc field of rx_ctrl field. + - Total bytes refers to len field. + - The CSI data corresponding to each Long Training Field(LTF) type is stored in a buffer starting from the buf field. Each item is stored as two bytes: imaginary part followed by real part. The order of each item is the same as the sub-carrier in the table. The order of LTF is: LLTF, HT-LTF, STBC-HT-LTF. However all 3 LTFs may not be present, depending on the channel and packet information (see above). + - If first_word_invalid field of wifi_csi_info_t is true, it means that the first four bytes of CSI data is invalid due to a hardware limitation in {IDF_TARGET_NAME}. - More information like RSSI, noise floor of RF, receiving time and antenna is in the rx_ctrl field. .. note:: - For STBC packet, CSI is provided for every space-time stream without CSD (cyclic shift delay). As each cyclic shift on the additional chains shall be -200ns, only the CSD angle of first space-time stream is recorded in sub-carrier 0 of HT-LTF and STBC-HT-LTF for there is no channel frequency response in sub-carrier 0. CSD[10:0] is 11 bits, ranging from -pi to pi. - - If LLTF, HT-LTF or STBC-HT-LTF is not enabled by calling API :cpp:func:`esp_wifi_set_csi_config`, the total bytes of CSI data will be fewer than that in the table. For example, if LLTF and HT-LTF is not enabled and STBC-HT-LTF is enabled, when a packet is received with the condition above/HT/40MHz/STBC, the total bytes of CSI data is 244 ((61 + 60) * 2 + 2 = 244, the result is aligned to four bytes and the last two bytes is invalid). + - If LLTF, HT-LTF or STBC-HT-LTF is not enabled by calling API :cpp:func:`esp_wifi_set_csi_config`, the total bytes of CSI data will be fewer than that in the table. For example, if LLTF and HT-LTF is not enabled and STBC-HT-LTF is enabled, when a packet is received with the condition above/HT/40MHz/STBC, the total bytes of CSI data is 244 ((61 + 60) * 2 + 2 = 244, the result is aligned to four bytes and the last two bytes is invalid). Wi-Fi Channel State Information Configure ------------------------------------------- @@ -1730,24 +1730,24 @@ The CSI receiving callback function runs from Wi-Fi task. So, do not do lengthy Wi-Fi HT20/40 ------------------------- -ESP32 supports Wi-Fi bandwidth HT20 or HT40, it doesn't support HT20/40 coexist. `esp_wifi_set_bandwidth` can be used to change the default bandwidth of station or AP. The default bandwidth for ESP32 station and AP is HT40. +{IDF_TARGET_NAME} supports Wi-Fi bandwidth HT20 or HT40, it doesn't support HT20/40 coexist. `esp_wifi_set_bandwidth` can be used to change the default bandwidth of station or AP. The default bandwidth for {IDF_TARGET_NAME} station and AP is HT40. In station mode, the actual bandwidth is firstly negotiated during the Wi-Fi connection. It is HT40 only if both the station and the connected AP support HT40, otherwise it's HT20. If the bandwidth of connected AP is changes, the actual bandwidth is negotiated again without Wi-Fi disconnecting. Similarly, in AP mode, the actual bandwidth is negotiated between AP and the stations that connect to the AP. It's HT40 if the AP and one of the stations support HT40, otherwise it's HT20. -In station/AP coexist mode, the station/AP can configure HT20/40 seperately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in ESP32. E.g. the configured bandwidth of AP is HT40, the configured primary channel is 6 and the configured secondary channel is 10. The station is connected to an router whose primary channel is 6 and secondary channel is 2, then the actual channel of AP is changed to primary 6 and secondary 2 automatically. +In station/AP coexist mode, the station/AP can configure HT20/40 seperately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in {IDF_TARGET_NAME}. E.g. the configured bandwidth of AP is HT40, the configured primary channel is 6 and the configured secondary channel is 10. The station is connected to an router whose primary channel is 6 and secondary channel is 2, then the actual channel of AP is changed to primary 6 and secondary 2 automatically. -Theoretically the HT40 can gain better throughput because the maximum raw physicial (PHY) data rate for HT40 is 150Mbps while it's 72Mbps for HT20. However, if the device is used in some special environment, e.g. there are too many other Wi-Fi devices around the ESP32 device, the performance of HT40 may be degraded. So if the applications need to support same or similar scenarios, it's recommended that the bandwidth is always configured to HT20. +Theoretically the HT40 can gain better throughput because the maximum raw physicial (PHY) data rate for HT40 is 150Mbps while it's 72Mbps for HT20. However, if the device is used in some special environment, e.g. there are too many other Wi-Fi devices around the {IDF_TARGET_NAME} device, the performance of HT40 may be degraded. So if the applications need to support same or similar scenarios, it's recommended that the bandwidth is always configured to HT20. Wi-Fi QoS ------------------------- -ESP32 supports all the mandatory features required in WFA Wi-Fi QoS Certification. +{IDF_TARGET_NAME} supports all the mandatory features required in WFA Wi-Fi QoS Certification. Four ACs(Access Category) are defined in Wi-Fi specification, each AC has a its own priority to access the Wi-Fi channel. Moreover a map rule is defined to map the QoS priority of other protocol, such as 802.11D or TCP/IP precedence to Wi-Fi AC. -Below is a table describes how the IP Precedences are mapped to Wi-Fi ACs in ESP32, it also indicates whether the AMPDU is supported for this AC. The table is sorted with priority descending order, namely, the AC_VO has highest priority. +Below is a table describes how the IP Precedences are mapped to Wi-Fi ACs in {IDF_TARGET_NAME}, it also indicates whether the AMPDU is supported for this AC. The table is sorted with priority descending order, namely, the AC_VO has highest priority. +------------------+------------------------+-----------------+ | IP Precedence | Wi-Fi AC | Support AMPDU? | @@ -1776,17 +1776,17 @@ Theoretically the higher priority AC has better performance than the low priorit Wi-Fi AMSDU ------------------------- -ESP32 supports receiving AMSDU but doesn't support transmitting AMSDU. The transmitting AMSDU is not necessary since ESP32 has transmitting AMPDU. +{IDF_TARGET_NAME} supports receiving AMSDU but doesn't support transmitting AMSDU. The transmitting AMSDU is not necessary since {IDF_TARGET_NAME} has transmitting AMPDU. Wi-Fi Fragment ------------------------- -ESP32 supports Wi-Fi receiving fragment, but doesn't support Wi-Fi transmitting fragment. The Wi-Fi transmitting fragment will be supported in future release. +{IDF_TARGET_NAME} supports Wi-Fi receiving fragment, but doesn't support Wi-Fi transmitting fragment. The Wi-Fi transmitting fragment will be supported in future release. WPS Enrolle ------------------------- -ESP32 supports WPS enrollee feature in Wi-Fi mode WIFI_MODE_STA or WIFI_MODE_APSTA. Currently ESP32 supports WPS enrollee type PBC and PIN. +{IDF_TARGET_NAME} supports WPS enrollee feature in Wi-Fi mode WIFI_MODE_STA or WIFI_MODE_APSTA. Currently {IDF_TARGET_NAME} supports WPS enrollee type PBC and PIN. .. _wifi-buffer-usage: @@ -1799,11 +1799,11 @@ Why Buffer Configuration Is Important +++++++++++++++++++++++++++++++++++++++ In order to get a robust, high-performance system, we need to consider the memory usage/configuration very carefully, because: - - the available memory in ESP32 is limited. + - the available memory in {IDF_TARGET_NAME} is limited. - currently, the default type of buffer in LwIP and Wi-Fi drivers is "dynamic", **which means that both the LwIP and Wi-Fi share memory with the application**. Programmers should always keep this in mind; otherwise, they will face a memory issue, such as "running out of heap memory". - - it is very dangerous to run out of heap memory, as this will cause ESP32 an "undefined behavior". Thus, enough heap memory should be reserved for the application, so that it never runs out of it. + - it is very dangerous to run out of heap memory, as this will cause {IDF_TARGET_NAME} an "undefined behavior". Thus, enough heap memory should be reserved for the application, so that it never runs out of it. - the Wi-Fi throughput heavily depends on memory-related configurations, such as the TCP window size, Wi-Fi RX/TX dynamic buffer number, etc. - - the peak heap memory that the ESP32 LwIP/Wi-Fi may consume depends on a number of factors, such as the maximum TCP/UDP connections that the application may have, etc. + - the peak heap memory that the {IDF_TARGET_NAME} LwIP/Wi-Fi may consume depends on a number of factors, such as the maximum TCP/UDP connections that the application may have, etc. - the total memory that the application requires is also an important factor when considering memory configuration. Due to these reasons, there is not a good-for-all application configuration. Rather, we have to consider memory configurations separately for every different application. @@ -1827,9 +1827,9 @@ The peak heap memory that Wi-Fi consumes is the **theoretically-maximum memory** - the maximum packet size that the Wi-Fi driver can send: wifi_tx_pkt_size_max So, the peak memory that the Wi-Fi driver consumes can be calculated with the following formula: - wifi_dynamic_peek_memory = (wifi_rx_dynamic_buf_num * wifi_rx_pkt_size_max) + (wifi_tx_dynamic_buf_num * wifi_tx_pkt_size_max) - -Generally, we do not need to care about the dynamic tx long buffers and dynamic tx long long buffers, because they are management frames which only have a small impact on the system. + wifi_dynamic_peek_memory = (wifi_rx_dynamic_buf_num * wifi_rx_pkt_size_max) + (wifi_tx_dynamic_buf_num * wifi_tx_pkt_size_max) + +Generally, we do not need to care about the dynamic tx long buffers and dynamic tx long long buffers, because they are management frames which only have a small impact on the system. Wi-Fi Menuconfig ----------------------- @@ -1853,13 +1853,13 @@ If you are going to modify the default number or type of buffer, it would be hel default_shape = roundedbox; # labels of diagram nodes - APPL_TASK [label="Application\n task", fontsize=12]; - LwIP_TASK [label="LwIP\n task", fontsize=12]; + APPL_TASK [label="Application\n task", fontsize=12]; + LwIP_TASK [label="LwIP\n task", fontsize=12]; WIFI_TASK [label="Wi-Fi\n task", fontsize=12]; # labels of description nodes - APPL_DESC [label="1> User data", width=120, height=25, shape=note, color=yellow]; - LwIP_DESC [label="2> Pbuf", width=120, height=25, shape=note, color=yellow]; + APPL_DESC [label="1> User data", width=120, height=25, shape=note, color=yellow]; + LwIP_DESC [label="2> Pbuf", width=120, height=25, shape=note, color=yellow]; WIFI_DESC [label="3> Dynamic (Static)\n TX Buffer", width=150, height=40, shape=note, color=yellow]; # node connections @@ -1889,14 +1889,14 @@ The following diagram shows how buffer is allocated/freed in the RX direction: default_shape = roundedbox; # labels of diagram nodes - APPL_TASK [label="Application\n task", fontsize=12]; - LwIP_TASK [label="LwIP\n task", fontsize=12]; + APPL_TASK [label="Application\n task", fontsize=12]; + LwIP_TASK [label="LwIP\n task", fontsize=12]; WIFI_TASK [label="Wi-Fi\n task", fontsize=12]; WIFI_INTR [label="Wi-Fi\n interrupt", fontsize=12]; # labels of description nodes - APPL_DESC [label="4> User\n Data Buffer", height=40, shape=note, color=yellow]; - LwIP_DESC [label="3> Pbuf", height=40, shape=note, color=yellow]; + APPL_DESC [label="4> User\n Data Buffer", height=40, shape=note, color=yellow]; + LwIP_DESC [label="3> Pbuf", height=40, shape=note, color=yellow]; WIFI_DESC [label="2> Dynamic\n RX Buffer", height=40, shape=note, color=yellow]; INTR_DESC [label="1> Static\n RX Buffer", height=40, shape=note, color=yellow]; @@ -1940,7 +1940,7 @@ The diagram shows the configuration of the Wi-Fi internal buffer. +------------------+------------+------------+--------------+---------------------------------------+ | Dynamic RX Buffer| Dynamic | 32 | Yes | The buffer length is variable and it | | | | | | depends on the received frames' | -| | | | | length. When the Wi-Fi driver receives| +| | | | | length. When the Wi-Fi driver receives| | | | | | a frame from the 'Hardware Rx Buffer',| | | | | | the 'Dynamic Rx Buffer' needs to be | | | | | | allocated from the heap. The number of| @@ -1963,7 +1963,7 @@ The diagram shows the configuration of the Wi-Fi internal buffer. | | | 1600Bytes | | initialized in esp_wifi_init() and | | | | | | freed in esp_wifi_deinit(). | | | | | | When the upper-layer (LwIP) sends | -| | | | | packets to the Wi-Fi driver, it | +| | | | | packets to the Wi-Fi driver, it | | | | | | firstly allocates a 'Static TX Buffer'| | | | | | and makes a copy of the upper-layer | | | | | | buffer. | @@ -1991,10 +1991,10 @@ Wi-Fi NVS Flash +++++++++++++++++++++ If the Wi-Fi NVS flash is enabled, all Wi-Fi configurations set via the Wi-Fi APIs will be stored into flash, and the Wi-Fi driver will start up with these configurations next time it powers on/reboots. However, the application can choose to disable the Wi-Fi NVS flash if it does not need to store the configurations into persistent memory, or has its own persistent storage, or simply due to debugging reasons, etc. -Wi-Fi AMPDU +Wi-Fi AMPDU +++++++++++++++++++++++++++ -ESP32 supports both receiving and transmitting AMPDU, the AMPDU can greatly improve the Wi-Fi throughput. +{IDF_TARGET_NAME} supports both receiving and transmitting AMPDU, the AMPDU can greatly improve the Wi-Fi throughput. Generally, the AMPDU should be enabled. Disabling AMPDU is usually for debugging purposes. @@ -2007,4 +2007,4 @@ Please refer to a separate document with :doc:`wireshark-user-guide`. :hidden: wireshark-user-guide - + diff --git a/docs/en/api-reference/network/esp_wifi.rst b/docs/en/api-reference/network/esp_wifi.rst index 17dde21e3b..5397aadaf9 100644 --- a/docs/en/api-reference/network/esp_wifi.rst +++ b/docs/en/api-reference/network/esp_wifi.rst @@ -6,11 +6,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 {IDF_TARGET_NAME} 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). {IDF_TARGET_NAME} connects to an access point. +- AP mode (aka Soft-AP mode or Access Point mode). Stations connect to the {IDF_TARGET_NAME}. +- Combined AP-STA mode ({IDF_TARGET_NAME} 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). diff --git a/docs/en/api-reference/peripherals/adc.rst b/docs/en/api-reference/peripherals/adc.rst index 4fcf6cb741..0dba625dc0 100644 --- a/docs/en/api-reference/peripherals/adc.rst +++ b/docs/en/api-reference/peripherals/adc.rst @@ -4,24 +4,27 @@ Analog to Digital Converter Overview -------- -The ESP32 integrates two 12-bit SAR (`Successive Approximation Register `_) ADCs supporting a total of 18 measurement channels (analog enabled pins). +The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register `_) ADCs supporting a total of 18 measurement channels (analog enabled pins). -The ADC driver API supports ADC1 (8 channels, attached to GPIOs 32 - 39), and ADC2 (10 channels, attached to GPIOs 0, 2, 4, 12 - 15 and 25 - 27). However, the usage of ADC2 has some restrictions for the application: -1. ADC2 is used by the Wi-Fi driver. Therefore the application can only use ADC2 when the Wi-Fi driver has not started. -2. Some of the ADC2 pins are used as strapping pins (GPIO 0, 2, 15) thus cannot be used freely. Such is the case in the following official Development Kits: +..only:: esp32 - - :ref:`ESP32 DevKitC `: GPIO 0 cannot be used due to external auto program circuits. - - :ref:`ESP-WROVER-KIT `: GPIO 0, 2, 4 and 15 cannot be used due to external connections for different purposes. + The ADC driver API supports ADC1 (8 channels, attached to GPIOs 32 - 39), and ADC2 (10 channels, attached to GPIOs 0, 2, 4, 12 - 15 and 25 - 27). However, the usage of ADC2 has some restrictions for the application: + + 1. ADC2 is used by the Wi-Fi driver. Therefore the application can only use ADC2 when the Wi-Fi driver has not started. + 2. Some of the ADC2 pins are used as strapping pins (GPIO 0, 2, 15) thus cannot be used freely. Such is the case in the following official Development Kits: + + - :ref:`ESP32 DevKitC `: GPIO 0 cannot be used due to external auto program circuits. + - :ref:`ESP-WROVER-KIT `: GPIO 0, 2, 4 and 15 cannot be used due to external connections for different purposes. Configuration and Reading ADC ----------------------------- The ADC should be configured before reading is taken. - - For ADC1, configure desired precision and attenuation by calling functions :cpp:func:`adc1_config_width` and :cpp:func:`adc1_config_channel_atten`. + - For ADC1, configure desired precision and attenuation by calling functions :cpp:func:`adc1_config_width` and :cpp:func:`adc1_config_channel_atten`. - For ADC2, configure the attenuation by :cpp:func:`adc2_config_channel_atten`. The reading width of ADC2 is configured every time you take the reading. - + Attenuation configuration is done per channel, see :cpp:type:`adc1_channel_t` and :cpp:type:`adc2_channel_t`, set as a parameter of above functions. Then it is possible to read ADC conversion result with :cpp:func:`adc1_get_raw` and :cpp:func:`adc2_get_raw`. Reading width of ADC2 should be set as a parameter of :cpp:func:`adc2_get_raw` instead of in the configuration functions. @@ -55,7 +58,7 @@ Reading voltage on ADC2 channel 7 (GPIO 27):: #include ... - + int read_raw; adc2_config_channel_atten( ADC2_CHANNEL_7, ADC_ATTEN_0db ); @@ -87,23 +90,23 @@ The value read in both these examples is 12 bits wide (range 0-4095). Minimizing Noise ---------------- -The ESP32 ADC can be sensitive to noise leading to large discrepancies in ADC readings. To minimize noise, users may connect a 0.1uF capacitor to the ADC input pad in use. Multisampling may also be used to further mitigate the effects of noise. +The {IDF_TARGET_NAME} ADC can be sensitive to noise leading to large discrepancies in ADC readings. To minimize noise, users may connect a 0.1uF capacitor to the ADC input pad in use. Multisampling may also be used to further mitigate the effects of noise. .. figure:: ../../../_static/adc-noise-graph.jpg :align: center :alt: ADC noise mitigation - + Graph illustrating noise mitigation using capacitor and multisampling of 64 samples. ADC Calibration --------------- -The :component_file:`esp_adc_cal/include/esp_adc_cal.h` API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100mV, however the true reference voltage can range from 1000mV to 1200mV amongst different ESP32s. +The :component_file:`esp_adc_cal/include/esp_adc_cal.h` API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100mV, however the true reference voltage can range from 1000mV to 1200mV amongst different {IDF_TARGET_NAME}s. .. figure:: ../../../_static/adc-vref-graph.jpg :align: center :alt: ADC reference voltage comparison - + Graph illustrating effect of differing reference voltages on the ADC voltage curve. Correcting ADC readings using this API involves characterizing one of the ADCs at a given attenuation to obtain a characteristics curve (ADC-Voltage curve) that takes into account the difference in ADC reference voltage. The characteristics curve is in the form of ``y = coeff_a * x + coeff_b`` and is used to convert ADC readings to voltages in mV. Calculation of the characteristics curve is based on calibration values which can be stored in eFuse or provided by the user. @@ -111,21 +114,23 @@ Correcting ADC readings using this API involves characterizing one of the ADCs a Calibration Values ^^^^^^^^^^^^^^^^^^ -Calibration values are used to generate characteristic curves that account for the unique ADC reference voltage of a particular ESP32. There are currently three sources of calibration values. The availability of these calibration values will depend on the type and production date of the ESP32 chip/module. +Calibration values are used to generate characteristic curves that account for the unique ADC reference voltage of a particular {IDF_TARGET_NAME}. There are currently three sources of calibration values. The availability of these calibration values will depend on the type and production date of the {IDF_TARGET_NAME} chip/module. * **Two Point** values represent each of the ADCs’ readings at 150mV and 850mV. To obtain more accurate calibration results these values should be measured by user and burned into eFuse ``BLOCK3``. -* **eFuse Vref** represents the true ADC reference voltage. This value is measured and burned into eFuse ``BLOCK0`` during factory calibration. +* **eFuse Vref** represents the true ADC reference voltage. This value is measured and burned into eFuse ``BLOCK0`` during factory calibration. * **Default Vref** is an estimate of the ADC reference voltage provided by the user as a parameter during characterization. If Two Point or eFuse Vref values are unavailable, **Default Vref** will be used. -Individual measurement and burning of the **eFuse Vref** has been applied to ESP32-D0WD and ESP32-D0WDQ6 chips produced on/after the 1st week of 2018. Such chips may be recognized by date codes on/later than 012018 (see Line 4 on figure below). +.. only:: esp32 -.. figure:: ../../../_static/chip_surface_marking.png - :align: center - :alt: ESP32 Chip Surface Marking - - ESP32 Chip Surface Marking + Individual measurement and burning of the **eFuse Vref** has been applied to ESP32-D0WD and ESP32-D0WDQ6 chips produced on/after the 1st week of 2018. Such chips may be recognized by date codes on/later than 012018 (see Line 4 on figure below). + + .. figure:: ../../../_static/chip_surface_marking.png + :align: center + :alt: ESP32 Chip Surface Marking + + ESP32 Chip Surface Marking If you would like to purchase chips or modules with calibration, double check with distributor or Espressif directly. @@ -135,7 +140,7 @@ If you are unable to check the date code (i.e. the chip may be enclosed inside a $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 adc_info -Replace ``/dev/ttyUSB0`` with ESP32 board's port name. +Replace ``/dev/ttyUSB0`` with {IDF_TARGET_NAME} board's port name. A chip that has specific **eFuse Vref** value programmed (in this case 1093mV) will be reported as follows:: @@ -163,9 +168,9 @@ Characterizing an ADC at a particular attenuation:: #include "driver/adc.h" #include "esp_adc_cal.h" - + ... - + //Characterize ADC at particular atten esp_adc_cal_characteristics_t *adc_chars = calloc(1, sizeof(esp_adc_cal_characteristics_t)); esp_adc_cal_value_t val_type = esp_adc_cal_characterize(unit, atten, ADC_WIDTH_BIT_12, DEFAULT_VREF, adc_chars); @@ -182,15 +187,15 @@ Reading an ADC then converting the reading to a voltage:: #include "driver/adc.h" #include "esp_adc_cal.h" - + ... uint32_t reading = adc1_get_raw(ADC1_CHANNEL_5); uint32_t voltage = esp_adc_cal_raw_to_voltage(reading, adc_chars); - + Routing ADC reference voltage to GPIO, so it can be manually measured (for **Default Vref**):: #include "driver/adc.h" - + ... esp_err_t status = adc2_vref_to_gpio(GPIO_NUM_25); diff --git a/docs/en/api-reference/peripherals/can.rst b/docs/en/api-reference/peripherals/can.rst index d6d986722d..bb63366d91 100644 --- a/docs/en/api-reference/peripherals/can.rst +++ b/docs/en/api-reference/peripherals/can.rst @@ -6,10 +6,10 @@ Controller Area Network (CAN) Overview -------- -The ESP32's peripherals contains a CAN Controller that supports Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID) of the CAN2.0B specification. +The {IDF_TARGET_NAME}'s peripherals contains a CAN Controller that supports Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID) of the CAN2.0B specification. .. warning:: - The ESP32 CAN controller is not compatible with CAN FD frames and will interpret such frames as errors. + The {IDF_TARGET_NAME} CAN controller is not compatible with CAN FD frames and will interpret such frames as errors. This programming guide is split into the following sections: @@ -199,9 +199,11 @@ Bit timing **macro initializers** are also available for commonly used CAN bus b - ``CAN_TIMING_CONFIG_800KBITS()`` - ``CAN_TIMING_CONFIG_1MBITS()`` -.. note:: - The macro initializers for 12.5K, 16K, and 20K bit rates are only available - for ESP32 revision 2 or later. +.. only::esp32 + + .. note:: + The macro initializers for 12.5K, 16K, and 20K bit rates are only available + for ESP32 revision 2 or later. Acceptance Filter ^^^^^^^^^^^^^^^^^ @@ -477,7 +479,7 @@ The following example shows how the calculate the acceptance mask given multiple Application Examples ^^^^^^^^^^^^^^^^^^^^ -**Network Example:** The CAN Network example demonstrates communication between two ESP32s using the CAN driver API. One CAN node acts as a network master initiate and ceasing the transfer of a data from another CAN node acting as a network slave. The example can be found via :example:`peripherals/can/can_network`. +**Network Example:** The CAN Network example demonstrates communication between two {IDF_TARGET_NAME}s using the CAN driver API. One CAN node acts as a network master initiate and ceasing the transfer of a data from another CAN node acting as a network slave. The example can be found via :example:`peripherals/can/can_network`. **Alert and Recovery Example:** This example demonstrates how to use the CAN driver's alert and bus recovery API. The example purposely introduces errors on the CAN bus to put the CAN controller into the Bus-Off state. An alert is used to detect the Bus-Off state and trigger the bus recovery process. The example can be found via :example:`peripherals/can/can_alert_and_recovery`. diff --git a/docs/en/api-reference/peripherals/dac.rst b/docs/en/api-reference/peripherals/dac.rst index d6581e7b7e..e9496f0ec0 100644 --- a/docs/en/api-reference/peripherals/dac.rst +++ b/docs/en/api-reference/peripherals/dac.rst @@ -4,7 +4,13 @@ Digital To Analog Converter Overview -------- -ESP32 has two 8-bit DAC (digital to analog converter) channels, connected to GPIO25 (Channel 1) and GPIO26 (Channel 2). +.. only:: esp32 + + {IDF_TARGET_NAME} has two 8-bit DAC (digital to analog converter) channels, connected to GPIO25 (Channel 1) and GPIO26 (Channel 2). + +.. only:: esp32s2beta + + {IDF_TARGET_NAME} has two 8-bit DAC (digital to analog converter) channels, connected to GPIO17 (Channel 1) and GPIO18 (Channel 2). The DAC driver allows these channels to be set to arbitrary voltages. diff --git a/docs/en/api-reference/peripherals/esp_slave_protocol.rst b/docs/en/api-reference/peripherals/esp_slave_protocol.rst index e99f7830ab..c0650a9660 100644 --- a/docs/en/api-reference/peripherals/esp_slave_protocol.rst +++ b/docs/en/api-reference/peripherals/esp_slave_protocol.rst @@ -6,7 +6,7 @@ Communication with ESP SDIO Slave ESP SDIO slave initialization ------------------------------ -The host should initialize the ESP32 SDIO slave according to the standard +The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the standard SDIO initialization process (Sector 3.1.2 of `SDIO Simplified Specification `_). In this specification and below, the SDIO slave is also called an (SD)IO card. All the diff --git a/docs/en/api-reference/peripherals/gpio.rst b/docs/en/api-reference/peripherals/gpio.rst index fb340e0ca2..87a4729752 100644 --- a/docs/en/api-reference/peripherals/gpio.rst +++ b/docs/en/api-reference/peripherals/gpio.rst @@ -4,10 +4,18 @@ 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. +.. only:: esp32 + + The {IDF_TARGET_NAME} 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. + +.. only:: esp32s2beta + + The {IDF_TARGET_NAME} chip features 43 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 <../../api-guides/ulp>` is running, or when analog functions such as ADC/DAC/etc are in use. diff --git a/docs/en/api-reference/peripherals/i2c.rst b/docs/en/api-reference/peripherals/i2c.rst index 59e58bb7f9..0a49678715 100644 --- a/docs/en/api-reference/peripherals/i2c.rst +++ b/docs/en/api-reference/peripherals/i2c.rst @@ -8,7 +8,7 @@ I2C is a serial, synchronous, half-duplex communication protocol that allows co- With such advantages as simplicity and low manufacturing cost, I2C is mostly used for communication of low-speed peripheral devices over short distances (within one foot). -ESP32 has two I2C controllers (also referred to as ports) which are responsible for handling communications on two I2C buses. Each I2C controller can operate as master or slave. As an example, one controller can act as a master and the other as a slave at the same time. +{IDF_TARGET_NAME} has two I2C controllers (also referred to as ports) which are responsible for handling communications on two I2C buses. Each I2C controller can operate as master or slave. As an example, one controller can act as a master and the other as a slave at the same time. Driver Features @@ -50,7 +50,7 @@ To establish I2C communication, start by configuring the driver. This is done by - Configure **communication pins** - Assign GPIO pins for SDA and SCL signals - - Set whether to enable ESP32's internal pull-ups + - Set whether to enable {IDF_TARGET_NAME}'s internal pull-ups - (Master only) Set I2C **clock speed** - (Slave only) Configure the following @@ -81,9 +81,9 @@ After the I2C driver is configured, install it by calling the function :cpp:func Communication as Master ^^^^^^^^^^^^^^^^^^^^^^^ -After installing the I2C driver, ESP32 is ready to communicate with other I2C devices. +After installing the I2C driver, {IDF_TARGET_NAME} is ready to communicate with other I2C devices. -ESP32's I2C controller operating as master is responsible for establishing communication with I2C slave devices and sending commands to trigger a slave to action, for example, to take a measurement and send the readings back to the master. +{IDF_TARGET_NAME}'s I2C controller operating as master is responsible for establishing communication with I2C slave devices and sending commands to trigger a slave to action, for example, to take a measurement and send the readings back to the master. For better process organization, the driver provides a container, called a "command link", that should be populated with a sequence of commands and then passed to the I2C controller for execution. @@ -155,7 +155,7 @@ Likewise, the command link to read from the slave looks as follows: Communication as Slave ^^^^^^^^^^^^^^^^^^^^^^ -After installing the I2C driver, ESP32 is ready to communicate with other I2C devices. +After installing the I2C driver, {IDF_TARGET_NAME} is ready to communicate with other I2C devices. The API provides the following functions for slaves @@ -179,7 +179,6 @@ During driver installation, an interrupt handler is installed by default. Howeve To delete an interrupt handler, call :cpp:func:`i2c_isr_free`. - .. _i2c-api-customized-configuration: Customized Configuration @@ -217,7 +216,7 @@ You can also select different pins for SDA and SCL signals and alter the configu .. note:: - ESP32's internal pull-ups are in the range of tens of kOhm, which is, in most cases, insufficient for use as I2C pull-ups. Users are advised to use external pull-ups with values described in the `I2C specification `_. + {IDF_TARGET_NAME}'s internal pull-ups are in the range of tens of kOhm, which is, in most cases, insufficient for use as I2C pull-ups. Users are advised to use external pull-ups with values described in the `I2C specification `_. .. _i2c-api-error-handling: diff --git a/docs/en/api-reference/peripherals/i2s.rst b/docs/en/api-reference/peripherals/i2s.rst index 37907c046e..7f4148d7c1 100644 --- a/docs/en/api-reference/peripherals/i2s.rst +++ b/docs/en/api-reference/peripherals/i2s.rst @@ -6,7 +6,7 @@ Overview I2S (Inter-IC Sound) is a serial, synchronous communication protocol that is usually used for transmitting audio data between two digital audio devices. -ESP32 integrates two I2S controllers, referred to as I2S0 and I2S1, both of which can be used for streaming audio and video digital data. +{IDF_TARGET_NAME} integrates two I2S controllers, referred to as I2S0 and I2S1, both of which can be used for streaming audio and video digital data. An I2S bus consists of the following lines: @@ -30,7 +30,9 @@ The I2S peripherals also support LCD mode for communicating data over a parallel - Camera slave receiving mode - ADC/DAC mode -For more information, see the `ESP32 Technical Reference Manual `_. +.. only:: esp32 + + For more information, see the `ESP32 Technical Reference Manual `_. .. note:: @@ -198,7 +200,7 @@ Configuring I2S to use internal DAC for analog output i2s_set_pin(i2s_num, NULL); //for internal DAC, this will enable both of the internal channels //You can call i2s_set_dac_mode to set built-in DAC output mode. - //i2s_set_dac_mode(I2S_DAC_CHANNEL_BOTH_EN); + //i2s_set_dac_mode(I2S_DAC_CHANNEL_BOTH_EN); i2s_set_sample_rates(i2s_num, 22050); //set sample rates diff --git a/docs/en/api-reference/peripherals/ledc.rst b/docs/en/api-reference/peripherals/ledc.rst index a726c83aab..17587e3b4c 100644 --- a/docs/en/api-reference/peripherals/ledc.rst +++ b/docs/en/api-reference/peripherals/ledc.rst @@ -6,7 +6,7 @@ LED Control Introduction ------------ -The LED control (LEDC) peripheral is primarily designed to control the intensity of LEDs, although it can also be used to generate PWM signals for other purposes as well. It has 16 channels which can generate independent waveforms that can be used, for example, to drive RGB LED devices. +The LED control (LEDC) peripheral is primarily designed to control the intensity of LEDs, although it can also be used to generate PWM signals for other purposes as well. It has 16 channels which can generate independent waveforms that can be used, for example, to drive RGB LED devices. A half of LEDC's channels operate in high speed mode. This mode is implemented in hardware and offers automatic and glitch-free changing of the PWM duty cycle. The other half of channels operate in low speed mode, where the moment of change depends on the application software. Each group of channels is also able to use different clock sources. @@ -121,7 +121,7 @@ The first two functions are called "behind the scenes" by :cpp:func:`ledc_channe Use Interrupts ^^^^^^^^^^^^^^ -When configuring an LEDC channel, one of the parameters selected within :cpp:type:`ledc_channel_config_t` is :cpp:type:`ledc_intr_type_t` which triggers an interrupt on fade completion. +When configuring an LEDC channel, one of the parameters selected within :cpp:type:`ledc_channel_config_t` is :cpp:type:`ledc_intr_type_t` which triggers an interrupt on fade completion. For registration of a handler to address this interrupt, call :cpp:func:`ledc_isr_register`. @@ -135,8 +135,13 @@ Of the total 8 timers and 16 channels available in the LED PWM Controller, half The advantage of high speed mode is glitch-free changeover of the timer settings. This means that if the timer settings are modified, the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the background, e.g., when :cpp:func:`ledc_timer_config` or :cpp:func:`ledc_timer_set` is called. -For additional details regarding speed modes, refer to `ESP32 Technical Reference Manual `_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver. +.. only:: esp32 + For additional details regarding speed modes, refer to `ESP32 Technical Reference Manual `_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver. + +.. only:: esp32s2beta + + For additional details regarding speed modes, refer to `ESP32-S2 Technical Reference Manual `_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver. .. _ledc-api-supported-range-frequency-duty-resolution: @@ -163,7 +168,7 @@ The LEDC driver will also capture and report attempts to configure frequency / d E (196) ledc: requested frequency and duty resolution cannot be achieved, try increasing freq_hz or duty_resolution. div_param=128000000 -The duty resolution is normally set using :cpp:type:`ledc_timer_bit_t`. This enumeration covers the range from 10 to 15 bits. If a smaller duty resolution is required (from 10 down to 1), enter the equivalent numeric values directly. +The duty resolution is normally set using :cpp:type:`ledc_timer_bit_t`. This enumeration covers the range from 10 to 15 bits. If a smaller duty resolution is required (from 10 down to 1), enter the equivalent numeric values directly. Application Example diff --git a/docs/en/api-reference/peripherals/mcpwm.rst b/docs/en/api-reference/peripherals/mcpwm.rst index d21d25c60a..55743df6c6 100644 --- a/docs/en/api-reference/peripherals/mcpwm.rst +++ b/docs/en/api-reference/peripherals/mcpwm.rst @@ -1,7 +1,7 @@ MCPWM ===== -ESP32 has two MCPWM units which can be used to control different types of motors. Each unit has three pairs of PWM outputs. +{IDF_TARGET_NAME} has two MCPWM units which can be used to control different types of motors. Each unit has three pairs of PWM outputs. .. figure:: ../../../_static/mcpwm-overview.png :align: center @@ -53,7 +53,7 @@ In this case we will describe a simple configuration to control a brushed DC mot Configuration covers the following steps: -1. Selection of a MPWn unit that will be used to drive the motor. There are two units available on-board of ESP32 and enumerated in :cpp:type:`mcpwm_unit_t`. +1. Selection of a MPWn unit that will be used to drive the motor. There are two units available on-board of {IDF_TARGET_NAME} and enumerated in :cpp:type:`mcpwm_unit_t`. 2. Initialization of two GPIOs as output signals within selected unit by calling :cpp:func:`mcpwm_gpio_init`. The two output signals are typically used to command the motor to rotate right or left. All available signal options are listed in :cpp:type:`mcpwm_io_signals_t`. To set more than a single pin at a time, use function :cpp:func:`mcpwm_set_pin` together with :cpp:type:`mcpwm_pin_config_t`. 3. Selection of a timer. There are three timers available within the unit. The timers are listed in :cpp:type:`mcpwm_timer_t`. 4. Setting of the timer frequency and initial duty within :cpp:type:`mcpwm_config_t` structure. @@ -89,8 +89,13 @@ There are couple of ways to adjust a signal on the outputs and changing how the Synchronization signals are referred to using two different enumerations. First one :cpp:type:`mcpwm_io_signals_t` is used together with function :cpp:func:`mcpwm_gpio_init` when selecting a GPIO as the signal input source. The second one :cpp:type:`mcpwm_sync_signal_t` is used when enabling or disabling synchronization with :cpp:func:`mcpwm_sync_enable` or :cpp:func:`mcpwm_sync_disable`. -* Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `ESP32 Technical Reference Manual`_. +.. only:: esp32 + * Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `ESP32 Technical Reference Manual`_. + +.. only:: esp32s2beta + + * Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `ESP32-S2 Technical Reference Manual`_. Capture ------- @@ -171,6 +176,8 @@ Examples of using MCPWM for motor control: :example:`peripherals/mcpwm`: .. _ESP32 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf +.. _ESP32-S2 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf + API Reference ------------- diff --git a/docs/en/api-reference/peripherals/rmt.rst b/docs/en/api-reference/peripherals/rmt.rst index c4c7985499..005333a01d 100644 --- a/docs/en/api-reference/peripherals/rmt.rst +++ b/docs/en/api-reference/peripherals/rmt.rst @@ -105,7 +105,7 @@ Common Parameters * The **channel** to be configured, select one from the :cpp:type:`rmt_channel_t` enumerator. * The RMT **operation mode** - whether this channel is used to transmit or receive data, selected by setting a **rmt_mode** members to one of the values from :cpp:type:`rmt_mode_t`. -* What is the **pin number** to transmit or receive RMT signals, selected by setting **gpio_num**. +* What is the **pin number** to transmit or receive RMT signals, selected by setting **gpio_num**. * How many **memory blocks** will be used by the channel, set with **mem_block_num**. * A **clock divider**, that will determine the range of pulse length generated by the RMT transmitter or discriminated by the receiver. Selected by setting **clk_div** to a value within [1 .. 255] range. The RMT source clock is typically APB CLK, 80Mhz by default. @@ -123,7 +123,7 @@ When configuring channel in transmit mode, set **tx_config** and the following m * Transmit the currently configured data items in a loop - **loop_en** * Enable the RMT carrier signal - **carrier_en** -* Frequency of the carrier in Hz - **carrier_freq_hz** +* Frequency of the carrier in Hz - **carrier_freq_hz** * Duty cycle of the carrier signal in percent (%) - **carrier_duty_percent** * Level of the RMT output, when the carrier is applied - **carrier_level** * Enable the RMT output if idle - **idle_output_en** @@ -153,14 +153,14 @@ Now, depending on how the channel is configured, we are ready to either `Transmi Transmit Data ------------- -Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized by the RMT controller, later called an 'item', is provided in a structure :cpp:type:`rmt_item32_t`, see :component_file:`soc/esp32/include/soc/rmt_caps.h`. Each item consists of two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure of an item is presented below. +Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized by the RMT controller, later called an 'item', is provided in a structure :cpp:type:`rmt_item32_t`, see :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_caps.h`. Each item consists of two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure of an item is presented below. .. packetdiag:: :caption: Structure of RMT items (L - signal level) :align: center packetdiag rmt_items { - colwidth = 32 + colwidth = 32 node_width = 10 node_height = 24 default_fontsize = 12 @@ -180,7 +180,7 @@ For a simple example how to define a block of items see :example:`peripherals/rm The items are provided to the RMT controller by calling function :cpp:func:`rmt_write_items`. This function also automatically triggers start of transmission. It may be called to wait for transmission completion or exit just after transmission start. In such case you can wait for the transmission end by calling :cpp:func:`rmt_wait_tx_done`. This function does not limit the number of data items to transmit. It is using an interrupt to successively copy the new data chunks to RMT's internal memory as previously provided data are sent out. -Another way to provide data for transmission is by calling :cpp:func:`rmt_fill_tx_items`. In this case transmission is not started automatically. To control the transmission process use :cpp:func:`rmt_tx_start` and :cpp:func:`rmt_tx_stop`. The number of items to sent is restricted by the size of memory blocks allocated in the RMT controller's internal memory, see :cpp:func:`rmt_set_mem_block_num`. +Another way to provide data for transmission is by calling :cpp:func:`rmt_fill_tx_items`. In this case transmission is not started automatically. To control the transmission process use :cpp:func:`rmt_tx_start` and :cpp:func:`rmt_tx_stop`. The number of items to sent is restricted by the size of memory blocks allocated in the RMT controller's internal memory, see :cpp:func:`rmt_set_mem_block_num`. Receive Data @@ -227,11 +227,11 @@ Receive Mode Parameters Use Interrupts -------------- -Registering of an interrupt handler for the RMT controller is done be calling :cpp:func:`rmt_isr_register`. +Registering of an interrupt handler for the RMT controller is done be calling :cpp:func:`rmt_isr_register`. .. note:: - When calling :cpp:func:`rmt_driver_install` to use the system RMT driver, a default ISR is being installed. In such a case you cannot register a generic ISR handler with :cpp:func:`rmt_isr_register`. + When calling :cpp:func:`rmt_driver_install` to use the system RMT driver, a default ISR is being installed. In such a case you cannot register a generic ISR handler with :cpp:func:`rmt_isr_register`. The RMT controller triggers interrupts on four specific events describes below. To enable interrupts on these events, the following functions are provided: @@ -242,7 +242,7 @@ The RMT controller triggers interrupts on four specific events describes below. Setting or clearing an interrupt enable mask for specific channels and events may be also done by calling :cpp:func:`rmt_set_intr_enable_mask` or :cpp:func:`rmt_clr_intr_enable_mask`. -When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/esp32/include/soc/rmt_struct.h`, where N is the RMT channel number [0, 7] and the ``event_name`` is one of four events described above. +When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/{IDT_TARGET_PATH_NAME}/include/soc/rmt_struct.h`, where N is the RMT channel number [0, 7] and the ``event_name`` is one of four events described above. If you do not need an ISR anymore, you can deregister it by calling a function :cpp:func:`rmt_isr_deregister`. diff --git a/docs/en/api-reference/protocols/esp_http_server.rst b/docs/en/api-reference/protocols/esp_http_server.rst index 0fffb0873b..ed414c2e60 100644 --- a/docs/en/api-reference/protocols/esp_http_server.rst +++ b/docs/en/api-reference/protocols/esp_http_server.rst @@ -5,7 +5,7 @@ HTTP Server Overview -------- -The HTTP Server component provides an ability for running a lightweight web server on ESP32. Following are detailed steps to use the API exposed by HTTP Server: +The HTTP Server component provides an ability for running a lightweight web server on {IDF_TARGET_NAME}. Following are detailed steps to use the API exposed by HTTP Server: * :cpp:func:`httpd_start`: Creates an instance of HTTP server, allocate memory/resources for it depending upon the specified configuration and outputs a handle to the server instance. The server has both, a listening socket (TCP) for HTTP traffic, and a control socket (UDP) for control signals, which are selected in a round robin fashion in the server task loop. The task priority and stack size are configurable during server instance creation by passing httpd_config_t structure to httpd_start(). TCP traffic is parsed as HTTP requests and, depending on the requested URI, user registered handlers are invoked which are supposed to send back HTTP response packets. * :cpp:func:`httpd_stop`: This stops the server with the provided handle and frees up any associated memory/resources. This is a blocking function that first signals a halt to the server task and then waits for the task to terminate. While stopping, the task will close all open connections, remove registered URI handlers and reset all session context data to empty. diff --git a/docs/en/api-reference/protocols/mdns.rst b/docs/en/api-reference/protocols/mdns.rst index 960169b0f6..1370b30154 100644 --- a/docs/en/api-reference/protocols/mdns.rst +++ b/docs/en/api-reference/protocols/mdns.rst @@ -12,8 +12,8 @@ mDNS is installed by default on most operating systems or is available as separa mDNS Properties ^^^^^^^^^^^^^^^ - * ``hostname``: the hostname that the device will respond to. If not set, the ``hostname`` will be read from the interface. Example: ``my-esp32`` will resolve to ``my-esp32.local`` - * ``default_instance``: friendly name for your device, like ``Jhon's ESP32 Thing``. If not set, ``hostname`` will be used. + * ``hostname``: the hostname that the device will respond to. If not set, the ``hostname`` will be read from the interface. Example: ``my-{IDF_TARGET_PATH_NAME}`` will resolve to ``my-{IDF_TARGET_PATH_NAME}.local`` + * ``default_instance``: friendly name for your device, like ``Jhon's {IDF_TARGET_NAME} Thing``. If not set, ``hostname`` will be used. Example method to start mDNS for the STA interface and set ``hostname`` and ``default_instance``: @@ -29,11 +29,11 @@ Example method to start mDNS for the STA interface and set ``hostname`` and ``de printf("MDNS Init failed: %d\n", err); return; } - + //set hostname - mdns_hostname_set("my-esp32"); + mdns_hostname_set("my-{IDF_TARGET_PATH_NAME}"); //set default instance - mdns_instance_name_set("Jhon's ESP32 Thing"); + mdns_instance_name_set("Jhon's {IDF_TARGET_NAME} Thing"); } mDNS Services @@ -41,9 +41,9 @@ mDNS Services mDNS can advertise information about network services that your device offers. Each service is defined by a few properties. - * ``instance_name``: friendly name for your service, like ``Jhon's ESP32 Web Server``. If not defined, ``default_instance`` will be used. + * ``instance_name``: friendly name for your service, like ``Jhon's E{IDF_TARGET_NAME} Web Server``. If not defined, ``default_instance`` will be used. * ``service_type``: (required) service type, prepended with underscore. Some common types can be found `here `_. - * ``proto``: (required) protocol that the service runs on, prepended with underscore. Example: ``_tcp`` or ``_udp`` + * ``proto``: (required) protocol that the service runs on, prepended with underscore. Example: ``_tcp`` or ``_udp`` * ``port``: (required) network port that the service runs on * ``txt``: ``{var, val}`` array of strings, used to define properties for your service @@ -55,19 +55,19 @@ Example method to add a few services and different properties:: mdns_service_add(NULL, "_http", "_tcp", 80, NULL, 0); mdns_service_add(NULL, "_arduino", "_tcp", 3232, NULL, 0); mdns_service_add(NULL, "_myservice", "_udp", 1234, NULL, 0); - + //NOTE: services must be added before their properties can be set //use custom instance for the web server - mdns_service_instance_name_set("_http", "_tcp", "Jhon's ESP32 Web Server"); + mdns_service_instance_name_set("_http", "_tcp", "Jhon's {IDF_TARGET_NAME} Web Server"); mdns_txt_item_t serviceTxtData[3] = { - {"board","esp32"}, + {"board","{{IDF_TARGET_PATH_NAME}}"}, {"u","user"}, {"p","password"} }; //set txt data for service (will free and replace current data) mdns_service_txt_set("_http", "_tcp", serviceTxtData, 3); - + //change service port mdns_service_port_set("_myservice", "_udp", 4321); } @@ -161,9 +161,9 @@ Example method to resolve local services:: Example of using the methods above:: void my_app_some_method(){ - //search for esp32-mdns.local - resolve_mdns_host("esp32-mdns"); - + //search for {IDF_TARGET_PATH_NAME}-mdns.local + resolve_mdns_host("{IDF_TARGET_PATH_NAME}-mdns"); + //search for HTTP servers find_mdns_service("_http", "_tcp"); //or file servers diff --git a/docs/en/api-reference/storage/nvs_flash.rst b/docs/en/api-reference/storage/nvs_flash.rst index 642483cf5f..ac02e5168e 100644 --- a/docs/en/api-reference/storage/nvs_flash.rst +++ b/docs/en/api-reference/storage/nvs_flash.rst @@ -14,15 +14,15 @@ You can find two code examples in the :example:`storage` directory of ESP-IDF ex Demonstrates how to read a single integer value from, and write it to NVS. - The value checked in this example holds the number of the ESP32 module restarts. The value's function as a counter is only possible due to its storing in NVS. + The value checked in this example holds the number of the {IDF_TARGET_NAME} module restarts. The value's function as a counter is only possible due to its storing in NVS. The example also shows how to check if a read / write operation was successful, or if a certain value has not been initialized in NVS. The diagnostic procedure is provided in plain text to help you track the program flow and capture any issues on the way. :example:`storage/nvs_rw_blob` - Demonstrates how to read a single integer value and a blob (binary large object), and write them to NVS to preserve this value between ESP32 module restarts. + Demonstrates how to read a single integer value and a blob (binary large object), and write them to NVS to preserve this value between {IDF_TARGET_NAME} module restarts. - * value - tracks the number of the ESP32 module soft and hard restarts. + * value - tracks the number of the {IDF_TARGET_NAME} module soft and hard restarts. * blob - contains a table with module run times. The table is read from NVS to dynamically allocated RAM. A new run time is added to the table on each manually triggered soft restart, and then the added run time is written to NVS. Triggering is done by pulling down GPIO0. The example also shows how to implement the diagnostic procedure to check if the read / write operation was successful. diff --git a/docs/en/api-reference/storage/spiffs.rst b/docs/en/api-reference/storage/spiffs.rst index 2bf5ee848a..82a0544028 100644 --- a/docs/en/api-reference/storage/spiffs.rst +++ b/docs/en/api-reference/storage/spiffs.rst @@ -75,11 +75,11 @@ in CMake:: If FLASH_IN_PROJECT/SPIFFS_IMAGE_FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually using ``esptool.py``, ``parttool.py``, or a custom build system target. There are cases where the contents of the base directory itself is generated at build time. Users can use DEPENDS/SPIFFS_IMAGE_DEPENDS to specify targets -that should be executed before generating the image. +that should be executed before generating the image. in Make:: - dep: + dep: ... SPIFFS_IMAGE_DEPENDS := dep @@ -111,9 +111,9 @@ To pack a folder into a 1-Megabyte image, run:: mkspiffs -c [src_folder] -b 4096 -p 256 -s 0x100000 spiffs.bin -To flash the image onto ESP32 at offset 0x110000, run:: +To flash the image onto {IDF_TARGET_NAME} at offset 0x110000, run:: - python esptool.py --chip esp32 --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin + python esptool.py --chip {IDF_TARGET_PATH_NAME} --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin Notes on which SPIFFS tool to use diff --git a/docs/en/api-reference/system/app_image_format.rst b/docs/en/api-reference/system/app_image_format.rst index 4dfe4f537a..a2e61ea45f 100644 --- a/docs/en/api-reference/system/app_image_format.rst +++ b/docs/en/api-reference/system/app_image_format.rst @@ -4,7 +4,7 @@ App Image Format An application image consists of the following structures: 1. The :cpp:type:`esp_image_header_t` structure describes the mode of SPI flash and the count of memory segments. -2. The :cpp:type:`esp_image_segment_header_t` structure describes each segment, its length, and its location in ESP32's memory, followed by the data with a length of ``data_len``. The data offset for each segment in the image is calculated in the following way: +2. The :cpp:type:`esp_image_segment_header_t` structure describes each segment, its length, and its location in {IDF_TARGET_NAME}'s memory, followed by the data with a length of ``data_len``. The data offset for each segment in the image is calculated in the following way: * offset for 0 Segment = sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`). * offset for 1 Segment = offset for 0 Segment + length of 0 Segment + sizeof(:cpp:type:`esp_image_segment_header_t`). @@ -17,7 +17,7 @@ To get the list of your image segments, please run the following command: :: - esptool.py --chip esp32 image_info build/app.bin + esptool.py --chip {IDF_TARGET_PATH_NAME} image_info build/app.bin :: @@ -58,8 +58,8 @@ You can also see the information on segments in the IDF logs while your applicat I (971) esp_image: segment 11: paddr=0x000a9b74 vaddr=0x50000004 size=0x00000 ( 0) load I (1012) esp_image: segment 12: paddr=0x000a9b7c vaddr=0x50000004 size=0x00000 ( 0) load -For more details on the type of memory segments and their address ranges, see the ESP32 Technical Reference Manual, Section 1.3.2 *Embedded Memory*. - +For more details on the type of memory segments and their address ranges, see the {IDF_TARGET_NAME} Technical Reference Manual, Section 1.3.2 *Embedded Memory*. + 3. The image has a single checksum byte after the last segment. This byte is written on a sixteen byte padded boundary, so the application image might need padding. 4. If the ``hash_appended`` field from :cpp:type:`esp_image_header_t` is set then a SHA256 checksum will be appended. The value of SHA256 is calculated on the range from first byte and up to this field. The length of this field is 32 bytes. 5. If the options :ref:`CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT` or :ref:`CONFIG_SECURE_BOOT_ENABLED` are enabled then the application image will have additional 68 bytes for an ECDSA signature, which includes: diff --git a/docs/en/api-reference/system/app_trace.rst b/docs/en/api-reference/system/app_trace.rst index 1fb97edca5..4e1771a629 100644 --- a/docs/en/api-reference/system/app_trace.rst +++ b/docs/en/api-reference/system/app_trace.rst @@ -4,7 +4,7 @@ Application Level Tracing Overview -------- -IDF provides useful feature for program behaviour analysis: application level tracing. It is implemented in the corresponding library and can be enabled via menuconfig. This feature allows to transfer arbitrary data between host and ESP32 via JTAG interface with small overhead on program execution. +IDF provides useful feature for program behaviour analysis: application level tracing. It is implemented in the corresponding library and can be enabled via menuconfig. This feature allows to transfer arbitrary data between host and {IDF_TARGET_NAME} via JTAG interface with small overhead on program execution. Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are: 1. Collecting application specific data, see :ref:`app_trace-application-specific-tracing` diff --git a/docs/en/api-reference/system/efuse.rst b/docs/en/api-reference/system/efuse.rst index 34c7414049..f50bda763b 100644 --- a/docs/en/api-reference/system/efuse.rst +++ b/docs/en/api-reference/system/efuse.rst @@ -11,15 +11,27 @@ The eFuse Manager library is designed to structure access to eFuse bits and make Hardware description -------------------- -The ESP32 has a number of eFuses which can store system and user parameters. Each eFuse is a one-bit field which can be programmed to 1 after which it cannot be reverted back to 0. -Some of system parameters are using these eFuse bits directly by hardware modules and have special place (for example EFUSE_BLK0). For more details see `ESP32 Technical Reference Manual `_ in part 20 eFuse controller. Some eFuse bits are available for user applications. +The {IDF_TARGET_NAME} has a number of eFuses which can store system and user parameters. Each eFuse is a one-bit field which can be programmed to 1 after which it cannot be reverted back to 0. +Some of system parameters are using these eFuse bits directly by hardware modules and have special place (for example EFUSE_BLK0). + +.. only:: esp32 + + For more details see `ESP32 Technical Reference Manual `_ in part 20 eFuse controller. Some eFuse bits are available for user applications. + + ESP32 has 4 eFuse blocks each of the size of 256 bits (not all bits are available): + + * EFUSE_BLK0 is used entirely for system purposes; + * EFUSE_BLK1 is used for flash encrypt key. If not using that Flash Encryption feature, they can be used for another purpose; + * EFUSE_BLK2 is used for security boot key. If not using that Secure Boot feature, they can be used for another purpose; + * EFUSE_BLK3 can be partially reserved for the custom MAC address, or used entirely for user application. Note that some bits are already used in IDF. + +.. only:: esp32s2 + + For more details see `ESP32-S2 Technical Reference Manual `_. Some eFuse bits are available for user applications. + + {IDF_TARGET_NAME} has 11 eFuse blocks each of the size of 256 bits (not all bits are available): -ESP32 has 4 eFuse blocks each of the size of 256 bits (not all bits are available): -* EFUSE_BLK0 is used entirely for system purposes; -* EFUSE_BLK1 is used for flash encrypt key. If not using that Flash Encryption feature, they can be used for another purpose; -* EFUSE_BLK2 is used for security boot key. If not using that Secure Boot feature, they can be used for another purpose; -* EFUSE_BLK3 can be partially reserved for the custom MAC address, or used entirely for user application. Note that some bits are already used in IDF. Each block is divided into 8 32-bits registers. @@ -62,7 +74,7 @@ bit_count comment This param is using for comment field, it also move to C-header file. The comment field can be omitted. - + If a non-sequential bit order is required to describe a field, then the field description in the following lines should be continued without specifying a name, this will indicate that it belongs to one field. For example two fields MAC_FACTORY and MAC_FACTORY_CRC: :: @@ -76,7 +88,7 @@ If a non-sequential bit order is required to describe a field, then the field de , EFUSE_BLK0, 40, 8, Factory MAC addr [4] , EFUSE_BLK0, 32, 8, Factory MAC addr [5] MAC_FACTORY_CRC, EFUSE_BLK0, 80, 8, CRC8 for factory MAC address - + This field will available in code as ESP_EFUSE_MAC_FACTORY and ESP_EFUSE_MAC_FACTORY_CRC. efuse_table_gen.py tool @@ -87,11 +99,11 @@ The tool is designed to generate C-source files from CSV file and validate field To generate a `common` files, use the following command ``idf.py efuse_common_table`` or: :: - - cd $IDF_PATH/components/efuse/ - ./efuse_table_gen.py esp32/esp_efuse_table.csv -After generation in the folder `esp32` create: + cd $IDF_PATH/components/efuse/ + ./efuse_table_gen.py {IDF_TARGET_PATH_NAME}/esp_efuse_table.csv + +After generation in the folder `{IDF_TARGET_PATH_NAME}` create: * `esp_efuse_table.c` file. * In `include` folder `esp_efuse_table.c` file. @@ -101,7 +113,7 @@ To generate a `custom` files, use the following command ``idf.py efuse_custom_ta :: cd $IDF_PATH/components/efuse/ - ./efuse_table_gen.py esp32/esp_efuse_table.csv PROJECT_PATH/main/esp_efuse_custom_table.csv + ./efuse_table_gen.py {IDF_TARGET_PATH_NAME}/esp_efuse_table.csv PROJECT_PATH/main/esp_efuse_custom_table.csv After generation in the folder PROJECT_PATH/main create: @@ -124,7 +136,7 @@ eFuse have three coding schemes: * ``3/4`` (value 1). * ``Repeat`` (value 2). -The coding scheme affects only EFUSE_BLK1, EFUSE_BLK2 and EFUSE_BLK3 blocks. EUSE_BLK0 block always has a coding scheme ``None``. +The coding scheme affects only EFUSE_BLK1, EFUSE_BLK2 and EFUSE_BLK3 blocks. EUSE_BLK0 block always has a coding scheme ``None``. Coding changes the number of bits that can be written into a block, the block length is constant 256, some of these bits are used for encoding and are not used. When using a coding scheme, the length of the payload that can be written is limited (for more details ``20.3.1.3 System Parameter coding_scheme``): @@ -136,7 +148,7 @@ When using a coding scheme, the length of the payload that can be written is lim You can find out the coding scheme of your chip: * run a ``espefuse.py -p COM4 summary`` command. -* from ``esptool`` utility logs (during flashing). +* from ``esptool`` utility logs (during flashing). * calling the function in the code :cpp:func:`esp_efuse_get_coding_scheme` for the EFUSE_BLK3 block. eFuse tables must always comply with the coding scheme in the chip. There is an :envvar:`EFUSE_CODE_SCHEME_SELECTOR` option to select the coding type for tables in a Kconfig. When generating source files, if your tables do not follow the coding scheme, an error message will be displayed. Adjust the length or offset fields. @@ -181,7 +193,7 @@ How add a new field :: - $ ./efuse_table_gen.py esp32/esp_efuse_table.csv --info + $ ./efuse_table_gen.py {IDF_TARGET_PATH_NAME}/esp_efuse_table.csv --info eFuse coding scheme: NONE # field_name efuse_block bit_start bit_count 1 WR_DIS_FLASH_CRYPT_CNT EFUSE_BLK0 2 1 @@ -226,23 +238,23 @@ How add a new field 40 ADC2_TP_HIGH EFUSE_BLK3 119 9 41 SECURE_VERSION EFUSE_BLK3 128 32 42 MAC_CUSTOM_VER EFUSE_BLK3 184 8 - + Used bits in eFuse table: EFUSE_BLK0 [2 2] [7 9] [16 18] [20 27] [32 87] [96 97] [105 109] [111 111] [136 144] [188 191] [194 194] [196 196] [198 201] - + EFUSE_BLK1 [0 255] - + EFUSE_BLK2 [0 255] - + EFUSE_BLK3 [0 55] [96 159] [184 191] - + Note: Not printed ranges are free for using. (bits in EFUSE_BLK0 are reserved for Espressif) - - Parsing eFuse CSV input file $IDF_PATH/components/efuse/esp32/esp_efuse_table.csv ... + + Parsing eFuse CSV input file $IDF_PATH/components/efuse/{IDF_TARGET_PATH_NAME}/esp_efuse_table.csv ... Verifying eFuse table... @@ -263,12 +275,12 @@ The Kconfig option :envvar:`CONFIG_EFUSE_VIRTUAL` will virtualize eFuse values i espefuse.py ^^^^^^^^^^^ -esptool includes a useful tool for reading/writing ESP32 eFuse bits - `espefuse.py `_. +esptool includes a useful tool for reading/writing {IDF_TARGET_NAME} eFuse bits - `espefuse.py `_. :: espefuse.py -p COM4 summary - + espefuse.py v2.3.1 Connecting........_ Security fuses: @@ -287,13 +299,13 @@ esptool includes a useful tool for reading/writing ESP32 eFuse bits - `espefuse. = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLK3 Variable Block 3 = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 fa 87 02 91 00 00 00 00 00 00 00 00 00 00 00 00 R/W - + Efuse fuses: WR_DIS Efuse write disable mask = 0 R/W (0x0) RD_DIS Efuse read disablemask = 0 R/W (0x0) CODING_SCHEME Efuse variable block length scheme = 1 R/W (0x1) (3/4) KEY_STATUS Usage of efuse block 3 (reserved) = 0 R/W (0x0) - + Config fuses: XPD_SDIO_FORCE Ignore MTDI pin (GPIO12) for VDD_SDIO on reset = 0 R/W (0x0) XPD_SDIO_REG If XPD_SDIO_FORCE, enable VDD_SDIO reg on reset = 0 R/W (0x0) @@ -304,14 +316,14 @@ esptool includes a useful tool for reading/writing ESP32 eFuse bits - `espefuse. SPI_PAD_CONFIG_HD Override SD_DATA_2 pad (GPIO9/SPIHD) = 0 R/W (0x0) SPI_PAD_CONFIG_CS0 Override SD_CMD pad (GPIO11/SPICS0) = 0 R/W (0x0) DISABLE_SDIO_HOST Disable SDIO host = 0 R/W (0x0) - + Identity fuses: MAC MAC Address = 84:0d:8e:18:8e:44 (CRC ad OK) R/W CHIP_VER_REV1 Silicon Revision 1 = 1 R/W (0x1) CHIP_VERSION Reserved for future chip versions = 2 R/W (0x2) CHIP_PACKAGE Chip package identifier = 0 R/W (0x0) - + Calibration fuses: BLK3_PART_RESERVE BLOCK3 partially served for ADC calibration data = 1 R/W (0x1) ADC_VREF Voltage reference calibration = 1114 R/W (0x2) @@ -319,13 +331,13 @@ esptool includes a useful tool for reading/writing ESP32 eFuse bits - `espefuse. ADC1_TP_HIGH ADC1 850mV reading = 3285 R/W (0x5) ADC2_TP_LOW ADC2 150mV reading = 449 R/W (0x7) ADC2_TP_HIGH ADC2 850mV reading = 3362 R/W (0x1f5) - + Flash voltage (VDD_SDIO) determined by GPIO12 on reset (High for 1.8V, Low/NC for 3.3V). To get a dump for all eFuse registers. :: - + espefuse.py -p COM4 dump $ espefuse.py -p COM4 dump diff --git a/docs/en/api-reference/system/heap_debug.rst b/docs/en/api-reference/system/heap_debug.rst index d00f17e480..92f74be404 100644 --- a/docs/en/api-reference/system/heap_debug.rst +++ b/docs/en/api-reference/system/heap_debug.rst @@ -280,7 +280,7 @@ To gather and analyse heap trace do the following on the host: Using this file GDB will connect to the target, reset it, and start tracing when program hits breakpoint at :cpp:func:`heap_trace_start`. Trace data will be saved to ``/tmp/heap_log.svdat``. Tracing will be stopped when program hits breakpoint at :cpp:func:`heap_trace_stop`. -4. Run GDB using the following command ``xtensa-esp32-elf-gdb -x gdbinit `` +4. Run GDB using the following command ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit `` 5. Quit GDB when program stops at :cpp:func:`heap_trace_stop`. Trace data are saved in ``/tmp/heap.svdat`` diff --git a/docs/en/api-reference/system/index.rst b/docs/en/api-reference/system/index.rst index dab87a1278..d990ef60d3 100644 --- a/docs/en/api-reference/system/index.rst +++ b/docs/en/api-reference/system/index.rst @@ -16,8 +16,8 @@ System API Heap Memory Allocation Heap Memory Debugging High Resolution Timer - Himem (large external SPI RAM) API - Inter-Processor Call + :esp32: Himem (large external SPI RAM) API + :esp32: Inter-Processor Call Call function with external stack Interrupt Allocation Logging diff --git a/docs/en/api-reference/system/intr_alloc.rst b/docs/en/api-reference/system/intr_alloc.rst index da15992432..9d200820c2 100644 --- a/docs/en/api-reference/system/intr_alloc.rst +++ b/docs/en/api-reference/system/intr_alloc.rst @@ -4,9 +4,17 @@ Interrupt allocation Overview -------- -The ESP32 has two cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected -to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in -multiple drivers. The esp_intr_alloc abstraction exists to hide all these implementation details. +.. only:: esp32 + + The {IDF_TARGET_NAME} has two cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected + to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in + multiple drivers. The esp_intr_alloc abstraction exists to hide all these implementation details. + +.. only.. esp32s2 + + The {IDF_TARGET_NAME} has one cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected + to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in + multiple drivers. The esp_intr_alloc abstraction exists to hide all these implementation details. A driver can allocate an interrupt for a certain peripheral by calling esp_intr_alloc (or esp_intr_alloc_sintrstatus). It can use the flags passed to this function to set the type of interrupt allocated, specifying a specific level or trigger method. The @@ -15,7 +23,7 @@ install the given interrupt handler and ISR to it. This code has two different types of interrupts it handles differently: Shared interrupts and non-shared interrupts. The simplest of the two are non-shared interrupts: a separate interrupt is allocated per esp_intr_alloc call and this interrupt is solely used for -the peripheral attached to it, with only one ISR that will get called. Shared interrupts can have multiple peripherals triggering +the peripheral attached to it, with only one ISR that will get called. Shared interrupts can have multiple peripherals triggering it, with multiple ISRs being called when one of the peripherals attached signals an interrupt. Thus, ISRs that are intended for shared interrupts should check the interrupt status of the peripheral they service in order to see if any action is required. @@ -24,7 +32,7 @@ only be level interrupts (because of the chance of missed interrupts when edge i used.) (The logic behind this: DevA and DevB share an int. DevB signals an int. Int line goes high. ISR handler calls code for DevA -> does nothing. ISR handler calls code for DevB, but while doing that, -DevA signals an int. ISR DevB is done, clears int for DevB, exits interrupt code. Now an +DevA signals an int. ISR DevB is done, clears int for DevB, exits interrupt code. Now an interrupt for DevA is still pending, but because the int line never went low (DevA kept it high even when the int for DevB was cleared) the interrupt is never serviced.) @@ -34,7 +42,7 @@ Multicore issues Peripherals that can generate interrupts can be divided in two types: - - External peripherals, within the ESP32 but outside the Xtensa cores themselves. Most ESP32 peripherals are of this type. + - External peripherals, within the {IDF_TARGET_NAME} but outside the Xtensa cores themselves. Most {IDF_TARGET_NAME} peripherals are of this type. - Internal peripherals, part of the Xtensa CPU cores themselves. Interrupt handling differs slightly between these two types of peripherals. @@ -89,7 +97,7 @@ Multiple Handlers Sharing A Source Several handlers can be assigned to a same source, given that all handlers are allocated using the ``ESP_INTR_FLAG_SHARED`` flag. They'll be all allocated to the interrupt, which the source is attached to, and called sequentially when the source is active. The handlers can be disabled and freed individually. The source is attached to the interrupt (enabled), if one or more handlers are enabled, otherwise detached. -A handler will never be called when disabled, while **its source may still be triggered** if any one of its handler enabled. +A handler will never be called when disabled, while **its source may still be triggered** if any one of its handler enabled. Sources attached to non-shared interrupt do not support this feature. diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst index 65ab940435..44512aa2c9 100644 --- a/docs/en/api-reference/system/mem_alloc.rst +++ b/docs/en/api-reference/system/mem_alloc.rst @@ -8,7 +8,7 @@ ESP-IDF applications use the common computer architecture patterns of *stack* (d Because ESP-IDF is a multi-threaded RTOS environment, each RTOS task has its own stack. By default, each of these stacks is allocated from the heap when the task is created. (See :cpp:func:`xTaskCreateStatic` for the alternative where stacks are statically allocated.) -Because ESP32 uses multiple types of RAM, it also contains multiple heaps with different capabilities. A capabilities-based memory allocator allows apps to make heap allocations for different purposes. +Because {IDF_TARGET_NAME} uses multiple types of RAM, it also contains multiple heaps with different capabilities. A capabilities-based memory allocator allows apps to make heap allocations for different purposes. For most purposes, the standard libc ``malloc()`` and ``free()`` functions can be used for heap allocation without any special consideration. @@ -18,7 +18,7 @@ capabilities-based heap memory allocator. If you want to have memory with certai Memory Capabilities ------------------- -The ESP32 contains multiple types of RAM: +The {IDF_TARGET_NAME} contains multiple types of RAM: - DRAM (Data RAM) is memory used to hold data. This is the most common kind of memory accessed as heap. - IRAM (Instruction RAM) usually holds executable data only. If accessed as generic memory, all accesses must be :ref:`32-bit aligned<32-Bit Accessible Memory>`. @@ -26,7 +26,7 @@ The ESP32 contains multiple types of RAM: For more details on these internal memory types, see :ref:`memory-layout`. -It's also possible to connect external SPI RAM to the ESP32 - :doc:`external RAM ` can be integrated into the ESP32's memory map using the flash cache, and accessed similarly to DRAM. +It's also possible to connect external SPI RAM to the {IDF_TARGET_NAME} - :doc:`external RAM ` can be integrated into the {IDF_TARGET_NAME}'s memory map using the flash cache, and accessed similarly to DRAM. DRAM uses capability ``MALLOC_CAP_8BIT`` (accessible in single byte reads and writes). When calling ``malloc()``, the ESP-IDF ``malloc()`` implementation internally calls ``heap_caps_malloc(size, MALLOC_CAP_8BIT)`` in order to allocate DRAM that is byte-addressable. To test the free DRAM heap size at runtime, call cpp:func:`heap_caps_get_free_size(MALLOC_CAP_8BIT)`. @@ -57,7 +57,7 @@ The :ref:`idf.py size ` command can be used to find the amount of I D/IRAM ^^^^^^ -Some memory in the ESP32 is available as either DRAM or IRAM. If memory is allocated from a D/IRAM region, the free heap size for both types of memory will decrease. +Some memory in the {IDF_TARGET_NAME} is available as either DRAM or IRAM. If memory is allocated from a D/IRAM region, the free heap size for both types of memory will decrease. Heap Sizes ^^^^^^^^^^ @@ -95,7 +95,7 @@ Use the ``MALLOC_CAP_DMA`` flag to allocate memory which is suitable for use wit If a certain memory structure is only addressed in 32-bit units, for example an array of ints or pointers, it can be useful to allocate it with the ``MALLOC_CAP_32BIT`` flag. This also allows the allocator to give out IRAM memory; something -which it can't do for a normal malloc() call. This can help to use all the available memory in the ESP32. +which it can't do for a normal malloc() call. This can help to use all the available memory in the {IDF_TARGET_NAME}. Memory allocated with ``MALLOC_CAP_32BIT`` can *only* be accessed via 32-bit reads and writes, any other type of access will generate a fatal LoadStoreError exception. @@ -105,7 +105,9 @@ External SPI Memory When :doc:`external RAM ` is enabled, external SPI RAM under 4MiB in size can be allocated using standard ``malloc`` calls, or via ``heap_caps_malloc(MALLOC_CAP_SPIRAM)``, depending on configuration. See :ref:`external_ram_config` for more details. -To use the region above the 4MiB limit, you can use the :doc:`himem API`. +..only:: esp32 + + To use the region above the 4MiB limit, you can use the :doc:`himem API`. API Reference - Heap Allocation diff --git a/docs/en/api-reference/system/ota.rst b/docs/en/api-reference/system/ota.rst index 941c68bb29..110c1dabee 100644 --- a/docs/en/api-reference/system/ota.rst +++ b/docs/en/api-reference/system/ota.rst @@ -139,7 +139,7 @@ This function works if set :ref:`CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK` option. In A typical anti-rollback scheme is ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- New firmware released with the elimination of vulnerabilities with the previous version of security. +- New firmware released with the elimination of vulnerabilities with the previous version of security. - After the developer makes sure that this firmware is working. He can increase the security version and release a new firmware. - Download new application. - To make it bootable, run the function :cpp:func:`esp_ota_set_boot_partition`. If the security version of the new application is smaller than the version in the chip, the new application will be erased. Update to new firmware is not possible. @@ -148,7 +148,7 @@ A typical anti-rollback scheme is - New application booted. Then the application should perform diagnostics of the operation and if it is completed successfully, you should call :cpp:func:`esp_ota_mark_app_valid_cancel_rollback` function to mark the running application with the ``ESP_OTA_IMG_VALID`` state and update the secure version on chip. Note that if was called :cpp:func:`esp_ota_mark_app_invalid_rollback_and_reboot` function a rollback may not happend due to the device may not have any bootable apps then it will return ``ESP_ERR_OTA_ROLLBACK_FAILED`` error and stay in the ``ESP_OTA_IMG_PENDING_VERIFY`` state. - The next update of app is possible if a running app is in the ``ESP_OTA_IMG_VALID`` state. -Recommendation: +Recommendation: If you want to avoid the download/erase overhead in case of the app from the server has security version lower then running app you have to get ``new_app_info.secure_version`` from the first package of an image and compare it with the secure version of efuse. Use ``esp_efuse_check_secure_version(new_app_info.secure_version)`` function if it is true then continue downloading otherwise abort. @@ -169,7 +169,7 @@ If you want to avoid the download/erase overhead in case of the app from the ser http_cleanup(client); task_fatal_error(); } - + image_header_was_checked = true; esp_ota_begin(update_partition, OTA_SIZE_UNKNOWN, &update_handle); @@ -189,7 +189,10 @@ Restrictions: ``security_version``: - In application image it is stored in ``esp_app_desc`` structure. The number is set :ref:`CONFIG_BOOTLOADER_APP_SECURE_VERSION`. -- In ESP32 it is stored in efuse ``EFUSE_BLK3_RDATA4_REG``. (when a eFuse bit is programmed to 1, it can never be reverted to 0). The number of bits set in this register is the ``security_version`` from app. + +.. only:: esp32 + + - In ESP32 it is stored in efuse ``EFUSE_BLK3_RDATA4_REG``. (when a eFuse bit is programmed to 1, it can never be reverted to 0). The number of bits set in this register is the ``security_version`` from app. .. _secure-ota-updates: @@ -267,13 +270,13 @@ The command-line interface of `otatool.py` has the following structure: otatool.py [command-args] [subcommand] [subcommand-args] - command-args - these are arguments that are needed for executing the main command (parttool.py), mostly pertaining to the target device - - subcommand - this is the operation to be performed + - subcommand - this is the operation to be performed - subcommand-args - these are arguments that are specific to the chosen operation .. code-block:: bash # Erase otadata, resetting the device to factory app - otatool.py --port "/dev/ttyUSB1" erase_otadata + otatool.py --port "/dev/ttyUSB1" erase_otadata # Erase contents of OTA app slot 0 otatool.py --port "/dev/ttyUSB1" erase_ota_partition --slot 0 diff --git a/docs/en/api-reference/system/perfmon.rst b/docs/en/api-reference/system/perfmon.rst index d135446113..70aa31b953 100644 --- a/docs/en/api-reference/system/perfmon.rst +++ b/docs/en/api-reference/system/perfmon.rst @@ -1,13 +1,13 @@ Performance Monitor =================== -The Performance Monitor component provides APIs to use ESP32 internal performance counters to profile functions and +The Performance Monitor component provides APIs to use {IDF_TARGET_NAME} internal performance counters to profile functions and applications. Application Example ------------------- -An example which combines performance monitor is provided in ``examples/system/perfmon`` directory. +An example which combines performance monitor is provided in ``examples/system/perfmon`` directory. This example initializes the performance monitor structure and execute them with printing the statistics. High level API Reference diff --git a/docs/en/api-reference/system/power_management.rst b/docs/en/api-reference/system/power_management.rst index 49acb39f8a..b26602d524 100644 --- a/docs/en/api-reference/system/power_management.rst +++ b/docs/en/api-reference/system/power_management.rst @@ -31,13 +31,8 @@ Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in an a - ``min_freq_mhz``: Minimum CPU frequency in MHz, i.e., the frequency used when only the ``ESP_PM_APB_FREQ_MAX`` lock is acquired. This field can be set to the XTAL frequency value, or the XTAL frequency divided by an integer. Note that 10 MHz is the lowest frequency at which the default REF_TICK clock of 1 MHz can be generated. - ``light_sleep_enable``: Whether the system should automatically enter light sleep when no locks are acquired (``true``/``false``). -.. only:: esp32 - Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency. - -.. only:: esp32s2beta - - Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_ESP32S2_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency. + Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency. .. note:: @@ -55,14 +50,14 @@ Applications have the ability to acquire/release locks in order to control the p Power management locks have acquire/release counters. If the lock has been acquired a number of times, it needs to be released the same number of times to remove associated restrictions. -ESP32 supports three types of locks described in the table below. +{IDF_TARGET_NAME} supports three types of locks described in the table below. ============================ ====================================================== Lock Description ============================ ====================================================== -``ESP_PM_CPU_FREQ_MAX`` Requests CPU frequency to be at the maximum value set with :cpp:func:`esp_pm_configure`. For ESP32, this value can be set to 80 MHz, 160 MHz, or 240 MHz. +``ESP_PM_CPU_FREQ_MAX`` Requests CPU frequency to be at the maximum value set with :cpp:func:`esp_pm_configure`. For {IDF_TARGET_NAME}, this value can be set to 80 MHz, 160 MHz, or 240 MHz. -``ESP_PM_APB_FREQ_MAX`` Requests the APB frequency to be at the maximum supported value. For ESP32, this is 80 MHz. +``ESP_PM_APB_FREQ_MAX`` Requests the APB frequency to be at the maximum supported value. For {IDF_TARGET_NAME}, this is 80 MHz. ``ESP_PM_NO_LIGHT_SLEEP`` Disables automatic switching to light sleep. ============================ ====================================================== diff --git a/docs/en/api-reference/system/sleep_modes.rst b/docs/en/api-reference/system/sleep_modes.rst index ab536aba22..74ee758214 100644 --- a/docs/en/api-reference/system/sleep_modes.rst +++ b/docs/en/api-reference/system/sleep_modes.rst @@ -4,13 +4,13 @@ Sleep Modes Overview -------- -ESP32 is capable of light sleep and deep sleep power saving modes. +{IDF_TARGET_NAME} is capable of light sleep and deep sleep power saving modes. In light sleep mode, digital peripherals, most of the RAM, and CPUs are clock-gated, and supply voltage is reduced. Upon exit from light sleep, peripherals and CPUs resume operation, their internal state is preserved. In deep sleep mode, CPUs, most of the RAM, and all the digital peripherals which are clocked from APB_CLK are powered off. The only parts of the chip which can still be powered on are: RTC controller, RTC peripherals (including ULP coprocessor), and RTC memories (slow and fast). -Wakeup from deep and light sleep modes can be done using several sources. These sources can be combined, in this case the chip will wake up when any one of the sources is triggered. Wakeup sources can be enabled using ``esp_sleep_enable_X_wakeup`` APIs and can be disabled using :cpp:func:`esp_sleep_disable_wakeup_source` API. Next section describes these APIs in detail. Wakeup sources can be configured at any moment before entering light or deep sleep mode. +Wakeup from deep and light sleep modes can be done using several sources. These sources can be combined, in this case the chip will wake up when any one of the sources is triggered. Wakeup sources can be enabled using ``esp_sleep_enable_X_wakeup`` APIs and can be disabled using :cpp:func:`esp_sleep_disable_wakeup_source` API. Next section describes these APIs in detail. Wakeup sources can be configured at any moment before entering light or deep sleep mode. Additionally, the application can force specific powerdown modes for the RTC peripherals and RTC memories using :cpp:func:`esp_sleep_pd_config` API. @@ -29,7 +29,7 @@ Wakeup sources Timer ^^^^^ -RTC controller has a built in timer which can be used to wake up the chip after a predefined amount of time. Time is specified at microsecond precision, but the actual resolution depends on the clock source selected for RTC SLOW_CLK. See chapter "Reset and Clock" of the ESP32 Technical Reference Manual for details about RTC clock options. +RTC controller has a built in timer which can be used to wake up the chip after a predefined amount of time. Time is specified at microsecond precision, but the actual resolution depends on the clock source selected for RTC SLOW_CLK. See chapter "Reset and Clock" of the {IDF_TARGET_NAME} Technical Reference Manual for details about RTC clock options. This wakeup mode doesn't require RTC peripherals or RTC memories to be powered on during sleep. @@ -40,7 +40,9 @@ Touch pad RTC IO module contains logic to trigger wakeup when a touch sensor interrupt occurs. You need to configure the touch pad interrupt before the chip starts deep sleep. -Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO). +.. only:: esp32 + + Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO). :cpp:func:`esp_sleep_enable_touchpad_wakeup` function can be used to enable this wakeup source. @@ -48,11 +50,13 @@ Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripheral External wakeup (ext0) ^^^^^^^^^^^^^^^^^^^^^^ -RTC IO module contains logic to trigger wakeup when one of RTC GPIOs is set to a predefined logic level. RTC IO is part of RTC peripherals power domain, so RTC peripherals will be kept powered on during deep sleep if this wakeup source is requested. +RTC IO module contains logic to trigger wakeup when one of RTC GPIOs is set to a predefined logic level. RTC IO is part of RTC peripherals power domain, so RTC peripherals will be kept powered on during deep sleep if this wakeup source is requested. Because RTC IO module is enabled in this mode, internal pullup or pulldown resistors can also be used. They need to be configured by the application using :cpp:func:`rtc_gpio_pullup_en` and :cpp:func:`rtc_gpio_pulldown_en` functions, before calling :cpp:func:`esp_sleep_start`. -In revisions 0 and 1 of the ESP32, this wakeup source is incompatible with ULP and touch wakeup sources. +.. only:: esp32 + + In revisions 0 and 1 of the ESP32, this wakeup source is incompatible with ULP and touch wakeup sources. :cpp:func:`esp_sleep_enable_ext0_wakeup` function can be used to enable this wakeup source. @@ -73,7 +77,7 @@ This wakeup source is implemented by the RTC controller. As such, RTC peripheral gpio_pulldown_en(gpio_num); .. warning:: After wake up from sleep, IO pad(s) used for wakeup will be configured as RTC IO. Before using these pads as digital GPIOs, reconfigure them using ``rtc_gpio_deinit(gpio_num)`` function. - + :cpp:func:`esp_sleep_enable_ext1_wakeup` function can be used to enable this wakeup source. ULP coprocessor wakeup @@ -81,7 +85,9 @@ ULP coprocessor wakeup ULP coprocessor can run while the chip is in sleep mode, and may be used to poll sensors, monitor ADC or touch sensor values, and wake up the chip when a specific event is detected. ULP coprocessor is part of RTC peripherals power domain, and it runs the program stored in RTC slow memory. RTC slow memory will be powered on during sleep if this wakeup mode is requested. RTC peripherals will be automatically powered on before ULP coprocessor starts running the program; once the program stops running, RTC peripherals are automatically powered down again. -Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO). +.. only:: esp32 + + Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO). :cpp:func:`esp_sleep_enable_ulp_wakeup` function can be used to enable this wakeup source. @@ -95,7 +101,7 @@ In addition to EXT0 and EXT1 wakeup sources described above, one more method of UART wakeup (light sleep only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When ESP32 receives UART input from external devices, it is often required to wake up the chip when input data is available. UART peripheral contains a feature which allows waking up the chip from light sleep when a certain number of positive edges on RX pin are seen. This number of positive edges can be set using :cpp:func:`uart_set_wakeup_threshold` function. Note that the character which triggers wakeup (and any characters before it) will not be received by the UART after wakeup. This means that the external device typically needs to send an extra character to the ESP32 to trigger wakeup, before sending the data. +When {IDF_TARGET_NAME} receives UART input from external devices, it is often required to wake up the chip when input data is available. UART peripheral contains a feature which allows waking up the chip from light sleep when a certain number of positive edges on RX pin are seen. This number of positive edges can be set using :cpp:func:`uart_set_wakeup_threshold` function. Note that the character which triggers wakeup (and any characters before it) will not be received by the UART after wakeup. This means that the external device typically needs to send an extra character to the {IDF_TARGET_NAME} to trigger wakeup, before sending the data. :cpp:func:`esp_sleep_enable_uart_wakeup` function can be used to enable this wakeup source. @@ -105,7 +111,9 @@ Power-down of RTC peripherals and memories By default, :cpp:func:`esp_deep_sleep_start` and :cpp:func:`esp_light_sleep_start` functions will power down all RTC power domains which are not needed by the enabled wakeup sources. To override this behaviour, :cpp:func:`esp_sleep_pd_config` function is provided. -Note: in revision 0 of the ESP32, RTC fast memory will always be kept enabled in deep sleep, so that the deep sleep stub can run after reset. This can be overridden, if the application doesn't need clean reset behaviour after deep sleep. +.. only:: esp32 + + Note: in revision 0 of the ESP32, RTC fast memory will always be kept enabled in deep sleep, so that the deep sleep stub can run after reset. This can be overridden, if the application doesn't need clean reset behaviour after deep sleep. If some variables in the program are placed into RTC slow memory (for example, using ``RTC_DATA_ATTR`` attribute), RTC slow memory will be kept powered on by default. This can be overridden using :cpp:func:`esp_sleep_pd_config` function, if desired. @@ -123,7 +131,7 @@ Entering deep sleep Configuring IOs --------------- -Some ESP32 IOs have internal pullups or pulldowns, which are enabled by default. If an external circuit drives this pin in deep sleep mode, current consumption may increase due to current flowing through these pullups and pulldowns. +Some {IDF_TARGET_NAME} IOs have internal pullups or pulldowns, which are enabled by default. If an external circuit drives this pin in deep sleep mode, current consumption may increase due to current flowing through these pullups and pulldowns. To isolate a pin, preventing extra current draw, call :cpp:func:`rtc_gpio_isolate` function. @@ -155,7 +163,7 @@ Previously configured wakeup source can be disabled later using :cpp:func:`esp_s Application Example ------------------- - + Implementation of basic functionality of deep sleep is shown in :example:`protocols/sntp` example, where ESP module is periodically waken up to retrieve time from NTP server. More extensive example in :example:`system/deep_sleep` illustrates usage of various deep sleep wakeup triggers and ULP coprocessor programming. diff --git a/docs/en/api-reference/system/system.rst b/docs/en/api-reference/system/system.rst index d0c8221cb4..a34213ab56 100644 --- a/docs/en/api-reference/system/system.rst +++ b/docs/en/api-reference/system/system.rst @@ -26,7 +26,7 @@ Note that ESP-IDF supports multiple heaps with different capabilities. Functions Random number generation ------------------------ -ESP32 contains a hardware random number generator, values from it can be obtained using :cpp:func:`esp_random`. +{IDF_TARGET_NAME} contains a hardware random number generator, values from it can be obtained using :cpp:func:`esp_random`. When Wi-Fi or Bluetooth are enabled, numbers returned by hardware random number generator (RNG) can be considered true random numbers. Without Wi-Fi or Bluetooth enabled, hardware RNG is a pseudo-random number generator. At startup, ESP-IDF bootloader seeds the hardware RNG with entropy, but care must be taken when reading random values between the start of ``app_main`` and initialization of Wi-Fi or Bluetooth drivers. @@ -38,32 +38,32 @@ These APIs allow querying and customizing MAC addresses for different network in In ESP-IDF these addresses are calculated from *Base MAC address*. Base MAC address can be initialized with factory-programmed value from internal eFuse, or with a user-defined value. In addition to setting the base MAC address, applications can specify the way in which MAC addresses are allocated to devices. See `Number of universally administered MAC address`_ section for more details. -For ESP32: +.. only:: esp32 -+---------------+--------------------------------+----------------------------------+ -| Interface | MAC address | MAC address | -| | (4 universally administered) | (2 universally administered) | -+===============+================================+==================================+ -| Wi-Fi Station | base_mac | base_mac | -+---------------+--------------------------------+----------------------------------+ -| Wi-Fi SoftAP | base_mac, +1 to the last octet | base_mac, first octet randomized | -+---------------+--------------------------------+----------------------------------+ -| Bluetooth | base_mac, +2 to the last octet | base_mac, +1 to the last octet | -+---------------+--------------------------------+----------------------------------+ -| Ethernet | base_mac, +3 to the last octet | base_mac, +1 to the last octet, | -| | | first octet randomized | -+---------------+--------------------------------+----------------------------------+ + +---------------+--------------------------------+----------------------------------+ + | Interface | MAC address | MAC address | + | | (4 universally administered) | (2 universally administered) | + +===============+================================+==================================+ + | Wi-Fi Station | base_mac | base_mac | + +---------------+--------------------------------+----------------------------------+ + | Wi-Fi SoftAP | base_mac, +1 to the last octet | base_mac, first octet randomized | + +---------------+--------------------------------+----------------------------------+ + | Bluetooth | base_mac, +2 to the last octet | base_mac, +1 to the last octet | + +---------------+--------------------------------+----------------------------------+ + | Ethernet | base_mac, +3 to the last octet | base_mac, +1 to the last octet, | + | | | first octet randomized | + +---------------+--------------------------------+----------------------------------+ -For ESP32-S2: +.. only:: esp32s2 -+---------------+--------------------------------+----------------------------------+ -| Interface | MAC address | MAC address | -| | (2 universally administered) | (1 universally administered) | -+===============+================================+==================================+ -| Wi-Fi Station | base_mac | base_mac | -+---------------+--------------------------------+----------------------------------+ -| Wi-Fi SoftAP | base_mac, +1 to the last octet | base_mac, first octet randomized | -+---------------+--------------------------------+----------------------------------+ + +---------------+--------------------------------+----------------------------------+ + | Interface | MAC address | MAC address | + | | (2 universally administered) | (1 universally administered) | + +===============+================================+==================================+ + | Wi-Fi Station | base_mac | base_mac | + +---------------+--------------------------------+----------------------------------+ + | Wi-Fi SoftAP | base_mac, +1 to the last octet | base_mac, first octet randomized | + +---------------+--------------------------------+----------------------------------+ Base MAC address ^^^^^^^^^^^^^^^^ @@ -101,7 +101,7 @@ Number of universally administered MAC address Several MAC addresses (universally administered by IEEE) are uniquely assigned to the networking interfaces (Wi-Fi/BT/Ethernet). The final octet of each universally administered MAC address increases by one. Only the first one of them (which is called base MAC address) is stored in eFuse or external storage, the others are generated from it. Here, 'generate' means adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address. -If the universally administered MAC addresses are not enough for all of the networking interfaces, locally administered MAC addresses which are derived from universally administered MAC addresses are assigned to the rest of networking interfaces. +If the universally administered MAC addresses are not enough for all of the networking interfaces, locally administered MAC addresses which are derived from universally administered MAC addresses are assigned to the rest of networking interfaces. See `this article `_ for the definition of local and universally administered MAC addresses. @@ -136,7 +136,7 @@ To get the version at build time, additional version macros are provided. They c * :c:macro:`ESP_IDF_VERSION_MAJOR`, :c:macro:`ESP_IDF_VERSION_MINOR`, :c:macro:`ESP_IDF_VERSION_PATCH` are defined to integers representing major, minor, and patch version. * :c:macro:`ESP_IDF_VERSION_VAL` and :c:macro:`ESP_IDF_VERSION` can be used when implementing version checks: - + .. code-block:: c #include "esp_idf_version.h" @@ -148,7 +148,7 @@ To get the version at build time, additional version macros are provided. They c App version ----------- -Application version is stored in :cpp:class:`esp_app_desc_t` structure. It is located in DROM sector and has a fixed offset from the beginning of the binary file. +Application version is stored in :cpp:class:`esp_app_desc_t` structure. It is located in DROM sector and has a fixed offset from the beginning of the binary file. The structure is located after :cpp:class:`esp_image_header_t` and :cpp:class:`esp_image_segment_header_t` structures. The field version has string type and max length 32 chars. To set version in your project manually you need to set ``PROJECT_VER`` variable in your project CMakeLists.txt/Makefile: diff --git a/docs/en/api-reference/system/wdts.rst b/docs/en/api-reference/system/wdts.rst index e185f7bace..55e858898b 100644 --- a/docs/en/api-reference/system/wdts.rst +++ b/docs/en/api-reference/system/wdts.rst @@ -17,11 +17,11 @@ Interrupt watchdog The interrupt watchdog makes sure the FreeRTOS task switching interrupt isn't blocked for a long time. This is bad because no other tasks, including potentially important ones like the WiFi task and the idle task, -can't get any CPU runtime. A blocked task switching interrupt can happen because a program runs into an +can't get any CPU runtime. A blocked task switching interrupt can happen because a program runs into an infinite loop with interrupts disabled or hangs in an interrupt. The default action of the interrupt watchdog is to invoke the panic handler. causing a register dump and an opportunity -for the programmer to find out, using either OpenOCD or gdbstub, what bit of code is stuck with interrupts +for the programmer to find out, using either OpenOCD or gdbstub, what bit of code is stuck with interrupts disabled. Depending on the configuration of the panic handler, it can also blindly reset the CPU, which may be preferred in a production environment. @@ -32,54 +32,54 @@ it will hard-reset the SOC. Task Watchdog Timer ^^^^^^^^^^^^^^^^^^^ -The Task Watchdog Timer (TWDT) is responsible for detecting instances of tasks -running for a prolonged period of time without yielding. This is a symptom of +The Task Watchdog Timer (TWDT) is responsible for detecting instances of tasks +running for a prolonged period of time without yielding. This is a symptom of CPU starvation and is usually caused by a higher priority task looping without yielding to a lower-priority task thus starving the lower priority task from CPU time. This can be an indicator of poorly written code that spinloops on a -peripheral, or a task that is stuck in an infinite loop. +peripheral, or a task that is stuck in an infinite loop. -By default the TWDT will watch the Idle Tasks of each CPU, however any task can +By default the TWDT will watch the Idle Tasks of each CPU, however any task can elect to be watched by the TWDT. Each watched task must 'reset' the TWDT -periodically to indicate that they have been allocated CPU time. If a task does -not reset within the TWDT timeout period, a warning will be printed with -information about which tasks failed to reset the TWDT in time and which -tasks are currently running on the ESP32 CPUs. -And also there is a possibility to redefine the function `esp_task_wdt_isr_user_handler` +periodically to indicate that they have been allocated CPU time. If a task does +not reset within the TWDT timeout period, a warning will be printed with +information about which tasks failed to reset the TWDT in time and which +tasks are currently running on the {IDF_TARGET_NAME} CPUs. +And also there is a possibility to redefine the function `esp_task_wdt_isr_user_handler` in the user code to receive this event. The TWDT is built around the Hardware Watchdog Timer in Timer Group 0. The TWDT can be initialized by calling :cpp:func:`esp_task_wdt_init` which will configure -the hardware timer. A task can then subscribe to the TWDT using -:cpp:func:`esp_task_wdt_add` in order to be watched. Each subscribed task must -periodically call :cpp:func:`esp_task_wdt_reset` to reset the TWDT. Failure by +the hardware timer. A task can then subscribe to the TWDT using +:cpp:func:`esp_task_wdt_add` in order to be watched. Each subscribed task must +periodically call :cpp:func:`esp_task_wdt_reset` to reset the TWDT. Failure by any subscribed tasks to periodically call :cpp:func:`esp_task_wdt_reset` indicates that one or more tasks have been starved of CPU time or are stuck in a loop somewhere. -A watched task can be unsubscribed from the TWDT using -:cpp:func:`esp_task_wdt_delete()`. A task that has been unsubscribed should no +A watched task can be unsubscribed from the TWDT using +:cpp:func:`esp_task_wdt_delete()`. A task that has been unsubscribed should no longer call :cpp:func:`esp_task_wdt_reset`. Once all tasks have unsubscribed -form the TWDT, the TWDT can be deinitialized by calling +form the TWDT, the TWDT can be deinitialized by calling :cpp:func:`esp_task_wdt_deinit()`. By default :ref:`CONFIG_ESP_TASK_WDT` in :ref:`project-configuration-menu` be enabled causing the TWDT to be initialized automatically during startup. Likewise -:ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` and +:ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` and :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1` are also enabled by default causing the two Idle Tasks to be subscribed to the TWDT during startup. JTAG and watchdogs ^^^^^^^^^^^^^^^^^^ -While debugging using OpenOCD, the CPUs will be halted every time a breakpoint -is reached. However if the watchdog timers continue to run when a breakpoint is -encountered, they will eventually trigger a reset making it very difficult to -debug code. Therefore OpenOCD will disable the hardware timers of both the -interrupt and task watchdogs at every breakpoint. Moreover, OpenOCD will not +While debugging using OpenOCD, the CPUs will be halted every time a breakpoint +is reached. However if the watchdog timers continue to run when a breakpoint is +encountered, they will eventually trigger a reset making it very difficult to +debug code. Therefore OpenOCD will disable the hardware timers of both the +interrupt and task watchdogs at every breakpoint. Moreover, OpenOCD will not reenable them upon leaving the breakpoint. This means that interrupt watchdog -and task watchdog functionality will essentially be disabled. No warnings or -panics from either watchdogs will be generated when the ESP32 is connected to +and task watchdog functionality will essentially be disabled. No warnings or +panics from either watchdogs will be generated when the {IDF_TARGET_NAME} is connected to OpenOCD via JTAG. @@ -89,12 +89,12 @@ Interrupt Watchdog API Reference Header File ^^^^^^^^^^^ - * :component_file:`esp32/include/esp_int_wdt.h` + * :component_file:`{IDF_TARGET_PATH_NAME}/include/esp_int_wdt.h` Functions --------- - + .. doxygenfunction:: esp_int_wdt_init Task Watchdog API Reference diff --git a/docs/en/contribute/add-ons-reference.rst b/docs/en/contribute/add-ons-reference.rst index 30fedb8ede..d715c41701 100644 --- a/docs/en/contribute/add-ons-reference.rst +++ b/docs/en/contribute/add-ons-reference.rst @@ -119,7 +119,6 @@ Other Extensions :idf_file:`docs/idf_extensions/include_build_file.py` The ``include-build-file`` directive is like the built-in ``include-file`` directive, but file path is evaluated relative to ``build_dir``. - :idf_file:`docs/idf_extensions/kconfig_reference.py` Subscribes to ``idf-info`` event and uses confgen to generate ``kconfig.inc`` from the components included in the default project build. This file is then included into :doc:`/api-reference/kconfig`. @@ -147,6 +146,12 @@ Other Extensions :idf_file:`docs/idf_extensions/util.py` A collection of utility functions useful primarily when building documentation locally (see :ref:`setup-for-building-documentation`) to reduce the time to generate documentation on a second and subsequent builds. +:idf_file:`docs/idf_extensions/format_idf_target.py` + An extension for replacing generic target related names with the idf_target passed to the Sphinx command line. + This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` will, if the backspaces are removed, render as This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`. + + This cannot be used inside tables. + Related Documents ----------------- diff --git a/docs/en/get-started/establish-serial-connection.rst b/docs/en/get-started/establish-serial-connection.rst index 2b15682640..903cdea1e2 100644 --- a/docs/en/get-started/establish-serial-connection.rst +++ b/docs/en/get-started/establish-serial-connection.rst @@ -1,38 +1,39 @@ -Establish Serial Connection with ESP32 -============================================== +Establish Serial Connection with {IDF_TARGET_NAME} +================================================== :link_to_translation:`zh_CN:[中文]` -This section provides guidance how to establish serial connection between ESP32 and PC. +This section provides guidance how to establish serial connection between {IDF_TARGET_NAME} and PC. -Connect ESP32 to PC --------------------- +Connect {IDF_TARGET_NAME} 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. +Connect the {IDF_TARGET_NAME} board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your {IDF_TARGET_NAME} 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: +Below are the links to drivers for {IDF_TARGET_NAME} boards produced by Espressif: +.. only:: esp32 -.. csv-table:: - :header: Development Board, USB Driver, Remarks - :widths: 40, 20, 40 + .. csv-table:: + :header: Development Board, USB Driver, Remarks + :widths: 40, 20, 40 - :ref:`ESP32-DevKitC `, `CP210x`_ - `ESP32-LyraT `_, `CP210x`_ - `ESP32-LyraTD-MSC `_, `CP210x`_ - :ref:`ESP32-PICO-KIT `, `CP210x`_ - :ref:`ESP-WROVER-KIT `, `FTDI`_ - :ref:`ESP32 Demo Board `, `FTDI`_ - `ESP-Prog`_, `FTDI`_, Programmer board (w/o ESP32) - `ESP32-MeshKit-Sense `_, n/a, Use with `ESP-Prog`_ - `ESP32-Sense Kit `_, n/a, Use with `ESP-Prog`_ + :ref:`ESP32-DevKitC `, `CP210x`_ + `ESP32-LyraT `_, `CP210x`_ + `ESP32-LyraTD-MSC `_, `CP210x`_ + :ref:`ESP32-PICO-KIT `, `CP210x`_ + :ref:`ESP-WROVER-KIT `, `FTDI`_ + :ref:`ESP32 Demo Board `, `FTDI`_ + `ESP-Prog`_, `FTDI`_, Programmer board (w/o ESP32) + `ESP32-MeshKit-Sense `_, n/a, Use with `ESP-Prog`_ + `ESP32-Sense Kit `_, n/a, Use with `ESP-Prog`_ -.. _CP210x: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers -.. _FTDI: http://www.ftdichip.com/Drivers/VCP.htm -.. _ESP-Prog: https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP-Prog_guide_en.md#introduction-to-the-esp-prog-board + .. _CP210x: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers + .. _FTDI: http://www.ftdichip.com/Drivers/VCP.htm + .. _ESP-Prog: https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP-Prog_guide_en.md#introduction-to-the-esp-prog-board -* CP210x: `CP210x USB to UART Bridge VCP Drivers `_ +* CP210x: `CP210x USB to UART Bridge VCP Drivers `_ * FTDI: `FTDI Virtual COM Port Drivers `_ The drivers above are primarily for reference. Under normal circumstances, the drivers should be bundled with and operating system and automatically installed upon connecting one of the listed boards to the PC. @@ -41,7 +42,7 @@ The drivers above are primarily for reference. Under normal circumstances, the d 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. +Check the list of identified COM ports in the Windows Device Manager. Disconnect {IDF_TARGET_NAME} 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 @@ -63,7 +64,7 @@ Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT 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: +To check the device name for the serial port of your {IDF_TARGET_NAME} 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 :: @@ -91,7 +92,7 @@ on Arch Linux this is done by adding the user to ``uucp`` group with the followi sudo usermod -a -G uucp $USER -Make sure you re-login to enable read and write permissions for the serial port. +Make sure you re-login to enable read and write permissions for the serial port. Verify serial connection @@ -116,7 +117,7 @@ Run terminal, set identified serial port, baud rate = 115200, data bits = 8, sto 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. +Then open serial port in terminal and check, if you see any log printed out by {IDF_TARGET_NAME}. The log contents will depend on application loaded to {IDF_TARGET_NAME}. An example log by {IDF_TARGET_NAME} is shown below. .. highlight:: none @@ -141,16 +142,16 @@ Then open serial port in terminal and check, if you see any log printed out by E ... -If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32. +If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to {IDF_TARGET_NAME}. .. note:: - For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal program before the ESP32 will boot and produce serial output. This depends on the hardware itself, most development boards (including all Espressif boards) *do not* have this issue. The issue is present if RTS & DTR are wired directly to the EN & GPIO0 pins. See the `esptool documentation`_ for more details. + For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal program before the {IDF_TARGET_NAME} will boot and produce serial output. This depends on the hardware itself, most development boards (including all Espressif boards) *do not* have this issue. The issue is present if RTS & DTR are wired directly to the EN & GPIO0 pins. See the `esptool documentation`_ for more details. .. note:: - Close serial terminal after verification that communication is working. In the next step we are going to use a different application to upload a new firmware to ESP32. This application will not be able to access serial port while it is open in terminal. + Close serial terminal after verification that communication is working. In the next step we are going to use a different application to upload a new firmware to {IDF_TARGET_NAME}. This application will not be able to access serial port while it is open in terminal. -If you got here from :ref:`get-started-connect` when installing s/w for ESP32 development, then you can continue with :ref:`get-started-configure`. +If you got here from :ref:`get-started-connect` when installing s/w for {IDF_TARGET_NAME} development, then you can continue with :ref:`get-started-configure`. .. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index 23f04922a8..6adb9dc4c7 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -4,64 +4,76 @@ Get Started :link_to_translation:`zh_CN:[中文]` -This document is intended to help you set up the software development environment for the hardware based on the ESP32 chip by Espressif. +This document is intended to help you set up the software development environment for the hardware based on the {IDF_TARGET_NAME} chip by Espressif. -After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then building, and flashing firmware onto an ESP32 board. +After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then building, and flashing firmware onto an {IDF_TARGET_NAME} board. .. include-build-file:: inc/version-note.inc Introduction ============ -ESP32 is a system on a chip that integrates the following features: +..only:: esp32 -* Wi-Fi (2.4 GHz band) -* Bluetooth 4.2 -* Dual high performance cores -* Ultra Low Power co-processor -* Several peripherals + {IDF_TARGET_NAME} is a system on a chip that integrates the following features: -Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability. + * Wi-Fi (2.4 GHz band) + * Bluetooth 4.2 + * Dual high performance cores + * Ultra Low Power co-processor + * Several peripherals -Espressif provides basic hardware and software resources to help application developers realize their ideas using the ESP32 series hardware. The software development framework by Espressif is intended for development of Internet-of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features. +.. only:: esp32s2 + + {IDF_TARGET_NAME} is a system on a chip that integrates the following features: + + * Wi-Fi (2.4 GHz band) + * Ultra Low Power co-processor + * Several peripherals + +Powered by 40 nm technology, {IDF_TARGET_NAME} provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability. + +Espressif provides basic hardware and software resources to help application developers realize their ideas using the {IDF_TARGET_NAME} series hardware. The software development framework by Espressif is intended for development of Internet-of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features. What You Need ============= Hardware: -* An **ESP32** board +* An **{IDF_TARGET_NAME}** board * **USB cable** - USB A / micro USB B * **Computer** running Windows, Linux, or macOS Software: -* **Toolchain** to compile code for ESP32 -* **Build tools** - CMake and Ninja to build a full **Application** for ESP32 -* **ESP-IDF** that essentially contains API (software libraries and source code) for ESP32 and scripts to operate the **Toolchain** +* **Toolchain** to compile code for {IDF_TARGET_NAME} +* **Build tools** - CMake and Ninja to build a full **Application** for {IDF_TARGET_NAME} +* **ESP-IDF** that essentially contains API (software libraries and source code) for {IDF_TARGET_NAME} and scripts to operate the **Toolchain** * **Text editor** to write programs (**Projects**) in C, e.g., `Eclipse `_ .. figure:: ../../_static/what-you-need.png :align: center - :alt: Development of applications for ESP32 + :alt: Development of applications for {IDF_TARGET_NAME} :figclass: align-center - Development of applications for ESP32 + Development of applications for {IDF_TARGET_NAME} Development Board Overviews =========================== -If you have one of ESP32 development boards listed below, you can click on the link to learn more about its hardware. +If you have one of {IDF_TARGET_NAME} development boards listed below, you can click on the link to learn more about its hardware. -.. toctree:: - :maxdepth: 1 +.. only:: esp32 - ESP32-DevKitC <../hw-reference/get-started-devkitc> - ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> - ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> - ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> + .. toctree:: + :maxdepth: 1 + + ESP32-DevKitC <../hw-reference/get-started-devkitc> + ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> + ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> + ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> .. _get-started-step-by-step: @@ -128,7 +140,7 @@ Some tools need to be installed on the computer before proceeding to the next st Step 2. Get ESP-IDF =================== -To build applications for the ESP32, you need the software libraries provided by Espressif in `ESP-IDF repository `_. +To build applications for the {IDF_TARGET_NAME}, you need the software libraries provided by Espressif in `ESP-IDF repository `_. To get ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``, following instructions below specific to your operating system. @@ -239,7 +251,7 @@ You can also automate this step, making ESP-IDF tools available in every termina Step 5. Start a Project ======================= -Now you are ready to prepare your application for ESP32. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. +Now you are ready to prepare your application for {IDF_TARGET_NAME}. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. Copy :example:`get-started/hello_world` to ``~/esp`` directory: @@ -272,9 +284,9 @@ It is also possible to build examples in-place, without copying them first. Step 6. Connect Your Device =========================== -Now connect your ESP32 board to the computer and check under what serial port the board is visible. +Now connect your {IDF_TARGET_NAME} board to the computer and check under what serial port the board is visible. -Serial ports have the following patterns in their names: +Serial ports have the following patterns in their names: - **Windows**: names like ``COM1`` - **Linux**: starting with ``/dev/tty`` @@ -336,9 +348,11 @@ To navigate and use ``menuconfig``, press the following keys: * ``?`` while highlighting a configuration item to display help about that item * ``/`` to find configuration items -.. attention:: +.. only:: esp32 - If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples. + .. attention:: + + If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples. .. _get-started-build: @@ -361,12 +375,12 @@ This command will compile the application and all ESP-IDF components, then it wi -- Building empty aws_iot component due to configuration -- Component names: ... -- Component paths: ... - + ... (more lines of build system output) - + [527/527] Generating hello-world.bin esptool.py v2.3.1 - + Project build complete. To flash, run this command: ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin or run 'idf.py -p PORT flash' @@ -379,17 +393,17 @@ If there are no errors, the build will finish by generating the firmware binary Step 9. Flash onto the Device ============================= -Flash the binaries that you just built onto your ESP32 board by running:: +Flash the binaries that you just built onto your {IDF_TARGET_NAME} board by running:: idf.py -p PORT [-b BAUD] flash -Replace PORT with your ESP32 board's serial port name from :ref:`get-started-connect`. +Replace PORT with your {IDF_TARGET_NAME} board's serial port name from :ref:`get-started-connect`. You can also change the flasher baud rate by replacing BAUD with the baud rate you need. The default baud rate is ``460800``. For more information on idf.py arguments, see :ref:`idf.py`. -.. note:: +.. note:: The option ``flash`` automatically builds and flashes the project, so running ``idf.py build`` is not necessary. @@ -400,8 +414,8 @@ For more information on idf.py arguments, see :ref:`idf.py`. esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin esptool.py v2.3.1 Connecting.... - Detecting chip type... ESP32 - Chip is ESP32D0WDQ6 (revision 1) + Detecting chip type... {IDF_TARGET_NAME} + Chip is {IDF_TARGET_NAME}D0WDQ6 (revision 1) Features: WiFi, BT, Dual Core Uploading stub... Running stub... @@ -420,7 +434,7 @@ For more information on idf.py arguments, see :ref:`idf.py`. Compressed 136672 bytes to 67544... Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)... Hash of data verified. - + Leaving... Hard resetting via RTS pin... @@ -471,9 +485,9 @@ To exit IDF monitor use the shortcut ``Ctrl+]``. :align: center :alt: Garbled output :figclass: align-center - + If you have such a problem, do the following: - + 1. Exit the monitor. 2. Go back to :ref:`menuconfig `. 3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz. diff --git a/docs/en/get-started/linux-setup-scratch.rst b/docs/en/get-started/linux-setup-scratch.rst index 361b54499a..cd684a645d 100644 --- a/docs/en/get-started/linux-setup-scratch.rst +++ b/docs/en/get-started/linux-setup-scratch.rst @@ -66,22 +66,22 @@ Download ``crosstool-NG`` and build it: Build the toolchain:: - ./ct-ng xtensa-esp32-elf + ./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf ./ct-ng build - chmod -R u+w builds/xtensa-esp32-elf + chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf -Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. +Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``. Add Toolchain to PATH ===================== The custom toolchain needs to be copied to a binary directory and added to the ``PATH``. -Choose a directory, for example ``~/esp/xtensa-esp32-elf/``, and copy the build output to this directory. +Choose a directory, for example ``~/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/``, and copy the build output to this 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-{IDF_TARGET_TOOLCHAIN_NAME}-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="$HOME/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin:$PATH" .. note:: @@ -94,7 +94,7 @@ Log off and log in back to make the ``.profile`` changes effective. Run the foll You are looking for similar result containing toolchain's path at the beginning of displayed string:: $ printenv PATH - /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/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-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 Instead of ``/home/user-name`` there should be a home path specific to your installation. diff --git a/docs/en/get-started/linux-setup.rst b/docs/en/get-started/linux-setup.rst index e647b79764..b54a4820c7 100644 --- a/docs/en/get-started/linux-setup.rst +++ b/docs/en/get-started/linux-setup.rst @@ -30,7 +30,7 @@ Additional Tips 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`. +With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the {IDF_TARGET_NAME}. :ref:`This can be solved by adding the current user to the dialout group`. Next Steps ========== diff --git a/docs/en/get-started/macos-setup-scratch.rst b/docs/en/get-started/macos-setup-scratch.rst index e46ea346b8..e906b9fe78 100644 --- a/docs/en/get-started/macos-setup-scratch.rst +++ b/docs/en/get-started/macos-setup-scratch.rst @@ -73,11 +73,11 @@ Download ``crosstool-NG`` and build it: Build the toolchain:: - ./ct-ng xtensa-esp32-elf + ./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf ./ct-ng build - chmod -R u+w builds/xtensa-esp32-elf + chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf -Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` to ``PATH`` environment variable. +Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin`` to ``PATH`` environment variable. Next Steps diff --git a/docs/en/get-started/windows-setup-scratch.rst b/docs/en/get-started/windows-setup-scratch.rst index 3ff02717c3..fb542877f1 100644 --- a/docs/en/get-started/windows-setup-scratch.rst +++ b/docs/en/get-started/windows-setup-scratch.rst @@ -81,12 +81,12 @@ Download the precompiled Windows toolchain: |download_link_win32| -Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``. +Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``. -Next, the ``bin`` subdirectory of this directory must be :ref:`added to your Path `. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``. +Next, the ``bin`` subdirectory of this directory must be :ref:`added to your Path `. For example, the directory to add may be ``C:\Program Files\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin``. .. note:: - If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment. + If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment. .. _add-directory-windows-path: diff --git a/docs/en/hw-reference/index.rst b/docs/en/hw-reference/index.rst index acbd376d4d..2cf714b69b 100644 --- a/docs/en/hw-reference/index.rst +++ b/docs/en/hw-reference/index.rst @@ -1,16 +1,30 @@ -************************ -ESP32 Hardware Reference -************************ +************************************ +{IDF_TARGET_NAME} Hardware Reference +************************************ :link_to_translation:`zh_CN:[中文]` -.. toctree:: - :maxdepth: 3 +.. only:: esp32 - Technical Reference Manual (PDF) - Datasheet (PDF) - Hardware Design Guidelines (PDF) - Silicon Errata (PDF) - Modules and Boards - Previous Versions of Modules and Boards - Espressif Products Ordering Information (PDF) - Regulatory Certificates \ No newline at end of file + .. toctree:: + :maxdepth: 3 + + Technical Reference Manual (PDF) + Datasheet (PDF) + Hardware Design Guidelines (PDF) + Silicon Errata (PDF) + Modules and Boards + Previous Versions of Modules and Boards + Espressif Products Ordering Information (PDF) + Regulatory Certificates + +.. only:: esp32s2beta + + .. toctree:: + :maxdepth: 3 + + Technical Reference Manual (PDF) + Datasheet (PDF) + Modules and Boards + Previous Versions of Modules and Boards + Espressif Products Ordering Information (PDF) + Regulatory Certificates \ No newline at end of file diff --git a/docs/en/libraries-and-frameworks/cloud-frameworks.rst b/docs/en/libraries-and-frameworks/cloud-frameworks.rst index d58cf00589..407d945806 100644 --- a/docs/en/libraries-and-frameworks/cloud-frameworks.rst +++ b/docs/en/libraries-and-frameworks/cloud-frameworks.rst @@ -1,21 +1,21 @@ Cloud Frameworks ================ -ESP32 supports multiple cloud frameworks using agents built on top of ESP-IDF. Here are the pointers to various supported cloud frameworks' agents and examples: +{IDF_TARGET_NAME} supports multiple cloud frameworks using agents built on top of ESP-IDF. Here are the pointers to various supported cloud frameworks' agents and examples: AWS IoT ------- -`https://github.com/espressif/esp-aws-iot `_ is an open source repository for ESP32 based on Amazon Web Services' `aws-iot-device-sdk-embedded-C `_. +`https://github.com/espressif/esp-aws-iot `_ is an open source repository for {IDF_TARGET_NAME} based on Amazon Web Services' `aws-iot-device-sdk-embedded-C `_. Azure IoT --------- -`https://github.com/espressif/esp-azure `_ is an open source repository for ESP32 based on Microsoft Azure's `azure-iot-sdk-c SDK `_. +`https://github.com/espressif/esp-azure `_ is an open source repository for {IDF_TARGET_NAME} based on Microsoft Azure's `azure-iot-sdk-c SDK `_. -Google IoT Core +Google IoT Core --------------- -`https://github.com/espressif/esp-google-iot `_ is an open source repository for ESP32 based on Google's `iot-device-sdk-embedded-c SDK `_. +`https://github.com/espressif/esp-google-iot `_ is an open source repository for {IDF_TARGET_NAME} based on Google's `iot-device-sdk-embedded-c SDK `_. diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index 47749e03a3..f35ffbd706 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -4,14 +4,23 @@ Flash Encryption :link_to_translation:`zh_CN:[中文]` -This document provides introduction to Flash encryption concept on ESP32 and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `ESP32 Technical reference manual`_. +.. only:: esp32 + + This document provides introduction to Flash encryption concept on {IDF_TARGET_NAME} and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `ESP32 Technical reference manual`_. + + .. _ESP32 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf + +.. only:: esp32s2beta + + This document provides introduction to Flash encryption concept on {IDF_TARGET_NAME} and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `ESP32-S2 Technical reference manual`_. + + .. _ESP32-S2 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf -.. _ESP32 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf Introduction ------------ -Flash encryption is a feature for encrypting the contents of the ESP32's attached SPI flash. When flash encryption is enabled, physical readout of the SPI flash is not sufficient to recover most flash contents. Encryption is applied by flashing the ESP32 with plaintext data, and (if encryption is enabled) the bootloader encrypts the data in place on first boot. +Flash encryption is a feature for encrypting the contents of the {IDF_TARGET_NAME}'s attached SPI flash. When flash encryption is enabled, physical readout of the SPI flash is not sufficient to recover most flash contents. Encryption is applied by flashing the {IDF_TARGET_NAME} with plaintext data, and (if encryption is enabled) the bootloader encrypts the data in place on first boot. With flash encryption enabled, following kinds of flash data are encrypted by default: @@ -30,13 +39,13 @@ Flash encryption is separate from the :doc:`Secure Boot ` feature, For production use, flash encryption should be enabled in the "Release" mode only. .. important:: - Enabling flash encryption limits the options for further updates of the ESP32. Make sure to read this document (including :ref:`flash-encryption-limitations`) and understand the implications of enabling flash encryption. + Enabling flash encryption limits the options for further updates of the {IDF_TARGET_NAME}. Make sure to read this document (including :ref:`flash-encryption-limitations`) and understand the implications of enabling flash encryption. .. _flash-encryption-efuse: eFuse Used During Flash Encryption Process ------------------------------------------- -The flash encryption operation is controlled by various eFuses available on ESP32. Below is the list of eFuse and their description: +The flash encryption operation is controlled by various eFuses available on {IDF_TARGET_NAME}. Below is the list of eFuse and their description: :: @@ -79,7 +88,7 @@ The flash encryption operation is controlled by various eFuses available on ESP3 not encrypt flash at boot time -Read and write access to above bits is controlled by appropriate bits in ``efuse_wr_disable`` and ``efuse_rd_disable`` registers. More information about ESP32 eFuse can be found at :doc:`eFuse manager <../api-reference/system/efuse>`. +Read and write access to above bits is controlled by appropriate bits in ``efuse_wr_disable`` and ``efuse_rd_disable`` registers. More information about {IDF_TARGET_NAME} eFuse can be found at :doc:`eFuse manager <../api-reference/system/efuse>`. Flash Encryption Process @@ -96,7 +105,7 @@ Assuming the eFuse values are in default state and second stage bootloader is co - For :ref:`flash_enc_development_mode` second stage bootloader will program only ``download_dis_decrypt`` & ``download_dis_cache`` eFuse bits to allow UART bootloader reflashing of encrypted binaries. Also ``FLASH_CRYPT_CNT`` eFuse bits will NOT be write protected. - The second stage bootloader then reboots the device to start executing encrypted image. It will transparently decrypt the flash contents and load into IRAM. -During development stage there is a frequent need to program different plaintext flash images and test the flash encryption process. This requires UART download mode to be able to load new plaintext images as many number of times as required. However during manufacturing or production UART download mode should not be allowed to access flash contents due to security reason. Hence this requires two different ESP32 configurations: one for development and other for production. Following section describes :ref:`flash_enc_development_mode` and :ref:`flash_enc_release_mode` for flash encryption and a step by step process to use them. +During development stage there is a frequent need to program different plaintext flash images and test the flash encryption process. This requires UART download mode to be able to load new plaintext images as many number of times as required. However during manufacturing or production UART download mode should not be allowed to access flash contents due to security reason. Hence this requires two different {IDF_TARGET_NAME} configurations: one for development and other for production. Following section describes :ref:`flash_enc_development_mode` and :ref:`flash_enc_release_mode` for flash encryption and a step by step process to use them. .. important:: Development mode as the name suggests should be used ONLY DURING DEVELOPMENT as it does not prevent modification and possible read back of encrypted flash contents. @@ -110,16 +119,16 @@ Steps to Setup Flash Encryption Development Mode ^^^^^^^^^^^^^^^^ -It is possible to run flash encryption process for development using either ESP32 internally generated key or external host generated keys. +It is possible to run flash encryption process for development using either {IDF_TARGET_NAME} internally generated key or external host generated keys. -Using ESP32 Generated Flash Encryption Key -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Using {IDF_TARGET_NAME} Generated Flash Encryption Key +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As mentioned above :ref:`flash_enc_development_mode` allows user to download as many plaintext images using UART download mode. Following steps needs to be done to test flash encryption process: -- Ensure you have a ESP32 device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`. +- Ensure you have a {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`. -- Navigate to flash encryption sample application in ``$IDF_PATH/examples/security/flash_encryption`` folder. This sample application will print the status of flash encryption: enabled or disabled. It will print the ``FLASH_CRYPT_CNT`` eFuse value. +- Navigate to flash encryption sample application in ``$IDF_PATH/examples/security/flash_encryption`` folder. This sample application will print the status of flash encryption: enabled or disabled. It will print the ``FLASH_CRYPT_CNT`` eFuse value. - Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features". @@ -130,7 +139,7 @@ As mentioned above :ref:`flash_enc_development_mode` allows user to download as - Select appropriate Bootloader log verbosity under Bootloader config. - Update to the partition table offset may be required since after enabling flash encryption the size of bootloader is increased. See :ref:`secure-boot-bootloader-size` - + - Save the configuration and exit. Build and flash the complete image including: bootloader, partition table and app. These partitions are initially written to the flash unencrypted. @@ -139,7 +148,7 @@ Build and flash the complete image including: bootloader, partition table and ap idf.py flash monitor -Once the flashing is complete device will reset and on next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application would get decrypted at runtime and executed. Below is a sample output when ESP32 boots after flash encryption is enabled for the first time. +Once the flashing is complete device will reset and on next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application would get decrypted at runtime and executed. Below is a sample output when {IDF_TARGET_NAME} boots after flash encryption is enabled for the first time. :: @@ -190,20 +199,20 @@ Once the flashing is complete device will reset and on next boot second stage bo I (201) flash_encrypt: Disable UART bootloader MMU cache... I (208) flash_encrypt: Disable JTAG... I (212) flash_encrypt: Disable ROM BASIC interpreter fallback... - I (219) esp_image: segment 0: paddr=0x00001020 vaddr=0x3fff0018 size=0x00004 ( 4) - I (227) esp_image: segment 1: paddr=0x0000102c vaddr=0x3fff001c size=0x02104 ( 8452) - I (239) esp_image: segment 2: paddr=0x00003138 vaddr=0x40078000 size=0x03528 ( 13608) - I (249) esp_image: segment 3: paddr=0x00006668 vaddr=0x40080400 size=0x01a08 ( 6664) + I (219) esp_image: segment 0: paddr=0x00001020 vaddr=0x3fff0018 size=0x00004 ( 4) + I (227) esp_image: segment 1: paddr=0x0000102c vaddr=0x3fff001c size=0x02104 ( 8452) + I (239) esp_image: segment 2: paddr=0x00003138 vaddr=0x40078000 size=0x03528 ( 13608) + I (249) esp_image: segment 3: paddr=0x00006668 vaddr=0x40080400 size=0x01a08 ( 6664) I (657) esp_image: segment 0: paddr=0x00020020 vaddr=0x3f400020 size=0x0808c ( 32908) map - I (669) esp_image: segment 1: paddr=0x000280b4 vaddr=0x3ffb0000 size=0x01ea4 ( 7844) - I (672) esp_image: segment 2: paddr=0x00029f60 vaddr=0x40080000 size=0x00400 ( 1024) + I (669) esp_image: segment 1: paddr=0x000280b4 vaddr=0x3ffb0000 size=0x01ea4 ( 7844) + I (672) esp_image: segment 2: paddr=0x00029f60 vaddr=0x40080000 size=0x00400 ( 1024) 0x40080000: _WindowOverflow4 at esp-idf/esp-idf/components/freertos/xtensa_vectors.S:1778 - I (676) esp_image: segment 3: paddr=0x0002a368 vaddr=0x40080400 size=0x05ca8 ( 23720) + I (676) esp_image: segment 3: paddr=0x0002a368 vaddr=0x40080400 size=0x05ca8 ( 23720) I (692) esp_image: segment 4: paddr=0x00030018 vaddr=0x400d0018 size=0x126a8 ( 75432) map 0x400d0018: _flash_cache_start at ??:? - I (719) esp_image: segment 5: paddr=0x000426c8 vaddr=0x400860a8 size=0x01f4c ( 8012) + I (719) esp_image: segment 5: paddr=0x000426c8 vaddr=0x400860a8 size=0x01f4c ( 8012) 0x400860a8: prvAddNewTaskToReadyList at esp-idf/esp-idf/components/freertos/tasks.c:4561 I (722) flash_encrypt: Encrypting partition 2 at offset 0x20000... @@ -261,7 +270,7 @@ Once the flashing is complete device will reset and on next boot second stage bo I (211) cpu_start: ELF file SHA256: 8770c886bdf561a7... I (217) cpu_start: ESP-IDF: v4.0-dev-850-gc4447462d-dirty I (224) cpu_start: Starting app cpu, entry point is 0x40080e4c - 0x40080e4c: call_start_cpu1 at esp-idf/esp-idf/components/esp32/cpu_start.c:265 + 0x40080e4c: call_start_cpu1 at esp-idf/esp-idf/components/{IDF_TARGET_PATH_NAME}/cpu_start.c:265 I (0) cpu_start: App cpu up. I (235) heap_init: Initializing. RAM available for dynamic allocation: @@ -275,7 +284,7 @@ Once the flashing is complete device will reset and on next boot second stage bo I (0) cpu_start: Starting scheduler on APP CPU. Sample program to check Flash Encryption - This is ESP32 chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash + This is {IDF_TARGET_NAME} chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash Flash encryption feature is enabled Flash encryption mode is DEVELOPMENT Flash in encrypted mode with flash_crypt_cnt = 1 @@ -303,17 +312,17 @@ If all partitions needs to be updated in encrypted format, it can be done as Using Host Generated Flash Encryption Key ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -It is possible to pregenerate the flash encryption key on the host computer and burn it into the ESP32's eFuse key block. This allows data to be pre-encrypted on the host and flashed to the ESP32 without needing a plaintext flash update. This feature allows encrypted flashing in both :ref:`flash_enc_development_mode` and :ref:`flash_enc_release_mode` modes. +It is possible to pregenerate the flash encryption key on the host computer and burn it into the {IDF_TARGET_NAME}'s eFuse key block. This allows data to be pre-encrypted on the host and flashed to the {IDF_TARGET_NAME} without needing a plaintext flash update. This feature allows encrypted flashing in both :ref:`flash_enc_development_mode` and :ref:`flash_enc_release_mode` modes. .. note:: This option is not recommended for production unless a separate key is generated for each individual device. -- Ensure you have a ESP32 device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`. +- Ensure you have a {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`. - Generate a random key with espsecure.py:: espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin -- Burn the key to the device (one time only). **This must be done before first encrypted boot**, otherwise the ESP32 will generate a random key that software can't access or modify:: +- Burn the key to the device (one time only). **This must be done before first encrypted boot**, otherwise the {IDF_TARGET_NAME} will generate a random key that software can't access or modify:: espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin @@ -353,7 +362,7 @@ Release Mode In Release mode UART bootloader can not perform flash encryption operations and new plaintext images can be downloaded ONLY using OTA scheme which will encrypt the plaintext image before writing to flash. -- Ensure you have a ESP32 device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`. +- Ensure you have a {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`. - Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features". @@ -382,7 +391,7 @@ For subsequent plaintext update in field :ref:`OTA scheme ` for more details. @@ -489,7 +498,7 @@ Key Points About Flash Encryption .. note:: The bootloader app binary ``bootloader.bin`` may become too large when both secure boot and flash encryption are enabled. See :ref:`secure-boot-bootloader-size`. .. important:: - Do not interrupt power to the ESP32 while the first boot encryption pass is running. If power is interrupted, the flash contents will be corrupted and require flashing with unencrypted data again. A reflash like this will not count towards the flashing limit. + Do not interrupt power to the {IDF_TARGET_NAME} while the first boot encryption pass is running. If power is interrupted, the flash contents will be corrupted and require flashing with unencrypted data again. A reflash like this will not count towards the flashing limit. .. _using-encrypted-flash: @@ -497,7 +506,7 @@ Key Points About Flash Encryption Using Encrypted Flash --------------------- -ESP32 app code can check if flash encryption is currently enabled by calling :cpp:func:`esp_flash_encryption_enabled`. Also, device can identify the flash encryption mode by calling :cpp:func:`esp_get_flash_encryption_mode`. +{IDF_TARGET_NAME} app code can check if flash encryption is currently enabled by calling :cpp:func:`esp_flash_encryption_enabled`. Also, device can identify the flash encryption mode by calling :cpp:func:`esp_get_flash_encryption_mode`. Once flash encryption is enabled, some care needs to be taken when accessing flash contents from code. @@ -558,7 +567,7 @@ Please refer to :doc:`OTA <../api-reference/system/ota>` for general information Disabling Flash Encryption -------------------------- -If you've accidentally enabled flash encryption for some reason, the next flash of plaintext data will soft-brick the ESP32 (the device will reboot continuously, printing the error ``flash read err, 1000``). +If you've accidentally enabled flash encryption for some reason, the next flash of plaintext data will soft-brick the {IDF_TARGET_NAME} (the device will reboot continuously, printing the error ``flash read err, 1000``). If flash encryption is enabled in Development mode, you can disable flash encryption again by writing ``FLASH_CRYPT_CNT`` eFuse. This can only be done three times per chip. @@ -569,7 +578,7 @@ If flash encryption is enabled in Development mode, you can disable flash encryp - Run ``espefuse.py`` (in ``components/esptool_py/esptool``) to disable the FLASH_CRYPT_CNT:: espefuse.py burn_efuse FLASH_CRYPT_CNT -Reset the ESP32 and flash encryption should be disabled, the bootloader will boot as normal. +Reset the {IDF_TARGET_NAME} and flash encryption should be disabled, the bootloader will boot as normal. .. _flash-encryption-limitations: @@ -596,7 +605,7 @@ Flash Encryption and Secure Boot It is recommended to use flash encryption and secure boot together. However, if Secure Boot is enabled then additional restrictions apply to reflashing the device: - :ref:`updating-encrypted-flash-ota` are not restricted (provided the new app is signed correctly with the Secure Boot signing key). -- :ref:`Plaintext serial flash updates ` are only possible if the :ref:`Reflashable ` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :ref:`Secure Boot ` docs.). In this configuration, ``idf.py bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data. +- :ref:`Plaintext serial flash updates ` are only possible if the :ref:`Reflashable ` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the {IDF_TARGET_NAME} (refer to :ref:`Secure Boot ` docs.). In this configuration, ``idf.py bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data. - :ref:`Reflashing via Pregenerated Flash Encryption Key ` is still possible, provided the bootloader is not reflashed. Reflashing the bootloader requires the same :ref:`Reflashable ` option to be enabled in the Secure Boot config. .. _flash-encryption-advanced-features: diff --git a/docs/en/security/secure-boot.rst b/docs/en/security/secure-boot.rst index 6ff969d90b..e13b285a38 100644 --- a/docs/en/security/secure-boot.rst +++ b/docs/en/security/secure-boot.rst @@ -7,7 +7,7 @@ Secure Boot is separate from the :doc:`Flash Encryption ` feat .. 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. + Enabling secure boot limits your options for further updates of your {IDF_TARGET_NAME}. Make sure to read this document throughly and understand the implications of enabling secure boot. Background ---------- @@ -49,7 +49,17 @@ The following keys are used by the secure boot process: - "secure bootloader key" is a 256-bit AES key that is stored in Efuse block 2. The bootloader can generate this key itself from the internal hardware random number generator, the user does not need to supply it (it is optionally possible to supply this key, see :ref:`secure-boot-reflashable`). The Efuse holding this key is read & write protected (preventing software access) before secure boot is enabled. - - By default, the Efuse Block 2 Coding Scheme is "None" and a 256 bit key is stored in this block. On some ESP32s, the Coding Scheme is set to 3/4 Encoding (CODING_SCHEME efuse has value 1) and a 192 bit key must be stored in this block. See ESP32 Technical Reference Manual section 20.3.1.3 *System Parameter coding_scheme* for more details. The algorithm operates on a 256 bit key in all cases, 192 bit keys are extended by repeating some bits (:ref:`details`). + - By default, the Efuse Block 2 Coding Scheme is "None" and a 256 bit key is stored in this block. On some {IDF_TARGET_NAME}s, the Coding Scheme is set to 3/4 Encoding (CODING_SCHEME efuse has value 1) and a 192 bit key must be stored in this block. + + .. only:: esp32 + + See ESP32 Technical Reference Manual section 20.3.1.3 *System Parameter coding_scheme* for more details. + + .. only:: esp32s2 + + See ESP32-S2 Technical Reference Manual for more details. + + The algorithm operates on a 256 bit key in all cases, 192 bit keys are extended by repeating some bits (:ref:`details`). - "secure boot signing key" is a standard ECDSA public/private key pair (see :ref:`secure-boot-image-signing-algorithm`) in PEM format. @@ -64,7 +74,7 @@ Bootloader Size When secure boot is enabled the bootloader app binary ``bootloader.bin`` may exceed the default bootloader size limit. This is especially likely if flash encryption is enabled as well. The default size limit is 0x7000 (28672) bytes (partition table offset 0x8000 - bootloader offset 0x1000). -If the bootloader becomes too large, the ESP32 will fail to boot - errors will be logged about either invalid partition table or invalid bootloader checksum. +If the bootloader becomes too large, the {IDF_TARGET_NAME} will fail to boot - errors will be logged about either invalid partition table or invalid bootloader checksum. Options to work around this are: @@ -100,11 +110,11 @@ How To Enable Secure Boot .. note:: ``idf.py flash`` doesn't flash the bootloader if secure boot is enabled. -8. Reset the ESP32 and it will boot the software bootloader you flashed. The software bootloader will enable secure boot on the chip, and then it verifies the app image signature and boots the app. You should watch the serial console output from the ESP32 to verify that secure boot is enabled and no errors have occurred due to the build configuration. +8. Reset the {IDF_TARGET_NAME} and it will boot the software bootloader you flashed. The software bootloader will enable secure boot on the chip, and then it verifies the app image signature and boots the app. You should watch the serial console output from the {IDF_TARGET_NAME} to verify that secure boot is enabled and no errors have occurred due to the build configuration. .. note:: Secure boot won't be enabled until after a valid partition table and app image have been flashed. This is to prevent accidents before the system is fully configured. -.. note:: If the ESP32 is reset or powered down during the first boot, it will start the process again on the next boot. +.. note:: If the {IDF_TARGET_NAME} is reset or powered down during the first boot, it will start the process again on the next boot. 9. On subsequent boots, the secure boot hardware will verify the software bootloader has not changed (using the secure bootloader key) and then the software bootloader will verify the signed partition table and app image (using the public key portion of the secure boot signing key). @@ -194,7 +204,7 @@ The following sections contain low-level reference descriptions of various secur Secure Boot Hardware Support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The first stage of secure boot verification (checking the software bootloader) is done via hardware. The ESP32's Secure Boot support hardware can perform three basic operations: +The first stage of secure boot verification (checking the software bootloader) is done via hardware. The {IDF_TARGET_NAME}'s Secure Boot support hardware can perform three basic operations: 1. Generate a random sequence of bytes from a hardware random number generator. From e06a57f34fa36e132a78ce9ece3934da7cb86fca Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Mon, 9 Dec 2019 14:30:29 +0800 Subject: [PATCH 17/47] doc: Changed toc filter reg.ex to be non-greedy Stops the parsing from crashing when the content contains a ":", e.g. in web-links --- docs/extensions/toctree_filter.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/extensions/toctree_filter.py b/docs/extensions/toctree_filter.py index 2f537a5fea..8cdb13cdbf 100644 --- a/docs/extensions/toctree_filter.py +++ b/docs/extensions/toctree_filter.py @@ -24,12 +24,13 @@ class TocTreeFilt(TocTree): when it scan the src/ directory, so it's also necessary to make sure that the files are covered by the exclude_patterns list in conf.py """ - RE_PATTERN = re.compile(r'^\s*:(.+):\s*(.+)$') + RE_PATTERN = re.compile(r'^\s*:(.+?):\s*(.+)$') def run(self): # Remove all TOC entries that should not be on display env = self.state.document.settings.env self.content = [self.filter_entry(env, e) for e in self.content if e is not None] + return super(TocTreeFilt, self).run() def filter_entry(self, env, entry): From d56ea52ea1b336170d5f14a0ac6487d40f7345da Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Tue, 10 Dec 2019 11:58:00 +0800 Subject: [PATCH 18/47] doc: EN doc update and fixed warnings --- docs/conf_common.py | 3 +- docs/en/api-guides/external-ram.rst | 24 +- docs/en/api-guides/freertos-smp.rst | 4 +- docs/en/api-guides/jtag-debugging/index.rst | 2 +- .../jtag-debugging/tips-and-quirks.rst | 15 +- docs/en/api-reference/peripherals/adc.rst | 2 +- docs/en/api-reference/peripherals/rmt.rst | 2 +- docs/en/api-reference/system/mem_alloc.rst | 2 +- docs/en/contribute/add-ons-reference.rst | 2 +- docs/en/get-started/index.rst | 2 +- docs/en/hw-reference/index.rst | 34 +- .../modules-and-boards-previous.rst | 228 +++++------ docs/en/hw-reference/modules-and-boards.rst | 376 +++++++++--------- 13 files changed, 345 insertions(+), 351 deletions(-) diff --git a/docs/conf_common.py b/docs/conf_common.py index 0425b077b9..7fd6b83a64 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -133,8 +133,8 @@ def update_exclude_patterns(tags): 'api-guides/ulp-legacy.rst', 'api-guides/unit-tests-legacy.rst', 'api-guides/jtag-debugging/configure-wrover.rst', - 'api-reference/bluetooth/**', 'api-reference/system/himem.rst', + 'api-reference/bluetooth/**', 'api-reference/system/ipc.rst', 'hw-reference/get-started-devkitc-v2.rst', 'hw-reference/get-started-devkitc.rst', @@ -149,7 +149,6 @@ def update_exclude_patterns(tags): 'gnu-make-legacy.rst']: exclude_patterns.append(e) - # The reST default role (used for this markup: `text`) to use for all # documents. # default_role = None diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index 2771ded682..1c05be4a5f 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -19,20 +19,22 @@ Hardware The ESP-PSRAM32 chip is a 1.8 V device which can only be used in parallel with a 1.8 V flash component. Make sure to either set the MTDI pin to a high signal level on bootup, or program {IDF_TARGET_NAME} eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip. -To connect the ESP-PSRAM32 chip to ESP32D0W*, connect the following signals: +.. only:: esp32 - * PSRAM /CE (pin 1) > ESP32 GPIO 16 - * PSRAM SO (pin 2) > flash DO - * PSRAM SIO[2] (pin 3) > flash WP - * PSRAM SI (pin 5) > flash DI - * PSRAM SCLK (pin 6) > ESP32 GPIO 17 - * PSRAM SIO[3] (pin 7) > flash HOLD - * PSRAM Vcc (pin 8) > ESP32 VCC_SDIO + To connect the ESP-PSRAM32 chip to ESP32D0W*, connect the following signals: -Connections for ESP32D2W* chips are TBD. + * PSRAM /CE (pin 1) > ESP32 GPIO 16 + * PSRAM SO (pin 2) > flash DO + * PSRAM SIO[2] (pin 3) > flash WP + * PSRAM SI (pin 5) > flash DI + * PSRAM SCLK (pin 6) > ESP32 GPIO 17 + * PSRAM SIO[3] (pin 7) > flash HOLD + * PSRAM Vcc (pin 8) > ESP32 VCC_SDIO -.. NOTE:: - Espressif produces the line of ESP32-WROVER modules which contain ESP32, 1.8 V flash, and ESP-PSRAM32. These modules are ready to be mounted on an end product PCB. + Connections for ESP32D2W* chips are TBD. + + .. NOTE:: + Espressif produces the line of ESP32-WROVER modules which contain ESP32, 1.8 V flash, and ESP-PSRAM32. These modules are ready to be mounted on an end product PCB. .. _external_ram_config: diff --git a/docs/en/api-guides/freertos-smp.rst b/docs/en/api-guides/freertos-smp.rst index 5f99a88a02..1c01774715 100644 --- a/docs/en/api-guides/freertos-smp.rst +++ b/docs/en/api-guides/freertos-smp.rst @@ -64,7 +64,7 @@ to ESP-IDF. not done so already. Furthermore, ``float`` cannot be used in interrupt service routines. -:ref:`task-deletion`: Task deletion behavior has been backported from FreeRTOS +`Task Deletion`_: Task deletion behavior has been backported from FreeRTOS v9.0.0 and modified to be SMP compatible. Task memory will be freed immediately when :cpp:func:`vTaskDelete` is called to delete a task that is not currently running and not pinned to the other core. Otherwise, freeing of task memory will still @@ -461,7 +461,7 @@ occur. ESP-IDF FreeRTOS provides the added feature of Deletion Callbacks. Deletion Callbacks are called automatically during task deletion to free memory pointed to by TLSP. Each TLSP can have its own Deletion Callback. Note that due to the -to :ref:`task-deletion` behavior, there can be instances where Deletion +to `Task Deletion`_ behavior, there can be instances where Deletion Callbacks are called in the context of the Idle Tasks. Therefore Deletion Callbacks **should never attempt to block** and critical sections should be kept as short as possible to minimize priority inversion. diff --git a/docs/en/api-guides/jtag-debugging/index.rst b/docs/en/api-guides/jtag-debugging/index.rst index 8e32b02467..44eff3595c 100644 --- a/docs/en/api-guides/jtag-debugging/index.rst +++ b/docs/en/api-guides/jtag-debugging/index.rst @@ -150,7 +150,7 @@ Open a terminal and set it up for using the ESP-IDF as described in the :ref:`se .. note:: - The files provided after ``-f`` above are specific for ESP-WROVER-KIT with :ref:`esp-modules-and-boards-esp32-wroom-32` module. You may need to provide different files depending on used hardware. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`. + The files provided after ``-f`` above are specific for ESP-WROVER-KIT with esp32-wroom-32 module. You may need to provide different files depending on used hardware. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`. .. highlight:: none diff --git a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst index 88a56e75d0..c95ad6e2df 100644 --- a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst @@ -103,7 +103,7 @@ What is the meaning of debugger's startup commands? On startup, debugger is issuing sequence of commands to reset the chip and halt it at specific line of code. This sequence (shown below) is user defined to pick up at most convenient / appropriate line and start debugging. -* ``set remote hardware-watchpoint-limit 2`` — Restrict GDB to using two hardware watchpoints supported by the chip, 2 for ESP32. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html. +* ``set remote hardware-watchpoint-limit 2`` — Restrict GDB to using two hardware watchpoints supported by the chip, 2 for {IDF_TARGET_NAME}. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html. * ``mon reset halt`` — reset the chip and keep the CPUs halted * ``flushregs`` — monitor (``mon``) command can not inform GDB that the target state has changed. GDB will assume that whatever stack the target had before ``mon reset halt`` will still be valid. In fact, after reset the target state will change, and executing ``flushregs`` is a way to force GDB to get new state from the target. * ``thb app_main`` — insert a temporary hardware breakpoint at ``app_main``, put here another function name if required @@ -117,7 +117,7 @@ Configuration of OpenOCD for specific target OpenOCD needs to be told what JTAG adapter to use and processor the JTAG adapter is connected to. To do so, use existing **board** configuration files located in OpenOCD's ``share/openocd/scripts/board`` folder. -For example, if you connect to ESP-WROVER-KIT with ESP-WROOM-32 module installed (see section :ref:`esp-modules-and-boards-esp-wrover-kit-v1`), use the following configuration files: +For example, if you connect to ESP-WROVER-KIT with ESP-WROOM-32 module installed, use the following configuration files: * ``board/esp32-wrover-kit-3.3v.cfg`` @@ -135,15 +135,16 @@ Adapter's clock speed See :ref:`jtag-debugging-tip-optimize-jtag-speed` for guidance how to set this value. +.. only:: esp32 -Single core debugging -""""""""""""""""""""" + Single core debugging + """"""""""""""""""""" -:: + :: - set ESP32_ONLYCPU 1 + set ESP32_ONLYCPU 1 -Comment out this line for dual core debugging. + Comment out this line for dual core debugging. Disable RTOS support diff --git a/docs/en/api-reference/peripherals/adc.rst b/docs/en/api-reference/peripherals/adc.rst index 0dba625dc0..3fc65869b7 100644 --- a/docs/en/api-reference/peripherals/adc.rst +++ b/docs/en/api-reference/peripherals/adc.rst @@ -7,7 +7,7 @@ Overview The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register `_) ADCs supporting a total of 18 measurement channels (analog enabled pins). -..only:: esp32 +.. only:: esp32 The ADC driver API supports ADC1 (8 channels, attached to GPIOs 32 - 39), and ADC2 (10 channels, attached to GPIOs 0, 2, 4, 12 - 15 and 25 - 27). However, the usage of ADC2 has some restrictions for the application: diff --git a/docs/en/api-reference/peripherals/rmt.rst b/docs/en/api-reference/peripherals/rmt.rst index 005333a01d..9c6534cbf8 100644 --- a/docs/en/api-reference/peripherals/rmt.rst +++ b/docs/en/api-reference/peripherals/rmt.rst @@ -242,7 +242,7 @@ The RMT controller triggers interrupts on four specific events describes below. Setting or clearing an interrupt enable mask for specific channels and events may be also done by calling :cpp:func:`rmt_set_intr_enable_mask` or :cpp:func:`rmt_clr_intr_enable_mask`. -When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/{IDT_TARGET_PATH_NAME}/include/soc/rmt_struct.h`, where N is the RMT channel number [0, 7] and the ``event_name`` is one of four events described above. +When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_struct.h`, where N is the RMT channel number [0, 7] and the ``event_name`` is one of four events described above. If you do not need an ISR anymore, you can deregister it by calling a function :cpp:func:`rmt_isr_deregister`. diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst index 44512aa2c9..a288834d0a 100644 --- a/docs/en/api-reference/system/mem_alloc.rst +++ b/docs/en/api-reference/system/mem_alloc.rst @@ -105,7 +105,7 @@ External SPI Memory When :doc:`external RAM ` is enabled, external SPI RAM under 4MiB in size can be allocated using standard ``malloc`` calls, or via ``heap_caps_malloc(MALLOC_CAP_SPIRAM)``, depending on configuration. See :ref:`external_ram_config` for more details. -..only:: esp32 +.. only:: esp32 To use the region above the 4MiB limit, you can use the :doc:`himem API`. diff --git a/docs/en/contribute/add-ons-reference.rst b/docs/en/contribute/add-ons-reference.rst index d715c41701..2e3a1bcbe4 100644 --- a/docs/en/contribute/add-ons-reference.rst +++ b/docs/en/contribute/add-ons-reference.rst @@ -148,7 +148,7 @@ Other Extensions :idf_file:`docs/idf_extensions/format_idf_target.py` An extension for replacing generic target related names with the idf_target passed to the Sphinx command line. - This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` will, if the backspaces are removed, render as This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`. + This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` will, if the backspaces are removed, render as This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`. This cannot be used inside tables. diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index 6adb9dc4c7..e3ea9c76c3 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -13,7 +13,7 @@ After that, a simple example will show you how to use ESP-IDF (Espressif IoT Dev Introduction ============ -..only:: esp32 +.. only:: esp32 {IDF_TARGET_NAME} is a system on a chip that integrates the following features: diff --git a/docs/en/hw-reference/index.rst b/docs/en/hw-reference/index.rst index 2cf714b69b..9978049ee8 100644 --- a/docs/en/hw-reference/index.rst +++ b/docs/en/hw-reference/index.rst @@ -3,28 +3,16 @@ ************************************ :link_to_translation:`zh_CN:[中文]` -.. only:: esp32 - - .. toctree:: +.. toctree:: :maxdepth: 3 - Technical Reference Manual (PDF) - Datasheet (PDF) - Hardware Design Guidelines (PDF) - Silicon Errata (PDF) - Modules and Boards - Previous Versions of Modules and Boards - Espressif Products Ordering Information (PDF) - Regulatory Certificates - -.. only:: esp32s2beta - - .. toctree:: - :maxdepth: 3 - - Technical Reference Manual (PDF) - Datasheet (PDF) - Modules and Boards - Previous Versions of Modules and Boards - Espressif Products Ordering Information (PDF) - Regulatory Certificates \ No newline at end of file + :esp32: Technical Reference Manual (PDF) + :esp32s2beta: Technical Reference Manual (PDF) + :esp32: Datasheet (PDF) + :esp32s2beta: Datasheet (PDF) + :esp32: Hardware Design Guidelines (PDF) + :esp32: Silicon Errata (PDF) + Modules and Boards + Previous Versions of Modules and Boards + Espressif Products Ordering Information (PDF) + Regulatory Certificates diff --git a/docs/en/hw-reference/modules-and-boards-previous.rst b/docs/en/hw-reference/modules-and-boards-previous.rst index 7ac3d1571a..7128bf5c73 100644 --- a/docs/en/hw-reference/modules-and-boards-previous.rst +++ b/docs/en/hw-reference/modules-and-boards-previous.rst @@ -1,10 +1,10 @@ .. _esp-modules-and-boards-previous: -********************************************* -Previous Versions of ESP32 Modules and Boards -********************************************* +********************************************************* +Previous Versions of {IDF_TARGET_NAME} Modules and Boards +********************************************************* -This sections contains overview and links to documentation of previous version ESP32 Modules and Boards that have been replaced with newer versions or discontinued. It is maintained for convenience of users as previous versions of some modules and boards are still in use and some may still be available for purchase. +This sections contains overview and links to documentation of previous version {IDF_TARGET_NAME} Modules and Boards that have been replaced with newer versions or discontinued. It is maintained for convenience of users as previous versions of some modules and boards are still in use and some may still be available for purchase. Modules (No updated or discontinued modules) @@ -18,172 +18,174 @@ Development Boards To see the latest development boards, please refer to section :ref:`esp-modules-and-boards`. -.. _esp-modules-and-boards-esp32-pico-kit-v4: +.. only:: esp32 -ESP32-PICO-KIT V4 ------------------ + .. _esp-modules-and-boards-esp32-pico-kit-v4: -The smallest ESP32 development board with all the components required to connect it directly to a PC USB port, and pin headers to plug into a mini breadboard. It is equipped with ESP32-PICO-D4 module that integrates 4 MB flash memory, a crystal oscillator, filter capacitors and RF matching circuit in one single package. As result, the fully functional development board requires only a few external components that can easy fit on a 20 x 52 mm PCB including antenna, LDO, USB-UART bridge and two buttons to reset it and put into download mode. + ESP32-PICO-KIT V4 + ----------------- -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-pico-kit-v4.jpeg - :align: center - :alt: ESP32-PICO-KIT V4 board - :width: 50% + The smallest ESP32 development board with all the components required to connect it directly to a PC USB port, and pin headers to plug into a mini breadboard. It is equipped with ESP32-PICO-D4 module that integrates 4 MB flash memory, a crystal oscillator, filter capacitors and RF matching circuit in one single package. As result, the fully functional development board requires only a few external components that can easy fit on a 20 x 52 mm PCB including antenna, LDO, USB-UART bridge and two buttons to reset it and put into download mode. - ESP32-PICO-KIT V4 board + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-pico-kit-v4.jpeg + :align: center + :alt: ESP32-PICO-KIT V4 board + :width: 50% -Comparing to ESP32-PICO-KIT V3, this version has revised printout and reduced number of exposed pins. Instead of 20, only 17 header pins are populated, so V4 can fit into a mini breadboard. + ESP32-PICO-KIT V4 board -Documentation -^^^^^^^^^^^^^ + Comparing to ESP32-PICO-KIT V3, this version has revised printout and reduced number of exposed pins. Instead of 20, only 17 header pins are populated, so V4 can fit into a mini breadboard. -* :doc:`../hw-reference/get-started-pico-kit` -* `ESP32-PICO-KIT V4 Schematic `_ (PDF) -* `ESP32-PICO-D4 Datasheet `_ (PDF) + Documentation + ^^^^^^^^^^^^^ -.. _esp-modules-and-boards-esp32-pico-kit-v3: + * :doc:`../hw-reference/get-started-pico-kit` + * `ESP32-PICO-KIT V4 Schematic `_ (PDF) + * `ESP32-PICO-D4 Datasheet `_ (PDF) -ESP32-PICO-KIT V3 ------------------ + .. _esp-modules-and-boards-esp32-pico-kit-v3: -The first public release of Espressif's ESP32-PICO-D4 module on a mini development board. The board has a USB port for programming and debugging and two rows of 20 pin headers to plug into a breadboard. The ESP32-PICO-D4 module itself is small and requires only a few external components. Besides two core CPUs it integrates 4MB flash memory, a crystal oscillator and antenna matching components in one single 7 x 7 mm package. As a result the module and all the components making the complete development board fit into 20 x 52 mm PCB. + ESP32-PICO-KIT V3 + ----------------- -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-pico-kit-v3.jpeg - :align: center - :alt: ESP32-PICO-KIT V3 board - :width: 50% + The first public release of Espressif's ESP32-PICO-D4 module on a mini development board. The board has a USB port for programming and debugging and two rows of 20 pin headers to plug into a breadboard. The ESP32-PICO-D4 module itself is small and requires only a few external components. Besides two core CPUs it integrates 4MB flash memory, a crystal oscillator and antenna matching components in one single 7 x 7 mm package. As a result the module and all the components making the complete development board fit into 20 x 52 mm PCB. - ESP32-PICO-KIT V3 board + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-pico-kit-v3.jpeg + :align: center + :alt: ESP32-PICO-KIT V3 board + :width: 50% -Documentation -^^^^^^^^^^^^^ + ESP32-PICO-KIT V3 board -* :doc:`../hw-reference/get-started-pico-kit-v3` -* `ESP32-PICO-KIT V3 Schematic `_ (PDF) -* `ESP32-PICO-D4 Datasheet `_ (PDF) + Documentation + ^^^^^^^^^^^^^ + + * :doc:`../hw-reference/get-started-pico-kit-v3` + * `ESP32-PICO-KIT V3 Schematic `_ (PDF) + * `ESP32-PICO-D4 Datasheet `_ (PDF) -.. _esp-modules-and-boards-esp32-devkitc-v2: + .. _esp-modules-and-boards-esp32-devkitc-v2: -ESP32 Core Board V2 / ESP32 DevKitC ------------------------------------ + ESP32 Core Board V2 / ESP32 DevKitC + ----------------------------------- -Small and convenient development board with ESP-WROOM-32 module installed, break out pin headers and minimum additional components. Includes USB to serial programming interface, that also provides power supply for the board. Has pushbuttons to reset the board and put it in upload mode. + Small and convenient development board with ESP-WROOM-32 module installed, break out pin headers and minimum additional components. Includes USB to serial programming interface, that also provides power supply for the board. Has pushbuttons to reset the board and put it in upload mode. -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-core-board-v2.png - :align: center - :alt: ESP32 Core Board V2 / ESP32 DevKitC board - :width: 50% + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-core-board-v2.png + :align: center + :alt: ESP32 Core Board V2 / ESP32 DevKitC board + :width: 50% - ESP32 Core Board V2 / ESP32 DevKitC board + ESP32 Core Board V2 / ESP32 DevKitC board -Documentation -^^^^^^^^^^^^^ + Documentation + ^^^^^^^^^^^^^ -* :doc:`../hw-reference/get-started-devkitc-v2` -* `ESP32 DevKitC V2 Schematic `__ (PDF) -* `CP210x USB to UART Bridge VCP Drivers `_ + * :doc:`../hw-reference/get-started-devkitc-v2` + * `ESP32 DevKitC V2 Schematic `__ (PDF) + * `CP210x USB to UART Bridge VCP Drivers `_ -.. _esp-modules-and-boards-esp-wrover-kit-v3: + .. _esp-modules-and-boards-esp-wrover-kit-v3: -ESP-WROVER-KIT V3 ------------------ + ESP-WROVER-KIT V3 + ----------------- -The ESP-WROVER-KIT V3 development board 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. This board has MicroSD card slot, 3.2” SPI LCD screen and dedicated header to connect a camera. It provides RGB diode for diagnostics. Includes 32.768 kHz XTAL for internal RTC to operate it in low power modes. + The ESP-WROVER-KIT V3 development board 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. This board has MicroSD card slot, 3.2” SPI LCD screen and dedicated header to connect a camera. It provides RGB diode for diagnostics. Includes 32.768 kHz XTAL for internal RTC to operate it in low power modes. -As all previous versions of ESP-WROVER-KIT boards, it is ready to accommodate an :ref:`esp-modules-and-boards-esp32-wroom-32` or :ref:`esp-modules-and-boards-esp32-wrover` module. + As all previous versions of ESP-WROVER-KIT boards, it is ready to accommodate an :ref:`esp-modules-and-boards-esp32-wroom-32` or :ref:`esp-modules-and-boards-esp32-wrover` module. -This is the first release of ESP-WROVER-KIT shipped with :ref:`esp-modules-and-boards-esp32-wrover` module installed by default. This release also introduced several design changes to conditioning and interlocking of signals to the bootstrapping pins. Also, a zero Ohm resistor (R166) has been added between WROVER/WROOM module and VDD33 net, which can be desoldered, or replaced with a shunt resistor, for current measurement. This is intended to facilitate power consumption analysis in various operation modes of ESP32. Refer to schematic - the changes are enclosed in green border. + This is the first release of ESP-WROVER-KIT shipped with :ref:`esp-modules-and-boards-esp32-wrover` module installed by default. This release also introduced several design changes to conditioning and interlocking of signals to the bootstrapping pins. Also, a zero Ohm resistor (R166) has been added between WROVER/WROOM module and VDD33 net, which can be desoldered, or replaced with a shunt resistor, for current measurement. This is intended to facilitate power consumption analysis in various operation modes of ESP32. Refer to schematic - the changes are enclosed in green border. -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-wrover-kit-v3.jpg - :align: center - :alt: ESP-WROVER-KIT V3 board - :width: 90% + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-wrover-kit-v3.jpg + :align: center + :alt: ESP-WROVER-KIT V3 board + :width: 90% - ESP-WROVER-KIT V3 board + ESP-WROVER-KIT V3 board -The camera header has been changed from male back to female. The board soldermask is matte black. The board on picture above has :ref:`esp-modules-and-boards-esp32-wrover` is installed. + The camera header has been changed from male back to female. The board soldermask is matte black. The board on picture above has :ref:`esp-modules-and-boards-esp32-wrover` is installed. -Documentation -^^^^^^^^^^^^^ + Documentation + ^^^^^^^^^^^^^ -* :doc:`../hw-reference/get-started-wrover-kit-v3` -* `ESP-WROVER-KIT V3 Schematic `__ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* `FTDI Virtual COM Port Drivers`_ + * :doc:`../hw-reference/get-started-wrover-kit-v3` + * `ESP-WROVER-KIT V3 Schematic `__ (PDF) + * :doc:`../api-guides/jtag-debugging/index` + * `FTDI Virtual COM Port Drivers`_ -.. _esp-modules-and-boards-esp-wrover-kit-v2: + .. _esp-modules-and-boards-esp-wrover-kit-v2: -ESP-WROVER-KIT V2 ------------------ + ESP-WROVER-KIT V2 + ----------------- -This is updated version of ESP32 DevKitJ V1 described above with design improvements identified when DevKitJ was in use, e.g. improved support for SD card. By default board has ESP-WROOM-32 module installed. + This is updated version of ESP32 DevKitJ V1 described above with design improvements identified when DevKitJ was in use, e.g. improved support for SD card. By default board has ESP-WROOM-32 module installed. -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-wrover-kit-v2.jpg - :align: center - :alt: ESP-WROVER-KIT V2 board - :width: 90% + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-wrover-kit-v2.jpg + :align: center + :alt: ESP-WROVER-KIT V2 board + :width: 90% - ESP-WROVER-KIT V2 board + ESP-WROVER-KIT V2 board -Comparing to previous version, this board has a shiny black finish and a male camera header. + Comparing to previous version, this board has a shiny black finish and a male camera header. -Documentation -^^^^^^^^^^^^^ + Documentation + ^^^^^^^^^^^^^ -* :doc:`../hw-reference/get-started-wrover-kit-v2` -* `ESP-WROVER-KIT V2 Schematic `__ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* `FTDI Virtual COM Port Drivers`_ + * :doc:`../hw-reference/get-started-wrover-kit-v2` + * `ESP-WROVER-KIT V2 Schematic `__ (PDF) + * :doc:`../api-guides/jtag-debugging/index` + * `FTDI Virtual COM Port Drivers`_ -.. _esp-modules-and-boards-esp-wrover-kit-v1: + .. _esp-modules-and-boards-esp-wrover-kit-v1: -ESP-WROVER-KIT V1 / ESP32 DevKitJ V1 ------------------------------------- + ESP-WROVER-KIT V1 / ESP32 DevKitJ V1 + ------------------------------------ -The first version of ESP-WROVER-KIT development board. Shipped with ESP-WROOM-32 on board. + The first version of ESP-WROVER-KIT development board. Shipped with ESP-WROOM-32 on board. -ESP-WROVER-KIT 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. The board has MicroSD card slot, 3.2” SPI LCD screen and dedicated header to connect a camera. It provides RGB diode for diagnostics. Includes 32.768 kHz XTAL for internal RTC to operate it in low power modes. + ESP-WROVER-KIT 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. The board has MicroSD card slot, 3.2” SPI LCD screen and dedicated header to connect a camera. It provides RGB diode for diagnostics. Includes 32.768 kHz XTAL for internal RTC to operate it in low power modes. -All versions of ESP-WROVER-KIT are ready to accommodate an ESP-WROOM-32 or ESP32-WROVER module. + All versions of ESP-WROVER-KIT are ready to accommodate an ESP-WROOM-32 or ESP32-WROVER module. -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-devkitj-v1.jpg - :align: center - :alt: ESP-WROVER-KIT V1 / ESP32 DevKitJ V1 board - :width: 90% + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-devkitj-v1.jpg + :align: center + :alt: ESP-WROVER-KIT V1 / ESP32 DevKitJ V1 board + :width: 90% - ESP-WROVER-KIT V1 / ESP32 DevKitJ V1 board + ESP-WROVER-KIT V1 / ESP32 DevKitJ V1 board -The board has red soldermask. + The board has red soldermask. -Documentation -^^^^^^^^^^^^^ + Documentation + ^^^^^^^^^^^^^ -* `ESP-WROVER-KIT V1 Schematic `__ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* `FTDI Virtual COM Port Drivers`_ + * `ESP-WROVER-KIT V1 Schematic `__ (PDF) + * :doc:`../api-guides/jtag-debugging/index` + * `FTDI Virtual COM Port Drivers`_ -.. _esp-modules-and-boards-esp32-demo-board: - -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. - -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-demo-board-v2.jpg - :align: center - :alt: ESP32 Demo Board V2 + .. _esp-modules-and-boards-esp32-demo-board: ESP32 Demo Board V2 + ------------------- -Production of this board is discontinued. + 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. -Documentation -^^^^^^^^^^^^^ + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-demo-board-v2.jpg + :align: center + :alt: ESP32 Demo Board V2 -* `ESP32 Demo Board V2 Schematic `__ (PDF) -* `FTDI Virtual COM Port Drivers`_ + ESP32 Demo Board V2 + + Production of this board is discontinued. + + Documentation + ^^^^^^^^^^^^^ + + * `ESP32 Demo Board V2 Schematic `__ (PDF) + * `FTDI Virtual COM Port Drivers`_ Related Documents diff --git a/docs/en/hw-reference/modules-and-boards.rst b/docs/en/hw-reference/modules-and-boards.rst index 788b7a38a1..e784f387bd 100644 --- a/docs/en/hw-reference/modules-and-boards.rst +++ b/docs/en/hw-reference/modules-and-boards.rst @@ -1,12 +1,12 @@ .. _esp-modules-and-boards: -************************ -ESP32 Modules and Boards -************************ +************************************ +{IDF_TARGET_NAME} Modules and Boards +************************************ :link_to_translation:`zh_CN:[中文]` -Espressif designs and manufactures different modules and development boards to help users evaluate the potential of the ESP32 family of chips. +Espressif designs and manufactures different modules and development boards to help users evaluate the potential of the {IDF_TARGET_NAME} family of chips. This document provides description of modules and development boards currently available from Espressif. @@ -19,286 +19,288 @@ This document provides description of modules and development boards currently a Modules ======= -This is a family of ESP32-based modules with some integrated key components, including a crystal oscillator and an antenna matching circuit. The modules constitute ready-made solutions for integration into final products. If combined with a few extra components, such as a programming interface, bootstrapping resistors, and pin headers, these modules can also be used for evaluation of ESP32's functionality. +This is a family of {IDF_TARGET_NAME}-based modules with some integrated key components, including a crystal oscillator and an antenna matching circuit. The modules constitute ready-made solutions for integration into final products. If combined with a few extra components, such as a programming interface, bootstrapping resistors, and pin headers, these modules can also be used for evaluation of {IDF_TARGET_NAME}'s functionality. The key characteristics of these modules are summarized in the table below. Some additional details are covered in the following sections. -=================== ============ =========== ========= ==== =============== -Module Chip Flash, MB PSRAM, MB Ant. Dimensions, mm -=================== ============ =========== ========= ==== =============== -ESP32-WROOM-32 ESP32-D0WDQ6 4 -- MIFA 18 × 25.5 × 3.1 -ESP32-WROOM-32D ESP32-D0WD 4, 8, or 16 -- MIFA 18 × 25.5 × 3.1 -ESP32-WROOM-32U ESP32-D0WD 4, 8, or 16 -- U.FL 18 × 19.2 × 3.1 -ESP32-SOLO-1 ESP32-S0WD 4 -- MIFA 18 × 25.5 × 3.1 -ESP32-WROVER (PCB) ESP32-D0WDQ6 4 8 MIFA 18 × 31.4 × 3.3 -ESP32-WROVER (IPEX) ESP32-D0WDQ6 4 8 U.FL 18 × 31.4 × 3.3 -ESP32-WROVER-B ESP32-D0WD 4, 8, or 16 8 MIFA 18 × 31.4 × 3.3 -ESP32-WROVER-IB ESP32-D0WD 4, 8, or 16 8 U.FL 18 × 31.4 × 3.3 -=================== ============ =========== ========= ==== =============== +.. only:: esp32 -* ESP32-**D**.. identifies a dual-core chip, ESP32-**S**.. identifies a single-core chip -* MIFA - Meandered Inverted-F Antenna -* U.FL - U.FL / IPEX antenna connector -* ESP32-WROOM-32x, ESP32-WROVER-B and ESP32-WROVER-IB modules come with 4 MB flash by default but also available with custom flash sizes of 8 MB and 16 MB, see `Espressif Products Ordering Information`_ (PDF) -* `ESP32 Chip Datasheet `__ (PDF) -* Initial release of the ESP32-WROVER module had 4 MB of PSRAM -* *ESP32-WROOM-32* was previously called *ESP-WROOM-32* + =================== ============ =========== ========= ==== =============== + Module Chip Flash, MB PSRAM, MB Ant. Dimensions, mm + =================== ============ =========== ========= ==== =============== + ESP32-WROOM-32 ESP32-D0WDQ6 4 -- MIFA 18 × 25.5 × 3.1 + ESP32-WROOM-32D ESP32-D0WD 4, 8, or 16 -- MIFA 18 × 25.5 × 3.1 + ESP32-WROOM-32U ESP32-D0WD 4, 8, or 16 -- U.FL 18 × 19.2 × 3.1 + ESP32-SOLO-1 ESP32-S0WD 4 -- MIFA 18 × 25.5 × 3.1 + ESP32-WROVER (PCB) ESP32-D0WDQ6 4 8 MIFA 18 × 31.4 × 3.3 + ESP32-WROVER (IPEX) ESP32-D0WDQ6 4 8 U.FL 18 × 31.4 × 3.3 + ESP32-WROVER-B ESP32-D0WD 4, 8, or 16 8 MIFA 18 × 31.4 × 3.3 + ESP32-WROVER-IB ESP32-D0WD 4, 8, or 16 8 U.FL 18 × 31.4 × 3.3 + =================== ============ =========== ========= ==== =============== + * ESP32-**D**.. identifies a dual-core chip, ESP32-**S**.. identifies a single-core chip + * MIFA - Meandered Inverted-F Antenna + * U.FL - U.FL / IPEX antenna connector + * ESP32-WROOM-32x, ESP32-WROVER-B and ESP32-WROVER-IB modules come with 4 MB flash by default but also available with custom flash sizes of 8 MB and 16 MB, see `Espressif Products Ordering Information`_ (PDF) + * `ESP32 Chip Datasheet `__ (PDF) + * Initial release of the ESP32-WROVER module had 4 MB of PSRAM + * *ESP32-WROOM-32* was previously called *ESP-WROOM-32* -.. _esp-modules-and-boards-esp32-wroom-32: -ESP32-WROOM-32 --------------- + .. _esp-modules-and-boards-esp32-wroom-32: -This is a basic and commonly adopted ESP32 module with the ESP32-D0WDQ6 chip on board. It was the first module of the WROOM / WROVER family released to the market. + ESP32-WROOM-32 + -------------- -For key characteristics, see the table in Section :ref:`esp-wroom-solo-wrover-modules`, `Espressif Products Ordering Information`_. + This is a basic and commonly adopted ESP32 module with the ESP32-D0WDQ6 chip on board. It was the first module of the WROOM / WROVER family released to the market. + For key characteristics, see the table in Section :ref:`esp-wroom-solo-wrover-modules`, `Espressif Products Ordering Information`_. -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32-front-back.jpg - :align: center - :alt: ESP32-WROOM-32 module (front and back) - :width: 45% - ESP32-WROOM-32 module (front and back) + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32-front-back.jpg + :align: center + :alt: ESP32-WROOM-32 module (front and back) + :width: 45% -Documentation -^^^^^^^^^^^^^ + ESP32-WROOM-32 module (front and back) -* `ESP32-WROOM-32 Datasheet `__ (PDF) -* `ESP32-WROOM-32 Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files + Documentation + ^^^^^^^^^^^^^ + * `ESP32-WROOM-32 Datasheet `__ (PDF) + * `ESP32-WROOM-32 Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files -.. _esp-modules-and-boards-esp32-wroom-32d-and-u: -ESP32-WROOM-32D / ESP32-WROOM-32U ---------------------------------- + .. _esp-modules-and-boards-esp32-wroom-32d-and-u: -Both modules integrate the ESP32-D0WD chip which has a smaller footprint than the chip ESP32-D0WDQ6 installed in :ref:`esp-modules-and-boards-esp32-wroom-32`. + ESP32-WROOM-32D / ESP32-WROOM-32U + --------------------------------- -For key characteristics, see the table in Section :ref:`esp-wroom-solo-wrover-modules` and `Espressif Products Ordering Information`_. + Both modules integrate the ESP32-D0WD chip which has a smaller footprint than the chip ESP32-D0WDQ6 installed in :ref:`esp-modules-and-boards-esp32-wroom-32`. -ESP32-WROOM-32U is the smallest representative of the whole WROOM / WROVER family of modules. + For key characteristics, see the table in Section :ref:`esp-wroom-solo-wrover-modules` and `Espressif Products Ordering Information`_. -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32d-front-back.jpg - :align: center - :alt: ESP32-WROOM-32D module (front and back) - :width: 45% + ESP32-WROOM-32U is the smallest representative of the whole WROOM / WROVER family of modules. - ESP32-WROOM-32D module (front and back) + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32d-front-back.jpg + :align: center + :alt: ESP32-WROOM-32D module (front and back) + :width: 45% -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32u-front-back.jpg - :align: center - :alt: ESP32-WROOM-32U module (front and back) - :width: 45% + ESP32-WROOM-32D module (front and back) - ESP32-WROOM-32U module (front and back) + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32u-front-back.jpg + :align: center + :alt: ESP32-WROOM-32U module (front and back) + :width: 45% -Documentation -^^^^^^^^^^^^^ + ESP32-WROOM-32U module (front and back) -* `ESP32-WROOM-32D / ESP32-WROOM-32U Datasheet `__ (PDF) + Documentation + ^^^^^^^^^^^^^ + * `ESP32-WROOM-32D / ESP32-WROOM-32U Datasheet `__ (PDF) -.. _esp-modules-and-boards-esp32-solo-1: -ESP32-SOLO-1 ------------- + .. _esp-modules-and-boards-esp32-solo-1: -This is a simplified version of the ESP32-WROOM-32D module. It contains a single-core ESP32 chip that supports a clock frequency of up to 160 MHz. + ESP32-SOLO-1 + ------------ -For key characteristics, see the table in Section :ref:`esp-wroom-solo-wrover-modules` and `Espressif Products Ordering Information`_. + This is a simplified version of the ESP32-WROOM-32D module. It contains a single-core ESP32 chip that supports a clock frequency of up to 160 MHz. -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-solo-1-front-back.jpg - :align: center - :alt: ESP32-SOLO-1 module (front and back) - :width: 45% + For key characteristics, see the table in Section :ref:`esp-wroom-solo-wrover-modules` and `Espressif Products Ordering Information`_. - ESP32-SOLO-1 module (front and back) + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-solo-1-front-back.jpg + :align: center + :alt: ESP32-SOLO-1 module (front and back) + :width: 45% + ESP32-SOLO-1 module (front and back) -Documentation -^^^^^^^^^^^^^ -* `ESP32-SOLO-1 Datasheet `__ (PDF) + Documentation + ^^^^^^^^^^^^^ + * `ESP32-SOLO-1 Datasheet `__ (PDF) -.. _esp-modules-and-boards-esp32-wrover: -ESP32-WROVER series -------------------- + .. _esp-modules-and-boards-esp32-wrover: -This series consists of a few modifications of ESP32-WROOM-32x modules, which among other upgrades include additional 8 MB SPI PSRAM (pseudo static RAM). + ESP32-WROVER series + ------------------- -For details, see the table in Section :ref:`esp-wroom-solo-wrover-modules` and `Espressif Products Ordering Information`_. + This series consists of a few modifications of ESP32-WROOM-32x modules, which among other upgrades include additional 8 MB SPI PSRAM (pseudo static RAM). -* **ESP32-WROVER (PCB)** and **ESP32-WROVER (IPEX)** have PSRAM that operates at 1.8 V and supports up to 144 MHz clock rate. -* **ESP32-WROVER-B** and **ESP32-WROVER-IB** have PSRAM that operates at 3.3 V and supports up to 133 MHz clock rate. + For details, see the table in Section :ref:`esp-wroom-solo-wrover-modules` and `Espressif Products Ordering Information`_. -The picture below shows an ESP32-WROVER module with a PCB antenna. + * **ESP32-WROVER (PCB)** and **ESP32-WROVER (IPEX)** have PSRAM that operates at 1.8 V and supports up to 144 MHz clock rate. + * **ESP32-WROVER-B** and **ESP32-WROVER-IB** have PSRAM that operates at 3.3 V and supports up to 133 MHz clock rate. -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wrover.jpg - :align: center - :alt: ESP32-WROVER module (front and back) - :width: 40% + The picture below shows an ESP32-WROVER module with a PCB antenna. - ESP32-WROVER module (front and back) + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wrover.jpg + :align: center + :alt: ESP32-WROVER module (front and back) + :width: 40% -Documentation -^^^^^^^^^^^^^ + ESP32-WROVER module (front and back) -* `ESP32-WROVER Datasheet `__ (PDF) -* `ESP32-WROVER-B Datasheet `__ (PDF) -* `ESP-PSRAM64 & ESP-PSRAM64H Datasheet `__ (PDF) -* `ESP32-WROVER Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files + Documentation + ^^^^^^^^^^^^^ + * `ESP32-WROVER Datasheet `__ (PDF) + * `ESP32-WROVER-B Datasheet `__ (PDF) + * `ESP-PSRAM64 & ESP-PSRAM64H Datasheet `__ (PDF) + * `ESP32-WROVER Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files -ESP32-PICO-D4 -------------- -ESP32-PICO-D4 is a System-in-Package (SiP) module, integrating all peripheral components seamlessly, including the following: + ESP32-PICO-D4 + ------------- -- 4 MB flash memory -- crystal oscillator -- filter capacitors -- RF matching circuit + ESP32-PICO-D4 is a System-in-Package (SiP) module, integrating all peripheral components seamlessly, including the following: -For key characteristics, see `Espressif Products Ordering Information`_. + - 4 MB flash memory + - crystal oscillator + - filter capacitors + - RF matching circuit + For key characteristics, see `Espressif Products Ordering Information`_. -Documentation -^^^^^^^^^^^^^ -* `ESP32-PICO-D4 Datasheet `__ (PDF) + Documentation + ^^^^^^^^^^^^^ + * `ESP32-PICO-D4 Datasheet `__ (PDF) -Development Boards -================== -Depending on the intended functionality, different development boards feature: + Development Boards + ================== -- Access to different ESP32 GPIO pins. -- Different interfaces: USB, JTAG. -- Different peripherals: touchpads, LCD screens, SD card slots, female headers for camera modules, etc. + Depending on the intended functionality, different development boards feature: -.. _esp-modules-and-boards-esp32-pico-kit: + - Access to different ESP32 GPIO pins. + - Different interfaces: USB, JTAG. + - Different peripherals: touchpads, LCD screens, SD card slots, female headers for camera modules, etc. -ESP32-PICO-KIT V4.1 -------------------- + .. _esp-modules-and-boards-esp32-pico-kit: -This is the smallest available ESP32-based development board. It features all the components for direct connection to a computer's USB port as well as pin headers for plugging into a mini breadboard. + ESP32-PICO-KIT V4.1 + ------------------- -The board is equipped with the `ESP32-PICO-D4`_ module. With such a module, the creation of a fully functional development board required only a few external components that fit on a PCB as small as 20 x 52 mm. The external components include antenna, LDO, USB-UART bridge, and two buttons for reset and activation of Firmware Download mode. + This is the smallest available ESP32-based development board. It features all the components for direct connection to a computer's USB port as well as pin headers for plugging into a mini breadboard. -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-pico-kit-v4.1.jpg - :align: center - :alt: ESP32-PICO-KIT V4.1 board - :width: 50% + The board is equipped with the `ESP32-PICO-D4`_ module. With such a module, the creation of a fully functional development board required only a few external components that fit on a PCB as small as 20 x 52 mm. The external components include antenna, LDO, USB-UART bridge, and two buttons for reset and activation of Firmware Download mode. - ESP32-PICO-KIT V4.1 board + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-pico-kit-v4.1.jpg + :align: center + :alt: ESP32-PICO-KIT V4.1 board + :width: 50% -Comparing to ESP32-PICO-KIT V4, this version features the CP2102N USB-UART bridge that provides faster transfer rates of up to 3 Mbps. + ESP32-PICO-KIT V4.1 board -Documentation -^^^^^^^^^^^^^ + Comparing to ESP32-PICO-KIT V4, this version features the CP2102N USB-UART bridge that provides faster transfer rates of up to 3 Mbps. -* :doc:`../hw-reference/get-started-pico-kit` -* `ESP32-PICO-KIT V4.1 Schematic `_ (PDF) -* `ESP32-PICO-KIT Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files -* `ESP32-PICO-D4 Datasheet `_ (PDF) + Documentation + ^^^^^^^^^^^^^ -Previous Versions -^^^^^^^^^^^^^^^^^ + * :doc:`../hw-reference/get-started-pico-kit` + * `ESP32-PICO-KIT V4.1 Schematic `_ (PDF) + * `ESP32-PICO-KIT Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files + * `ESP32-PICO-D4 Datasheet `_ (PDF) -* :ref:`esp-modules-and-boards-esp32-pico-kit-v4` -* :ref:`esp-modules-and-boards-esp32-pico-kit-v3` + Previous Versions + ^^^^^^^^^^^^^^^^^ + * :ref:`esp-modules-and-boards-esp32-pico-kit-v4` + * :ref:`esp-modules-and-boards-esp32-pico-kit-v3` -.. _esp-modules-and-boards-esp32-devkitc: - -ESP32 DevKitC V4 ----------------- -This is a small and convenient development board that features: + .. _esp-modules-and-boards-esp32-devkitc: -- :ref:`esp-modules-and-boards-esp32-wroom-32` module -- USB-to-serial programming interface that also provides power supply for the board -- pin headers -- pushbuttons for reset and activation of Firmware Download mode -- a few other components + ESP32 DevKitC V4 + ---------------- -Comparing to the previous :ref:`esp-modules-and-boards-esp32-devkitc-v2`, this version can integrate :ref:`esp-modules-and-boards-esp32-wrover` module instead of ESP32-WROOM-32 and has the CP2102N chip that supports faster baud rates. + This is a small and convenient development board that features: -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-devkitc-v4-front.jpg - :align: center - :alt: ESP32 DevKitC V4 board - :width: 50% + - :ref:`esp-modules-and-boards-esp32-wroom-32` module + - USB-to-serial programming interface that also provides power supply for the board + - pin headers + - pushbuttons for reset and activation of Firmware Download mode + - a few other components - ESP32 DevKitC V4 board + Comparing to the previous :ref:`esp-modules-and-boards-esp32-devkitc-v2`, this version can integrate :ref:`esp-modules-and-boards-esp32-wrover` module instead of ESP32-WROOM-32 and has the CP2102N chip that supports faster baud rates. -Documentation -^^^^^^^^^^^^^ + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-devkitc-v4-front.jpg + :align: center + :alt: ESP32 DevKitC V4 board + :width: 50% -* :doc:`../hw-reference/get-started-devkitc` -* `ESP32-DevKitC schematic `_ (PDF) -* `ESP32-DevKitC Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files -* `CP210x USB to UART Bridge VCP Drivers `_ + ESP32 DevKitC V4 board -Previous Versions -^^^^^^^^^^^^^^^^^ + Documentation + ^^^^^^^^^^^^^ -* :ref:`esp-modules-and-boards-esp32-devkitc-v2` + * :doc:`../hw-reference/get-started-devkitc` + * `ESP32-DevKitC schematic `_ (PDF) + * `ESP32-DevKitC Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files + * `CP210x USB to UART Bridge VCP Drivers `_ + Previous Versions + ^^^^^^^^^^^^^^^^^ -.. _esp-modules-and-boards-esp-wrover-kit: + * :ref:`esp-modules-and-boards-esp32-devkitc-v2` -ESP-WROVER-KIT V4.1 -------------------- -This board features: + .. _esp-modules-and-boards-esp-wrover-kit: -- Dual port USB-to-serial converter for programming -- JTAG interface for debugging -- MicroSD card slot -- 3.2” SPI LCD screen -- Female headers for a camera module -- RGB LED for diagnostics -- 32.768 kHz XTAL for internal RTC to operate it in low power modes + ESP-WROVER-KIT V4.1 + ------------------- -Power can be supplied either via USB or via a standard 5 mm power supply jack. A power source can be selected with a jumper and can be turned on/off with a separate switch. + This board features: -This version of the ESP-WROVER-KIT board integrates the ESP-WROVER-B module that has 8 MB PSRAM for flexible extended storage and data processing capabilities. The board can accommodate other versions of ESP modules described in :ref:`esp-wroom-solo-wrover-modules`. + - Dual port USB-to-serial converter for programming + - JTAG interface for debugging + - MicroSD card slot + - 3.2” SPI LCD screen + - Female headers for a camera module + - RGB LED for diagnostics + - 32.768 kHz XTAL for internal RTC to operate it in low power modes -Comparing to :ref:`esp-modules-and-boards-esp-wrover-kit-v3`, this board has the following design changes: + Power can be supplied either via USB or via a standard 5 mm power supply jack. A power source can be selected with a jumper and can be turned on/off with a separate switch. -- JP8, JP11, and JP13 have been combined into a single JP2. -- USB connector has been changed to DIP type and moved to the lower right corner of the board. -- R61 has been changed to a Zero-ohm resistor. -- Some components have been replaced with functional equivalents based on test results and sourcing options, e.g., the EN and Boot buttons. + This version of the ESP-WROVER-KIT board integrates the ESP-WROVER-B module that has 8 MB PSRAM for flexible extended storage and data processing capabilities. The board can accommodate other versions of ESP modules described in :ref:`esp-wroom-solo-wrover-modules`. -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-wrover-kit-v4.1-front.jpg - :align: center - :alt: ESP-WROVER-KIT V4.1 board - :width: 90% + Comparing to :ref:`esp-modules-and-boards-esp-wrover-kit-v3`, this board has the following design changes: - ESP-WROVER-KIT V4.1 board + - JP8, JP11, and JP13 have been combined into a single JP2. + - USB connector has been changed to DIP type and moved to the lower right corner of the board. + - R61 has been changed to a Zero-ohm resistor. + - Some components have been replaced with functional equivalents based on test results and sourcing options, e.g., the EN and Boot buttons. -The board in the picture above integrates the ESP32-WROVER-B module. + .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-wrover-kit-v4.1-front.jpg + :align: center + :alt: ESP-WROVER-KIT V4.1 board + :width: 90% -Documentation -^^^^^^^^^^^^^ + ESP-WROVER-KIT V4.1 board -* :doc:`../hw-reference/get-started-wrover-kit` -* `ESP-WROVER-KIT V4.1 Schematic `__ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* `FTDI Virtual COM Port Drivers`_ + The board in the picture above integrates the ESP32-WROVER-B module. -Previous Versions -^^^^^^^^^^^^^^^^^ + Documentation + ^^^^^^^^^^^^^ -* :ref:`esp-modules-and-boards-esp-wrover-kit-v3` -* :ref:`esp-modules-and-boards-esp-wrover-kit-v2` -* :ref:`esp-modules-and-boards-esp-wrover-kit-v1` + * :doc:`../hw-reference/get-started-wrover-kit` + * `ESP-WROVER-KIT V4.1 Schematic `__ (PDF) + * :doc:`../api-guides/jtag-debugging/index` + * `FTDI Virtual COM Port Drivers`_ + + Previous Versions + ^^^^^^^^^^^^^^^^^ + + * :ref:`esp-modules-and-boards-esp-wrover-kit-v3` + * :ref:`esp-modules-and-boards-esp-wrover-kit-v2` + * :ref:`esp-modules-and-boards-esp-wrover-kit-v1` Related Documents From a7bac4721a8cf6a6215e52b9dc6534e61b79a6d7 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Tue, 10 Dec 2019 12:54:13 +0800 Subject: [PATCH 19/47] doc: Add external ram note link to CN translation --- docs/en/api-guides/wifi.rst | 2 +- docs/zh_CN/api-guides/external-ram.rst | 25 ++++++++++--------- .../inc/external-ram-esp32-notes.rst | 1 + 3 files changed, 15 insertions(+), 13 deletions(-) create mode 100644 docs/zh_CN/api-guides/inc/external-ram-esp32-notes.rst diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index 140c61b69b..3e675aed80 100644 --- a/docs/en/api-guides/wifi.rst +++ b/docs/en/api-guides/wifi.rst @@ -412,7 +412,7 @@ Below is a "big scenario" which describes some small scenarios in AP mode: {IDF_TARGET_NAME} Wi-Fi Scan ------------------------- +---------------------------- Currently, the esp_wifi_scan_start() API is supported only in Station or Station+AP mode. diff --git a/docs/zh_CN/api-guides/external-ram.rst b/docs/zh_CN/api-guides/external-ram.rst index aaa6710fb2..986484e4ac 100644 --- a/docs/zh_CN/api-guides/external-ram.rst +++ b/docs/zh_CN/api-guides/external-ram.rst @@ -9,19 +9,19 @@ 简介 ============ -ESP32 提供了 520 KB 的片上 SRAM，可以满足大部分需求。但有些场景可能需要更多 RAM，因此 ESP32 另外提供了高达 4 MB 的片外 SPI RAM 存储器以供用户使用。片外 RAM 被添加到内存映射中，在某些范围内与片上 RAM 使用方式相同。 +{IDF_TARGET_NAME} 提供了 520 KB 的片上 SRAM，可以满足大部分需求。但有些场景可能需要更多 RAM，因此 {IDF_TARGET_NAME} 另外提供了高达 4 MB 的片外 SPI RAM 存储器以供用户使用。片外 RAM 被添加到内存映射中，在某些范围内与片上 RAM 使用方式相同。 硬件 ======== -ESP32 支持与 SPI Flash 芯片并联的 SPI PSRAM。ESP32 支持多种类型的 RAM 芯片，但 ESP32 SDK 当前仅支持 ESP-PSRAM32 芯片。 +{IDF_TARGET_NAME} 支持与 SPI Flash 芯片并联的 SPI PSRAM。{IDF_TARGET_NAME} 支持多种类型的 RAM 芯片，但 {IDF_TARGET_NAME} SDK 当前仅支持 ESP-PSRAM32 芯片。 -ESP-PSRAM32 芯片的工作电压为 1.8 V，只能与 1.8 V flash 并联使用。请确保在启动时将 MTDI 管脚设置为高电平，或者将 ESP32 中的熔丝设置为始终使用 1.8 V 的 VDD_SIO 电平，否则有可能会损坏 PSRAM 和/或 flash 芯片。 +ESP-PSRAM32 芯片的工作电压为 1.8 V，只能与 1.8 V flash 并联使用。请确保在启动时将 MTDI 管脚设置为高电平，或者将 {IDF_TARGET_NAME} 中的熔丝设置为始终使用 1.8 V 的 VDD_SIO 电平，否则有可能会损坏 PSRAM 和/或 flash 芯片。 要将 ESP-PSRAM 芯片连接到 ESP32D0W*，请连接以下信号： * PSRAM /CE (pin 1) > ESP32 GPIO 16 * PSRAM SO (pin 2) > flash DO - * PSRAM SIO[2] (pin 3) > flash WP + * PSRAM SIO[2] (pin 3) > flash WP * PSRAM SI (pin 5) > flash DI * PSRAM SCLK (pin 6) > ESP32 GPIO 17 * PSRAM SIO[3] (pin 7) > flash HOLD @@ -46,10 +46,10 @@ ESP-IDF 完全支持将外部存储器集成到您的应用程序中。您可以 .. _external_ram_config_memory_map: -集成片外 RAM 到 ESP32 内存映射 +集成片外 RAM 到 {IDF_TARGET_NAME} 内存映射 ----------------------------------- -在 :ref:`CONFIG_SPIRAM_USE` 中选择 "Integrate RAM into ESP32 memory map（集成片外 RAM 到 ESP32 内存映射）" 选项。 +在 :ref:`CONFIG_SPIRAM_USE` 中选择 "Integrate RAM into {IDF_TARGET_NAME} memory map（集成片外 RAM 到 {IDF_TARGET_NAME} 内存映射）" 选项。 这是集成片外 RAM 最基础的设置选项，大多数用户需要用到其他更高级的选项。 @@ -62,24 +62,24 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据 添加片外 RAM 到内存分配程序 -------------------------------------------- -在 :ref:`CONFIG_SPIRAM_USE` 中选择 "Make RAM allocatable using heap_caps_malloc(..., MALLOC_CAP_SPIRAM)" 选项。 +在 :ref:`CONFIG_SPIRAM_USE` 中选择 "Make RAM allocatable using heap_caps_malloc(..., MALLOC_CAP_SPIRAM)" 选项。 启用上述选项后，片外 RAM 被映射到地址 0x3F800000，并将这个区域添加到 :doc:`内存分配程序 ` 里携带 ``MALLOC_CAP_SPIRAM`` 的标志 -程序如果想从片外存储器分配存储空间，则需要调用 ``heap_caps_malloc(size, MALLOC_CAP_SPIRAM)``，之后可以调用 ``free()`` 函数释放这部分存储空间。 +程序如果想从片外存储器分配存储空间，则需要调用 ``heap_caps_malloc(size, MALLOC_CAP_SPIRAM)``，之后可以调用 ``free()`` 函数释放这部分存储空间。 .. _external_ram_config_malloc: 调用 malloc() 分配片外 RAM --------------------------------- -在 :ref:`CONFIG_SPIRAM_USE` 中选择 "Make RAM allocatable using malloc() as well" 选项，该选项为默认选项。 +在 :ref:`CONFIG_SPIRAM_USE` 中选择 "Make RAM allocatable using malloc() as well" 选项，该选项为默认选项。 启用此选项后，片外存储器将被添加到内存分配程序（与上一选项相同），同时也将被添加到由标准 ``malloc()`` 返回的 RAM 中。 - + 这允许应用程序使用片外 RAM 而无需重写代码以使用 ``heap_caps_malloc(..., MALLOC_CAP_SPIRAM)``。 -如果某次内存分配偏向于片外存储器，您也可以使用 :ref:`CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL` 设置分配空间的大小阈值，控制分配结果： +如果某次内存分配偏向于片外存储器，您也可以使用 :ref:`CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL` 设置分配空间的大小阈值，控制分配结果： - 如果分配的空间小于阈值，分配程序将首先选择内部存储器。 - 如果分配的空间等于或大于阈值，分配程序将首先选择外部存储器。 @@ -115,7 +115,7 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据 * 片外 RAM 与片外 flash 使用相同的 cache 区域，即频繁在片外 RAM 访问的变量可以像在片上 RAM 中一样快速读取和修改。但访问大块数据时（大于 32 KB），cache 空间可能会不足，访问速度将回落到片外 RAM 访问速度。此外，访问大块数据可以“挤出” flash cache，可能会降低代码执行速度。 * 片外 RAM 不可用作任务堆栈存储器。因此 :cpp:func:`xTaskCreate` 及类似函数将始终为堆栈和任务 TCB 分配片上储存器，而 :cpp:func:`xTaskCreateStatic` 类型的函数将检查传递的 Buffer 是否属于片上存储器。但对于不以任何方式直接或间接调用 ROM 中代码的任务，menuconfig 选项 :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` 将消除 `xTaskCreateStatic` 中的检查，从而允许任务堆栈存储在外部 RAM 中。但是，不建议使用此方法。 - + * 默认情况下，片外 RAM 初始化失败将终止 ESP-IDF 启动。如果想禁用此功能，可启用 :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND` 配置选项。如果启用 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`，:ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND` 选项将不能使用，这是因为在链接时，链接器已经向片外 RAM 分配符号。 @@ -123,5 +123,6 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据 .. include:: inc/external-ram-esp32-notes.rst +.. _ESP32 ECO: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf diff --git a/docs/zh_CN/api-guides/inc/external-ram-esp32-notes.rst b/docs/zh_CN/api-guides/inc/external-ram-esp32-notes.rst new file mode 100644 index 0000000000..d0847aee7e --- /dev/null +++ b/docs/zh_CN/api-guides/inc/external-ram-esp32-notes.rst @@ -0,0 +1 @@ +.. include:: ../../en/api-guides/inc/external-ram-esp32-notes.rst \ No newline at end of file From cfeb9e68cb6fce1fcce075483e34d10a67f2aa0c Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Tue, 10 Dec 2019 14:55:35 +0800 Subject: [PATCH 20/47] doc: Changed Chinese doc to use dynamic chip name --- docs/zh_CN/api-guides/app_trace.rst | 12 +- docs/zh_CN/api-guides/build-system.rst | 18 +-- docs/zh_CN/api-guides/console.rst | 2 +- docs/zh_CN/api-guides/external-ram.rst | 2 +- docs/zh_CN/api-guides/fatal-errors.rst | 73 ++++------ docs/zh_CN/api-guides/general-notes.rst | 20 +-- .../jtag-debugging/building-openocd-linux.rst | 4 +- .../jtag-debugging/building-openocd-macos.rst | 5 +- .../building-openocd-windows.rst | 4 +- .../jtag-debugging/configure-other-jtag.rst | 30 +++- .../jtag-debugging/debugging-examples.rst | 137 ++++++++++-------- .../zh_CN/api-guides/jtag-debugging/index.rst | 54 +++---- .../jtag-debugging/tips-and-quirks.rst | 106 ++++++++------ .../jtag-debugging/using-debugger.rst | 40 ++--- .../api-guides/linker-script-generation.rst | 34 ++--- docs/zh_CN/api-guides/partition-tables.rst | 20 +-- docs/zh_CN/api-guides/tools/idf-monitor.rst | 14 +- docs/zh_CN/api-guides/ulp.rst | 10 +- docs/zh_CN/api-guides/unit-tests.rst | 12 +- docs/zh_CN/api-reference/network/esp_wifi.rst | 10 +- docs/zh_CN/api-reference/protocols/mdns.rst | 26 ++-- docs/zh_CN/api-reference/storage/spiffs.rst | 14 +- .../api-reference/system/power_management.rst | 28 ++-- .../establish-serial-connection.rst | 54 +++---- docs/zh_CN/get-started/index.rst | 82 ++++++----- .../zh_CN/get-started/linux-setup-scratch.rst | 8 +- docs/zh_CN/get-started/linux-setup.rst | 2 +- .../zh_CN/get-started/macos-setup-scratch.rst | 8 +- .../get-started/windows-setup-scratch.rst | 10 +- docs/zh_CN/get-started/windows-setup.rst | 2 +- docs/zh_CN/hw-reference/index.rst | 12 +- .../zh_CN/hw-reference/modules-and-boards.rst | 4 +- 32 files changed, 448 insertions(+), 409 deletions(-) diff --git a/docs/zh_CN/api-guides/app_trace.rst b/docs/zh_CN/api-guides/app_trace.rst index b47d7db99d..7b8774d540 100644 --- a/docs/zh_CN/api-guides/app_trace.rst +++ b/docs/zh_CN/api-guides/app_trace.rst @@ -5,7 +5,7 @@ 概述 ---- -为了分析应用程序的行为，IDF 提供了一个有用的功能：应用层跟踪。这个功能以库的形式提供，可以通过 menuconfig 开启。此功能使得用户可以在程序运行开销很小的前提下，通过 JTAG 接口在主机和 ESP32 之间传输任意数据。 +为了分析应用程序的行为，IDF 提供了一个有用的功能：应用层跟踪。这个功能以库的形式提供，可以通过 menuconfig 开启。此功能使得用户可以在程序运行开销很小的前提下，通过 JTAG 接口在主机和 {IDF_TARGET_NAME} 之间传输任意数据。 开发人员可以使用这个功能库将应用程序的运行状态发送给主机，在运行时接收来自主机的命令或者其他类型的信息。该库的主要使用场景有： @@ -30,7 +30,7 @@ **后验模式：** 这是默认的模式，该模式不需要和主机进行交互。在这种模式下，跟踪模块不会检查主机是否已经从 *HW UP BUFFER* 缓冲区读走所有数据，而是直接使用新数据覆盖旧数据。该模式在用户仅对最新的跟踪数据感兴趣时会很有用，例如分析程序在崩溃之前的行为。主机可以稍后根据用户的请求来读取数据，例如通过特殊的 OpenOCD 命令（假如使用了 JTAG 接口）。 -**流模式：** 当主机连接到 ESP32 时，跟踪模块会进入此模式。在这种模式下，跟踪模块在新数据写入 *HW UP BUFFER* 之前会检查其中是否有足够的空间，并在必要的时候等待主机读取数据并释放足够的内存。用户会将最长的等待时间作为超时时间参数传递给相应的 API 函数，如果超时时间是个有限值，那么应用程序有可能会因为超时而将待写的数据丢弃。尤其需要注意，如果在讲究时效的代码中（如中断处理函数，操作系统调度等）指定了无限的超时时间，那么系统会产生故障。为了避免丢失此类关键数据，开发人员可以通过在 menuconfig 中开启 :ref:`CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX` 选项来启用额外的数据缓冲区。此宏还指定了在上述条件下可以缓冲的数据大小，它有助于缓解由于 USB 总线拥塞等原因导致的向主机传输数据间歇性减缓的状况。但是，当跟踪数据流的平均比特率超过硬件接口的能力时，它也无能为力。 +**流模式：** 当主机连接到 {IDF_TARGET_NAME} 时，跟踪模块会进入此模式。在这种模式下，跟踪模块在新数据写入 *HW UP BUFFER* 之前会检查其中是否有足够的空间，并在必要的时候等待主机读取数据并释放足够的内存。用户会将最长的等待时间作为超时时间参数传递给相应的 API 函数，如果超时时间是个有限值，那么应用程序有可能会因为超时而将待写的数据丢弃。尤其需要注意，如果在讲究时效的代码中（如中断处理函数，操作系统调度等）指定了无限的超时时间，那么系统会产生故障。为了避免丢失此类关键数据，开发人员可以通过在 menuconfig 中开启 :ref:`CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX` 选项来启用额外的数据缓冲区。此宏还指定了在上述条件下可以缓冲的数据大小，它有助于缓解由于 USB 总线拥塞等原因导致的向主机传输数据间歇性减缓的状况。但是，当跟踪数据流的平均比特率超过硬件接口的能力时，它也无能为力。 配置选项与依赖项 @@ -56,7 +56,7 @@ 如何使用这个库 -------------- -该库提供了用于在主机和 ESP32 之间传输任意数据的 API。当在 menuconfig 中启用时，目标应用程序的跟踪模块会在系统启动时自动初始化，因此用户需要做的就是调用相应的 API 来发送、接收或者刷新数据。 +该库提供了用于在主机和 {IDF_TARGET_NAME} 之间传输任意数据的 API。当在 menuconfig 中启用时，目标应用程序的跟踪模块会在系统启动时自动初始化，因此用户需要做的就是调用相应的 API 来发送、接收或者刷新数据。 .. _app_trace-application-specific-tracing: @@ -327,7 +327,7 @@ IDF 中另一个基于应用层跟踪库的实用功能是系统级跟踪，它 若需使用这个功能，需要在 menuconfig 中开启 :ref:`CONFIG_SYSVIEW_ENABLE` 选项，具体路径为： *Component config > Application Level Tracing > FreeRTOS SystemView Tracing* 。在同一个菜单栏下还开启了其他几个选项： -1. *ESP32 timer to use as SystemView timestamp source* （:ref:`CONFIG_SYSVIEW_TS_SOURCE`）选择 SystemView 事件使用的时间戳来源。在单核模式下，使用 ESP32 内部的循环计数器生成时间戳，其最大的工作频率是 240 MHz（时间戳粒度大约为 4 ns）。在双核模式下，使用工作在 40 MHz 的外部定时器，因此时间戳粒度为 25 ns。 +1. *{IDF_TARGET_NAME} timer to use as SystemView timestamp source* （:ref:`CONFIG_SYSVIEW_TS_SOURCE`）选择 SystemView 事件使用的时间戳来源。在单核模式下，使用 {IDF_TARGET_NAME} 内部的循环计数器生成时间戳，其最大的工作频率是 240 MHz（时间戳粒度大约为 4 ns）。在双核模式下，使用工作在 40 MHz 的外部定时器，因此时间戳粒度为 25 ns。 2. 可以单独启用或禁用的 SystemView 事件集合（``CONFIG_SYSVIEW_EVT_XXX``）： - Trace Buffer Overflow Event @@ -341,7 +341,7 @@ IDF 中另一个基于应用层跟踪库的实用功能是系统级跟踪，它 - Task Create Event - Task Terminate Event - System Idle Event - - Timer Enter Event + - Timer Enter Event - Timer Exit Event IDF 中已经包含了所有用于生成兼容 SystemView 跟踪信息的代码，用户只需配置必要的项目选项（如上所示），然后构建、烧写映像到目标板，接着参照前面的介绍，使用 OpenOCD 收集数据。 @@ -406,7 +406,7 @@ Start 子命令语法： 数据可视化 """""""""" -收集到跟踪数据后，用户可以使用特殊的工具来可视化结果并分析程序的行为。遗憾的是，SystemView 不支持从多个核心进行跟踪。所以当追踪双核模式下的 ESP32 时会生成两个文件：一个用于 PRO CPU，另一个用于 APP CPU。用户可以将每个文件加载到工具中单独分析。 +收集到跟踪数据后，用户可以使用特殊的工具来可视化结果并分析程序的行为。遗憾的是，SystemView 不支持从多个核心进行跟踪。所以当追踪双核模式下的 ESP32 时会生成两个文件：一个用于 PRO CPU，另一个用于 APP CPU。用户可以将每个文件加载到工具中单独分析。 在工具中单独分析每个核的跟踪数据是比较棘手的，幸运的是， Eclipse 中有一款 *Impulse* 的插件可以加载多个跟踪文件，并且可以在同一个视图中检查来自两个内核的事件。此外，与免费版的 SystemView 相比，此插件没有 1,000,000 个事件的限制。 diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index 88a7c8b990..04baf23dc9 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -13,7 +13,7 @@ 一个 ESP-IDF 项目可以看作是多个不同组件的集合，例如一个显示当前湿度的网页服务器会包含以下组件： -- ESP32 基础库，包括 libc、ROM bindings 等 +- {IDF_TARGET_NAME} 基础库，包括 libc、ROM bindings 等 - Wi-Fi 驱动 - TCP/IP 协议栈 - FreeRTOS 操作系统 @@ -30,7 +30,7 @@ ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候， - ``项目配置`` 保存在项目根目录下名为 ``sdkconfig`` 的文件中，可以通过 ``idf.py menuconfig`` 进行修改，且一个项目只能包含一个项目配置。 - ``应用程序`` 是由 ESP-IDF 构建得到的可执行文件。一个项目通常会构建两个应用程序：项目应用程序（可执行的主文件，即用户自定义的固件）和引导程序（启动并初始化项目应用程序）。 - ``组件`` 是模块化且独立的代码，会被编译成静态库（.a 文件）并链接到应用程序。部分组件由 ESP-IDF 官方提供，其他组件则来源于其它开源项目。 -- ``目标`` 特指运行构建后应用程序的硬件设备。ESP-IDF 当前仅支持 ``ESP32`` 这一个硬件目标。 +- ``目标`` 特指运行构建后应用程序的硬件设备。ESP-IDF 当前仅支持 ``{IDF_TARGET_NAME}`` 这一个硬件目标。 请注意，以下内容并不属于项目的组成部分： @@ -49,7 +49,7 @@ idf.py - CMake_，配置待构建的系统 - 命令行构建工具（Ninja_ 或 `GNU Make`） -- `esptool.py`_，烧录 ESP32 +- `esptool.py`_，烧录 {IDF_TARGET_NAME} :ref:`入门指南 ` 简要介绍了如何设置 ``idf.py`` 用于配置、构建并烧录项目。 @@ -68,10 +68,10 @@ idf.py - ``idf.py clean`` 会把构建输出的文件从构建目录中删除，从而清理整个项目。下次构建时会强制“重新完整构建”这个项目。清理时，不会删除 CMake 配置输出及其他文件。 - ``idf.py fullclean`` 会将整个 ``build`` 目录下的内容全部删除，包括所有 CMake 的配置输出文件。下次构建项目时，CMake 会从头开始配置项目。请注意，该命令会递归删除构建目录下的 *所有文件*，请谨慎使用。项目配置文件不会被删除。 -- ``idf.py flash`` 会在必要时自动构建项目，并将生成的二进制程序烧录进 ESP32 设备中。``-p`` 和 ``-b`` 选项可分别设置串口的设备名和烧录时的波特率。 -- ``idf.py monitor`` 用于显示 ESP32 设备的串口输出。``-p`` 选项可用于设置主机端串口的设备名，按下 ``Ctrl-]`` 可退出监视器。更多有关监视器的详情，请参阅 :doc:`tools/idf-monitor`。 +- ``idf.py flash`` 会在必要时自动构建项目，并将生成的二进制程序烧录进 {IDF_TARGET_NAME} 设备中。``-p`` 和 ``-b`` 选项可分别设置串口的设备名和烧录时的波特率。 +- ``idf.py monitor`` 用于显示 {IDF_TARGET_NAME} 设备的串口输出。``-p`` 选项可用于设置主机端串口的设备名，按下 ``Ctrl-]`` 可退出监视器。更多有关监视器的详情，请参阅 :doc:`tools/idf-monitor`。 -多个 ``idf.py`` 命令可合并成一个，例如，``idf.py -p COM4 clean flash monitor`` 会依次清理源码树，构建项目，烧录进 ESP32 设备，最后运行串口监视器。 +多个 ``idf.py`` 命令可合并成一个，例如，``idf.py -p COM4 clean flash monitor`` 会依次清理源码树，构建项目，烧录进 {IDF_TARGET_NAME} 设备，最后运行串口监视器。 .. Note:: 环境变量 ``ESPPORT`` 和 ``ESPBAUD`` 可分别用作 ``-p`` 和 ``-b`` 选项的默认值。在命令行中，重新为这两个选项赋值，会覆盖其默认值。 @@ -81,8 +81,8 @@ idf.py ^^^^^^^^ - ``idf.py app``，``idf.py bootloader``，``idf.py partition_table`` 仅可用于从适用的项目中构建应用程序、引导程序或分区表。 -- ``idf.py app-flash`` 等匹配命令，仅将项目的特定部分烧录至 ESP32。 -- ``idf.py -p PORT erase_flash`` 会使用 esptool.py 擦除 ESP32 的整个 Flash。 +- ``idf.py app-flash`` 等匹配命令，仅将项目的特定部分烧录至 {IDF_TARGET_NAME}。 +- ``idf.py -p PORT erase_flash`` 会使用 esptool.py 擦除 {IDF_TARGET_NAME} 的整个 Flash。 - ``idf.py size`` 会打印应用程序相关的大小信息，``idf.py size-components`` 和 ``idf.py size-files`` 这两个命令相似，分别用于打印每个组件或源文件的详细信息。 - ``idf.py reconfigure`` 命令会重新运行 CMake_ （即便无需重新运行）。正常使用时，并不需要运行此命令，但当源码树中添加/删除文件后或更改 CMake cache 变量时，此命令会非常有用，例如，``idf.py -DNAME='VALUE' reconfigure`` 会将 CMake cache 中的变量 ``NAME`` 的值设置为 ``VALUE``。 @@ -776,7 +776,7 @@ Flash 参数 您可以参照如下命令将任意烧录参数文件传递给 ``esptool.py``:: - python esptool.py --chip esp32 write_flash @build/flash_project_args + python esptool.py --chip {IDF_TARGET_PATH_NAME} write_flash @build/flash_project_args 也可以手动复制参数文件中的数据到命令行中执行。 diff --git a/docs/zh_CN/api-guides/console.rst b/docs/zh_CN/api-guides/console.rst index 45872445f5..d5dd81f78f 100644 --- a/docs/zh_CN/api-guides/console.rst +++ b/docs/zh_CN/api-guides/console.rst @@ -16,7 +16,7 @@ ESP-IDF 提供了 ``console`` 组件，它包含了开发基于串口的交互 行编辑功能允许用户通过按键输入来编辑命令，使用退格键删除符号，使用左/右键在命令中移动光标，使用上/下键导航到之前输入的命令，使用制表键（“Tab”）来自动补全命令。 -.. note:: 此功能依赖于终端应用程序对 ANSI 转移符的支持，显示原始 UART 数据的串口监视器不能与行编辑库一同使用。如果运行 get_started/console 示例程序的时候观察到的输出结果是 ``[6n`` 或者类似的转义字符而不是命令行提示符 ``[esp32]>`` 时，就表明当前的串口监视器不支持 ANSI 转移字符。已知可用的串口监视程序有 GNU screen，minicom 和 idf_monitor.py（可以通过在项目目录下执行 ``idf.py monitor`` 来调用）。 +.. note:: 此功能依赖于终端应用程序对 ANSI 转移符的支持，显示原始 UART 数据的串口监视器不能与行编辑库一同使用。如果运行 get_started/console 示例程序的时候观察到的输出结果是 ``[6n`` 或者类似的转义字符而不是命令行提示符 ``[{IDFT_TARGET_PATH_NAME}]>`` 时，就表明当前的串口监视器不支持 ANSI 转移字符。已知可用的串口监视程序有 GNU screen，minicom 和 idf_monitor.py（可以通过在项目目录下执行 ``idf.py monitor`` 来调用）。 前往这里可以查看 `linenoise `_ 库提供的所有函数的描述。 diff --git a/docs/zh_CN/api-guides/external-ram.rst b/docs/zh_CN/api-guides/external-ram.rst index 986484e4ac..d6148a0cc0 100644 --- a/docs/zh_CN/api-guides/external-ram.rst +++ b/docs/zh_CN/api-guides/external-ram.rst @@ -47,7 +47,7 @@ ESP-IDF 完全支持将外部存储器集成到您的应用程序中。您可以 .. _external_ram_config_memory_map: 集成片外 RAM 到 {IDF_TARGET_NAME} 内存映射 ------------------------------------ +--------------------------------------- 在 :ref:`CONFIG_SPIRAM_USE` 中选择 "Integrate RAM into {IDF_TARGET_NAME} memory map（集成片外 RAM 到 {IDF_TARGET_NAME} 内存映射）" 选项。 diff --git a/docs/zh_CN/api-guides/fatal-errors.rst b/docs/zh_CN/api-guides/fatal-errors.rst index a9f40b672e..b3c97201cb 100644 --- a/docs/zh_CN/api-guides/fatal-errors.rst +++ b/docs/zh_CN/api-guides/fatal-errors.rst @@ -39,39 +39,28 @@ 不管哪种情况，错误原因都会被打印在括号中。请参阅 :ref:`Guru-Meditation-Errors` 以查看所有可能的出错原因。 -.. only:: esp32 +紧急处理程序接下来的行为将取决于 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC` 的设置，支持的选项包括： - 紧急处理程序接下来的行为将取决于 :ref:`CONFIG_ESP32_PANIC` 的设置，支持的选项包括： - -.. only:: esp32s2 - - 紧急处理程序接下来的行为将取决于 :ref:`CONFIG_ESP32S2_PANIC` 的设置，支持的选项包括： - -- 打印 CPU 寄存器，然后重启（``CONFIG_ESP32_PANIC_PRINT_REBOOT``）- 默认选项 +- 打印 CPU 寄存器，然后重启（``CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC_PRINT_REBOOT``）- 默认选项 打印系统发生异常时 CPU 寄存器的值，打印回溯，最后重启芯片。 -- 打印 CPU 寄存器，然后暂停（``CONFIG_ESP32_PANIC_PRINT_HALT``） +- 打印 CPU 寄存器，然后暂停（``CONFIG_E{IDF_TARGET_CFG_PREFIX}_PANIC_PRINT_HALT``） 与上一个选项类似，但不会重启，而是选择暂停程序的运行。重启程序需要外部执行复位操作。 -- 静默重启（``CONFIG_ESP32_PANIC_SILENT_REBOOT``） +- 静默重启（``CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC_SILENT_REBOOT``） 不打印 CPU 寄存器的值，也不打印回溯，立即重启芯片。 -- 调用 GDB Stub（``CONFIG_ESP32_PANIC_GDBSTUB``） +- 调用 GDB Stub（``CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC_GDBSTUB``） 启动 GDB 服务器，通过控制台 UART 接口与 GDB 进行通信。详细信息请参阅 :ref:`GDB-Stub`。 紧急处理程序的行为还受到另外两个配置项的影响： -.. only:: esp32 - - 如果 :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` 被使能了（默认），紧急处理程序会检测 ESP32 是否已经连接 JTAG 调试器。如果检测成功，程序会暂停运行，并将控制权交给调试器。在这种情况下，寄存器和回溯不会被打印到控制台，并且也不会使用 GDB Stub 和 Core Dump 的功能。 - -.. only:: esp32s2 - - - 如果 :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` 被使能了（默认），紧急处理程序会检测 ESP32-S2 是否已经连接 JTAG 调试器。如果检测成功，程序会暂停运行，并将控制权交给调试器。在这种情况下，寄存器和回溯不会被打印到控制台，并且也不会使用 GDB Stub 和 Core Dump 的功能。 +- 如果 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEBUG_OCDAWARE` 被使能了（默认），紧急处理程序会检测 {IDF_TARGET_NAME} 是否已经连接 JTAG 调试器。如果检测成功，程序会暂停运行，并将控制权交给调试器。在这种情况下，寄存器和回溯不会被打印到控制台，并且也不会使用 GDB Stub 和 Core Dump 的功能。 - 如果使能了 :doc:`Core Dump ` 功能（``CONFIG_ESP32_ENABLE_COREDUMP_TO_FLASH`` 或者 ``CONFIG_ESP32_ENABLE_COREDUMP_TO_UART`` 选项），系统状态（任务堆栈和寄存器）会被转储到 Flash 或者 UART 以供后续分析。 @@ -81,7 +70,7 @@ :scale: 100% :caption: 紧急处理程序流程图（点击放大） :align: center - + blockdiag panic-handler { orientation = portrait; edge_layout = flowchart; @@ -123,15 +112,15 @@ 寄存器转储与回溯 ---------------- -除非启用了 ``CONFIG_ESP32_PANIC_SILENT_REBOOT`` 否则紧急处理程序会将 CPU 寄存器和回溯打印到控制台:: +除非启用了 ``CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC_SILENT_REBOOT`` 否则紧急处理程序会将 CPU 寄存器和回溯打印到控制台:: Core 0 register dump: - PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 - A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc - A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 - A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 - A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d - EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff + PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 + A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc + A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 + A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 + A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d + EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 @@ -146,21 +135,21 @@ 如果使用了 :doc:`IDF 监视器 `，该工具会将程序计数器的值转换为对应的代码位置（函数名，文件名，行号），并加以注释:: Core 0 register dump: - PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 + PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36 - A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc - A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 - A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 + A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc + A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 + A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 0x40082d1c: _calloc_r at /Users/user/esp/esp-idf/components/newlib/syscalls.c:51 - A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d - EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff + A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d + EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36 - 0x400d0802: main_task at /Users/user/esp/esp-idf/components/esp32/cpu_start.c:470 + 0x400d0802: main_task at /Users/user/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/cpu_start.c:470 若要查找发生严重错误的代码位置，请查看 "Backtrace" 的后面几行，发生严重错误的代码显示在顶行，后续几行显示的是调用堆栈。 @@ -169,7 +158,7 @@ GDB Stub -------- -如果启用了 ``CONFIG_ESP32_PANIC_GDBSTUB`` 选项，在发生严重错误时，紧急处理程序不会复位芯片，相反，它将启动 GDB 远程协议服务器，通常称为 GDB Stub。发生这种情况时，可以让主机上运行的 GDB 实例通过 UART 端口连接到 ESP32。 +如果启用了 ``CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC_GDBSTUB`` 选项，在发生严重错误时，紧急处理程序不会复位芯片，相反，它将启动 GDB 远程协议服务器，通常称为 GDB Stub。发生这种情况时，可以让主机上运行的 GDB 实例通过 UART 端口连接到 {IDF_TARGET_NAME}。 如果使用了 :doc:`IDF 监视器 `，该工具会在 UART 端口检测到 GDB Stub 提示符后自动启动 GDB，输出会类似于:: @@ -180,7 +169,7 @@ GDB Stub This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. - This GDB was configured as "--host=x86_64-build_apple-darwin16.3.0 --target=xtensa-esp32-elf". + This GDB was configured as "--host=x86_64-build_apple-darwin16.3.0 --target=xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf". Type "show configuration" for configuration details. For bug reporting instructions, please see: . @@ -193,7 +182,7 @@ GDB Stub 0x400e1b41 in app_main () at /Users/user/esp/example/main/main.cpp:36 36 *((int*) 0) = 0; - (gdb) + (gdb) 在 GDB 会话中，我们可以检查 CPU 寄存器，本地和静态变量以及内存中任意位置的值。但是不支持设置断点，改变 PC 值或者恢复程序的运行。若要复位程序，请退出 GDB 会话，在 IDF 监视器 中连续输入 Ctrl-T Ctrl-R，或者按下开发板上的复位按键也可以重新运行程序。 @@ -219,10 +208,10 @@ IllegalInstruction - FreeRTOS 中的任务函数已返回。在 FreeRTOS 中，如果想终止任务函数，需要调用 :cpp:func:`vTaskDelete` 函数释放当前任务的资源，而不是直接返回。 - 无法从 SPI Flash 中加载下一条指令，这通常发生在： - + - 应用程序将 SPI Flash 的引脚重新配置为其它功能（如 GPIO，UART 等等）。有关 SPI Flash 引脚的详细信息，请参阅硬件设计指南和芯片/模组的数据手册。 - - - 某些外部设备意外连接到 SPI Flash 的引脚上，干扰了 ESP32 和 SPI Flash 之间的通信。 + + - 某些外部设备意外连接到 SPI Flash 的引脚上，干扰了 {IDF_TARGET_NAME} 和 SPI Flash 之间的通信。 InstrFetchProhibited @@ -277,13 +266,7 @@ Cache disabled but cached memory region accessed 欠压 ^^^^ -.. only:: esp32 - - ESP32 内部集成掉电检测电路，并且会默认启用。如果电源电压低于安全值，掉电检测器可以触发系统复位。掉电检测器可以使用 :ref:`CONFIG_ESP32_BROWNOUT_DET` 和 :ref:`CONFIG_ESP32_BROWNOUT_DET_LVL_SEL` 这两个选项进行设置。 - -.. only:: esp32s2 - - ESP32-S2 内部集成掉电检测电路，并且会默认启用。如果电源电压低于安全值，掉电检测器可以触发系统复位。掉电检测器可以使用 :ref:`CONFIG_ESP32S2_BROWNOUT_DET` 和 :ref:`CONFIG_ESP32S2_BROWNOUT_DET_LVL_SEL` 这两个选项进行设置。 +{IDF_TARGET_NAME} 内部集成掉电检测电路，并且会默认启用。如果电源电压低于安全值，掉电检测器可以触发系统复位。掉电检测器可以使用 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_BROWNOUT_DET` 和 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_BROWNOUT_DET_LVL_SEL` 这两个选项进行设置。 当掉电检测器被触发时，会打印如下信息:: diff --git a/docs/zh_CN/api-guides/general-notes.rst b/docs/zh_CN/api-guides/general-notes.rst index 320ed2a91b..b808879739 100644 --- a/docs/zh_CN/api-guides/general-notes.rst +++ b/docs/zh_CN/api-guides/general-notes.rst @@ -5,12 +5,12 @@ ESP-IDF 编程注意事项 应用程序的启动流程 ------------------ -本文将会介绍 ESP32 从上电到运行 ``app_main`` +本文将会介绍 {IDF_TARGET_NAME} 从上电到运行 ``app_main`` 函数中间所经历的步骤（即启动流程）。 宏观上，该启动流程可以分为如下 3 个步骤： -1. 一级引导程序被固化在了 ESP32 内部的 ROM 中，它会从 Flash 的 +1. 一级引导程序被固化在了 {IDF_TARGET_NAME} 内部的 ROM 中，它会从 Flash 的 ``0x1000`` 偏移地址处加载二级引导程序至 RAM(IRAM & DRAM) 中。 2. 二级引导程序从 Flash 中加载分区表和主程序镜像至内存中，主程序中包含了 @@ -26,10 +26,10 @@ ESP-IDF 编程注意事项 SoC 复位后，PRO CPU 会立即开始运行，执行复位向量代码，而 APP CPU 仍然保持复位状态。在启动过程中，PRO CPU 会执行所有的初始化操作。APP CPU 的复位状态会在应用程序启动代码的 ``call_start_cpu0`` -函数中失效。复位向量代码位于 ESP32 芯片掩膜 ROM 的 ``0x40000400`` +函数中失效。复位向量代码位于 {IDF_TARGET_NAME} 芯片掩膜 ROM 的 ``0x40000400`` 地址处，该地址不能被修改。 -复位向量调用的启动代码会根据 ``GPIO_STRAP_REG`` 寄存器的值来确定 ESP32 +复位向量调用的启动代码会根据 ``GPIO_STRAP_REG`` 寄存器的值来确定 {IDF_TARGET_NAME} 的工作模式，该寄存器保存着复位后 bootstrap 引脚的电平状态。根据不同的复位原因，程序会执行不同的操作： @@ -67,7 +67,7 @@ SoC 复位后，PRO CPU 会立即开始运行，执行复位向量代码，而 A 在 ESP-IDF 中，存放在 Flash 的 ``0x1000`` 偏移地址处的二进制镜像就是二级引导程序。二级引导程序的源码可以在 ESP-IDF -的 components/bootloader 目录下找到。请注意，对于 ESP32 +的 components/bootloader 目录下找到。请注意，对于 {IDF_TARGET_NAME} 芯片来说，这并不是唯一的安排程序镜像的方式。事实上用户完全可以把一个功能齐全的应用程序烧写到 Flash 的 ``0x1000`` 偏移地址处运行，但这超出本文档的范围。ESP-IDF 使用二级引导程序可以增加 Flash 分区的灵活性（使用分区表），并且方便实现 @@ -99,7 +99,7 @@ ESP-IDF 中。目前，可以通过将 bootloader 应用程序启动阶段 ~~~~~~~~~~~~~~~~ -ESP-IDF 应用程序的入口是 ``components/esp32/cpu_start.c`` 文件中的 +ESP-IDF 应用程序的入口是 ``components/{IDF_TARGET_PATH_NAME}/cpu_start.c`` 文件中的 ``call_start_cpu0`` 函数，该函数主要完成了两件事，一是启用堆分配器，二是使 APP CPU 跳转到其入口点—— ``call_start_cpu1`` 函数。PRO CPU 上的代码会给 APP @@ -110,7 +110,7 @@ CPU 跳转到 ``start_cpu0`` 函数，APP CPU 跳转到 ``start_cpu1`` 函数。 ``start_cpu0`` 和 ``start_cpu1`` 这两个函数都是弱类型的，这意味着如果某些特定的应用程序需要修改初始化顺序，就可以通过重写这两个函数来实现。 ``start_cpu0`` 默认的实现方式是初始化用户在 ``menuconfig`` -中选择的组件，具体实现步骤可以阅读 ``components/esp32/cpu_start.c`` +中选择的组件，具体实现步骤可以阅读 ``components/{IDF_TARGET_PATH_NAME}/cpu_start.c`` 文件中的源码。请注意，此阶段会调用应用程序中存在的 C++ 全局构造函数。一旦所有必要的组件都初始化好，就会创建 *main task* ，并启动 FreeRTOS 的调度器。 @@ -129,7 +129,7 @@ task* ，并启动 FreeRTOS 的调度器。 应用程序的内存布局 ------------------ -ESP32 芯片具有灵活的内存映射功能，本小节将介绍 ESP-IDF +{IDF_TARGET_NAME} 芯片具有灵活的内存映射功能，本小节将介绍 ESP-IDF 默认使用这些功能的方式。 ESP-IDF 应用程序的代码可以放在以下内存区域之一。 @@ -154,7 +154,7 @@ RAM。除了开始的 64kB 用作 PRO CPU 和 APP CPU void IRAM_ATTR gpio_isr_handler(void* arg) { - // ... + // ... } 下面列举了应用程序中可能或者应该放入 IRAM 中运行例子。 @@ -169,7 +169,7 @@ RAM。除了开始的 64kB 用作 PRO CPU 和 APP CPU DRAM 中。 - 可以将一些时间关键的代码放在 IRAM 中，这样可以缩减从 Flash - 加载代码所消耗的时间。ESP32 是通过 32kB 的高速缓存来从外部 Flash + 加载代码所消耗的时间。{IDF_TARGET_NAME} 是通过 32kB 的高速缓存来从外部 Flash 中读取代码和数据的，将函数放在 IRAM 中运行可以减少由高速缓存未命中引起的时间延迟。 diff --git a/docs/zh_CN/api-guides/jtag-debugging/building-openocd-linux.rst b/docs/zh_CN/api-guides/jtag-debugging/building-openocd-linux.rst index 9041dd1195..2c77287f80 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/building-openocd-linux.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/building-openocd-linux.rst @@ -11,7 +11,7 @@ Linux 环境下从源码编译 OpenOCD 下载 OpenOCD 源码 ================= -支持 ESP32 的 OpenOCD 源代码可以从乐鑫官方的 GitHub 获得，网址为 https://github.com/espressif/openocd-esp32。请使用以下命令来下载源代码:: +支持 {IDF_TARGET_NAME} 的 OpenOCD 源代码可以从乐鑫官方的 GitHub 获得，网址为 https://github.com/espressif/openocd-esp32。请使用以下命令来下载源代码:: cd ~/esp git clone --recursive https://github.com/espressif/openocd-esp32.git @@ -73,4 +73,4 @@ Linux 环境下从源码编译 OpenOCD 下一步 ====== -想要进一步配置调试环境，请前往 :ref:`jtag-debugging-configuring-esp32-target` 章节。 +想要进一步配置调试环境，请前往 :ref:`jtag-debugging-configuring-target` 章节。 diff --git a/docs/zh_CN/api-guides/jtag-debugging/building-openocd-macos.rst b/docs/zh_CN/api-guides/jtag-debugging/building-openocd-macos.rst index 376aba6ba7..c107dcc7ac 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/building-openocd-macos.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/building-openocd-macos.rst @@ -10,7 +10,7 @@ MacOS 环境下从源码编译 OpenOCD 下载 OpenOCD 源码 ================= -支持 ESP32 的 OpenOCD 源代码可以从乐鑫官方的 GitHub 获得，网址为 https://github.com/espressif/openocd-esp32。请使用以下命令来下载源代码:: +支持 {IDF_TARGET_NAME} 的 OpenOCD 源代码可以从乐鑫官方的 GitHub 获得，网址为 https://github.com/espressif/openocd-esp32。请使用以下命令来下载源代码:: cd ~/esp git clone --recursive https://github.com/espressif/openocd-esp32.git @@ -50,5 +50,4 @@ MacOS 环境下从源码编译 OpenOCD 下一步 ====== -想要进一步配置调试环境，请前往 :ref:`jtag-debugging-configuring-esp32-target` 章节。 - \ No newline at end of file +想要进一步配置调试环境，请前往 :ref:`jtag-debugging-configuring-target` 章节。 diff --git a/docs/zh_CN/api-guides/jtag-debugging/building-openocd-windows.rst b/docs/zh_CN/api-guides/jtag-debugging/building-openocd-windows.rst index 1a554b7515..25f8d684ca 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/building-openocd-windows.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/building-openocd-windows.rst @@ -11,7 +11,7 @@ Windows 环境下从源码编译 OpenOCD 下载 OpenOCD 源码 ================= -支持 ESP32 的 OpenOCD 源代码可以从乐鑫官方的 GitHub 获得，网址为 https://github.com/espressif/openocd-esp32。请使用以下命令来下载源代码:: +支持 {IDF_TARGET_NAME} 的 OpenOCD 源代码可以从乐鑫官方的 GitHub 获得，网址为 https://github.com/espressif/openocd-esp32。请使用以下命令来下载源代码:: cd ~/esp git clone --recursive https://github.com/espressif/openocd-esp32.git @@ -72,4 +72,4 @@ Windows 环境下从源码编译 OpenOCD 下一步 ====== -想要进一步配置调试环境，请前往 :ref:`jtag-debugging-configuring-esp32-target` 章节。 +想要进一步配置调试环境，请前往 :ref:`jtag-debugging-configuring-target` 章节。 diff --git a/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst b/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst index 6c549d235c..d29f91b08f 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst @@ -2,13 +2,15 @@ ================== :link_to_translation:`en:[English]` -关于适配 OpenOCD 和 ESP32 的 JTAG 接口选择问题，请参考 :ref:`jtag-debugging-selecting-jtag-adapter` 章节，确保 JTAG 适配器能够与 OpenOCD 和 ESP32 一同工作。然后按照以下三个步骤进行设置，使其正常工作。 +关于适配 OpenOCD 和 {IDF_TARGET_NAME} 的 JTAG 接口选择问题，请参考 :ref:`jtag-debugging-selecting-jtag-adapter` 章节，确保 JTAG 适配器能够与 OpenOCD 和 {IDF_TARGET_NAME} 一同工作。然后按照以下三个步骤进行设置，使其正常工作。 配置硬件 ^^^^^^^^ -1. 找到 JTAG 接口和 ESP32 板上需要相互连接并建立通信的引脚/信号。 +1. 找到 JTAG 接口和 {IDF_TARGET_NAME} 板上需要相互连接并建立通信的引脚/信号。 + +.. only:: esp32 +---+---------------+-----------+ | | ESP32 引脚 | JTAG 信号 | @@ -26,9 +28,27 @@ | 6 | GND | GND | +---+---------------+-----------+ -2. 检查 ESP32 上用于 JTAG 通信的的引脚是否被连接到了其它硬件上，这可能会影响 JTAG 的工作。 +.. only:: esp32s2 -3. 连接 ESP32 和 JTAG 接口上的引脚/信号。 + +---+-----------------------+-------------+ + | | ESP32-S2 Pin | JTAG Signal | + +===+=======================+=============+ + | 1 | CHIP_PU | TRST_N | + +---+-----------------------+-------------+ + | 2 | MTDO / GPIO40 | TDO | + +---+-----------------------+-------------+ + | 3 | MTDI / GPIO41 | TDI | + +---+-----------------------+-------------+ + | 4 | MTCK / GPIO39 | TCK | + +---+-----------------------+-------------+ + | 5 | MTMS / GPIO42 | TMS | + +---+-----------------------+-------------+ + | 6 | GND | GND | + +---+-----------------------+-------------+ + +2. 检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的的引脚是否被连接到了其它硬件上，这可能会影响 JTAG 的工作。 + +3. 连接 {IDF_TARGET_NAME} 和 JTAG 接口上的引脚/信号。 配置驱动 @@ -39,7 +59,7 @@ 连接 ^^^^ -将 JTAG 接口连接到计算机，打开 ESP32 和 JTAG 接口板上的电源，然后检查计算机是否可以识别到 JTAG 接口。 +将 JTAG 接口连接到计算机，打开 {IDF_TARGET_NAME} 和 JTAG 接口板上的电源，然后检查计算机是否可以识别到 JTAG 接口。 要继续设置调试环境，请前往 :ref:`jtag-debugging-run-openocd` 章节。 diff --git a/docs/zh_CN/api-guides/jtag-debugging/debugging-examples.rst b/docs/zh_CN/api-guides/jtag-debugging/debugging-examples.rst index c79d40d775..2434431b08 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/debugging-examples.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/debugging-examples.rst @@ -38,7 +38,7 @@ 浏览代码，查看堆栈和线程 ^^^^^^^^^^^^^^^^^^^^^^^^ -当目标暂停时，调试器会在 “Debug” 窗口中显示线程的列表，程序暂停的代码行在下面的另一个窗口中被高亮显示，如下图所示。此时板子上的 LED 停止了闪烁。 +当目标暂停时，调试器会在 “Debug” 窗口中显示线程的列表，程序暂停的代码行在下面的另一个窗口中被高亮显示，如下图所示。此时板子上的 LED 停止了闪烁。 .. figure:: ../../../_static/debugging-target-halted.jpg :align: center @@ -47,7 +47,7 @@ 调试时目标停止 -暂停的程序所在线程也会被展开，显示函数调用的堆栈，它表示直到目标暂停所在代码行（下图高亮处）为止的相关函数的调用关系。1 号线程下函数调用堆栈的第一行包含了最后一个调用的函数 ``app_main()``，根据下一行显示，它又是在函数 ``main_task()`` 中被调用的。堆栈的每一行还包含调用函数的文件名和行号。通过单击每个堆栈的条目，在下面的窗口中，你将看到此文件的内容。 +暂停的程序所在线程也会被展开，显示函数调用的堆栈，它表示直到目标暂停所在代码行（下图高亮处）为止的相关函数的调用关系。1 号线程下函数调用堆栈的第一行包含了最后一个调用的函数 ``app_main()``，根据下一行显示，它又是在函数 ``main_task()`` 中被调用的。堆栈的每一行还包含调用函数的文件名和行号。通过单击每个堆栈的条目，在下面的窗口中，你将看到此文件的内容。 通过展开线程，你可以浏览整个应用程序。展开 5 号线程，它包含了更长的函数调用堆栈，你可以看到函数调用旁边的数字，比如 ``0x4000000c``，它们代表未以源码形式提供的二进制代码所在的内存地址。 @@ -153,7 +153,16 @@ 要显示或者设置内存的内容，请使用“调试”视图中位于底部的 “Memory” 选项卡。 -在 “Memory” 选项卡下，我们将在内存地址 ``0x3FF44004`` 处读取和写入内容。该地址也是 ``GPIO_OUT_REG`` 寄存器的地址，可以用来控制（设置或者清除）某个 GPIO 的电平。关于该寄存器的更多详细信息，请参阅 `ESP32 技术参考手册 `_ 中的 IO_MUX 和 GPIO Matrix 章节。 +在 “Memory” 选项卡下，我们将在内存地址 ``0x3FF44004`` 处读取和写入内容。该地址也是 ``GPIO_OUT_REG`` 寄存器的地址，可以用来控制（设置或者清除）某个 GPIO 的电平。 + +.. only:: esp32 + + 关于该寄存器的更多详细信息，请参阅 `ESP32 技术参考手册 `_ 中的 IO_MUX 和 GPIO Matrix 章节。 + +.. only:: esp32s2beta + + 关于该寄存器的更多详细信息，请参阅 `ESP32-S2 技术参考手册 `_ 中的 IO_MUX 和 GPIO Matrix 章节。 + 同样在 ``blink.c`` 项目文件中，在两个 ``gpio_set_level`` 语句的后面各设置一个断点，单击 “Memory” 选项卡，然后单击 “Add Memory Monitor” 按钮，在弹出的对话框中输入 ``0x3FF44004``。 @@ -184,7 +193,7 @@ 常见的调试任务是在程序运行期间检查程序中某个变量的值，为了演示这个功能，更新 ``blink.c`` 文件，在 ``blink_task`` 函数的上面添加一个全局变量的声明 ``int i``，然后在 ``while(1)`` 里添加 ``i++``，这样每次 LED 改变状态的时候，变量 ``i`` 都会增加 1。 -退出调试器，这样就不会与新代码混淆，然后重新构建并烧写代码到 ESP32 中，接着重启调试器。注意，这里不需要我们重启 OpenOCD。 +退出调试器，这样就不会与新代码混淆，然后重新构建并烧写代码到 {IDF_TARGET_NAME} 中，接着重启调试器。注意，这里不需要我们重启 OpenOCD。 一旦程序停止运行，在代码 ``i++`` 处添加一个断点。 @@ -229,7 +238,7 @@ Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink.c:43 43 xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5, NULL); - (gdb) + (gdb) @@ -250,19 +259,19 @@ 浏览代码，查看堆栈和线程 ^^^^^^^^^^^^^^^^^^^^^^^^ -当看到 ``(gdb)`` 提示符的时候，应用程序已停止运行，LED 也停止闪烁。 +当看到 ``(gdb)`` 提示符的时候，应用程序已停止运行，LED 也停止闪烁。 要找到代码暂停的位置，输入 ``l`` 或者 ``list`` 命令，调试器会打印出停止点（``blink.c`` 代码文件的第 43 行）附近的几行代码 :: (gdb) l 38 } 39 } - 40 + 40 41 void app_main() 42 { 43 xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5, NULL); 44 } - (gdb) + (gdb) 也可以通过输入 ``l 30, 40`` 等命令来查看特定行号范围内的代码。 @@ -271,15 +280,15 @@ (gdb) bt #0 app_main () at /home/user-name/esp/blink/main/./blink.c:43 - #1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/esp32/./cpu_start.c:339 - (gdb) + #1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:339 + (gdb) -输出的第 0 行表示应用程序暂停之前调用的最后一个函数，即我们之前列出的 ``app_main ()``。``app_main ()`` 又被位于 ``cpu_start.c`` 文件第 339 行的 ``main_task`` 函数调用。 +输出的第 0 行表示应用程序暂停之前调用的最后一个函数，即我们之前列出的 ``app_main ()``。``app_main ()`` 又被位于 ``cpu_start.c`` 文件第 339 行的 ``main_task`` 函数调用。 想查看 ``cpu_start.c`` 文件中 ``main_task`` 函数的上下文，需要输入 ``frame N``，其中 N = 1，因为根据前面的输出，``main_task`` 位于 #1 下:: (gdb) frame 1 - #1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/esp32/./cpu_start.c:339 + #1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:339 339 app_main(); (gdb) @@ -294,8 +303,8 @@ 339 app_main(); 340 vTaskDelete(NULL); 341 } - 342 - (gdb) + 342 + (gdb) 通过打印前面的一些行，你会看到我们一直在寻找的 ``main_task`` 函数:: @@ -316,27 +325,27 @@ 339 app_main(); 340 vTaskDelete(NULL); 341 } - (gdb) + (gdb) 如果要查看其他代码，可以输入 ``i threads`` 命令，则会输出目标板上运行的线程列表:: (gdb) i threads - Id Target Id Frame + Id Target Id Frame 8 Thread 1073411336 (dport) 0x400d0848 in dport_access_init_core (arg=) - at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:170 - 7 Thread 1073408744 (ipc0) xQueueGenericReceive (xQueue=0x3ffae694, pvBuffer=0x0, xTicksToWait=1644638200, + at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./dport_access.c:170 + 7 Thread 1073408744 (ipc0) xQueueGenericReceive (xQueue=0x3ffae694, pvBuffer=0x0, xTicksToWait=1644638200, xJustPeeking=0) at /home/user-name/esp/esp-idf/components/freertos/./queue.c:1452 6 Thread 1073431096 (Tmr Svc) prvTimerTask (pvParameters=0x0) at /home/user-name/esp/esp-idf/components/freertos/./timers.c:445 5 Thread 1073410208 (ipc1 : Running) 0x4000bfea in ?? () 4 Thread 1073432224 (dport) dport_access_init_core (arg=0x0) - at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:150 + at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./dport_access.c:150 3 Thread 1073413156 (IDLE) prvIdleTask (pvParameters=0x0) at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282 2 Thread 1073413512 (IDLE) prvIdleTask (pvParameters=0x0) at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282 * 1 Thread 1073411772 (main : Running) app_main () at /home/user-name/esp/blink/main/./blink.c:43 - (gdb) + (gdb) 线程列表显示了每个线程最后一个被调用的函数以及所在的 C 源文件名（如果存在的话）。 @@ -359,7 +368,7 @@ #6 0x4000000c in ?? () #7 0x4000000c in ?? () #8 0x4000000c in ?? () - (gdb) + (gdb) 如上所示，回溯可能会包含多个条目，方便查看直至目标停止运行的函数调用顺序。如果找不到某个函数的源码文件，将会使用问号 ``??`` 替代，这表示该函数是以二进制格式提供的。像 ``0x4000bfea`` 这样的值是被调用函数所在的内存地址。 @@ -384,18 +393,18 @@ (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB6F6 (active) APP_CPU: PC=0x400D10D8 + Target halted. PRO_CPU: PC=0x400DB6F6 (active) APP_CPU: PC=0x400D10D8 Breakpoint 2, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:33 33 gpio_set_level(BLINK_GPIO, 0); (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB6F8 (active) APP_CPU: PC=0x400D10D8 - Target halted. PRO_CPU: PC=0x400DB704 (active) APP_CPU: PC=0x400D10D8 + Target halted. PRO_CPU: PC=0x400DB6F8 (active) APP_CPU: PC=0x400D10D8 + Target halted. PRO_CPU: PC=0x400DB704 (active) APP_CPU: PC=0x400D10D8 Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:36 36 gpio_set_level(BLINK_GPIO, 1); - (gdb) + (gdb) 只有在输入命令 ``c`` 恢复程序运行后才能看到 LED 改变状态。 @@ -407,16 +416,16 @@ breakpoint already hit 1 time 3 breakpoint keep y 0x400db704 in blink_task at /home/user-name/esp/blink/main/./blink.c:36 breakpoint already hit 1 time - (gdb) + (gdb) 请注意，断点序号（在 ``Num`` 栏列出）从 2 开始，这是因为在调试器启动时执行 ``thb app_main`` 命令已经在 ``app_main()`` 函数处建立了第一个断点。由于它是一个临时断点，已经被自动删除，所以没有被列出。 -要删除一个断点，请输入 ``delete N`` 命令（或者简写成 ``d N``），其中 ``N`` 代表断点序号:: +要删除一个断点，请输入 ``delete N`` 命令（或者简写成 ``d N``），其中 ``N`` 代表断点序号:: (gdb) delete 1 No breakpoint number 1. (gdb) delete 2 - (gdb) + (gdb) 更多关于断点的信息，请参阅 :ref:`jtag-debugging-tip-breakpoints` 和 :ref:`jtag-debugging-tip-where-breakpoints`。 @@ -437,9 +446,9 @@ Program received signal SIGINT, Interrupt. [Switching to Thread 1073413512] - 0x400d0c00 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/esp32/./freertos_hooks.c:52 + 0x400d0c00 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./freertos_hooks.c:52 52 asm("waiti 0"); - (gdb) + (gdb) 在上图所示的情况下，应用程序已经在 ``freertos_hooks.c`` 文件的第 52 行暂停运行，现在您可以通过输入 ``c`` 再次将其恢复运行或者进行如下所述的一些调试工作。 @@ -461,44 +470,44 @@ Num Type Disp Enb Address What 3 breakpoint keep y 0x400db704 in blink_task at /home/user-name/esp/blink/main/./blink.c:36 breakpoint already hit 1 time - (gdb) + (gdb) 输入 ``c`` 恢复程序运行然后等它在断点处停止运行:: (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB754 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB754 (active) APP_CPU: PC=0x400D1128 Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:36 36 gpio_set_level(BLINK_GPIO, 1); - (gdb) + (gdb) 然后输入 ``n`` 多次，观察调试器是如何单步执行一行代码的:: (gdb) n - Target halted. PRO_CPU: PC=0x400DB756 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB758 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB756 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB758 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128 37 vTaskDelay(1000 / portTICK_PERIOD_MS); (gdb) n - Target halted. PRO_CPU: PC=0x400DB75E (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400846FC (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB761 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB746 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB75E (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400846FC (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB761 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB746 (active) APP_CPU: PC=0x400D1128 33 gpio_set_level(BLINK_GPIO, 0); - (gdb) + (gdb) 如果你输入 ``s``，那么调试器将进入子程序:: (gdb) s - Target halted. PRO_CPU: PC=0x400DB748 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB74B (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DC04F (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB748 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB74B (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DC04F (active) APP_CPU: PC=0x400D1128 gpio_set_level (gpio_num=GPIO_NUM_4, level=0) at /home/user-name/esp/esp-idf/components/driver/./gpio.c:183 183 GPIO_CHECK(GPIO_IS_VALID_OUTPUT_GPIO(gpio_num), "GPIO output gpio_num error", ESP_ERR_INVALID_ARG); - (gdb) + (gdb) 上述例子中，调试器进入 ``gpio_set_level(BLINK_GPIO, 0)`` 代码内部，同时代码窗口快速切换到 ``gpio.c`` 驱动文件。 @@ -518,8 +527,8 @@ (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB75E (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB74E (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB75E (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB74E (active) APP_CPU: PC=0x400D1128 Breakpoint 2, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:34 34 vTaskDelay(1000 / portTICK_PERIOD_MS); @@ -527,14 +536,14 @@ 0x3ff44004: 0x00000000 (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB751 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB751 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128 Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:37 37 vTaskDelay(1000 / portTICK_PERIOD_MS); (gdb) x /1wx 0x3FF44004 0x3ff44004: 0x00000010 - (gdb) + (gdb) 如果闪烁的 LED 连接到了 GPIO4，那么每次 LED 改变状态时你会看到第 4 比特被翻转:: @@ -558,7 +567,7 @@ 常见的调试任务是在程序运行期间检查程序中某个变量的值，为了能够演示这个功能，更新 ``blink.c`` 文件，在 ``blink_task`` 函数的上面添加一个全局变量的声明 ``int i``，然后在 ``while(1)`` 里添加 ``i++``，这样每次 LED 改变状态的时候，变量 ``i`` 都会增加 1。 -退出调试器，这样就不会与新代码混淆，然后重新构建并烧写代码到 ESP32 中，接着重启调试器。注意，这里不需要我们重启 OpenOCD。 +退出调试器，这样就不会与新代码混淆，然后重新构建并烧写代码到 {IDF_TARGET_NAME} 中，接着重启调试器。注意，这里不需要我们重启 OpenOCD。 一旦程序停止运行，输入命令 ``watch i``:: @@ -570,7 +579,7 @@ (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB751 (active) APP_CPU: PC=0x400D0811 + Target halted. PRO_CPU: PC=0x400DB751 (active) APP_CPU: PC=0x400D0811 [New Thread 1073432196] Program received signal SIGTRAP, Trace/breakpoint trap. @@ -583,14 +592,14 @@ (gdb) p i $1 = 3 - (gdb) + (gdb) 要修改 ``i`` 的值，请使用 ``set`` 命令，如下所示（可以将其打印输出来查看是否确已修改）:: (gdb) set var i = 0 (gdb) p i $3 = 0 - (gdb) + (gdb) 最多可以使用两个观察点，详细信息请参阅 :ref:`jtag-debugging-tip-breakpoints`。 @@ -613,14 +622,14 @@ (gdb) set var i = 0 (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB755 (active) APP_CPU: PC=0x400D112C - Target halted. PRO_CPU: PC=0x400DB753 (active) APP_CPU: PC=0x400D112C - Target halted. PRO_CPU: PC=0x400DB755 (active) APP_CPU: PC=0x400D112C - Target halted. PRO_CPU: PC=0x400DB753 (active) APP_CPU: PC=0x400D112C + Target halted. PRO_CPU: PC=0x400DB755 (active) APP_CPU: PC=0x400D112C + Target halted. PRO_CPU: PC=0x400DB753 (active) APP_CPU: PC=0x400D112C + Target halted. PRO_CPU: PC=0x400DB755 (active) APP_CPU: PC=0x400D112C + Target halted. PRO_CPU: PC=0x400DB753 (active) APP_CPU: PC=0x400D112C Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:34 34 gpio_set_level(BLINK_GPIO, 0); - (gdb) + (gdb) 获得命令的帮助信息 @@ -634,7 +643,7 @@ Unlike "step", if the current source line calls a subroutine, this command does not enter the subroutine, but instead steps over the call, in effect treating it as a single source line. - (gdb) + (gdb) 只需输入 ``help`` 命令，即可获得高级命令列表，帮助你了解更多详细信息。此外，还可以参考一些 GDB 命令速查表，比如 http://darkdust.net/files/GDB%20Cheat%20Sheet.pdf。虽然不是所有命令都适用于嵌入式环境，但还是会有所裨益。 @@ -642,7 +651,7 @@ 结束调试会话 ^^^^^^^^^^^^ -输入命令 ``q`` 可以退出调试器:: +输入命令 ``q`` 可以退出调试器:: (gdb) q A debugging session is active. @@ -652,4 +661,4 @@ Quit anyway? (y or n) y Detaching from program: /home/user-name/esp/blink/build/blink.elf, Remote target Ending remote debugging. - user-name@computer-name:~/esp/blink$ + user-name@computer-name:~/esp/blink$ diff --git a/docs/zh_CN/api-guides/jtag-debugging/index.rst b/docs/zh_CN/api-guides/jtag-debugging/index.rst index 88405967ab..e6222327aa 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/index.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/index.rst @@ -2,17 +2,17 @@ JTAG 调试 ========= :link_to_translation:`en:[English]` -本文将指导安装 ESP32 的 OpenOCD 调试环境，并介绍如何使用 GDB 来调试 ESP32 的应用程序。本文的组织结构如下： +本文将指导安装 {IDF_TARGET_NAME} 的 OpenOCD 调试环境，并介绍如何使用 GDB 来调试 {IDF_TARGET_NAME} 的应用程序。本文的组织结构如下： :ref:`jtag-debugging-introduction` 介绍本指南主旨。 :ref:`jtag-debugging-how-it-works` - 介绍 ESP32，JTAG（Joint Test Action Group）接口，OpenOCD 和 GDB 是如何相互连接从而实现 ESP32 的调试功能。 + 介绍 {IDF_TARGET_NAME}，JTAG（Joint Test Action Group）接口，OpenOCD 和 GDB 是如何相互连接从而实现 {IDF_TARGET_NAME} 的调试功能。 :ref:`jtag-debugging-selecting-jtag-adapter` 介绍有关 JTAG 硬件适配器的选择及参照标准。 :ref:`jtag-debugging-setup-openocd` 介绍如何安装官方预编译好的 OpenOCD 软件包并验证是否安装成功。 -:ref:`jtag-debugging-configuring-esp32-target` +:ref:`jtag-debugging-configuring-target` 介绍如何设置 OpenOCD 软件并安装 JTAG 硬件适配器，这两者共同组成最终的调试目标。 :ref:`jtag-debugging-launching-debugger` 介绍如何从 :ref:`Eclipse 集成开发环境 ` 和 :ref:`命令行终端 ` 启动 GDB 调试会话。 @@ -21,20 +21,22 @@ JTAG 调试 :ref:`jtag-debugging-building-openocd` 介绍如何在 :doc:`Windows `，:doc:`Linux ` 和 :doc:`MacOS ` 操作系统上从源码构建 OpenOCD。 :ref:`jtag-debugging-tips-and-quirks` - 介绍使用 OpenOCD 和 GDB 通过 JTAG 接口调试 ESP32 时的注意事项和补充内容。 + 介绍使用 OpenOCD 和 GDB 通过 JTAG 接口调试 {IDF_TARGET_NAME} 时的注意事项和补充内容。 .. _jtag-debugging-introduction: 引言 ---- -ESP32 具有两个强大的 Xtensa 内核，支持多种程序架构。ESP-IDF 自带的 FreeRTOS 操作系统具有多核抢占式多线程的功能，它允许用户以更加直观的方式编写软件。 +.. only:: esp32 -与此相对地，简便的编程方式会给程序的调试带来困难（如果没有合适的工具），比如找出由两个线程引起的错误，并且这两个线程在单独的 CPU 核上同时运行，仅凭 ``printf`` 语句会花费很长的时间来定位到该错误。在大多数情况下，调试此类问题更快的方法是使用调试器，连接到处理器的调试端口。 + ESP32 具有两个强大的 Xtensa 内核，支持多种程序架构。ESP-IDF 自带的 FreeRTOS 操作系统具有多核抢占式多线程的功能，它允许用户以更加直观的方式编写软件。 -乐鑫已经为 ESP32 处理器和多核 FreeRTOS 架构移植好了 OpenOCD，它将成为大多数 ESP32 应用程序的基础。此外，乐鑫还提供了一些 OpenOCD 本身并不支持的工具来进一步丰富调试的功能。 + 与此相对地，简便的编程方式会给程序的调试带来困难（如果没有合适的工具），比如找出由两个线程引起的错误，并且这两个线程在单独的 CPU 核上同时运行，仅凭 ``printf`` 语句会花费很长的时间来定位到该错误。在大多数情况下，调试此类问题更快的方法是使用调试器，连接到处理器的调试端口。 -本文将指导如何在 Linux，Windows 和 MacOS 环境下为 ESP32 安装 OpenOCD，并使用 GDB 进行软件调试。除了个别操作系统的安装过程有所差别以外，软件用户界面和使用流程都是一样的。 +乐鑫已经为 {IDF_TARGET_NAME} 处理器和多核 FreeRTOS 架构移植好了 OpenOCD，它将成为大多数 {IDF_TARGET_NAME} 应用程序的基础。此外，乐鑫还提供了一些 OpenOCD 本身并不支持的工具来进一步丰富调试的功能。 + +本文将指导如何在 Linux，Windows 和 MacOS 环境下为 {IDF_TARGET_NAME} 安装 OpenOCD，并使用 GDB 进行软件调试。除了个别操作系统的安装过程有所差别以外，软件用户界面和使用流程都是一样的。 .. note:: 本文使用的图片素材来自于 Ubuntu 16.04 LTE 上 Eclipse Neon 3 软件的截图，不同的操作系统（Windows， MacOS 或者 Linux）和 Eclipse 软件版本在用户界面上可能会有细微的差别。 @@ -44,21 +46,21 @@ ESP32 具有两个强大的 Xtensa 内核，支持多种程序架构。ESP-IDF 工作原理 -------- -通过 JTAG（Joint Test Action Group）接口使用 OpenOCD 调试 ESP32 时所需要的一些关键的软件和硬件包括 **xtensa-esp32-elf-gdb -调试器**，**OpenOCD 片上调试器** 和连接到 **ESP32** 目标的 **JTAG 适配器**。 +通过 JTAG（Joint Test Action Group）接口使用 OpenOCD 调试 {IDF_TARGET_NAME} 时所需要的一些关键的软件和硬件包括 **xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb +调试器**，**OpenOCD 片上调试器** 和连接到 **{IDF_TARGET_NAME}** 目标的 **JTAG 适配器**。 .. figure:: ../../../_static/jtag-debugging-overview_zh.jpg :align: center - :alt: JTAG debugging - overview diagram + :alt: JTAG debugging - overview diagram :figclass: align-center JTAG 调试 - 概述图 -在 “Application Loading and Monitoring” 下还有另外一组软件和硬件，它们用来编译、构建和烧写应用程序到 ESP32 上，以及监视来自 ESP32 的运行诊断信息。 +在 “Application Loading and Monitoring” 下还有另外一组软件和硬件，它们用来编译、构建和烧写应用程序到 {IDF_TARGET_NAME} 上，以及监视来自 {IDF_TARGET_NAME} 的运行诊断信息。 `Eclipse `__ 环境集成了 JTAG 调试和应用程序加载、监视的功能，它使得软件从编写、编译、加载到调试的迭代过程变得更加快速而简单。所有的软件均适用于 Windows，Linux 和 MacOS 平台。 -如果你使用的是 :doc:`ESP-WROVER-KIT 开发板 <../../hw-reference/modules-and-boards>`，得益于板载的 FT232H 芯片，PC 和 ESP32 的连接仅仅需要一根 USB 线即可完成。FT232H 提供了两路 USB 通道，一路连接到 JTAG，另一路连接到 UART。 +如果你使用的是 :doc:`ESP-WROVER-KIT 开发板 <../../hw-reference/modules-and-boards>`，得益于板载的 FT232H 芯片，PC 和 {IDF_TARGET_NAME} 的连接仅仅需要一根 USB 线即可完成。FT232H 提供了两路 USB 通道，一路连接到 JTAG，另一路连接到 UART。 根据用户的喜好，除了使用 Eclipse 集成开发环境，还可以直接在命令行终端运行 `debugger` 和 `idf.py build`。 @@ -67,13 +69,13 @@ ESP32 具有两个强大的 Xtensa 内核，支持多种程序架构。ESP-IDF 选择 JTAG 适配器 ---------------- -上手 JTAG 最快速便捷的方式是使用 :doc:`ESP-WROVER-KIT 开发板 <../../hw-reference/modules-and-boards>`，因为它板载了 JTAG 调试接口，无需使用外部的 JTAG 硬件适配器和额外的线缆来连接 JTAG 与 ESP32。ESP-WROVER-KIT 采用 FT2232H 提供的 JTAG 接口，可以稳定运行在 20 MHz 的时钟频率，外接的适配器很难达到这个速度。 +上手 JTAG 最快速便捷的方式是使用 :doc:`ESP-WROVER-KIT 开发板 <../../hw-reference/modules-and-boards>`，因为它板载了 JTAG 调试接口，无需使用外部的 JTAG 硬件适配器和额外的线缆来连接 JTAG 与 {IDF_TARGET_NAME}。ESP-WROVER-KIT 采用 FT2232H 提供的 JTAG 接口，可以稳定运行在 20 MHz 的时钟频率，外接的适配器很难达到这个速度。 -如果你想使用单独的 JTAG 适配器，请确保其与 ESP32 的电平电压和 OpenOCD 软件都兼容。ESP32 使用的是业界标准的 JTAG 接口，它省略了（实际上也并不需要）TRST 信号脚。JTAG 使用的 IO 引脚由 VDD_3P3_RTC 电源引脚供电（通常连接到外部 3.3 V 的电源轨），因此 JTAG 硬件适配器的引脚需要能够在该电压范围内正常工作。 +如果你想使用单独的 JTAG 适配器，请确保其与 {IDF_TARGET_NAME} 的电平电压和 OpenOCD 软件都兼容。{IDF_TARGET_NAME} 使用的是业界标准的 JTAG 接口，它省略了（实际上也并不需要）TRST 信号脚。JTAG 使用的 IO 引脚由 VDD_3P3_RTC 电源引脚供电（通常连接到外部 3.3 V 的电源轨），因此 JTAG 硬件适配器的引脚需要能够在该电压范围内正常工作。 -在软件方面，OpenOCD 支持相当多数量的 JTAG 适配器，可以参阅 `OpenOCD 支持的适配器列表 `_ （尽管上面显示的器件不太完整），这个页面还列出了兼容 SWD 接口的适配器，但是请注意，ESP32 目前并不支持 SWD。此外那些被硬编码为只支持特定产品线的 JTAG 适配器也不能在 ESP32 上工作，比如用于 STM32 产品家族的 ST-LINK 适配器。 +在软件方面，OpenOCD 支持相当多数量的 JTAG 适配器，可以参阅 `OpenOCD 支持的适配器列表 `_ （尽管上面显示的器件不太完整），这个页面还列出了兼容 SWD 接口的适配器，但是请注意，{IDF_TARGET_NAME} 目前并不支持 SWD。此外那些被硬编码为只支持特定产品线的 JTAG 适配器也不能在 {IDF_TARGET_NAME} 上工作，比如用于 STM32 产品家族的 ST-LINK 适配器。 -JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 GND。某些 JTAG 适配器还需要 ESP32 提供一路电源到适配器的某个引脚上（比如 Vtar）用以设置适配器的工作电压。SRST 信号线是可选的，它可以连接到 ESP32 的 CH_PD 引脚上，尽管目前 OpenOCD 对该信号线的支持还非常有限。 +JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 GND。某些 JTAG 适配器还需要 {IDF_TARGET_NAME} 提供一路电源到适配器的某个引脚上（比如 Vtar）用以设置适配器的工作电压。SRST 信号线是可选的，它可以连接到 {IDF_TARGET_NAME} 的 CH_PD 引脚上，尽管目前 OpenOCD 对该信号线的支持还非常有限。 .. _jtag-debugging-setup-openocd: @@ -105,12 +107,12 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G 另外，我们还可以从源代码编译 OpenOCD 工具，相关详细信息请参阅 :ref:`jtag-debugging-building-openocd` 章节。 -.. _jtag-debugging-configuring-esp32-target: +.. _jtag-debugging-configuring-target: -配置 ESP32 目标板 ------------------ +配置 {IDF_TARGET_NAME} 目标板 +---------------------------- -安装好 OpenOCD 之后就可以配置 ESP32 目标（即带 JTAG 接口的 ESP32 板），具体可以通过以下三个步骤进行： +安装好 OpenOCD 之后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG 接口的 {IDF_TARGET_NAME} 板），具体可以通过以下三个步骤进行： - 配置并连接 JTAG 接口 - 运行 OpenOCD @@ -120,7 +122,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G 配置并连接 JTAG 接口 ~~~~~~~~~~~~~~~~~~~~ -此步骤取决于您使用的 JTAG 和 ESP32 板，请参考以下两种情况。 +此步骤取决于您使用的 JTAG 和 {IDF_TARGET_NAME} 板，请参考以下两种情况。 .. toctree:: :maxdepth: 1 @@ -167,7 +169,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G - 如果出现指示权限问题的错误，请参阅 ``~/esp/openocd-esp32`` 目录下 OpenOCD README 文件中关于 “Permissions delegation” 的说明。 - 如果发现配置文件有错误，例如 ``Can't find board/esp32-wrover-kit-3.3v.cfg``，请检查 ``-s`` 后面的路径，OpenOCD 会根据此路径来查找 ``-f`` 指定的文件。此外，还需要检查配置文件是否确实位于该路径下。 -- 如果看到 JTAG 错误（输出全是 1 或者全是 0），请检查硬件连接，除了 ESP32 的引脚之外是否还有其他信号连接到了 JTAG，并查看是否所有器件都已经上电。 +- 如果看到 JTAG 错误（输出全是 1 或者全是 0），请检查硬件连接，除了 {IDF_TARGET_NAME} 的引脚之外是否还有其他信号连接到了 JTAG，并查看是否所有器件都已经上电。 .. _jtag-upload-app-debug: @@ -175,7 +177,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G 上传待调试的应用程序 ~~~~~~~~~~~~~~~~~~~~ -您可以像往常一样构建并上传 ESP32 应用程序，具体请参阅 :ref:`get-started-build` 章节。 +您可以像往常一样构建并上传 {IDF_TARGET_NAME} 应用程序，具体请参阅 :ref:`get-started-build` 章节。 除此以外，还支持使用 OpenOCD 通过 JTAG 接口将应用程序镜像烧写到闪存中，命令如下:: @@ -199,7 +201,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G 启动调试器 ---------- -ESP32 的工具链中带有 GNU 调试器（简称 GDB） ``xtensa-esp32-elf-gdb``，它和其它工具链软件存放在同一个 bin 目录下。除了直接在命令行终端中调用并操作 GDB 外，还可以在 IDE (例如 Eclipse，Visual Studio Code 等）中调用它，在图形用户界面的帮助下间接操作 GDB，无需在终端中输入任何命令。 +{IDF_TARGET_NAME} 的工具链中带有 GNU 调试器（简称 GDB） ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb``，它和其它工具链软件存放在同一个 bin 目录下。除了直接在命令行终端中调用并操作 GDB 外，还可以在 IDE (例如 Eclipse，Visual Studio Code 等）中调用它，在图形用户界面的帮助下间接操作 GDB，无需在终端中输入任何命令。 关于以上两种调试器的使用方法，详见以下链接。 @@ -226,7 +228,7 @@ ESP32 的工具链中带有 GNU 调试器（简称 GDB） ``xtensa-esp32-elf-gdb 此外还会提供 :ref:`在命令行终端进行调试 ` 的案例。 -在演示之前，请设置好 ESP32 目标板并加载 :example:`get-started/blink` 至 ESP32 中。 +在演示之前，请设置好 {IDF_TARGET_NAME} 目标板并加载 :example:`get-started/blink` 至 {IDF_TARGET_NAME} 中。 .. _jtag-debugging-building-openocd: diff --git a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst index 54963a3ccf..55fe4c4616 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst @@ -9,7 +9,7 @@ 可用的断点和观察点 ^^^^^^^^^^^^^^^^^^ -ESP32 调试器支持 2 个硬件断点和 64 个软件断点。硬件断点是由 ESP32 芯片内部的逻辑电路实现的，能够设置在代码的任何位置：闪存或者 IRAM 的代码区域。除此以外，OpenOCD 实现了两种软件断点：闪存断点（最多 32 个）和 IRAM 断点（最多 32 个）。目前 GDB 无法在闪存中设置软件断点，因此除非解决此限制，否则这些断点只能由 OpenOCD 模拟为硬件断点。（详细信息可以参阅 :ref:`下面 `）。ESP32 还支持 2 个观察点，所以可以观察两个变量的变化或者通过 GDB 命令 ``watch myVariable`` 来读取变量的值。请注意 menuconfig 中的 :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` 选项会使用第二个观察点，如果你想在 OpenOCD 或者 GDB 中再次尝试使用这个观察点，可能不会得到预期的结果。详情请查看 menuconfig 中的帮助文档。 +{IDF_TARGET_NAME} 调试器支持 2 个硬件断点和 64 个软件断点。硬件断点是由 {IDF_TARGET_NAME} 芯片内部的逻辑电路实现的，能够设置在代码的任何位置：闪存或者 IRAM 的代码区域。除此以外，OpenOCD 实现了两种软件断点：闪存断点（最多 32 个）和 IRAM 断点（最多 32 个）。目前 GDB 无法在闪存中设置软件断点，因此除非解决此限制，否则这些断点只能由 OpenOCD 模拟为硬件断点。（详细信息可以参阅 :ref:`下面 `）。{IDF_TARGET_NAME} 还支持 2 个观察点，所以可以观察两个变量的变化或者通过 GDB 命令 ``watch myVariable`` 来读取变量的值。请注意 menuconfig 中的 :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` 选项会使用第二个观察点，如果你想在 OpenOCD 或者 GDB 中再次尝试使用这个观察点，可能不会得到预期的结果。详情请查看 menuconfig 中的帮助文档。 .. _jtag-debugging-tip-where-breakpoints: @@ -25,9 +25,9 @@ ESP32 调试器支持 2 个硬件断点和 64 个软件断点。硬件断点是 闪存映射 vs 软件闪存断点 ^^^^^^^^^^^^^^^^^^^^^^^^ -为了在闪存中设置或者清除软件断点，OpenOCD 需要知道它们在闪存中的地址。为了完成从 ESP32 的地址空间到闪存地址的转换，OpenOCD 使用闪存中程序代码区域的映射。这些映射被保存在程序映像的头部，位于二进制数据（代码段和数据段）之前，并且特定于写入闪存的每一个应用程序的映像。因此，为了支持软件闪存断点，OpenOCD 需要知道待调试的应用程序映像在闪存中的位置。默认情况下，OpenOCD 会在 0x8000 处读取分区表并使用第一个找到的应用程序映像的映射，但是也可能会存在无法工作的情况，比如分区表不在标准的闪存位置，甚至可能有多个映像：一个出厂映像和两个 OTA 映像，你可能想要调试其中的任意一个。为了涵盖所有可能的调试情况，OpenOCD 支持特殊的命令，用于指定待调试的应用程序映像在闪存中的具体位置。该命令具有以下格式： +为了在闪存中设置或者清除软件断点，OpenOCD 需要知道它们在闪存中的地址。为了完成从 {IDF_TARGET_NAME} 的地址空间到闪存地址的转换，OpenOCD 使用闪存中程序代码区域的映射。这些映射被保存在程序映像的头部，位于二进制数据（代码段和数据段）之前，并且特定于写入闪存的每一个应用程序的映像。因此，为了支持软件闪存断点，OpenOCD 需要知道待调试的应用程序映像在闪存中的位置。默认情况下，OpenOCD 会在 0x8000 处读取分区表并使用第一个找到的应用程序映像的映射，但是也可能会存在无法工作的情况，比如分区表不在标准的闪存位置，甚至可能有多个映像：一个出厂映像和两个 OTA 映像，你可能想要调试其中的任意一个。为了涵盖所有可能的调试情况，OpenOCD 支持特殊的命令，用于指定待调试的应用程序映像在闪存中的具体位置。该命令具有以下格式： -``esp32 appimage_offset `` +``esp32 appimage_offset `` 偏移量应为十六进制格式，如果要恢复默认行为，可以将偏移地址设置为 ``-1`` 。 @@ -54,13 +54,7 @@ OpenOCD 支持的编译时的选项 ESP-IDF 有一些针对 OpenOCD 调试功能的选项可以在编译时进行设置： -.. only:: esp32 - - * :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` 默认会被使能。如果程序抛出了不可修复或者未处理的异常，并且此时已经连接上了 JTAG 调试器（即 OpenOCD 正在运行），那么 ESP-IDF 将会进入调试器工作模式。 - -.. only:: esp32s2 - - * :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` 默认会被使能。如果程序抛出了不可修复或者未处理的异常，并且此时已经连接上了 JTAG 调试器（即 OpenOCD 正在运行），那么 ESP-IDF 将会进入调试器工作模式。 +* :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEBUG_OCDAWARE` 默认会被使能。如果程序抛出了不可修复或者未处理的异常，并且此时已经连接上了 JTAG 调试器（即 OpenOCD 正在运行），那么 ESP-IDF 将会进入调试器工作模式。 * :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` 默认没有使能。在所有任务堆栈的末尾设置观察点，从 1 号开始索引。这是调试任务堆栈溢出的最准确的方式。 @@ -76,14 +70,16 @@ OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRT .. _jtag-debugging-tip-code-flash-voltage: -在 OpenOCD 的配置文件中设置 SPI 闪存的工作电压 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. only:: esp33 -ESP32 的 MTDI 引脚是用于 JTAG 通信的四个引脚之一，同时也是 ESP32 的 bootstrapping 引脚。上电时，ESP32 会在 MTDI 引脚上采样二进制电平，据此来设置内部的稳压器，用于给外部的 SPI 闪存芯片供电。如果上电时 MTDI 引脚上的二进制电平为低电平，则稳压器会被设置为 3.3 V；如果 MTDI 引脚为高电平，则稳压器会被设置为 1.8 V。MTDI 引脚通常需要一个上拉电阻或者直接使能内部的弱下拉电阻（详见 `ESP32 系列芯片技术规格书 `_ ），具体取决于所使用的 SPI 芯片的类型。但是一旦连接上 JTAG 后，原来用于实现 bootstrapping 功能的上拉或者下拉电阻都会被覆盖掉。 + 在 OpenOCD 的配置文件中设置 SPI 闪存的工作电压 + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -为了解决这个问题，OpenOCD 的板级配置文件（例如 ESP32-WROOM-32 模组的 ``boards\esp-wroom-32.cfg``）提供了 ``ESP32_FLASH_VOLTAGE`` 参数来设置 ``TDO`` 信号线在空闲状态下的二进制电平，这样就可以减少由于闪存电压不正确而导致的应用程序启动不良的几率。 + ESP32 的 MTDI 引脚是用于 JTAG 通信的四个引脚之一，同时也是 ESP32 的 bootstrapping 引脚。上电时，ESP32 会在 MTDI 引脚上采样二进制电平，据此来设置内部的稳压器，用于给外部的 SPI 闪存芯片供电。如果上电时 MTDI 引脚上的二进制电平为低电平，则稳压器会被设置为 3.3 V；如果 MTDI 引脚为高电平，则稳压器会被设置为 1.8 V。MTDI 引脚通常需要一个上拉电阻或者直接使能内部的弱下拉电阻（详见 `ESP32 系列芯片技术规格书 `_ ），具体取决于所使用的 SPI 芯片的类型。但是一旦连接上 JTAG 后，原来用于实现 bootstrapping 功能的上拉或者下拉电阻都会被覆盖掉。 -查看 JTAG 连接的 ESP32 模组的规格书，检查其 SPI 闪存芯片的供电电压值，然后再相应的设置 ``ESP32_FLASH_VOLTAGE``。大多数的 WROOM 模组使用 3.3 V 的闪存芯片，但是 WROVER 模组使用 1.8 V 的闪存芯片。 + 为了解决这个问题，OpenOCD 的板级配置文件（例如 ESP32-WROOM-32 模组的 ``boards\esp-wroom-32.cfg``）提供了 ``ESP32_FLASH_VOLTAGE`` 参数来设置 ``TDO`` 信号线在空闲状态下的二进制电平，这样就可以减少由于闪存电压不正确而导致的应用程序启动不良的几率。 + + 查看 JTAG 连接的 ESP32 模组的规格书，检查其 SPI 闪存芯片的供电电压值，然后再相应的设置 ``ESP32_FLASH_VOLTAGE``。大多数的 WROOM 模组使用 3.3 V 的闪存芯片，但是 WROVER 模组使用 1.8 V 的闪存芯片。 .. _jtag-debugging-tip-optimize-jtag-speed: @@ -106,7 +102,7 @@ ESP32 的 MTDI 引脚是用于 JTAG 通信的四个引脚之一，同时也是 E 在启动时，调试器发出一系列命令来复位芯片并使其在特定的代码行停止运行。这个命令序列（如下所示）支持自定义，用户可以选择在最方便合适的代码行开始调试工作。 -* ``set remote hardware-watchpoint-limit 2`` — 限制 GDB 仅使用 ESP32 支持的两个硬件观察点。更多详细信息，请查阅 `GDB 配置远程目标 `_ 。 +* ``set remote hardware-watchpoint-limit 2`` — 限制 GDB 仅使用 {IDF_TARGET_NAME} 支持的两个硬件观察点。更多详细信息，请查阅 `GDB 配置远程目标 `_ 。 * ``mon reset halt`` — 复位芯片并使 CPU 停止运行。 * ``flushregs`` — monitor (``mon``) 命令无法通知 GDB 目标状态已经更改，GDB 会假设在 ``mon reset halt`` 之前所有的任务堆栈仍然有效。实际上，复位后目标状态将发生变化。执行 ``flushregs`` 是一种强制 GDB 从目标获取最新状态的方法。 * ``thb app_main`` — 在 ``app_main`` 处插入一个临时的硬件断点，如果有需要，可以将其替换为其他函数名。 @@ -139,14 +135,16 @@ OpenOCD 需要知道当前使用的 JTAG 适配器的类型，以及其连接的 请参阅 :ref:`jtag-debugging-tip-optimize-jtag-speed` 以获取有关如何设置此值的指导。 -单核调试 -"""""""" +.. only:: esp32 -:: + 单核调试 + """""""" - set ESP32_ONLYCPU 1 + :: -如果是双核调试，请注释掉这一行。 + set ESP32_ONLYCPU 1 + + 如果是双核调试，请注释掉这一行。 禁用 RTOS 支持 @@ -169,40 +167,44 @@ ESP32 的 SPI 闪存芯片的电源电压 如果 SPI 闪存芯片的电源电压为 3.3 V， 请注释掉这一行，更多信息请参阅： :ref:`jtag-debugging-tip-code-flash-voltage`。 + + ESP32 的目标配置文件 """""""""""""""""""" -:: +.. only:: esp32 - source [find target/esp32.cfg] + :: -.. note:: + source [find target/esp32.cfg] - 除非你熟悉 OpenOCD 内部的工作原理，否则请不要更改 ``source [find target/esp32.cfg]`` 这一行。 + .. note:: -目前 ``target/esp32.cfg`` 仍然是 ESP32 目标（esp108 和 esp32）的唯一配置文件。支持的配置矩阵如下所示： + 除非你熟悉 OpenOCD 内部的工作原理，否则请不要更改 ``source [find target/esp32.cfg]`` 这一行。 - +---------------+---------------+---------------+ - | Dual/single | RTOS | Target used | - +===============+===============+===============+ - | dual | FreeRTOS | esp32 | - +---------------+---------------+---------------+ - | single | FreeRTOS | esp108 (*) | - +---------------+---------------+---------------+ - | dual | none | esp108 | - +---------------+---------------+---------------+ - | single | none | esp108 | - +---------------+---------------+---------------+ + 目前 ``target/esp32.cfg`` 仍然是 ESP32 目标（esp108 和 esp32）的唯一配置文件。支持的配置矩阵如下所示： - (*) — 我们计划修复此问题，并在后续提交中添加对 esp32 目标的单核调试的支持。 + +---------------+---------------+---------------+ + | Dual/single | RTOS | Target used | + +===============+===============+===============+ + | dual | FreeRTOS | esp32 | + +---------------+---------------+---------------+ + | single | FreeRTOS | esp108 (*) | + +---------------+---------------+---------------+ + | dual | none | esp108 | + +---------------+---------------+---------------+ + | single | none | esp108 | + +---------------+---------------+---------------+ -更多信息，请查看 ``board/esp-wroom-32.cfg`` 配置文件的注释部分。 + (*) — 我们计划修复此问题，并在后续提交中添加对 esp32 目标的单核调试的支持。 + + 更多信息，请查看 ``board/esp-wroom-32.cfg`` 配置文件的注释部分。 .. _jtag-debugging-tip-reset-by-debugger: -复位 ESP32 -^^^^^^^^^^ +复位 {IDF_TARGET_NAME} +^^^^^^^^^^^^^^^^^^^^^ 通过在 GDB 中输入 ``mon reset`` 或者 ``mon reset halt`` 来复位板子。 @@ -212,7 +214,9 @@ ESP32 的目标配置文件 不要将 JTAG 引脚用于其他功能 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -如果除了 ESP32 模组和 JTAG 适配器之外的其他硬件也连接到了 JTAG 引脚，那么 JTAG 的操作可能会受到干扰。ESP32 JTAG 使用以下引脚： +如果除了 {IDF_TARGET_NAME} 模组和 JTAG 适配器之外的其他硬件也连接到了 JTAG 引脚，那么 JTAG 的操作可能会受到干扰。{IDF_TARGET_NAME} JTAG 使用以下引脚： + +.. only:: esp32 +---+----------------+-------------+ | | ESP32 JTAG Pin | JTAG Signal | @@ -226,7 +230,21 @@ ESP32 的目标配置文件 | 4 | MTMS / GPIO14 | TMS | +---+----------------+-------------+ -如果用户应用程序更改了 JTAG 引脚的配置，JTAG 通信可能会失败。如果 OpenOCD 正确初始化（检测到两个 Tensilica 内核），但在程序运行期间失去了同步并报出大量 DTR/DIR 错误，则应用程序可能将 JTAG 引脚重新配置为其他功能或者用户忘记将 Vtar 连接到 JTAG 适配器。 +.. only:: esp32s2 + + +---+-----------------------+-------------+ + | | ESP32-S2 Pin | JTAG Signal | + +===+=======================+=============+ + | 1 | MTDO / GPIO40 | TDO | + +---+-----------------------+-------------+ + | 2 | MTDI / GPIO41 | TDI | + +---+-----------------------+-------------+ + | 3 | MTCK / GPIO39 | TCK | + +---+-----------------------+-------------+ + | 4 | MTMS / GPIO42 | TMS | + +---+-----------------------+-------------+ + +如果用户应用程序更改了 JTAG 引脚的配置，JTAG 通信可能会失败。如果 OpenOCD 正确初始化（检测到两个 Tensilica 内核），但在程序运行期间失去了同步并报出大量 DTR/DIR 错误，则应用程序可能将 JTAG 引脚重新配置为其他功能或者用户忘记将 Vtar 连接到 JTAG 适配器。 .. highlight:: none @@ -276,7 +294,7 @@ ESP32 的目标配置文件 :: - xtensa-esp32-elf-gdb -ex "set remotelogfile gdb_log.txt" + xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -ex "set remotelogfile gdb_log.txt" 也可以将命令 ``remotelogfile gdb_log.txt`` 添加到 ``gdbinit`` 文件中。 diff --git a/docs/zh_CN/api-guides/jtag-debugging/using-debugger.rst b/docs/zh_CN/api-guides/jtag-debugging/using-debugger.rst index e57f354625..ee0c751cc5 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/using-debugger.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/using-debugger.rst @@ -35,7 +35,7 @@ GDB 硬件调试的配置 - Main 选项卡 -6. 点击 “Debugger” 选项卡，在 “GDB Command” 栏中输入 ``xtensa-esp32-elf-gdb`` 来调用调试器。 +6. 点击 “Debugger” 选项卡，在 “GDB Command” 栏中输入 ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb`` 来调用调试器。 7. 更改 “Remote host” 的默认配置，在 “Port number” 下面输入 ``3333``。 @@ -82,9 +82,9 @@ 上面的启动序列看起来有些复杂，如果你对其中的初始化命令不太熟悉，请查阅 :ref:`jtag-debugging-tip-debugger-startup-commands` 章节获取更多说明。 -12. 如果你前面已经完成 :ref:`jtag-debugging-configuring-esp32-target` 中介绍的步骤，那么目标正在运行并准备与调试器进行对话。按下 “Debug” 按钮就可以直接调试。否则请按下 “Apply” 按钮保存配置，返回 :ref:`jtag-debugging-configuring-esp32-target` 章节进行配置，最后再回到这里开始调试。 +12. 如果你前面已经完成 :ref:`jtag-debugging-configuring-target` 中介绍的步骤，那么目标正在运行并准备与调试器进行对话。按下 “Debug” 按钮就可以直接调试。否则请按下 “Apply” 按钮保存配置，返回 :ref:`jtag-debugging-configuring-target` 章节进行配置，最后再回到这里开始调试。 -一旦所有 1 - 12 的配置步骤都已经完成，Eclipse 就会打开 “Debug” 视图，如下图所示。 +一旦所有 1 - 12 的配置步骤都已经完成，Eclipse 就会打开 “Debug” 视图，如下图所示。 .. figure:: ../../../_static/debug-perspective.jpg :align: center @@ -101,7 +101,7 @@ 在命令行中使用 GDB ^^^^^^^^^^^^^^^^^^ -1. 为了能够启动调试会话，需要先启动并运行目标，如果还没有完成，请按照 :ref:`jtag-debugging-configuring-esp32-target` 中的介绍进行操作。 +1. 为了能够启动调试会话，需要先启动并运行目标，如果还没有完成，请按照 :ref:`jtag-debugging-configuring-target` 中的介绍进行操作。 .. highlight:: bash @@ -124,7 +124,7 @@ thb app_main c - 将此文件保存在当前目录中。 + 将此文件保存在当前目录中。 有关 ``gdbinit`` 文件内部的更多详细信息，请参阅 :ref:`jtag-debugging-tip-debugger-startup-commands` 章节。 @@ -134,7 +134,7 @@ :: - xtensa-esp32-elf-gdb -x gdbinit build/blink.elf + xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit build/blink.elf .. highlight:: none @@ -142,14 +142,14 @@ :: - user-name@computer-name:~/esp/blink$ xtensa-esp32-elf-gdb -x gdbinit build/blink.elf + user-name@computer-name:~/esp/blink$ xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit build/blink.elf GNU gdb (crosstool-NG crosstool-ng-1.22.0-61-gab8375a) 7.10 Copyright (C) 2015 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. - This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=xtensa-esp32-elf". + This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf". Type "show configuration" for configuration details. For bug reporting instructions, please see: . @@ -158,20 +158,20 @@ For help, type "help". Type "apropos word" to search for commands related to "word"... Reading symbols from build/blink.elf...done. - 0x400d10d8 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/esp32/./freertos_hooks.c:52 + 0x400d10d8 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/{IDF_TARGET_TOOLCHAIN_NAME}/./freertos_hooks.c:52 52 asm("waiti 0"); - JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - JTAG tap: esp32.slave tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F). - esp32: Core was reset (pwrstat=0x5F, after clear 0x0F). - Target halted. PRO_CPU: PC=0x5000004B (active) APP_CPU: PC=0x00000000 - esp32: target state: halted - esp32: Core was reset (pwrstat=0x1F, after clear 0x0F). - Target halted. PRO_CPU: PC=0x40000400 (active) APP_CPU: PC=0x40000400 - esp32: target state: halted + JTAG tap: {IDF_TARGET_PATH_NAME}.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) + JTAG tap: {IDF_TARGET_PATH_NAME}.slave tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) + {IDF_TARGET_PATH_NAME}: Debug controller was reset (pwrstat=0x5F, after clear 0x0F). + {IDF_TARGET_PATH_NAME}: Core was reset (pwrstat=0x5F, after clear 0x0F). + {IDF_TARGET_PATH_NAME} halted. PRO_CPU: PC=0x5000004B (active) APP_CPU: PC=0x00000000 + {IDF_TARGET_PATH_NAME}: target state: halted + {IDF_TARGET_PATH_NAME}: Core was reset (pwrstat=0x1F, after clear 0x0F). + Target halted. PRO_CPU: PC=0x40000400 (active) APP_CPU: PC=0x40000400 + {IDF_TARGET_PATH_NAME}: target state: halted Hardware assisted breakpoint 1 at 0x400db717: file /home/user-name/esp/blink/main/./blink.c, line 43. 0x0: 0x00000000 - Target halted. PRO_CPU: PC=0x400DB717 (active) APP_CPU: PC=0x400D10D8 + Target halted. PRO_CPU: PC=0x400DB717 (active) APP_CPU: PC=0x400D10D8 [New Thread 1073428656] [New Thread 1073413708] [New Thread 1073431316] @@ -183,7 +183,7 @@ Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink.c:43 43 xTaskCreate(&blink_task, "blink_task", 512, NULL, 5, NULL); - (gdb) + (gdb) 注意上面日志的倒数第三行显示了调试器已经在 ``app_main()`` 函数的断点处停止，该断点在 ``gdbinit`` 文件中设定。由于处理器已经暂停运行，LED 也不会闪烁。如果这也是你看到的现象，你可以开始调试了。 diff --git a/docs/zh_CN/api-guides/linker-script-generation.rst b/docs/zh_CN/api-guides/linker-script-generation.rst index 9e47f70445..d639b5f1de 100644 --- a/docs/zh_CN/api-guides/linker-script-generation.rst +++ b/docs/zh_CN/api-guides/linker-script-generation.rst @@ -5,7 +5,7 @@ 概述 ---- -ESP32 的代码和数据可以存放在多个 :ref:`内存区域 `。通常，代码和只读数据存放在 flash 区域，可写数据存放在内存中。我们经常需要更改代码或者数据的默认映射区域，例如为了提高性能，将关键部分的代码和只读数据放置到内存中，或者将代码、数据和只读数据存放到 RTC 内存中以便在 :doc:`唤醒桩 ` 和 :doc:`ULP 协处理器 ` 中使用。 +{IDF_TARGET_NAME} 的代码和数据可以存放在多个 :ref:`内存区域 `。通常，代码和只读数据存放在 flash 区域，可写数据存放在内存中。我们经常需要更改代码或者数据的默认映射区域，例如为了提高性能，将关键部分的代码和只读数据放置到内存中，或者将代码、数据和只读数据存放到 RTC 内存中以便在 :doc:`唤醒桩 ` 和 :doc:`ULP 协处理器 ` 中使用。 IDF 的链接脚本生成机制允许用户在组件级别定义代码和数据的存放区域。组件通过 :ref:`链接片段文件 ` 描述如何映射目标文件的输入段（甚至可以是某个具体的函数或者数据）。在构建应用程序时，链接片段文件会被收集、解析并处理，然后扩充到 :ref:`链接脚本模板 ` 中形成最终的链接脚本文件，该链接脚本会被用于链接最终的二进制应用程序。 @@ -99,8 +99,8 @@ CMake [mapping] archive: libcomponent.a entries: - object1:function1 (noflash) - object2:function2 (rtc) + object1:function1 (noflash) + object2:function2 (rtc) ``object1.o`` 和 ``object2.o`` 的剩余函数以及整个 ``object3.o`` 目标文件会被存放到默认区域。指定数据存放区域的方法很类似，仅需将 ``：`` 之后的函数名，替换为变量名即可。 @@ -179,7 +179,7 @@ CMake else if CONFIG_PERFORMANCE_LEVEL == 1 only place object1.o in RAM else - place entire libcomponent.a in RTC memory + place entire libcomponent.a in RTC memory 条件测试还支持 :ref:`其他操作 `。 @@ -220,7 +220,7 @@ CMake I. sections 片段 """""""""""""""" -sections 片段定义了 GCC 编译器输出的目标文件段的列表，可以是默认的段（比如 ``.text`` 段、``.data`` 段），也可以是用户通过 ``__attribute__`` 关键字自定义的段。 +sections 片段定义了 GCC 编译器输出的目标文件段的列表，可以是默认的段（比如 ``.text`` 段、``.data`` 段），也可以是用户通过 ``__attribute__`` 关键字自定义的段。 此外，用户还可以在某类段后增加一个 ``+``，表示囊括列表中的“所有这类段”和“所有以这类段开头的段”。相较于显式地罗列所有的段，我们更推荐使用这种方式。 @@ -257,7 +257,7 @@ sections 片段定义了 GCC 编译器输出的目标文件段的列表，可以 II. scheme 片段 """"""""""""""" -scheme 片段定义了为每个 sections 指定的 ``target``。 +scheme 片段定义了为每个 sections 指定的 ``target``。 **语法** @@ -288,11 +288,11 @@ scheme 片段定义了为每个 sections 指定的 ``target``。 *(.literal .literal.* .text .text.*) -此后，这些生成的 catch-all 规则将用于未指定映射规则的情况。 +此后，这些生成的 catch-all 规则将用于未指定映射规则的情况。 .. note:: - ``default`` scheme 是在 :component:`esp32/ld/esp32_fragments.lf` 文件中定义的，此外，快速上手指南中提到的内置 ``noflash`` scheme 片段和 ``rtc`` scheme 片段也是在这个文件中定义的。 + ``default`` scheme 是在 :component:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}_fragments.lf` 文件中定义的，此外，快速上手指南中提到的内置 ``noflash`` scheme 片段和 ``rtc`` scheme 片段也是在这个文件中定义的。 .. _ldgen-mapping-fragment : @@ -337,7 +337,7 @@ mapping 片段的映射条目共有三种类型，分别为： ``Type III`` 指定了 ``*``，也就是指定了归档文件中所有目标文件。 -接下来，让我们通过展开一个 ``Type II`` 映射条目，更好地理解映射条目的含义。最初： +接下来，让我们通过展开一个 ``Type II`` 映射条目，更好地理解映射条目的含义。最初： .. code-block:: none @@ -347,8 +347,8 @@ mapping 片段的映射条目共有三种类型，分别为： .. code-block:: none - object (sections -> target, - sections -> target, + object (sections -> target, + sections -> target, ...) 然后再根据条目定义，将这个 sections 片段展开： @@ -358,11 +358,11 @@ mapping 片段的映射条目共有三种类型，分别为： object (.section, .section, ... -> target, # 根据目标文件将这里所列出的所有段放在该目标位置 - + .section, .section, - ... -> target, # 同样的方法指定其他段 - + ... -> target, # 同样的方法指定其他段 + ...) # 直至所有段均已展开 .. _ldgen-type1-limitations : @@ -395,11 +395,11 @@ mapping 片段的映射条目共有三种类型，分别为： [mapping:lwip] archive: liblwip.a entries: - : LWIP_IRAM_OPTIMIZATION = y # 如果 CONFIG_LWIP_IRAM_OPTIMIZATION 在 sdkconfig 中被定义为 'y' + : LWIP_IRAM_OPTIMIZATION = y # 如果 CONFIG_LWIP_IRAM_OPTIMIZATION 在 sdkconfig 中被定义为 'y' ip4:ip4_route_src_hook (noflash) # 将 ip4.o:ip4_route_src_hook，ip4.o:ip4_route_src 和 ip4:ip4_route_src (noflash) # ip4.o:ip4_route 映射到 noflash scheme ip4:ip4_route (noflash) # 该 scheme 会将他们存放到 RAM 中 - + : default # 否则不使用特殊的映射规则 .. _ldgen-script-templates : @@ -491,7 +491,7 @@ mapping 片段的映射条目共有三种类型，分别为： 链接脚本模板 ^^^^^^^^^^^^ -目前使用的链接脚本模板是 :component:`esp32/ld/esp32.project.ld.in`，仅用于应用程序的构建，生成的链接脚本文件将放在同一组件的构建目录下。值得注意的是，修改此链接描述文件模板会触发应用程序的二进制文件的重新链接。 +目前使用的链接脚本模板是 :component:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}.project.ld.in`，仅用于应用程序的构建，生成的链接脚本文件将放在同一组件的构建目录下。值得注意的是，修改此链接描述文件模板会触发应用程序的二进制文件的重新链接。 链接片段文件 ^^^^^^^^^^^^ diff --git a/docs/zh_CN/api-guides/partition-tables.rst b/docs/zh_CN/api-guides/partition-tables.rst index 24786bb4e9..7f6404e1bc 100644 --- a/docs/zh_CN/api-guides/partition-tables.rst +++ b/docs/zh_CN/api-guides/partition-tables.rst @@ -5,9 +5,9 @@ 概述 ---- -每片 ESP32 的 flash 可以包含多个应用程序，以及多种不同类型的数据（例如校准数据、文件系统数据、参数存储器数据等）。因此，我们需要引入分区表的概念。 +每片 {IDF_TARGET_NAME} 的 flash 可以包含多个应用程序，以及多种不同类型的数据（例如校准数据、文件系统数据、参数存储器数据等）。因此，我们需要引入分区表的概念。 -具体来说，ESP32 在 flash 的 :ref:`默认偏移地址 ` 0x8000 处烧写一张分区表。该分区表的长度为 0xC00 字节（最多可以保存 95 条分区表条目）。分区表数据后还保存着该表的 MD5 校验和，用于验证分区表的完整性。此外，如果芯片使能了 :doc:`安全启动 ` 功能，则该分区表后还会保存签名信息。 +具体来说，{IDF_TARGET_NAME} 在 flash 的 :ref:`默认偏移地址 ` 0x8000 处烧写一张分区表。该分区表的长度为 0xC00 字节（最多可以保存 95 条分区表条目）。分区表数据后还保存着该表的 MD5 校验和，用于验证分区表的完整性。此外，如果芯片使能了 :doc:`安全启动 ` 功能，则该分区表后还会保存签名信息。 分区表中的每个条目都包括以下几个部分：Name（标签）、Type（app、data 等）、SubType 以及在 flash 中的偏移量（分区的加载地址）。 @@ -24,7 +24,7 @@ 以下是 "Single factory app, no OTA" 选项的分区表信息摘要： - # Espressif ESP32 Partition Table + # Espressif {IDF_TARGET_NAME} Partition Table # Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x6000, phy_init, data, phy, 0xf000, 0x1000, @@ -35,7 +35,7 @@ 以下是 "Factory app, two OTA definitions" 选项的分区表信息摘要： - # Espressif ESP32 Partition Table + # Espressif {IDF_TARGET_NAME} Partition Table # Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x4000, otadata, data, ota, 0xd000, 0x2000, @@ -70,7 +70,7 @@ CSV 文件的格式与上面摘要中打印的格式相同，但是在 CSV 文 Name 字段 ~~~~~~~~~ -Name 字段可以是任何有意义的名称，但不能超过 16 个字符（之后的内容将被截断）。该字段对 ESP32 并不是特别重要。 +Name 字段可以是任何有意义的名称，但不能超过 16 个字符（之后的内容将被截断）。该字段对 {IDF_TARGET_NAME} 并不是特别重要。 Type 字段 ~~~~~~~~~ @@ -86,7 +86,7 @@ SubType 字段 ~~~~~~~~~~~~ SubType 字段长度为 8 bit，内容与具体 Type 有关。目前，esp-idf 仅仅规定了 “app” 和 “data” 两种子类型。 - + * 当 Type 定义为 ``app`` 时，SubType 字段可以指定为 factory (0)，ota_0 (0x10) ... ota_15 (0x1F) 或者 test (0x20)。 - factory (0) 是默认的 app 分区。Bootloader 将默认加在该应用程序。但如果存在类型为 data/ota 分区，则 Bootloader 将加载 data/ota 分区中的数据，进而判断启动哪个 OTA 镜像文件。 @@ -95,12 +95,12 @@ SubType 字段长度为 8 bit，内容与具体 Type 有关。目前，esp-idf - ota_0 (0x10) ... ota_15 (0x1F) 为 OTA 应用程序分区，Bootloader 将根据 OTA 数据分区中的数据来决定加载哪个 OTA 应用程序分区中的程序。在使用 OTA 功能时，应用程序应至少拥有 2 个 OTA 应用程序分区（ota_0 和 ota_1）。更多详细信息，请参考 :doc:`OTA 文档 ` 。 - test (0x2) 为预留 app 子类型，用于工厂测试过程。注意，目前，esp-idf 并不支持这种子类型。 - + * 当 Type 定义为 ``data`` 时，SubType 字段可以指定为 ota (0)，phy (1)，nvs (2) 或者 nvs_keys (4)。 - ota (0) 即 :ref:`OTA 数据分区 ` ，用于存储当前所选的 OTA 应用程序的信息。这个分区的大小需要设定为 0x2000。更多详细信息，请参考 :doc:`OTA 文档 <../api-reference/system/ota>` 。 - phy (1) 分区用于存放 PHY 初始化数据，从而保证可以为每个设备单独配置 PHY，而非必须采用固件中的统一 PHY 初始化数据。 - + - 默认配置下，phy 分区并不启用，而是直接将 phy 初始化数据编译至应用程序中，从而节省分区表空间（直接将此分区删掉）。 - 如果需要从此分区加载 phy 初始化数据，请打开项目配置菜单（``idf.py menuconfig``），并且使能 :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` 选项。此时，您还需要手动将 phy 初始化数据烧至设备 flash（esp-idf 编译系统并不会自动完成该操作）。 - nvs (2) 是专门给 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 使用的分区。 @@ -133,7 +133,7 @@ Flags 字段 当前仅支持 ``encrypted`` 标记。如果 Flags 字段设置为 ``encrypted``，且已启用 :doc:`Flash Encryption ` 功能，则该分区将会被加密。 -.. note:: +.. note:: ``app`` 分区始终会被加密，不管 Flags 字段是否设置。 @@ -171,7 +171,7 @@ MD5 校验和 在执行 ``idf.py partition_table`` 命令时，手动烧写分区表的命令也将打印在终端上。 -.. note:: +.. note:: 分区表的更新并不会擦除根据之前分区表存储的数据。此时，您可以使用 ``idf.py erase_flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。 diff --git a/docs/zh_CN/api-guides/tools/idf-monitor.rst b/docs/zh_CN/api-guides/tools/idf-monitor.rst index 15078eb0b9..4d83e65732 100644 --- a/docs/zh_CN/api-guides/tools/idf-monitor.rst +++ b/docs/zh_CN/api-guides/tools/idf-monitor.rst @@ -78,11 +78,11 @@ IDF 监视器为寄存器转储补充如下信息:: 0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:47 0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:42 0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:33 - 0x400d071d: main_task at /home/gus/esp/32/idf/components/esp32/./cpu_start.c:254 + 0x400d071d: main_task at /home/gus/esp/32/idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:254 IDF 监视器在后台运行以下命令，解码各地址:: - xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS + xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS 配置 GDBStub 以启用 GDB @@ -92,19 +92,13 @@ IDF 监视器在后台运行以下命令，解码各地址:: 或者选择配置 panic 处理器以运行 GDBStub，GDBStub 工具可以与 GDB_ 项目调试器进行通信，允许读取内存、检查调用堆栈帧和变量等。GDBStub 虽然没有 JTAG 通用，但不需要使用特殊硬件。 -.. only:: esp32 - - 如需启用 GDBStub，请运行 ``idf.py menuconfig`` （适用于 CMake 编译系统），并将 :ref:`CONFIG_ESP32_PANIC` 选项设置为 ``Invoke GDBStub``。 - -.. only:: esp32s2 - - 如需启用 GDBStub，请运行 ``idf.py menuconfig`` （适用于 CMake 编译系统），并将 :ref:`CONFIG_ESP32S2_PANIC` 选项设置为 ``Invoke GDBStub``。 +如需启用 GDBStub，请运行 ``idf.py menuconfig`` （适用于 CMake 编译系统），并将 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC` 选项设置为 ``Invoke GDBStub``。 在这种情况下，如果 panic 处理器被触发，只要 IDF 监视器监控到 GDBStub 已经加载，panic 处理器就会自动暂停串行监控并使用必要的参数运行 GDB。GDB 退出后，通过 RTS 串口线复位开发板。如果未连接 RTS 串口线，请按复位键，手动复位开发板。 IDF 监控器在后台运行如下命令:: - xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf + xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf 输出筛选 diff --git a/docs/zh_CN/api-guides/ulp.rst b/docs/zh_CN/api-guides/ulp.rst index 223e42df4e..b65d3a7581 100644 --- a/docs/zh_CN/api-guides/ulp.rst +++ b/docs/zh_CN/api-guides/ulp.rst @@ -6,8 +6,8 @@ ULP 协处理器编程 .. toctree:: :maxdepth: 1 - ESP32 指令集参考 - ESP32-S2 指令集参考 + :esp32: 指令集参考 + :esp32s2: 指令集参考 使用宏进行编程（遗留） @@ -32,7 +32,7 @@ ULP 协处理器代码是用汇编语言编写的，并使用 `binutils-esp32ulp 1. 用汇编语言编写的 ULP 代码必须导入到一个或多个 `.S` 扩展文件中，且这些文件必须放在组件目录中一个独立的目录中，例如 `ulp/`。 -.. note: 在注册组件（通过 ``idf_component_register``）时，不应将该目录添加到 ``SRC_DIRS`` 参数中。因为 ESP-IDF 构建系统将基于文件扩展名编译在 ``SRC_DIRS`` 中搜索到的文件。对于 ``.S`` 文件，使用的是 ``xtensa-esp32-elf-as`` 汇编器。但这并不适用于 ULP 程序集文件，因此体现这种区别最简单的方式就是将 ULP 程序集文件放到单独的目录中。同样，ULP 程序集源文件也 **不应该** 添加到 ``SRCS`` 中。请参考如下步骤，查看如何正确添加 ULP 程序集源文件。 +.. note: 在注册组件（通过 ``idf_component_register``）时，不应将该目录添加到 ``SRC_DIRS`` 参数中。因为 ESP-IDF 构建系统将基于文件扩展名编译在 ``SRC_DIRS`` 中搜索到的文件。对于 ``.S`` 文件，使用的是 ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-as`` 汇编器。但这并不适用于 ULP 程序集文件，因此体现这种区别最简单的方式就是将 ULP 程序集文件放到单独的目录中。同样，ULP 程序集源文件也 **不应该** 添加到 ``SRCS`` 中。请参考如下步骤，查看如何正确添加 ULP 程序集源文件。 2. 注册后从组件 CMakeLists.txt 中调用 ``ulp_embed_binary`` 示例如下:: @@ -53,9 +53,9 @@ ULP 协处理器代码是用汇编语言编写的，并使用 `binutils-esp32ulp 在内部，构建系统将按照以下步骤编译 ULP 程序： 1. **通过 C 预处理器运行每个程序集文件 (foo.S)。** 此步骤在组件编译目录中生成预处理的程序集文件 (foo.ulp.S)，同时生成依赖文件 (foo.ulp.d)。 - + 2. **通过汇编器运行预处理过的汇编源码。** 此步骤会生成目标文件 (foo.ulp.o) 和清单 (foo.ulp.lst)。清单文件仅用于调试，不用于编译进程的后续步骤。 - + 3. **通过 C 预处理器运行链接器脚本模板。** 模板位于 ``components/ulp/ld`` 目录中。 4. **将目标文件链接到 ELF 输出文件** (``ulp_app_name.elf``)。此步骤生成的.map 文件 (``ulp_app_name.map``) 默认用于调试。 diff --git a/docs/zh_CN/api-guides/unit-tests.rst b/docs/zh_CN/api-guides/unit-tests.rst index d915495644..fed2fd1303 100644 --- a/docs/zh_CN/api-guides/unit-tests.rst +++ b/docs/zh_CN/api-guides/unit-tests.rst @@ -1,5 +1,5 @@ -ESP32 中的单元测试 -========================== +{IDF_TARGET_NAME} 中的单元测试 +============================ :link_to_translation:`en:[English]` ESP-IDF @@ -32,7 +32,7 @@ C 文件可以包含多个测试用例。测试文件的名字要以 “test” 没有必要在每个测试用例中使用 ``UNITY_BEGIN()`` 和 ``UNITY_END()`` 来声明主函数的区域， ``unity_platform.c`` 会自动调用 ``UNITY_BEGIN()``\ ， 然后运行测试用例，最后调用 ``UNITY_END()``。 -``test`` 子目录应包含 ：ref：`组件 CMakeLists.txt `，因为他们本身就是一种组件。ESP-IDF 使用了 +``test`` 子目录应包含 ：ref：`组件 CMakeLists.txt `，因为他们本身就是一种组件。ESP-IDF 使用了 ``unity`` 测试框架，需要将其指定为组件的依赖项。通常，组件 ：ref：`需要手动指定待编译的源文件 `;但是，对于测试组件来说，这个要求被放宽为仅建议将参数 ``SRC_DIRS`` 用于 ``idf_component_register``。 @@ -133,7 +133,7 @@ DUT2（slave）终端： TEST_ASSERT(reason == DEEPSLEEP_RESET); } - TEST_CASE_MULTIPLE_STAGES("reset reason check for deepsleep", "[esp32]", trigger_deepsleep, check_deepsleep_reset_reason); + TEST_CASE_MULTIPLE_STAGES("reset reason check for deepsleep", "[{IDF_TARGET_PATH_NAME}]", trigger_deepsleep, check_deepsleep_reset_reason); 多阶段测试用例向用户呈现了一组测试函数，它需要用户进行交互（选择用例并选择不同的阶段）来运行。 @@ -171,7 +171,7 @@ DUT2（slave）终端： 运行单元测试 ------------ -烧写完成后重启 ESP32， 它将启动单元测试程序。 +烧写完成后重启 {IDF_TARGET_NAME}， 它将启动单元测试程序。 当单元测试应用程序空闲时，输入回车键，它会打印出测试菜单，其中包含所有的测试项目。 @@ -199,7 +199,7 @@ DUT2（slave）终端： (17) "SPI Master no response when switch from host1 (HSPI) to host2 (VSPI)" [spi] (18) "SPI Master DMA test, TX and RX in different regions" [spi] (19) "SPI Master DMA test: length, start, not aligned" [spi] - (20) "reset reason check for deepsleep" [esp32][test_env=UT_T2_1][multi_stage] + (20) "reset reason check for deepsleep" [{IDF_TARGET_PATH_NAME}][test_env=UT_T2_1][multi_stage] (1) "trigger_deepsleep" (2) "check_deepsleep_reset_reason" diff --git a/docs/zh_CN/api-reference/network/esp_wifi.rst b/docs/zh_CN/api-reference/network/esp_wifi.rst index 53d9a95ddd..36df726bcb 100644 --- a/docs/zh_CN/api-reference/network/esp_wifi.rst +++ b/docs/zh_CN/api-reference/network/esp_wifi.rst @@ -6,13 +6,13 @@ Wi-Fi 库 概述 ----- -Wi-Fi 库支持配置及监控 ESP32 Wi-Fi 连网功能。 +Wi-Fi 库支持配置及监控 {IDF_TARGET_NAME} Wi-Fi 连网功能。 支持配置： -- 基站模式（即 STA 模式或 Wi-Fi 客户端模式），此时 ESP32 连接到接入点 (AP)。 -- AP 模式（即 Soft-AP 模式或接入点模式），此时基站连接到 ESP32。 -- AP-STA 共存模式（ESP32 既是接入点，同时又作为基站连接到另外一个接入点）。 +- 基站模式（即 STA 模式或 Wi-Fi 客户端模式），此时 {IDF_TARGET_NAME} 连接到接入点 (AP)。 +- AP 模式（即 Soft-AP 模式或接入点模式），此时基站连接到 {IDF_TARGET_NAME}。 +- AP-STA 共存模式（{IDF_TARGET_NAME} 既是接入点，同时又作为基站连接到另外一个接入点）。 - 上述模式的各种安全模式（WPA、WPA2 及 WEP 等）。 - 扫描接入点（包括主动扫描及被动扫描）。 @@ -26,7 +26,7 @@ ESP-IDF 示例项目的 :example:`wifi` 目录下包含以下应用程序： * Wi-Fi 示例代码； -* 另外一个简单的应用程序 `esp-idf-template `_，演示了如何将 ESP32 模组连接到 AP。 +* 另外一个简单的应用程序 `esp-idf-template `_，演示了如何将 {IDF_TARGET_NAME} 模组连接到 AP。 API 参考 diff --git a/docs/zh_CN/api-reference/protocols/mdns.rst b/docs/zh_CN/api-reference/protocols/mdns.rst index 29e935213e..29bdbf3457 100644 --- a/docs/zh_CN/api-reference/protocols/mdns.rst +++ b/docs/zh_CN/api-reference/protocols/mdns.rst @@ -12,8 +12,8 @@ mDNS 是一种组播 UDP 服务，用来提供本地网络服务和主机发现 mDNS 属性 ^^^^^^^^^ - * ``hostname``：设备会去响应的主机名，如果没有设置，会根据设备的网络接口名定义 ``hostname`` 。例如，``my-esp32`` 会被解析为 ``my-esp32.local``。 - * ``default_instance``：默认实例名（即易记的设备名），例如 ``Jhon's ESP32 Thing``。如果没有设置，将会使用 ``hostname``。 + * ``hostname``：设备会去响应的主机名，如果没有设置，会根据设备的网络接口名定义 ``hostname`` 。例如，``my-{IDF_TARGET_PATH_NAME}`` 会被解析为 ``my-{IDF_TARGET_PATH_NAME}.local``。 + * ``default_instance``：默认实例名（即易记的设备名），例如 ``Jhon's {IDF_TARGET_NAME} Thing``。如果没有设置，将会使用 ``hostname``。 以下为 STA 接口启动 mDNS 服务并设置 ``hostname`` 和 ``default_instance`` 的示例方法： @@ -29,11 +29,11 @@ mDNS 属性 printf("MDNS Init failed: %d\n", err); return; } - + // 设置 hostname - mdns_hostname_set("my-esp32"); + mdns_hostname_set("my-{IDF_TARGET_PATH_NAME}"); // 设置默认实例 - mdns_instance_name_set("Jhon's ESP32 Thing"); + mdns_instance_name_set("Jhon's {IDF_TARGET_NAME} Thing"); } mDNS 服务 @@ -41,7 +41,7 @@ mDNS 服务 mDNS 可以广播设备能够提供的网络服务的相关信息，每个服务会由以下属性构成。 - * ``instance_name``：实例名（即易记的服务名），例如 ``Jhon's ESP32 Web Server``。如果没有定义，会使用 ``default_instance``。 + * ``instance_name``：实例名（即易记的服务名），例如 ``Jhon's {IDF_TARGET_NAME} Web Server``。如果没有定义，会使用 ``default_instance``。 * ``service_type``：（必需）服务类型，以下划线为前缀，`这里 `_ 列出了常见的类型。 * ``proto``：（必需）服务运行所依赖的协议，以下划线为前缀，例如 ``_tcp`` 或者 ``_udp``。 * ``port``：（必需）服务运行所用的端口号。 @@ -55,19 +55,19 @@ mDNS 可以广播设备能够提供的网络服务的相关信息，每个服务 mdns_service_add(NULL, "_http", "_tcp", 80, NULL, 0); mdns_service_add(NULL, "_arduino", "_tcp", 3232, NULL, 0); mdns_service_add(NULL, "_myservice", "_udp", 1234, NULL, 0); - + // 注意：必须先添加服务，然后才能设置其属性 // web 服务器使用自定义的实例名 - mdns_service_instance_name_set("_http", "_tcp", "Jhon's ESP32 Web Server"); + mdns_service_instance_name_set("_http", "_tcp", "Jhon's {IDF_TARGET_NAME} Web Server"); mdns_txt_item_t serviceTxtData[3] = { - {"board","esp32"}, + {"board","{IDF_TARGET_PATH_NAME}"}, {"u","user"}, {"p","password"} }; // 设置服务的文本数据（会释放并替换当前数据） mdns_service_txt_set("_http", "_tcp", serviceTxtData, 3); - + // 修改服务端口号 mdns_service_port_set("_myservice", "_udp", 4321); } @@ -161,9 +161,9 @@ mDNS 提供查询服务和解析主机 IP/IPv6 地址的方法。 使用上述方法的示例:: void my_app_some_method(){ - // 搜索 esp32-mdns.local - resolve_mdns_host("esp32-mdns"); - + // 搜索 {IDF_TARGET_PATH_NAME}-mdns.local + resolve_mdns_host("{IDF_TARGET_PATH_NAME}-mdns"); + // 搜索 HTTP 服务器 find_mdns_service("_http", "_tcp"); // 或者搜索文件服务器 diff --git a/docs/zh_CN/api-reference/storage/spiffs.rst b/docs/zh_CN/api-reference/storage/spiffs.rst index 494282c571..28d4997a07 100644 --- a/docs/zh_CN/api-reference/storage/spiffs.rst +++ b/docs/zh_CN/api-reference/storage/spiffs.rst @@ -35,11 +35,11 @@ spiffsgen.py python spiffsgen.py --help -上述可选参数对应 SPIFFS 构建配置选项。若想顺利生成可用的映像，请确保使用的参数或配置与构建 SPIFFS 时所用的参数或配置相同。运行帮助命令将显示参数所对应的 SPIFFS 构建配置。如未指定参数，将使用帮助信息中的默认值。 +上述可选参数对应 SPIFFS 构建配置选项。若想顺利生成可用的映像，请确保使用的参数或配置与构建 SPIFFS 时所用的参数或配置相同。运行帮助命令将显示参数所对应的 SPIFFS 构建配置。如未指定参数，将使用帮助信息中的默认值。 映像生成后，您可以使用 ``esptool.py`` 或 ``parttool.py`` 烧录映像。 -您可以在命令行或脚本中手动单独调用 ``spiffsgen.py``，也可以直接从构建系统调用 ``spiffs_create_partition_image`` 来使用 ``spiffsgen.py``。 +您可以在命令行或脚本中手动单独调用 ``spiffsgen.py``，也可以直接从构建系统调用 ``spiffs_create_partition_image`` 来使用 ``spiffsgen.py``。 在 Make 构建系统中运行:: @@ -51,14 +51,14 @@ spiffsgen.py spiffs_create_partition_image( [FLASH_IN_PROJECT] [DEPENDS dep dep dep...]) -在构建系统中使用 ``spiffsgen.py`` 更为方便，构建配置自动传递给 ``spiffsgen.py`` 工具，确保生成的映像可用于构建。比如，单独调用 ``spiffsgen.py`` 时需要用到 *image_size* 参数，但在构建系统中调用 ``spiffs_create_partition_image`` 时，仅需要 *partition* 参数，映像大小将直接从工程分区表中获取。 +在构建系统中使用 ``spiffsgen.py`` 更为方便，构建配置自动传递给 ``spiffsgen.py`` 工具，确保生成的映像可用于构建。比如，单独调用 ``spiffsgen.py`` 时需要用到 *image_size* 参数，但在构建系统中调用 ``spiffs_create_partition_image`` 时，仅需要 *partition* 参数，映像大小将直接从工程分区表中获取。 Make 构建系统和 CMake 构建系统结构有所不同，请注意以下几点： - 在 Make 构建系统中使用 ``spiffs_create_partition_image``，需从工程 Makefile 中调用； - 在 CMake 构建系统中使用 ``spiffs_create_partition_image``，需从组件 CMakeLists.txt 文件调用。 -您也可以指定 ``FLASH_IN_PROJECT``，然后使用 ``idf.py flash`` 或 ``make flash`` 将映像与应用程序二进制文件、分区表等一起自动烧录至设备，例如： +您也可以指定 ``FLASH_IN_PROJECT``，然后使用 ``idf.py flash`` 或 ``make flash`` 将映像与应用程序二进制文件、分区表等一起自动烧录至设备，例如： 在 Make 构建系统中运行:: @@ -75,7 +75,7 @@ Make 构建系统和 CMake 构建系统结构有所不同，请注意以下几 在 Make 构建系统中运行:: - dep: + dep: ... SPIFFS_IMAGE_DEPENDS := dep @@ -87,7 +87,7 @@ Make 构建系统和 CMake 构建系统结构有所不同，请注意以下几 spiffs_create_partition_image(my_spiffs_partition my_folder DEPENDS dep) -请参考 :example:`storage/spiffsgen`，查看示例。 +请参考 :example:`storage/spiffsgen`，查看示例。 mkspiffs ^^^^^^^^^^^ @@ -107,7 +107,7 @@ mkspiffs 运行以下命令，将映像烧录到 ESP32（偏移量：0x110000）:: - python esptool.py --chip esp32 --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin + python esptool.py --chip {IDF_TARGET_PATH_NAME} --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin 选择合适的 SPIFFS 工具 diff --git a/docs/zh_CN/api-reference/system/power_management.rst b/docs/zh_CN/api-reference/system/power_management.rst index acf3fb728b..7e54879826 100644 --- a/docs/zh_CN/api-reference/system/power_management.rst +++ b/docs/zh_CN/api-reference/system/power_management.rst @@ -16,41 +16,35 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求， - RTOS 可以要求 CPU 在有任务准备开始运行时以最高配置频率工作。 - 一些外设可能需要中断才能启用，因此其驱动也会要求禁用 Light-sleep 模式。 -因为请求较高的 APB 频率或 CPU 频率，以及禁用 Light-sleep 模式会增加功耗，请将组件使用的电源管理锁降到最少。 +因为请求较高的 APB 频率或 CPU 频率，以及禁用 Light-sleep 模式会增加功耗，请将组件使用的电源管理锁降到最少。 电源管理配置 ------------- -编译时可使用 :ref:`CONFIG_PM_ENABLE` 选项启用电源管理功能。 +编译时可使用 :ref:`CONFIG_PM_ENABLE` 选项启用电源管理功能。 启用电源管理功能将会增加中断延迟。额外延迟与多个因素有关，例如：CPU 频率、单/双核模式、是否需要进行频率切换等。CPU 频率为 240 MHz 且未启用频率调节时，最小额外延迟为 0.2 us；如果启用频率调节，且在中断入口将频率由 40 MHz 调节至 80 MHz，则最大额外延迟为 40 us。 应用程序可以通过调用 :cpp:func:`esp_pm_configure` 函数启用动态调频 (DFS) 功能和自动 Light-sleep 模式。此函数的参数为 :cpp:class:`esp_pm_config_esp32_t`，定义了频率调节的相关设置。在此参数结构中，需要初始化下面三个字段： -.. only:: esp32 +- ``max_freq_mhz``：最大 CPU 频率 (MHz)，即获取 ``ESP_PM_CPU_FREQ_MAX`` 锁后所使用的频率。该字段通常设置为 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEFAULT_CPU_FREQ_MHZ`。 - - ``max_freq_mhz``：最大 CPU 频率 (MHz)，即获取 ``ESP_PM_CPU_FREQ_MAX`` 锁后所使用的频率。该字段通常设置为 :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ`。 +- ``min_freq_mhz``：最小 CPU 频率 (MHz)，即仅获取 ``ESP_PM_APB_FREQ_MAX`` 锁后所使用的频率。该字段可设置为晶振 (XTAL) 频率值，或者 XTAL 频率值除以整数。注意，10 MHz 是生成 1 MHz 的 REF_TICK 默认时钟所需的最小频率。 -.. only:: esp32s2 - - - ``max_freq_mhz``：最大 CPU 频率 (MHz)，即获取 ``ESP_PM_CPU_FREQ_MAX`` 锁后所使用的频率。该字段通常设置为 :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ`。 - -- ``min_freq_mhz``：最小 CPU 频率 (MHz)，即仅获取 ``ESP_PM_APB_FREQ_MAX`` 锁后所使用的频率。该字段可设置为晶振 (XTAL) 频率值，或者 XTAL 频率值除以整数。注意，10 MHz 是生成 1 MHz 的 REF_TICK 默认时钟所需的最小频率。 - -- ``light_sleep_enable``：没有获取任何管理锁时，决定系统是否需要自动进入 Light-sleep 状态 (``true``/``false``)。 +- ``light_sleep_enable``：没有获取任何管理锁时，决定系统是否需要自动进入 Light-sleep 状态 (``true``/``false``)。 .. only:: esp32 - 或者，如果在 menuconfig 中启用了 :ref:`CONFIG_PM_DFS_INIT_AUTO` 选项，最大 CPU 频率将由 :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` 设置决定，最小 CPU 频率将锁定为 XTAL 频率。 + 或者，如果在 menuconfig 中启用了 :ref:`CONFIG_PM_DFS_INIT_AUTO` 选项，最大 CPU 频率将由 :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` 设置决定，最小 CPU 频率将锁定为 XTAL 频率。 .. only:: esp32s2 - 或者，如果在 menuconfig 中启用了 :ref:`CONFIG_PM_DFS_INIT_AUTO` 选项，最大 CPU 频率将由 :ref:`CONFIG_ESP32S2_DEFAULT_CPU_FREQ_MHZ` 设置决定，最小 CPU 频率将锁定为 XTAL 频率。 + 或者，如果在 menuconfig 中启用了 :ref:`CONFIG_PM_DFS_INIT_AUTO` 选项，最大 CPU 频率将由 :ref:`CONFIG_ESP32S2_DEFAULT_CPU_FREQ_MHZ` 设置决定，最小 CPU 频率将锁定为 XTAL 频率。 .. note:: 1. 自动 Light-sleep 模式基于 FreeRTOS Tickless Idle 功能，因此如果在 menuconfig 中没有启用 :ref:`CONFIG_FREERTOS_USE_TICKLESS_IDLE` 选项，在请求自动 Light-sleep 时，:cpp:func:`esp_pm_configure` 将会返回 `ESP_ERR_NOT_SUPPORTED` 错误。 - 2. 在 Light-sleep 状态下，外设设有时钟门控，不会产生来自 GPIO 和内部外设的中断。:doc:`sleep_modes` 文档中所提到的唤醒源可用于从 Light-sleep 状态触发唤醒。例如，EXT0 和 EXT1 唤醒源就可以通过 GPIO 唤醒芯片。 + 2. 在 Light-sleep 状态下，外设设有时钟门控，不会产生来自 GPIO 和内部外设的中断。:doc:`sleep_modes` 文档中所提到的唤醒源可用于从 Light-sleep 状态触发唤醒。例如，EXT0 和 EXT1 唤醒源就可以通过 GPIO 唤醒芯片。 电源管理锁 ---------------------- @@ -73,7 +67,7 @@ ESP32 支持下表中所述的三种电源管理锁。 .. only:: esp32 - .. include:: inc/power_management_esp32.rst + .. include:: ../../en/inc/power_management_esp32.rst 动态调频和外设驱动 ------------------------------------------------ @@ -82,7 +76,7 @@ ESP32 支持下表中所述的三种电源管理锁。 下面的外设不受 APB 频率变更的影响： -- **UART**：如果 REF_TICK 用作时钟源，则 UART 不受 APB 频率变更影响。请查看 :cpp:class:`uart_config_t` 中的 `use_ref_tick`。 +- **UART**：如果 REF_TICK 用作时钟源，则 UART 不受 APB 频率变更影响。请查看 :cpp:class:`uart_config_t` 中的 `use_ref_tick`。 - **LEDC**：如果 REF_TICK 用作时钟源，则 LEDC 不受 APB 频率变更影响。请查看 :cpp:func:`ledc_timer_config` 函数。 - **RMT**：如果 REF_TICK 用作时钟源，则 RMT 不受 APB 频率变更影响。此驱动程序尚不支持 REF_TICK，但可以清除相应通道的 ``RMT_REF_ALWAYS_ON_CHx`` 位来启用该功能。 @@ -98,7 +92,7 @@ ESP32 支持下表中所述的三种电源管理锁。 - **SPI slave**：从调用 :cpp:func:`spi_slave_initialize` 至 :cpp:func:`spi_slave_free` 期间。 - **Ethernet**：从调用 :cpp:func:`esp_eth_driver_install` 至 :cpp:func:`esp_eth_driver_uninstall` 期间。 - **WiFi**：从调用 :cpp:func:`esp_wifi_start` 至 :cpp:func:`esp_wifi_stop` 期间。如果启用了调制解调器睡眠模式，广播关闭时将释放此管理锁。 -- **CAN**：从调用 :cpp:func:`can_driver_install` 至 :cpp:func:`can_driver_uninstall` 期间。 +- **CAN**：从调用 :cpp:func:`can_driver_install` 至 :cpp:func:`can_driver_uninstall` 期间。 .. only:: esp32 diff --git a/docs/zh_CN/get-started/establish-serial-connection.rst b/docs/zh_CN/get-started/establish-serial-connection.rst index 0219250dd2..3995ee28db 100644 --- a/docs/zh_CN/get-started/establish-serial-connection.rst +++ b/docs/zh_CN/get-started/establish-serial-connection.rst @@ -1,31 +1,33 @@ -与 ESP32 创建串口连接 +与 {IDF_TARGET_NAME} 创建串口连接 ============================================== :link_to_translation:`en:[English]` -本章节主要介绍如何创建 ESP32 和 PC 之间的串口连接。 +本章节主要介绍如何创建 {IDF_TARGET_NAME} 和 PC 之间的串口连接。 -连接 ESP32 和 PC --------------------- +连接 {IDF_TARGET_NAME} 和 PC +--------------------------- -用 USB 线将 ESP32 开发板连接到 PC。如果设备驱动程序没有自动安装，请先确认 ESP32 开发板上的 USB 转串口芯片（或外部转串口适配器）型号，然后在网上搜索驱动程序，并进行手动安装。 +用 USB 线将 {IDF_TARGET_NAME} 开发板连接到 PC。如果设备驱动程序没有自动安装，请先确认 {IDF_TARGET_NAME} 开发板上的 USB 转串口芯片（或外部转串口适配器）型号，然后在网上搜索驱动程序，并进行手动安装。 -以下是乐鑫 ESP32 开发板驱动程序的链接： +以下是乐鑫 {IDF_TARGET_NAME} 开发板驱动程序的链接： -.. csv-table:: - :header: 开发板, USB 驱动, 备注 - :widths: 40, 20, 40 +.. only:: esp32 - :ref:`ESP32-DevKitC `, `CP210x`_ - `ESP32-LyraT `_, `CP210x`_ - `ESP32-LyraTD-MSC `_, `CP210x`_ - :ref:`ESP32-PICO-KIT `, `CP210x`_ - :ref:`ESP-WROVER-KIT `, `FTDI`_ - :ref:`ESP32 Demo 板 `, `FTDI`_ - `ESP-Prog`_, `FTDI`_, 编程板 (w/o ESP32) - `ESP32-MeshKit-Sense `_, n/a, 搭配 `ESP-Prog`_ 使用 - `ESP32-Sense Kit `_, n/a, 搭配 `ESP-Prog`_ 使用 + .. csv-table:: + :header: 开发板, USB 驱动, 备注 + :widths: 40, 20, 40 + + :ref:`ESP32-DevKitC `, `CP210x`_ + `ESP32-LyraT `_, `CP210x`_ + `ESP32-LyraTD-MSC `_, `CP210x`_ + :ref:`ESP32-PICO-KIT `, `CP210x`_ + :ref:`ESP-WROVER-KIT `, `FTDI`_ + :ref:`ESP32 Demo 板 `, `FTDI`_ + `ESP-Prog`_, `FTDI`_, 编程板 (w/o ESP32) + `ESP32-MeshKit-Sense `_, n/a, 搭配 `ESP-Prog`_ 使用 + `ESP32-Sense Kit `_, n/a, 搭配 `ESP-Prog`_ 使用 .. _CP210x: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers .. _FTDI: http://www.ftdichip.com/Drivers/VCP.htm @@ -34,12 +36,12 @@ * CP210x: `CP210x USB 至 UART 桥 VCP 驱动程序 `_ * FTDI: `FTDI 虚拟 COM 端口驱动程序 `_ -以上驱动仅用于参考。一般情况下，当上述任一 ESP32 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中，并已经自动安装。 +以上驱动仅用于参考。一般情况下，当上述任一 {IDF_TARGET_NAME} 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中，并已经自动安装。 在 Windows 上查看端口 --------------------- -检查 Windows 设备管理器中的 COM 端口列表。断开 ESP32 与 PC 的连接，然后重新连接，查看哪个端口从列表中消失，然后再次出现。 +检查 Windows 设备管理器中的 COM 端口列表。断开 {IDF_TARGET_NAME} 与 PC 的连接，然后重新连接，查看哪个端口从列表中消失，然后再次出现。 以下为 ESP32 DevKitC 和 ESP32 WROVER KIT 串口： @@ -61,7 +63,7 @@ 在 Linux 和 MacOS 上查看端口 ----------------------------- -查看 ESP32 开发板（或外部转串口适配器）的串口设备名称，请运行两次以下命令。首先，断开开发板或适配器，第一次运行命令；然后，连接开发板或适配器，第二次运行命令。其中，第二次运行命令后出现的端口即是 ESP32 对应的串口： +查看 {IDF_TARGET_NAME} 开发板（或外部转串口适配器）的串口设备名称，请运行两次以下命令。首先，断开开发板或适配器，第一次运行命令；然后，连接开发板或适配器，第二次运行命令。其中，第二次运行命令后出现的端口即是 {IDF_TARGET_NAME} 对应的串口： Linux :: @@ -113,7 +115,7 @@ MacOS :: 在 Linux 操作系统中使用 PuTTY 设置串口通信参数 -然后，请检查 ESP32 是否有打印日志。如有，请在终端打开串口进行查看。这里，日志内容取决于加载到 ESP32 的应用程序，下图即为一个示例。 +然后，请检查 {IDF_TARGET_NAME} 是否有打印日志。如有，请在终端打开串口进行查看。这里，日志内容取决于加载到 {IDF_TARGET_NAME} 的应用程序，下图即为一个示例。 .. highlight:: none @@ -138,17 +140,17 @@ MacOS :: ... -如果打印出的日志是可读的（而不是乱码），则表示串口连接正常。此时，你可以继续进行安装，并最终将应用程序上载到 ESP32。 +如果打印出的日志是可读的（而不是乱码），则表示串口连接正常。此时，你可以继续进行安装，并最终将应用程序上载到 {IDF_TARGET_NAME}。 .. note:: - 在某些串口接线方式下，在 ESP32 启动并开始打印串口日志前，需要在终端程序中禁用串口 RTS ＆ DTR 引脚。该问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况，绝大多数开发板（包括乐鑫所有的开发板）都没有这个问题。更多详细信息，参见 `esptool 文档`_。 + 在某些串口接线方式下，在 {IDF_TARGET_NAME} 启动并开始打印串口日志前，需要在终端程序中禁用串口 RTS ＆ DTR 引脚。该问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况，绝大多数开发板（包括乐鑫所有的开发板）都没有这个问题。更多详细信息，参见 `esptool 文档`_。 .. note:: - 请在验证完串口通信正常后，关闭串口终端。下一步，我们将使用另一个应用程序将新的固件上传到 ESP32。此时，如果串口被占用则无法成功。 + 请在验证完串口通信正常后，关闭串口终端。下一步，我们将使用另一个应用程序将新的固件上传到 {IDF_TARGET_NAME}。此时，如果串口被占用则无法成功。 -如你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-connect` 跳转到了这里，请从 :ref:`get-started-configure` 继续阅读。 +如你在安装 {IDF_TARGET_NAME} 硬件开发的软件环境时，从 :ref:`get-started-connect` 跳转到了这里，请从 :ref:`get-started-configure` 继续阅读。 .. _esptool 文档: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst index 6040bdf56b..907638154f 100644 --- a/docs/zh_CN/get-started/index.rst +++ b/docs/zh_CN/get-started/index.rst @@ -4,48 +4,58 @@ :link_to_translation:`en:[English]` -本文档旨在指导用户搭建 ESP32 硬件开发的软件环境，通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 ESP32 开发板等步骤。 +本文档旨在指导用户搭建 {IDF_TARGET_NAME} 硬件开发的软件环境，通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 {IDF_TARGET_NAME} 开发板等步骤。 .. include-build-file:: inc/version-note.inc 概述 ============ -ESP32 SoC 芯片支持以下功能： +.. only:esp32 -* 2.4 GHz Wi-Fi -* 蓝牙 4.2 -* 高性能双核 -* 超低功耗协处理器 -* 多种外设 + ESP32 SoC 芯片支持以下功能： -ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、稳定性、通用性和可靠性，适用于各种应用场景和不同功耗需求。 + * 2.4 GHz Wi-Fi + * 蓝牙 4.2 + * 高性能双核 + * 超低功耗协处理器 + * 多种外设 -乐鑫为用户提供完整的软、硬件资源，进行 ESP32 硬件设备的开发。其中，乐鑫的软件开发环境 ESP-IDF 旨在协助用户快速开发物联网 (IoT) 应用，可满足用户对 Wi-Fi、蓝牙、低功耗等方面的要求。 +.. only:esp32s2 + + ESP32-S2 SoC 芯片支持以下功能： + + * 2.4 GHz Wi-Fi + * 超低功耗协处理器 + * 多种外设 + +{IDF_TARGET_NAME} 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、稳定性、通用性和可靠性，适用于各种应用场景和不同功耗需求。 + +乐鑫为用户提供完整的软、硬件资源，进行 {IDF_TARGET_NAME} 硬件设备的开发。其中，乐鑫的软件开发环境 ESP-IDF 旨在协助用户快速开发物联网 (IoT) 应用，可满足用户对 Wi-Fi、蓝牙、低功耗等方面的要求。 准备工作 ============= 硬件： -* 一款 **ESP32** 开发板 +* 一款 **{IDF_TARGET_NAME}** 开发板 * **USB 数据线** (A 转 Micro-B) * PC（Windows、Linux 或 Mac OS） 软件： -* 设置 **工具链**，用于编译 ESP32 代码； -* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32 **应用程序**； -* 获取 **ESP-IDF** 软件开发框架。该框架已经基本包含 ESP32 使用的 API（软件库和源代码）和运行 **工具链** 的脚本； +* 设置 **工具链**，用于编译 {IDF_TARGET_NAME} 代码； +* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 {IDF_TARGET_NAME} **应用程序**； +* 获取 **ESP-IDF** 软件开发框架。该框架已经基本包含 {IDF_TARGET_NAME} 使用的 API（软件库和源代码）和运行 **工具链** 的脚本； * 安装 C 语言编程（**工程**）的 **文本编辑器**，例如 `Eclipse `_。 .. figure:: ../../_static/what-you-need.png :align: center - :alt: ESP32 应用程序开发 + :alt: {IDF_TARGET_NAME} 应用程序开发 :figclass: align-center - ESP32 应用程序开发 + {IDF_TARGET_NAME} 应用程序开发 开发板简介 @@ -53,13 +63,15 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 请点击下方连接，了解有关具体开发板的详细信息。 -.. toctree:: - :maxdepth: 1 +.. only:: esp32 - ESP32-DevKitC <../hw-reference/get-started-devkitc> - ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> - ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> - ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> + .. toctree:: + :maxdepth: 1 + + ESP32-DevKitC <../hw-reference/get-started-devkitc> + ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> + ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> + ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> .. _get-started-step-by-step: @@ -127,7 +139,7 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 第二步：获取 ESP-IDF ================================= -在围绕 ESP32 构建应用程序之前，请先获取乐鑫提供的软件库文件 `ESP-IDF 仓库 `_。 +在围绕 {IDF_TARGET_NAME} 构建应用程序之前，请先获取乐鑫提供的软件库文件 `ESP-IDF 仓库 `_。 获取 ESP-IDF 的本地副本：打开终端，切换到您要保存 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。针对不同操作系统的详细步骤，请见下文。 @@ -238,7 +250,7 @@ Linux 和 MacOS 操作系统 第五步：开始创建工程 ======================================== -现在，您可以开始准备开发 ESP32 应用程序了。您可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。 +现在，您可以开始准备开发 {IDF_TARGET_NAME} 应用程序了。您可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。 将 :example:`get-started/hello_world` 复制至您本地的 ``~/esp`` 目录下： @@ -269,7 +281,7 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照 第六步：连接设备 ========================================== -现在，请将您的 ESP32 开发板连接到 PC，并查看开发板使用的串口。 +现在，请将您的 {IDF_TARGET_NAME} 开发板连接到 PC，并查看开发板使用的串口。 通常，串口在不同操作系统下显示的名称有所不同： @@ -328,9 +340,11 @@ Windows 操作系统 * ``英文问号`` （查询配置选项）：调出有关该选项的帮助菜单 * ``/ 键``：寻找配置工程 -.. attention:: +.. only:: esp32 - 如果您使用的是 ESP32-DevKitC（板载 ESP32-SOLO-1 模组），请在烧写示例程序前，前往 ``menuconfig`` 中使能单核模式（:ref:`CONFIG_FREERTOS_UNICORE`）。 + .. attention:: + + 如果您使用的是 ESP32-DevKitC（板载 ESP32-SOLO-1 模组），请在烧写示例程序前，前往 ``menuconfig`` 中使能单核模式（:ref:`CONFIG_FREERTOS_UNICORE`）。 .. _get-started-build: @@ -371,11 +385,11 @@ Windows 操作系统 第九步：烧录到设备 ============================= -请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板： +请使用以下命令，将刚刚生成的二进制文件烧录至您的 {IDF_TARGET_NAME} 开发板： ``idf.py -p PORT [-b BAUD] flash`` -请将 PORT 替换为 ESP32 开发板的串口名称，具体可见 :ref:`get-started-connect`。 +请将 PORT 替换为 {IDF_TARGET_NAME} 开发板的串口名称，具体可见 :ref:`get-started-connect`。 您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为 ``460800``。 @@ -392,8 +406,8 @@ Windows 操作系统 esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin esptool.py v2.3.1 Connecting.... - Detecting chip type... ESP32 - Chip is ESP32D0WDQ6 (revision 1) + Detecting chip type... {IDF_TARGET_NAME} + Chip is {IDF_TARGET_NAME}D0WDQ6 (revision 1) Features: WiFi, BT, Dual Core Uploading stub... Running stub... @@ -465,9 +479,9 @@ Windows 操作系统 :align: center :alt: 乱码输出 :figclass: align-center - + 此时，您可以： - + 1. 退出监视器。 2. 打开 :ref:`menuconfig `。 3. 进入 ``Component config`` --> ``ESP32-specific`` --> ``Main XTAL frequency`` 进行配置，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 设置为 26 MHz。 @@ -484,14 +498,14 @@ Windows 操作系统 - 请前往 :doc:`IDF 监视器 <../api-guides/tools/idf-monitor>`，了解更多使用 IDF 监视器的快捷键和其他详情。 - 请前往 :ref:`idf.py`，查看更多 ``idf.py`` 命令和选项。 -**恭喜，您已完成 ESP32 的入门学习！** +**恭喜，您已完成 {IDF_TARGET_NAME} 的入门学习！** 现在，您可以尝试一些其他 :idf:`examples`，或者直接开发自己的应用程序。 更新 ESP-IDF ================ -乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf` 中的指示，重新完成克隆。 +乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf` 中的指示，重新完成克隆。 此外，您可以仅更新变更部分。具体方式，请前往 :ref:`更新 ` 章节查看。 diff --git a/docs/zh_CN/get-started/linux-setup-scratch.rst b/docs/zh_CN/get-started/linux-setup-scratch.rst index 528f25cee2..2a8e94892a 100644 --- a/docs/zh_CN/get-started/linux-setup-scratch.rst +++ b/docs/zh_CN/get-started/linux-setup-scratch.rst @@ -62,11 +62,13 @@ 编译工具链:: - ./ct-ng xtensa-esp32-elf + ./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf ./ct-ng build - chmod -R u+w builds/xtensa-esp32-elf + chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf -编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 :ref:`标准设置指南 ` 的介绍，将工具链添加到 ``PATH``。 +.. only:: esp32 + + 编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``。请按照 :ref:`标准设置指南 ` 的介绍，将工具链添加到 ``PATH``。 后续步骤 diff --git a/docs/zh_CN/get-started/linux-setup.rst b/docs/zh_CN/get-started/linux-setup.rst index 0f30654ca3..6dd835cd93 100644 --- a/docs/zh_CN/get-started/linux-setup.rst +++ b/docs/zh_CN/get-started/linux-setup.rst @@ -30,7 +30,7 @@ Linux 平台工具链的标准设置 权限问题 /dev/ttyUSB0 ------------------------------------------------------------ -使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 `。 +使用某些 Linux 版本向 {IDF_TARGET_NAME} 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 `。 后续步骤 ========== diff --git a/docs/zh_CN/get-started/macos-setup-scratch.rst b/docs/zh_CN/get-started/macos-setup-scratch.rst index 3cc738cf46..f880317cd9 100644 --- a/docs/zh_CN/get-started/macos-setup-scratch.rst +++ b/docs/zh_CN/get-started/macos-setup-scratch.rst @@ -67,17 +67,17 @@ MacPorts 需要完整的 XCode 软件，而 homebrew 只需要安装 XCode 命 cd ~/esp/ctng-volume -下载并编译 ``crosstool-NG`` +下载并编译 ``crosstool-NG`` .. include-build-file:: inc/scratch-build-code.inc 编译工具链:: - ./ct-ng xtensa-esp32-elf + ./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf ./ct-ng build - chmod -R u+w builds/xtensa-esp32-elf + chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf -编译得到的工具链会被保存到 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。使用工具链前，请将 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` 添加至 ``PATH`` 环境变量。 +编译得到的工具链会被保存到 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``。使用工具链前，请将 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin`` 添加至 ``PATH`` 环境变量。 后续步骤 diff --git a/docs/zh_CN/get-started/windows-setup-scratch.rst b/docs/zh_CN/get-started/windows-setup-scratch.rst index ecc9531fb1..76dff786d6 100644 --- a/docs/zh_CN/get-started/windows-setup-scratch.rst +++ b/docs/zh_CN/get-started/windows-setup-scratch.rst @@ -35,7 +35,7 @@ ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。 .. note:: 在克隆远程仓库时，不要忘记加上 ``--recursive`` 选项。否则，请接着运行以下命令，获取所有子模块 :: - + cd esp-idf git submodule update --init @@ -56,7 +56,7 @@ Ninja 编译工具 .. note:: 目前，Ninja 仅提供支持 64 位 Windows 版本的 bin 文件。您也可以配合其他编译工具在 32 位 Windows 版本中使用 CMake 和 ``idf.py`` ，比如 mingw-make。但是目前暂无关于此工具的说明文档。 -从（`下载页面 `_）下载最新发布的 Windows 平台稳定版 ninja_。 +从（`下载页面 `_）下载最新发布的 Windows 平台稳定版 ninja_。 适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。您需要将该文件解压到目录，并 :ref:`添加到您的路径 ` （或者选择您路径中的已有目录）。 @@ -88,12 +88,12 @@ Python 安装完成后，从 Windows 开始菜单中打开“命令提示符” |download_link_win32| -解压压缩包文件到 ``C:\Program Files`` （或其他位置）。压缩包文件包含一个 ``xtensa-esp32-elf`` 目录。 +解压压缩包文件到 ``C:\Program Files`` （或其他位置）。压缩包文件包含一个 ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf`` 目录。 -然后，请将该目录下的 ``bin`` 子目录 :ref:`添加到您的路径 `。例如，``C:\Program Files\xtensa-esp32-elf\bin``。 +然后，请将该目录下的 ``bin`` 子目录 :ref:`添加到您的路径 `。例如，``C:\Program Files\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin``。 .. note:: - 如果您已安装 MSYS2 环境（适用 "GNU Make" 编译系统），则可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-esp32-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。 + 如果您已安装 MSYS2 环境（适用 "GNU Make" 编译系统），则可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。 .. _add-directory-windows-path: diff --git a/docs/zh_CN/get-started/windows-setup.rst b/docs/zh_CN/get-started/windows-setup.rst index 1a5b763bf8..c3cb983425 100644 --- a/docs/zh_CN/get-started/windows-setup.rst +++ b/docs/zh_CN/get-started/windows-setup.rst @@ -12,7 +12,7 @@ Windows 平台工具链的标准设置 概述 ============ -ESP-IDF 需要安装一些必备工具，才能围绕 ESP32 构建固件，包括 Python、Git、交叉编译器、menuconfig 工具、CMake和 Ninja 编译工具等。 +ESP-IDF 需要安装一些必备工具，才能围绕 {IDF_TARGET_NAME} 构建固件，包括 Python、Git、交叉编译器、menuconfig 工具、CMake和 Ninja 编译工具等。 在本入门指南中，我们通过 **命令提示符** 进行有关操作。不过，您在安装 ESP-IDF 后还可以使用 :doc:`Eclipse ` 或其他支持 CMake 的图形化工具 IDE。 diff --git a/docs/zh_CN/hw-reference/index.rst b/docs/zh_CN/hw-reference/index.rst index f65e95a6c3..5aab701a27 100644 --- a/docs/zh_CN/hw-reference/index.rst +++ b/docs/zh_CN/hw-reference/index.rst @@ -6,11 +6,13 @@ ESP32 H/W 硬件参考 .. toctree:: :maxdepth: 2 - ESP32 技术参考手册 (PDF) - ESP32 技术规格书 (PDF) - ESP32 硬件设计指南 (PDF) - ESP32 勘误表及解决方法 (PDF) + :esp32: ESP32 技术参考手册 (PDF) + :esp32s2beta: ESP32-S2 技术参考手册 (PDF) + :esp32: ESP32 技术规格书 (PDF) + :esp32s2beta: ESP32-S2 技术规格书 (PDF) + :esp32: ESP32 硬件设计指南 (PDF) + :esp32: ESP32 勘误表及解决方法 (PDF) 模组与开发板 模组与开发板（历史版本） 乐鑫产品订购信息 (PDF) - 乐鑫产品证书 \ No newline at end of file + 乐鑫产品证书 diff --git a/docs/zh_CN/hw-reference/modules-and-boards.rst b/docs/zh_CN/hw-reference/modules-and-boards.rst index eeeb746d23..b1843052ee 100644 --- a/docs/zh_CN/hw-reference/modules-and-boards.rst +++ b/docs/zh_CN/hw-reference/modules-and-boards.rst @@ -80,7 +80,7 @@ ESP32-WROOM-32D/ESP32-WROOM-32U 模组 两款模组均集成了 ESP32-D0WD 芯片，与 :ref:`esp-modules-and-boards-esp32-wroom-32` 集成的 ESP32-D0WDQ6 相比，ESP32-D0WD 芯片的封装更小，在 PCB 上占用的面积更小。 -有关这两款模组的详细信息，请查看 :ref:`esp-wroom-solo-wrover-modules` 中的表格和 `乐鑫产品订购信息`_。 +有关这两款模组的详细信息，请查看 :ref:`esp-wroom-solo-wrover-modules` 中的表格和 `乐鑫产品订购信息`_。 ESP32-WROOM-32U 是整个 WROOM/WROVER 模组系列中最小的模组。 @@ -214,7 +214,7 @@ ESP32-PICO-KIT V4.1 开发板集成了 `ESP32-PICO-D4 模组`_，只需在 PCB ( .. _esp-modules-and-boards-esp32-devkitc: - + ESP32 DevKitC V4 开发板 ------------------------------ From 1a90470f02394a737e68957330c82dd1d592c4ec Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Wed, 11 Dec 2019 15:45:30 +0800 Subject: [PATCH 21/47] doc: Split HW-Reference into seperate files/folders for different chips --- docs/conf_common.py | 20 +- .../api-guides/esp-ble-mesh/ble-mesh-faq.rst | 2 +- docs/en/api-guides/external-ram.rst | 5 +- .../jtag-debugging/configure-wrover.rst | 4 +- docs/en/api-guides/jtag-debugging/index.rst | 18 +- .../establish-serial-connection.rst | 8 +- docs/en/get-started-legacy/index.rst | 18 +- docs/en/get-started/index.rst | 8 +- .../{ => esp32}/get-started-devkitc-v2.rst | 4 +- .../{ => esp32}/get-started-devkitc.rst | 16 +- .../get-started-ethernet-kit-v1.0.rst | 26 +- .../{ => esp32}/get-started-ethernet-kit.rst | 32 +- .../{ => esp32}/get-started-pico-kit-v3.rst | 8 +- .../{ => esp32}/get-started-pico-kit.rst | 18 +- .../{ => esp32}/get-started-wrover-kit-v2.rst | 28 +- .../{ => esp32}/get-started-wrover-kit-v3.rst | 26 +- .../{ => esp32}/get-started-wrover-kit.rst | 26 +- .../esp32/inc/modules-and-boards-esp32.rst | 289 +++++++++++++ .../inc/modules-and-boards-previous-esp32.rst | 179 ++++++++ .../inc/modules-and-boards-esp32s2.rst | 21 + .../modules-and-boards-previous-esp32s2.rst | 12 + docs/en/hw-reference/index.rst | 2 +- .../modules-and-boards-previous.rst | 179 +------- docs/en/hw-reference/modules-and-boards.rst | 291 +------------ docs/zh_CN/api-guides/external-ram.rst | 2 +- .../jtag-debugging/configure-wrover.rst | 6 +- .../zh_CN/api-guides/jtag-debugging/index.rst | 4 +- .../jtag-debugging/tips-and-quirks.rst | 2 +- .../api-reference/system/power_management.rst | 2 +- docs/zh_CN/get-started-legacy/index.rst | 12 +- docs/zh_CN/get-started/index.rst | 8 +- .../{ => esp32}/get-started-devkitc-v2.rst | 6 +- .../{ => esp32}/get-started-devkitc.rst | 14 +- .../get-started-ethernet-kit-v1.0.rst | 18 +- .../esp32/get-started-ethernet-kit.rst | 1 + .../{ => esp32}/get-started-pico-kit-v3.rst | 12 +- .../{ => esp32}/get-started-pico-kit.rst | 20 +- .../{ => esp32}/get-started-wrover-kit-v2.rst | 32 +- .../{ => esp32}/get-started-wrover-kit-v3.rst | 28 +- .../{ => esp32}/get-started-wrover-kit.rst | 54 +-- .../esp32/inc/modules-and-boards-esp32.rst | 294 +++++++++++++ .../inc/modules-and-boards-previous-esp32.rst | 1 + .../inc/modules-and-boards-esp32s2.rst | 1 + .../modules-and-boards-previous-esp32s2.rst | 1 + .../hw-reference/get-started-ethernet-kit.rst | 409 ------------------ docs/zh_CN/hw-reference/index.rst | 2 +- .../modules-and-boards-previous.rst | 25 +- .../zh_CN/hw-reference/modules-and-boards.rst | 297 +------------ 48 files changed, 1077 insertions(+), 1414 deletions(-) rename docs/en/hw-reference/{ => esp32}/get-started-devkitc-v2.rst (92%) rename docs/en/hw-reference/{ => esp32}/get-started-devkitc.rst (92%) rename docs/en/hw-reference/{ => esp32}/get-started-ethernet-kit-v1.0.rst (95%) rename docs/en/hw-reference/{ => esp32}/get-started-ethernet-kit.rst (95%) rename docs/en/hw-reference/{ => esp32}/get-started-pico-kit-v3.rst (88%) rename docs/en/hw-reference/{ => esp32}/get-started-pico-kit.rst (94%) rename docs/en/hw-reference/{ => esp32}/get-started-wrover-kit-v2.rst (90%) rename docs/en/hw-reference/{ => esp32}/get-started-wrover-kit-v3.rst (94%) rename docs/en/hw-reference/{ => esp32}/get-started-wrover-kit.rst (94%) create mode 100644 docs/en/hw-reference/esp32/inc/modules-and-boards-esp32.rst create mode 100644 docs/en/hw-reference/esp32/inc/modules-and-boards-previous-esp32.rst create mode 100644 docs/en/hw-reference/esp32s2/inc/modules-and-boards-esp32s2.rst create mode 100644 docs/en/hw-reference/esp32s2/inc/modules-and-boards-previous-esp32s2.rst rename docs/zh_CN/hw-reference/{ => esp32}/get-started-devkitc-v2.rst (87%) rename docs/zh_CN/hw-reference/{ => esp32}/get-started-devkitc.rst (89%) rename docs/zh_CN/hw-reference/{ => esp32}/get-started-ethernet-kit-v1.0.rst (94%) create mode 100644 docs/zh_CN/hw-reference/esp32/get-started-ethernet-kit.rst rename docs/zh_CN/hw-reference/{ => esp32}/get-started-pico-kit-v3.rst (89%) rename docs/zh_CN/hw-reference/{ => esp32}/get-started-pico-kit.rst (94%) rename docs/zh_CN/hw-reference/{ => esp32}/get-started-wrover-kit-v2.rst (89%) rename docs/zh_CN/hw-reference/{ => esp32}/get-started-wrover-kit-v3.rst (94%) rename docs/zh_CN/hw-reference/{ => esp32}/get-started-wrover-kit.rst (92%) create mode 100644 docs/zh_CN/hw-reference/esp32/inc/modules-and-boards-esp32.rst create mode 100644 docs/zh_CN/hw-reference/esp32/inc/modules-and-boards-previous-esp32.rst create mode 100644 docs/zh_CN/hw-reference/esp32s2/inc/modules-and-boards-esp32s2.rst create mode 100644 docs/zh_CN/hw-reference/esp32s2/inc/modules-and-boards-previous-esp32s2.rst delete mode 100644 docs/zh_CN/hw-reference/get-started-ethernet-kit.rst diff --git a/docs/conf_common.py b/docs/conf_common.py index 7fd6b83a64..6d4e94b0ed 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -136,19 +136,18 @@ def update_exclude_patterns(tags): 'api-reference/system/himem.rst', 'api-reference/bluetooth/**', 'api-reference/system/ipc.rst', - 'hw-reference/get-started-devkitc-v2.rst', - 'hw-reference/get-started-devkitc.rst', - 'hw-reference/get-started-ethernet-kit-v1.0.rst', - 'hw-reference/get-started-ethernet-kit.rst', - 'hw-reference/get-started-pico-kit-v3.rst', - 'hw-reference/get-started-pico-kit.rst', - 'hw-reference/get-started-wrover-kit-v2.rst', - 'hw-reference/get-started-wrover-kit-v3.rst', - 'hw-reference/get-started-wrover-kit.rst', 'get-started-legacy/**', - 'gnu-make-legacy.rst']: + 'gnu-make-legacy.rst', + 'hw-reference/esp32/**']: exclude_patterns.append(e) + if "esp32s2" not in tags: + # Exclude ESP32-only document pages so they aren't found in the initial search for .rst files + # note: in toctrees, these also need to be marked with a :esp32: filter + for e in ['hw-reference/esp32s2/**']: + exclude_patterns.append(e) + + # The reST default role (used for this markup: `text`) to use for all # documents. # default_role = None @@ -349,7 +348,6 @@ texinfo_documents = [ # texinfo_no_detailmenu = False - # Override RTD CSS theme to introduce the theme corrections # https://github.com/rtfd/sphinx_rtd_theme/pull/432 def setup(app): diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst index 55eaddca7e..4dc2cfd4a9 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst @@ -527,7 +527,7 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m 3.2 Why is the Wi-Fi throughput so low when Wi-Fi and ESP-BLE-MESH coexist? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The `ESP32-DevKitC <../../hw-reference/get-started-devkitc>`_ board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1Mbps. + The `ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>`_ board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1Mbps. And some configurations in menuconfig shall be enabled to support PSRAM. diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index 1c05be4a5f..182e167e5e 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -33,8 +33,9 @@ The ESP-PSRAM32 chip is a 1.8 V device which can only be used in parallel with a Connections for ESP32D2W* chips are TBD. - .. NOTE:: - Espressif produces the line of ESP32-WROVER modules which contain ESP32, 1.8 V flash, and ESP-PSRAM32. These modules are ready to be mounted on an end product PCB. + .. note:: + + Espressif produces the line of ESP32-WROVER modules which contain ESP32, 1.8 V flash, and ESP-PSRAM32. These modules are ready to be mounted on an end product PCB. .. _external_ram_config: diff --git a/docs/en/api-guides/jtag-debugging/configure-wrover.rst b/docs/en/api-guides/jtag-debugging/configure-wrover.rst index d80001694b..93d08179a7 100644 --- a/docs/en/api-guides/jtag-debugging/configure-wrover.rst +++ b/docs/en/api-guides/jtag-debugging/configure-wrover.rst @@ -8,7 +8,7 @@ All versions of ESP-WROVER-KIT boards have built-in JTAG functionality. Putting Configure Hardware ^^^^^^^^^^^^^^^^^^ -1. Enable on-board JTAG functionality by setting JP8 according to :doc:`../../hw-reference/get-started-wrover-kit`, Section :ref:`get-started-esp-wrover-kit-v4.1-setup-options`. +1. Enable on-board JTAG functionality by setting JP8 according to :doc:`../../hw-reference/esp32/get-started-wrover-kit`, Section :ref:`get-started-esp-wrover-kit-v4.1-setup-options`. 2. Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation: @@ -104,7 +104,7 @@ On macOS, using FT2232 for JTAG and serial port at the same time needs some addi 1. Manually unload the FTDI serial port driver before starting OpenOCD, start OpenOCD, then load the serial port driver. -2. Modify FTDI driver configuration so that it doesn't load itself for channel B of FT2232 chip, which is the channel used for JTAG on WROVER KIT. +2. Modify FTDI driver configuration so that it doesn't load itself for channel B of FT2232 chip, which is the channel used for JTAG on WROVER KIT. Manually unloading the driver ............................. diff --git a/docs/en/api-guides/jtag-debugging/index.rst b/docs/en/api-guides/jtag-debugging/index.rst index 44eff3595c..475279da45 100644 --- a/docs/en/api-guides/jtag-debugging/index.rst +++ b/docs/en/api-guides/jtag-debugging/index.rst @@ -279,20 +279,10 @@ Tips and Quirks This section provides collection of links to all tips and quirks referred to from various parts of this guide. -* :ref:`jtag-debugging-tip-breakpoints` -* :ref:`jtag-debugging-tip-where-breakpoints` -* :ref:`jtag-debugging-tip-flash-mappings` -* :ref:`jtag-debugging-tip-why-next-works-as-step` -* :ref:`jtag-debugging-tip-code-options` -* :ref:`jtag-debugging-tip-freertos-support` -* :ref:`jtag-debugging-tip-code-flash-voltage` -* :ref:`jtag-debugging-tip-optimize-jtag-speed` -* :ref:`jtag-debugging-tip-debugger-startup-commands` -* :ref:`jtag-debugging-tip-openocd-configure-target` -* :ref:`jtag-debugging-tip-reset-by-debugger` -* :ref:`jtag-debugging-tip-jtag-pins-reconfigured` -* :ref:`jtag-debugging-tip-at-firmware-issue` -* :ref:`jtag-debugging-tip-reporting-issues` +.. toctree:: + :maxdepth: 2 + + tips-and-quirks Related Documents diff --git a/docs/en/get-started-legacy/establish-serial-connection.rst b/docs/en/get-started-legacy/establish-serial-connection.rst index 83a4f933be..d52ab57b08 100644 --- a/docs/en/get-started-legacy/establish-serial-connection.rst +++ b/docs/en/get-started-legacy/establish-serial-connection.rst @@ -3,7 +3,7 @@ Establish Serial Connection with ESP32 (Legacy GNU Make) :link_to_translation:`zh_CN:[中文]` .. include:: ../gnu-make-legacy.rst - + This section provides guidance how to establish serial connection between ESP32 and PC. @@ -30,10 +30,10 @@ Below are the links to drivers for ESP32 and other boards produced by Espressif: `ESP32-Sense Kit `_, n/a, Use with `ESP-Prog`_ .. _CP210x: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers -.. _FTDI: http://www.ftdichip.com/Drivers/VCP.htm +.. _FTDI: http://www.ftdichip.com/Drivers/VCP.htm .. _ESP-Prog: https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP-Prog_guide_en.md#introduction-to-the-esp-prog-board -* CP210x: `CP210x USB to UART Bridge VCP Drivers `_ +* CP210x: `CP210x USB to UART Bridge VCP Drivers `_ * FTDI: `FTDI Virtual COM Port Drivers `_ The drivers above are primarily for reference. Under normal circumstances, the drivers should be bundled with and operating system and automatically installed upon connecting one of the listed boards to the PC. @@ -88,7 +88,7 @@ on Arch Linux this is done by adding the user to ``uucp`` group with the followi sudo usermod -a -G uucp $USER -Make sure you re-login to enable read and write permissions for the serial port. +Make sure you re-login to enable read and write permissions for the serial port. Verify serial connection diff --git a/docs/en/get-started-legacy/index.rst b/docs/en/get-started-legacy/index.rst index e3294a4189..0ea89b44c5 100644 --- a/docs/en/get-started-legacy/index.rst +++ b/docs/en/get-started-legacy/index.rst @@ -59,10 +59,10 @@ If you have one of ESP32 development boards listed below, you can click on the l .. toctree:: :maxdepth: 1 - ESP32-DevKitC <../hw-reference/get-started-devkitc> - ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> - ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> - ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> + ESP32-DevKitC <../hw-reference/esp32/get-started-devkitc> + ESP-WROVER-KIT <../hw-reference/esp32/get-started-wrover-kit> + ESP32-PICO-KIT <../hw-reference/esp32/get-started-pico-kit> + ESP32-Ethernet-Kit <../hw-reference/esp32/get-started-ethernet-kit> .. _get-started-step-by-step-legacy: @@ -96,7 +96,7 @@ Step 1. Set up the Toolchain The toolchain is a set of programs for compiling code and building applications. -The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow the provided instructions. +The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow the provided instructions. .. toctree:: :hidden: @@ -179,7 +179,7 @@ The python packages required by ESP-IDF are located in ``IDF_PATH/requirements.t .. note:: - Please check the version of the Python interpreter that you will be using with ESP-IDF. For this, run + Please check the version of the Python interpreter that you will be using with ESP-IDF. For this, run the command ``python --version`` and depending on the result, you might want to use ``python2``, ``python2.7`` or similar instead of just ``python``, e.g.:: @@ -226,7 +226,7 @@ Step 6. Connect Your Device Now connect your ESP32 board to the computer and check under what serial port the board is visible. -Serial ports have the following patterns in their names: +Serial ports have the following patterns in their names: - **Windows**: names like ``COM1`` - **Linux**: starting with ``/dev/tty`` @@ -421,9 +421,9 @@ Some environment variables can be specified whilst calling ``make`` allowing use +-----------------+--------------------------------------------------------------+ .. note:: - + You can export environment variables (e.g. ``export ESPPORT=/dev/ttyUSB1``). - All subsequent calls of ``make`` within the same terminal session will use + All subsequent calls of ``make`` within the same terminal session will use the exported value given that the variable is not simultaneously overridden. diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index e3ea9c76c3..4580acbd67 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -70,10 +70,10 @@ If you have one of {IDF_TARGET_NAME} development boards listed below, you can cl .. toctree:: :maxdepth: 1 - ESP32-DevKitC <../hw-reference/get-started-devkitc> - ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> - ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> - ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> + ESP32-DevKitC <../hw-reference/esp32/get-started-devkitc> + ESP-WROVER-KIT <../hw-reference/esp32/get-started-wrover-kit> + ESP32-PICO-KIT <../hw-reference/esp32/get-started-pico-kit> + ESP32-Ethernet-Kit <../hw-reference/esp32/get-started-ethernet-kit> .. _get-started-step-by-step: diff --git a/docs/en/hw-reference/get-started-devkitc-v2.rst b/docs/en/hw-reference/esp32/get-started-devkitc-v2.rst similarity index 92% rename from docs/en/hw-reference/get-started-devkitc-v2.rst rename to docs/en/hw-reference/esp32/get-started-devkitc-v2.rst index bef33a2780..f0d2e2594d 100644 --- a/docs/en/hw-reference/get-started-devkitc-v2.rst +++ b/docs/en/hw-reference/esp32/get-started-devkitc-v2.rst @@ -29,7 +29,7 @@ The following figure and the table below describe the key components, interfaces .. _get-started-esp32-devkitc-v2-board-front-make: -.. figure:: ../../_static/esp32-devkitc-v2-functional-overview.png +.. figure:: ../../../_static/esp32-devkitc-v2-functional-overview.png :align: center :alt: ESP32-DevKitC V2 board layout :figclass: align-center @@ -71,7 +71,7 @@ Start Application Development Before powering up your ESP32-DevKitC V2, please make sure that the board is in good condition with no obvious signs of damage. -After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. +After that, proceed to :doc:`../../get-started/index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents diff --git a/docs/en/hw-reference/get-started-devkitc.rst b/docs/en/hw-reference/esp32/get-started-devkitc.rst similarity index 92% rename from docs/en/hw-reference/get-started-devkitc.rst rename to docs/en/hw-reference/esp32/get-started-devkitc.rst index 3d10640252..c083da7754 100644 --- a/docs/en/hw-reference/get-started-devkitc.rst +++ b/docs/en/hw-reference/esp32/get-started-devkitc.rst @@ -3,7 +3,7 @@ ESP32-DevKitC V4 Getting Started Guide :link_to_translation:`zh_CN:[中文]` -This guide shows how to start using the ESP32-DevKitC V4 development board. For description of other versions of ESP32-DevKitC check :doc:`../hw-reference/index`. +This guide shows how to start using the ESP32-DevKitC V4 development board. For description of other versions of ESP32-DevKitC check :doc:`../../hw-reference/index`. What You Need @@ -21,7 +21,7 @@ You can skip the introduction sections and go directly to Section `Start Applica Overview -------- -ESP32-DevKitC V4 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 either connect peripherals with jumper wires or mount ESP32-DevKitC V4 on a breadboard. +ESP32-DevKitC V4 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 either connect peripherals with jumper wires or mount ESP32-DevKitC V4 on a breadboard. To cover a wide range of user requirements, the following versions of ESP32-DevKitC V4 are available: @@ -48,7 +48,7 @@ The following figure and the table below describe the key components, interfaces .. _get-started-esp32-devkitc-board-front: -.. figure:: ../../_static/esp32-devkitc-functional-overview.jpg +.. figure:: ../../../_static/esp32-devkitc-functional-overview.jpg :align: center :alt: ESP32-DevKitC V4 with ESP-WROOM-32 module soldered :figclass: align-center @@ -76,7 +76,7 @@ The following figure and the table below describe the key components, interfaces .. note:: - The pins D0, D1, D2, D3, CMD and CLK are used internally for communication between ESP32 and SPI flash memory. They are grouped on both sides near the USB connector. Avoid using these pins, as it may disrupt access to the SPI flash memory / SPI RAM. + The pins D0, D1, D2, D3, CMD and CLK are used internally for communication between ESP32 and SPI flash memory. They are grouped on both sides near the USB connector. Avoid using these pins, as it may disrupt access to the SPI flash memory / SPI RAM. .. note:: @@ -108,7 +108,7 @@ The component C15 may cause the following issues on earlier ESP32-DevKitC V4 boa In case these issues occur, please remove the component. The figure below shows C15 highlighted in yellow. -.. figure:: ../../_static/esp32-devkitc-c15-location.png +.. figure:: ../../../_static/esp32-devkitc-c15-location.png :align: center :alt: Location of C15 (colored yellow) on ESP32-DevKitC V4 board :figclass: align-center @@ -122,13 +122,13 @@ Start Application Development Before powering up your ESP32-DevKitC V4, please make sure that the board is in good condition with no obvious signs of damage. -After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. +After that, proceed to :doc:`../../get-started/index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Board Dimensions ---------------- -.. figure:: ../../_static/esp32-devkitc-dimensions-back.jpg +.. figure:: ../../../_static/esp32-devkitc-dimensions-back.jpg :align: center :alt: ESP32 DevKitC board dimensions - back :figclass: align-center @@ -145,7 +145,7 @@ Related Documents * `ESP32-WROOM-32D & ESP32-WROOM-32U Datasheet `_ (PDF) * `ESP32-WROVER Datasheet `_ (PDF) * `ESP32-WROVER-B Datasheet `_ (PDF) -* `Espressif Product Ordering Information `_ (PDF) +* `Espressif Product Ordering Information `_ (PDF) .. toctree:: :hidden: diff --git a/docs/en/hw-reference/get-started-ethernet-kit-v1.0.rst b/docs/en/hw-reference/esp32/get-started-ethernet-kit-v1.0.rst similarity index 95% rename from docs/en/hw-reference/get-started-ethernet-kit-v1.0.rst rename to docs/en/hw-reference/esp32/get-started-ethernet-kit-v1.0.rst index 5bb64ae8ec..2965319936 100644 --- a/docs/en/hw-reference/get-started-ethernet-kit-v1.0.rst +++ b/docs/en/hw-reference/esp32/get-started-ethernet-kit-v1.0.rst @@ -25,7 +25,7 @@ It consists of two development boards, the Ethernet board A and the PoE board B, .. _get-started-esp32-ethernet-kit-b-v1.0: -.. figure:: ../../_static/esp32-ethernet-kit-v1.0.png +.. figure:: ../../../_static/esp32-ethernet-kit-v1.0.png :align: center :alt: ESP32-Ethernet-Kit V1.0 :figclass: align-center @@ -40,7 +40,7 @@ Functionality Overview The block diagram below shows the main components of ESP32-Ethernet-Kit and their interconnections. -.. figure:: ../../_static/esp32-ethernet-kit-block-diagram.png +.. figure:: ../../../_static/esp32-ethernet-kit-block-diagram.png :align: center :scale: 50% :alt: ESP32-Ethernet-Kit block diagram (click to enlarge) @@ -60,7 +60,7 @@ The following two figures and tables describe the key components, interfaces, an Ethernet Board (A) ^^^^^^^^^^^^^^^^^^ -.. figure:: ../../_static/esp32-ethernet-kit-a-v1.0-layout.png +.. figure:: ../../../_static/esp32-ethernet-kit-a-v1.0-layout.png :align: center :scale: 80% :alt: ESP32-Ethernet-Kit - Ethernet board (A) layout @@ -121,7 +121,7 @@ GPIO Header 1 This header provides six unpopulated through-hole solder pad PoE Board (B) ^^^^^^^^^^^^^ -This board coverts power delivered over the Ethernet cable (PoE) to provide a power supply for the Ethernet board (A). The main components of the PoE board (B) are shown on the block diagram under `Functionality Overview`_. +This board coverts power delivered over the Ethernet cable (PoE) to provide a power supply for the Ethernet board (A). The main components of the PoE board (B) are shown on the block diagram under `Functionality Overview`_. The PoE board (B) has the following features: @@ -130,7 +130,7 @@ The PoE board (B) has the following features: To take advantage of the PoE functionality the **RJ45 Port** of the Ethernet board (A) should be connected with an Ethernet cable to a switch that supports PoE. When the Ethernet board (A) detects 5 V power output from the PoE board (B), the USB power will be automatically cut off. -.. figure:: ../../_static/esp32-ethernet-kit-b-v1.0-layout.png +.. figure:: ../../../_static/esp32-ethernet-kit-b-v1.0-layout.png :align: center :scale: 80% :alt: ESP32-Ethernet-Kit - PoE board (B) @@ -171,7 +171,7 @@ DIP SW GPIO Pin Pin Functionality if DIP SW is ON 5 GPIO4 Connected to FT2232H to provide JTAG functionality 6 GPIO2 Connected to on-board 25 MHz oscillator 7 GPIO5 Connected to RESET_N input of IP101GRI - 8 n/a + 8 n/a ======= ================ ================================================================ You can make a certain GPIO pin available for other purposes by putting its DIP SW to the Off position. @@ -195,7 +195,7 @@ This is a 2 x 2 jumper pin header intended for the UART flow control. GPIO Allocation --------------- -This section describes allocation of ESP32 GPIOs to specific interfaces or functions of the ESP32-Ethernet-Kit. +This section describes allocation of ESP32 GPIOs to specific interfaces or functions of the ESP32-Ethernet-Kit. IP101GRI (PHY) Interface @@ -234,7 +234,7 @@ The allocation of the ESP32 (MAC) pins to IP101GRI (PHY) is shown in the table b GPIO Header 1 ^^^^^^^^^^^^^ -This header exposes some GPIOs that are not used elsewhere on the ESP32-Ethernet-Kit. +This header exposes some GPIOs that are not used elsewhere on the ESP32-Ethernet-Kit. ==== ================ . ESP32 Pin @@ -258,7 +258,7 @@ This header contains the GPIOs with specific MII functionality (except GPIO2), a ==== ========== ================= ================== 1 GPIO17 EMAC_CLK_180 See note 1 2 GPIO16 EMAC_CLK_OUT See note 1 - 3 GPIO4 EMAC_TX_ER + 3 GPIO4 EMAC_TX_ER 4 GPIO2 n/a See note 2 5 GPIO5 EMAC_RX_CLK See note 2 ==== ========== ================= ================== @@ -346,7 +346,7 @@ Initial Setup Now to Development ^^^^^^^^^^^^^^^^^^ -Proceed to :doc:`../get-started/index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. +Proceed to :doc:`../../get-started/index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Move on to the next section only if you have successfully completed all the above steps. @@ -354,7 +354,7 @@ Move on to the next section only if you have successfully completed all the abov Configure and Load the Ethernet Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -After setting up the development environment and testing the board, you can configure and flash the :example:`ethernet/ethernet` example. This example has been created for testing Ethernet functionality. It supports different PHY, including **IP101GRI** installed on :ref:`ESP32-Ethernet-Kit V1.0 board `. +After setting up the development environment and testing the board, you can configure and flash the :example:`ethernet/ethernet` example. This example has been created for testing Ethernet functionality. It supports different PHY, including **IP101GRI** installed on :ref:`ESP32-Ethernet-Kit V1.0 board `. Related Documents @@ -364,8 +364,8 @@ Related Documents * `ESP32-Ethernet-Kit V1.0 PoE board (B) schematic`_ (PDF) * `ESP32 Datasheet `_ (PDF) * `ESP32-WROVER-B Datasheet `_ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* :doc:`../hw-reference/index` +* :doc:`../../api-guides/jtag-debugging/index` +* :doc:`../../hw-reference/index` .. _ESP32-Ethernet-Kit V1.0 Ethernet board (A) schematic: https://dl.espressif.com/dl/schematics/SCH_ESP32-ETHERNET-KIT_A_V1.0_20190517.pdf .. _ESP32-Ethernet-Kit V1.0 PoE board (B) schematic: https://dl.espressif.com/dl/schematics/SCH_ESP32-ETHERNET-KIT_B_V1.0_20190517.pdf diff --git a/docs/en/hw-reference/get-started-ethernet-kit.rst b/docs/en/hw-reference/esp32/get-started-ethernet-kit.rst similarity index 95% rename from docs/en/hw-reference/get-started-ethernet-kit.rst rename to docs/en/hw-reference/esp32/get-started-ethernet-kit.rst index cb8bfb31ab..c0d149f76a 100644 --- a/docs/en/hw-reference/get-started-ethernet-kit.rst +++ b/docs/en/hw-reference/esp32/get-started-ethernet-kit.rst @@ -25,7 +25,7 @@ It consists of two development boards, the Ethernet board A and the PoE board B. .. _get-started-esp32-ethernet-kit-v1.1: -.. figure:: ../../_static/esp32-ethernet-kit-v1.1.png +.. figure:: ../../../_static/esp32-ethernet-kit-v1.1.png :align: center :alt: ESP32-Ethernet-Kit V1.1 :figclass: align-center @@ -40,7 +40,7 @@ Functionality Overview The block diagram below shows the main components of ESP32-Ethernet-Kit and their interconnections. -.. figure:: ../../_static/esp32-ethernet-kit-v1.1-block-diagram.png +.. figure:: ../../../_static/esp32-ethernet-kit-v1.1-block-diagram.png :align: center :scale: 60% :alt: ESP32-Ethernet-Kit block diagram (click to enlarge) @@ -60,7 +60,7 @@ The following figures and tables describe the key components, interfaces, and co Ethernet Board (A) ^^^^^^^^^^^^^^^^^^ -.. figure:: ../../_static/esp32-ethernet-kit-a-v1.1-layout.png +.. figure:: ../../../_static/esp32-ethernet-kit-a-v1.1-layout.png :align: center :scale: 80% :alt: ESP32-Ethernet-Kit - Ethernet board (A) layout @@ -114,7 +114,7 @@ GPIO Header 1 This header provides six unpopulated through-hole solder pad PoE Board (B) ^^^^^^^^^^^^^ -This board coverts power delivered over the Ethernet cable (PoE) to provide a power supply for the Ethernet board (A). The main components of the PoE board (B) are shown on the block diagram under `Functionality Overview`_. +This board coverts power delivered over the Ethernet cable (PoE) to provide a power supply for the Ethernet board (A). The main components of the PoE board (B) are shown on the block diagram under `Functionality Overview`_. The PoE board (B) has the following features: @@ -123,7 +123,7 @@ The PoE board (B) has the following features: To take advantage of the PoE functionality the **RJ45 Port** of the Ethernet board (A) should be connected with an Ethernet cable to a switch that supports PoE. When the Ethernet board (A) detects 5 V power output from the PoE board (B), the USB power will be automatically cut off. -.. figure:: ../../_static/esp32-ethernet-kit-b-v1.0-layout.png +.. figure:: ../../../_static/esp32-ethernet-kit-b-v1.0-layout.png :align: center :scale: 80% :alt: ESP32-Ethernet-Kit - PoE board (B) @@ -153,7 +153,7 @@ This section describes options to configure the ESP32-Ethernet-Kit hardware. Function Switch ^^^^^^^^^^^^^^^ -When in On position, this DIP switch is routing listed GPIOs to FT2232H to provide JTAG functionality. When in Off position, the GPIOs may be used for other purposes. +When in On position, this DIP switch is routing listed GPIOs to FT2232H to provide JTAG functionality. When in Off position, the GPIOs may be used for other purposes. ======= ================ DIP SW GPIO Pin @@ -183,7 +183,7 @@ RMII Clock Sourced Externally by PHY By default, the ESP32-Ethernet-Kit is configured to provide RMII clock for the IP101GRI PHY's 50M_CLKO output. The clock signal is generated by the frequency multiplication of 25 MHz crystal connected to the PHY. For details, please see the figure below. -.. figure:: ../../_static/esp32-ethernet-kit-rmii-clk-from-phy.png +.. figure:: ../../../_static/esp32-ethernet-kit-rmii-clk-from-phy.png :align: center :scale: 80% :alt: RMII Clock from IP101GRI PHY @@ -196,10 +196,10 @@ Please note that the PHY is reset on power up by pulling the RESET_N signal down RMII Clock Sourced Internally from ESP32's APLL """"""""""""""""""""""""""""""""""""""""""""""" -Another option is to source the RMII Clock from internal ESP32 APLL, see figure below. The clock signal coming from GPIO0 is first inverted, to account for transmission line delay, and then supplied to the PHY. +Another option is to source the RMII Clock from internal ESP32 APLL, see figure below. The clock signal coming from GPIO0 is first inverted, to account for transmission line delay, and then supplied to the PHY. -.. figure:: ../../_static/esp32-ethernet-kit-rmii-clk-to-phy.png +.. figure:: ../../../_static/esp32-ethernet-kit-rmii-clk-to-phy.png :align: center :scale: 80% :alt: RMII Clock from ESP Internal APLL @@ -213,7 +213,7 @@ To implement this option, users need to remove or add some RC components on the GPIO Allocation --------------- -This section describes allocation of ESP32 GPIOs to specific interfaces or functions of the ESP32-Ethernet-Kit. +This section describes allocation of ESP32 GPIOs to specific interfaces or functions of the ESP32-Ethernet-Kit. IP101GRI (PHY) Interface @@ -252,7 +252,7 @@ The allocation of the ESP32 (MAC) pins to IP101GRI (PHY) is shown in the table b GPIO Header 1 ^^^^^^^^^^^^^ -This header exposes some GPIOs that are not used elsewhere on the ESP32-Ethernet-Kit. +This header exposes some GPIOs that are not used elsewhere on the ESP32-Ethernet-Kit. ==== ================ . ESP32 Pin @@ -329,7 +329,7 @@ GPIO Allocation Summary .. note:: 1. To prevent the power-on state of the GPIO0 from being affected by the clock output on the PHY side, the RESET_N signal to PHY defaults to low, turning the clock output off. After power-on you can control RESET_N with GPIO5 to turn the clock output on. See also `RMII Clock Sourced Externally by PHY`_. For PHYs that cannot turn off the clock output through RESET_N, it is recommended to use a crystal module that can be disabled / enabled externally. Similarly like when using RESET_N, the oscillator module should be disabled by default and turned on by ESP32 after power-up. For a reference design please see `ESP32-Ethernet-Kit V1.1 Ethernet board (A) schematic`_. - + 2. The ESP32 pins GPIO16 and GPIO17 are not broken out to the ESP32-WROVER-B module and therefore not available for use. If you need to use these pins, please solder a module without PSRAM memory inside, e.g. the ESP32-WROOM-32D or ESP32-SOLO-1. @@ -351,7 +351,7 @@ Initial Setup Now to Development ^^^^^^^^^^^^^^^^^^ -Proceed to :doc:`../get-started/index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. +Proceed to :doc:`../../get-started/index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Move on to the next section only if you have successfully completed all the above steps. @@ -359,7 +359,7 @@ Move on to the next section only if you have successfully completed all the abov Configure and Load the Ethernet Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -After setting up the development environment and testing the board, you can configure and flash the :example:`ethernet/ethernet` example. This example has been created for testing Ethernet functionality. It supports different PHY, including **IP101GRI** installed on :ref:`get-started-esp32-ethernet-kit-v1.1`. +After setting up the development environment and testing the board, you can configure and flash the :example:`ethernet/ethernet` example. This example has been created for testing Ethernet functionality. It supports different PHY, including **IP101GRI** installed on :ref:`get-started-esp32-ethernet-kit-v1.1`. Summary of Changes from ESP32-Ethernet-Kit V1.0 @@ -387,8 +387,8 @@ Related Documents * `ESP32-Ethernet-Kit V1.0 PoE board (B) schematic`_ (PDF) * `ESP32 Datasheet `_ (PDF) * `ESP32-WROVER-B Datasheet `_ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* :doc:`../hw-reference/index` +* :doc:`../../api-guides/jtag-debugging/index` +* :doc:`../../hw-reference/index` .. _ESP32-Ethernet-Kit V1.1 Ethernet board (A) schematic: https://dl.espressif.com/dl/schematics/SCH_ESP32-ETHERNET-KIT_A_V1.1_20190711.pdf .. _ESP32-Ethernet-Kit V1.0 PoE board (B) schematic: https://dl.espressif.com/dl/schematics/SCH_ESP32-ETHERNET-KIT_B_V1.0_20190517.pdf diff --git a/docs/en/hw-reference/get-started-pico-kit-v3.rst b/docs/en/hw-reference/esp32/get-started-pico-kit-v3.rst similarity index 88% rename from docs/en/hw-reference/get-started-pico-kit-v3.rst rename to docs/en/hw-reference/esp32/get-started-pico-kit-v3.rst index b8b2366f61..d96ab35238 100644 --- a/docs/en/hw-reference/get-started-pico-kit-v3.rst +++ b/docs/en/hw-reference/esp32/get-started-pico-kit-v3.rst @@ -2,7 +2,7 @@ ESP32-PICO-KIT V3 Getting Started Guide ======================================= :link_to_translation:`zh_CN:[中文]` -This guide shows how to get started with the ESP32-PICO-KIT V3 mini development board. For the description of other ESP32-PICO-KIT versions, please check :doc:`../hw-reference/index`. +This guide shows how to get started with the ESP32-PICO-KIT V3 mini development board. For the description of other ESP32-PICO-KIT versions, please check :doc:`../../hw-reference/index`. What You Need @@ -30,7 +30,7 @@ Functional Description The following figure and the table below describe the key components, interfaces, and controls of the ESP32-PICO-KIT V3 board. -.. figure:: ../../_static/esp32-pico-kit-v3-layout.jpg +.. figure:: ../../../_static/esp32-pico-kit-v3-layout.jpg :align: center :alt: ESP32-PICO-KIT V3 board layout :figclass: align-center @@ -65,7 +65,7 @@ Start Application Development Before powering up your ESP32-PICO-KIT V3, please make sure that the board is in good condition with no obvious signs of damage. -After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. +After that, proceed to :doc:`../../get-started/index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents @@ -73,5 +73,5 @@ Related Documents * `ESP32-PICO-KIT V3 schematic `_ (PDF) * `ESP32-PICO-D4 Datasheet `_ (PDF) -* :doc:`../hw-reference/index` +* :doc:`../../hw-reference/index` diff --git a/docs/en/hw-reference/get-started-pico-kit.rst b/docs/en/hw-reference/esp32/get-started-pico-kit.rst similarity index 94% rename from docs/en/hw-reference/get-started-pico-kit.rst rename to docs/en/hw-reference/esp32/get-started-pico-kit.rst index 73c4b5ef65..0273a72234 100644 --- a/docs/en/hw-reference/get-started-pico-kit.rst +++ b/docs/en/hw-reference/esp32/get-started-pico-kit.rst @@ -2,7 +2,7 @@ ESP32-PICO-KIT V4 / V4.1 Getting Started Guide ============================================== :link_to_translation:`zh_CN:[中文]` -This guide shows how to get started with the ESP32-PICO-KIT V4 / V4.1 mini development board. For the description of other ESP32-PICO-KIT versions, please check :doc:`../hw-reference/index`. +This guide shows how to get started with the ESP32-PICO-KIT V4 / V4.1 mini development board. For the description of other ESP32-PICO-KIT versions, please check :doc:`../../hw-reference/index`. This particular description covers ESP32-PICO-KIT V4 and V4.1. The difference is the upgraded USB-UART bridge from CP2102 in V4 with up to 1 Mbps transfer rates to CP2102N in V4.1 with up to 3 Mbps transfer rates. @@ -33,7 +33,7 @@ This setup reduces the costs of additional external components as well as the co The development board features a USB-UART Bridge circuit which allows developers to connect the board to a computer's USB port for flashing and debugging. -All the IO signals and system power on ESP32-PICO-D4 are led out to two rows of 20 x 0.1" header pads on both sides of the development board for easy access. For compatibility with Dupont wires, 2 x 17 header pads are populated with two rows of male pin headers. The remaining 2 x 3 header pads beside the antenna are not populated. These pads may be populated later by the user if required. +All the IO signals and system power on ESP32-PICO-D4 are led out to two rows of 20 x 0.1" header pads on both sides of the development board for easy access. For compatibility with Dupont wires, 2 x 17 header pads are populated with two rows of male pin headers. The remaining 2 x 3 header pads beside the antenna are not populated. These pads may be populated later by the user if required. .. note:: @@ -45,7 +45,7 @@ Functionality Overview The block diagram below shows the main components of ESP32-PICO-KIT and their interconnections. -.. figure:: ../../_static/esp32-pico-kit-v4-functional-block-diagram.png +.. figure:: ../../../_static/esp32-pico-kit-v4-functional-block-diagram.png :align: center :alt: ESP32-PICO-KIT functional block diagram :figclass: align-center @@ -60,7 +60,7 @@ The following figure and the table below describe the key components, interfaces .. _get-started-pico-kit-v4-board-front: -.. figure:: ../../_static/esp32-pico-kit-v4.1-f-layout.jpeg +.. figure:: ../../../_static/esp32-pico-kit-v4.1-f-layout.jpeg :align: center :alt: ESP32-PICO-KIT board layout :figclass: align-center @@ -118,7 +118,7 @@ No. Name Type Function ====== ================= ====== ====================================================== 1 FLASH_SD1 (FSD1) I/O | GPIO8, SD_DATA1, SPID, HS1_DATA1 :ref:`(See 1) ` , U2CTS 2 FLASH_SD3 (FSD3) I/O | GPIO7, SD_DATA0, SPIQ, HS1_DATA0 :ref:`(See 1) ` , U2RTS -3 FLASH_CLK (FCLK) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`(See 1) ` , U1CTS +3 FLASH_CLK (FCLK) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`(See 1) ` , U1CTS 4 IO21 I/O | GPIO21, VSPIHD, EMAC_TX_EN 5 IO22 I/O | GPIO22, VSPIWP, U0RTS, EMAC_TXD1 6 IO19 I/O | GPIO19, VSPIQ, U0CTS, EMAC_TXD0 @@ -193,7 +193,7 @@ Start Application Development Before powering up your ESP32-PICO-KIT, please make sure that the board is in good condition with no obvious signs of damage. -After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. +After that, proceed to :doc:`../../get-started/index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Board Dimensions @@ -201,14 +201,14 @@ Board Dimensions The dimensions are 52 x 20.3 x 10 mm (2.1" x 0.8" x 0.4"). -.. figure:: ../../_static/esp32-pico-kit-v4.1-dimensions-back.jpg +.. figure:: ../../../_static/esp32-pico-kit-v4.1-dimensions-back.jpg :align: center :alt: ESP32-PICO-KIT dimensions - back :figclass: align-center ESP32-PICO-KIT dimensions - back -.. figure:: ../../_static/esp32-pico-kit-v4-dimensions-side.jpg +.. figure:: ../../../_static/esp32-pico-kit-v4-dimensions-side.jpg :align: center :alt: ESP32-PICO-KIT V4 dimensions - side :figclass: align-center @@ -225,7 +225,7 @@ Related Documents * `ESP32-PICO-KIT V4.1 schematic `_ (PDF) * `ESP32-PICO-KIT Reference Design `_ containing OrCAD schematic, PCB layout, gerbers and BOM * `ESP32-PICO-D4 Datasheet `_ (PDF) -* :doc:`../hw-reference/index` +* :doc:`../../hw-reference/index` .. toctree:: diff --git a/docs/en/hw-reference/get-started-wrover-kit-v2.rst b/docs/en/hw-reference/esp32/get-started-wrover-kit-v2.rst similarity index 90% rename from docs/en/hw-reference/get-started-wrover-kit-v2.rst rename to docs/en/hw-reference/esp32/get-started-wrover-kit-v2.rst index 1aa0c6b595..75fbba8c1a 100644 --- a/docs/en/hw-reference/get-started-wrover-kit-v2.rst +++ b/docs/en/hw-reference/esp32/get-started-wrover-kit-v2.rst @@ -2,7 +2,7 @@ ESP-WROVER-KIT V2 Getting Started Guide ======================================= :link_to_translation:`zh_CN:[中文]` -This guide shows how to get started with the ESP-WROVER-KIT V2 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../hw-reference/index`. +This guide shows how to get started with the ESP-WROVER-KIT V2 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../../hw-reference/index`. What You Need @@ -39,7 +39,7 @@ Functionality Overview The block diagram below shows the main components of ESP-WROVER-KIT and their interconnections. -.. figure:: ../../_static/esp-wrover-kit-block-diagram.png +.. figure:: ../../../_static/esp-wrover-kit-block-diagram.png :align: center :alt: ESP-WROVER-KIT block diagram :figclass: align-center @@ -54,7 +54,7 @@ The following two figures and the table below describe the key components, inter .. _get-started-esp-wrover-kit-v2-board-front: -.. figure:: ../../_static/esp-wrover-kit-v2-layout-front.png +.. figure:: ../../../_static/esp-wrover-kit-v2-layout-front.png :align: center :alt: ESP-WROVER-KIT board layout - front :figclass: align-center @@ -63,7 +63,7 @@ The following two figures and the table below describe the key components, inter .. _get-started-esp-wrover-kit-v2-board-back: -.. figure:: ../../_static/esp-wrover-kit-v2-layout-back.png +.. figure:: ../../../_static/esp-wrover-kit-v2-layout-back.png :align: center :alt: ESP-WROVER-KIT board layout - back :figclass: align-center @@ -170,7 +170,7 @@ Turn the **Power Switch** to ON, the **5V Power On LED** should light up. Now to Development ^^^^^^^^^^^^^^^^^^ -Please proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. +Please proceed to :doc:`../../get-started/index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents @@ -180,16 +180,16 @@ Related Documents * `ESP32 Datasheet `_ (PDF) * `ESP32-WROVER Datasheet `_ (PDF) * `ESP32-WROOM-32 Datasheet `_ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* :doc:`../hw-reference/index` +* :doc:`../../api-guides/jtag-debugging/index` +* :doc:`../../hw-reference/index` -.. |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-tx-rx| image:: ../../_static/wrover-jp11-tx-rx.png -.. |jp14| image:: ../../_static/wrover-jp14.png +.. |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-tx-rx| image:: ../../../_static/wrover-jp11-tx-rx.png +.. |jp14| image:: ../../../_static/wrover-jp14.png .. _ESP-WROVER-KIT V2 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf diff --git a/docs/en/hw-reference/get-started-wrover-kit-v3.rst b/docs/en/hw-reference/esp32/get-started-wrover-kit-v3.rst similarity index 94% rename from docs/en/hw-reference/get-started-wrover-kit-v3.rst rename to docs/en/hw-reference/esp32/get-started-wrover-kit-v3.rst index 276c6877ba..cb2c1cf36d 100644 --- a/docs/en/hw-reference/get-started-wrover-kit-v3.rst +++ b/docs/en/hw-reference/esp32/get-started-wrover-kit-v3.rst @@ -3,7 +3,7 @@ ESP-WROVER-KIT V3 Getting Started Guide ======================================= :link_to_translation:`zh_CN:[中文]` -This guide shows how to get started with the ESP-WROVER-KIT V3 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../hw-reference/index`. +This guide shows how to get started with the ESP-WROVER-KIT V3 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../../hw-reference/index`. What You Need @@ -40,7 +40,7 @@ Functionality Overview The block diagram below shows the main components of ESP-WROVER-KIT and their interconnections. -.. figure:: ../../_static/esp-wrover-kit-block-diagram.png +.. figure:: ../../../_static/esp-wrover-kit-block-diagram.png :align: center :alt: ESP-WROVER-KIT block diagram :figclass: align-center @@ -55,7 +55,7 @@ The following two figures and the table below describe the key components, inter .. _get-started-esp-wrover-kit-v3-board-front: -.. figure:: ../../_static/esp-wrover-kit-v3-layout-front.jpg +.. figure:: ../../../_static/esp-wrover-kit-v3-layout-front.jpg :align: center :alt: ESP-WROVER-KIT board layout - front :figclass: align-center @@ -64,7 +64,7 @@ The following two figures and the table below describe the key components, inter .. _get-started-esp-wrover-kit-v3-board-back: -.. figure:: ../../_static/esp-wrover-kit-v3-layout-back.jpg +.. figure:: ../../../_static/esp-wrover-kit-v3-layout-back.jpg :align: center :alt: ESP-WROVER-KIT board layout - back :figclass: align-center @@ -280,7 +280,7 @@ RGB LED ^^^^^^^ ==== ========== ========= -. ESP32 Pin RGB LED +. ESP32 Pin RGB LED ==== ========== ========= 1 GPIO0 Red 2 GPIO2 Green @@ -354,7 +354,7 @@ Turn the **Power Switch** to ON, the **5V Power On LED** should light up. Now to Development ^^^^^^^^^^^^^^^^^^ -Please proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. +Please proceed to :doc:`../../get-started/index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents @@ -364,14 +364,14 @@ Related Documents * `ESP32 Datasheet `_ (PDF) * `ESP32-WROVER Datasheet `_ (PDF) * `ESP32-WROOM-32 Datasheet `_ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* :doc:`../hw-reference/index` +* :doc:`../../api-guides/jtag-debugging/index` +* :doc:`../../hw-reference/index` -.. |jp7-ext_5v| image:: ../../_static/esp-wrover-kit-v3-jp7-ext_5v.png -.. |jp7-usb_5v| image:: ../../_static/esp-wrover-kit-v3-jp7-usb_5v.png -.. |jp8| image:: ../../_static/esp-wrover-kit-v3-jp8.png -.. |jp11-tx-rx| image:: ../../_static/esp-wrover-kit-v3-jp11-tx-rx.png -.. |jp14| image:: ../../_static/esp-wrover-kit-v3-jp14.png +.. |jp7-ext_5v| image:: ../../../_static/esp-wrover-kit-v3-jp7-ext_5v.png +.. |jp7-usb_5v| image:: ../../../_static/esp-wrover-kit-v3-jp7-usb_5v.png +.. |jp8| image:: ../../../_static/esp-wrover-kit-v3-jp8.png +.. |jp11-tx-rx| image:: ../../../_static/esp-wrover-kit-v3-jp11-tx-rx.png +.. |jp14| image:: ../../../_static/esp-wrover-kit-v3-jp14.png .. _ESP-WROVER-KIT V3 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-3.pdf diff --git a/docs/en/hw-reference/get-started-wrover-kit.rst b/docs/en/hw-reference/esp32/get-started-wrover-kit.rst similarity index 94% rename from docs/en/hw-reference/get-started-wrover-kit.rst rename to docs/en/hw-reference/esp32/get-started-wrover-kit.rst index b10f62688a..93b6acfe96 100644 --- a/docs/en/hw-reference/get-started-wrover-kit.rst +++ b/docs/en/hw-reference/esp32/get-started-wrover-kit.rst @@ -2,7 +2,7 @@ ESP-WROVER-KIT V4.1 Getting Started Guide ========================================= :link_to_translation:`zh_CN:[中文]` -This guide shows how to get started with the ESP-WROVER-KIT V4.1 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../hw-reference/index`. +This guide shows how to get started with the ESP-WROVER-KIT V4.1 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../../hw-reference/index`. What You Need @@ -40,7 +40,7 @@ Functionality Overview The block diagram below shows the main components of ESP-WROVER-KIT and their interconnections. -.. figure:: ../../_static/esp-wrover-kit-block-diagram.png +.. figure:: ../../../_static/esp-wrover-kit-block-diagram.png :align: center :alt: ESP-WROVER-KIT block diagram :figclass: align-center @@ -55,7 +55,7 @@ The following two figures and the table below describe the key components, inter .. _get-started-esp-wrover-kit-v4.1-board-front: -.. figure:: ../../_static/esp-wrover-kit-v4.1-layout-front.png +.. figure:: ../../../_static/esp-wrover-kit-v4.1-layout-front.png :align: center :alt: ESP-WROVER-KIT board layout - front :figclass: align-center @@ -64,7 +64,7 @@ The following two figures and the table below describe the key components, inter .. _get-started-esp-wrover-kit-v4.1-board-back: -.. figure:: ../../_static/esp-wrover-kit-v4.1-layout-back.png +.. figure:: ../../../_static/esp-wrover-kit-v4.1-layout-back.png :align: center :alt: ESP-WROVER-KIT board layout - back :figclass: align-center @@ -284,7 +284,7 @@ RGB LED ^^^^^^^ ==== ========== ========= -. ESP32 Pin RGB LED +. ESP32 Pin RGB LED ==== ========== ========= 1 GPIO0 Red 2 GPIO2 Green @@ -358,7 +358,7 @@ Turn the **Power Switch** to ON, the **5V Power On LED** should light up. Now to Development ^^^^^^^^^^^^^^^^^^ -Please proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. +Please proceed to :doc:`../../get-started/index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents @@ -367,14 +367,14 @@ Related Documents * `ESP-WROVER-KIT V4.1 schematic`_ (PDF) * `ESP32 Datasheet `_ (PDF) * `ESP32-WROVER-B Datasheet `_ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* :doc:`../hw-reference/index` +* :doc:`../../api-guides/jtag-debugging/index` +* :doc:`../../hw-reference/index` -.. |jp7-ext_5v| image:: ../../_static/esp-wrover-kit-v4.1-jp7-ext_5v.jpg -.. |jp7-usb_5v| image:: ../../_static/esp-wrover-kit-v4.1-jp7-usb_5v.jpg -.. |jp2-jtag| image:: ../../_static/esp-wrover-kit-v4.1-jp2-jtag.jpg -.. |jp2-tx-rx| image:: ../../_static/esp-wrover-kit-v4.1-jp2-tx-rx.jpg -.. |jp14| image:: ../../_static/esp-wrover-kit-v4.1-jp14.jpg +.. |jp7-ext_5v| image:: ../../../_static/esp-wrover-kit-v4.1-jp7-ext_5v.jpg +.. |jp7-usb_5v| image:: ../../../_static/esp-wrover-kit-v4.1-jp7-usb_5v.jpg +.. |jp2-jtag| image:: ../../../_static/esp-wrover-kit-v4.1-jp2-jtag.jpg +.. |jp2-tx-rx| image:: ../../../_static/esp-wrover-kit-v4.1-jp2-tx-rx.jpg +.. |jp14| image:: ../../../_static/esp-wrover-kit-v4.1-jp14.jpg .. _ESP-WROVER-KIT V4.1 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_V4_1.pdf diff --git a/docs/en/hw-reference/esp32/inc/modules-and-boards-esp32.rst b/docs/en/hw-reference/esp32/inc/modules-and-boards-esp32.rst new file mode 100644 index 0000000000..fc18de3345 --- /dev/null +++ b/docs/en/hw-reference/esp32/inc/modules-and-boards-esp32.rst @@ -0,0 +1,289 @@ +.. _esp-wroom-solo-wrover-modules: + +Modules +======= + +This is a family of ESP32-based modules with some integrated key components, including a crystal oscillator and an antenna matching circuit. The modules constitute ready-made solutions for integration into final products. If combined with a few extra components, such as a programming interface, bootstrapping resistors, and pin headers, these modules can also be used for evaluation of ESP32's functionality. + +The key characteristics of these modules are summarized in the table below. Some additional details are covered in the following sections. + +=================== ============ =========== ========= ==== =============== +Module Chip Flash, MB PSRAM, MB Ant. Dimensions, mm +=================== ============ =========== ========= ==== =============== +ESP32-WROOM-32 ESP32-D0WDQ6 4 -- MIFA 18 × 25.5 × 3.1 +ESP32-WROOM-32D ESP32-D0WD 4, 8, or 16 -- MIFA 18 × 25.5 × 3.1 +ESP32-WROOM-32U ESP32-D0WD 4, 8, or 16 -- U.FL 18 × 19.2 × 3.1 +ESP32-SOLO-1 ESP32-S0WD 4 -- MIFA 18 × 25.5 × 3.1 +ESP32-WROVER (PCB) ESP32-D0WDQ6 4 8 MIFA 18 × 31.4 × 3.3 +ESP32-WROVER (IPEX) ESP32-D0WDQ6 4 8 U.FL 18 × 31.4 × 3.3 +ESP32-WROVER-B ESP32-D0WD 4, 8, or 16 8 MIFA 18 × 31.4 × 3.3 +ESP32-WROVER-IB ESP32-D0WD 4, 8, or 16 8 U.FL 18 × 31.4 × 3.3 +=================== ============ =========== ========= ==== =============== + +* ESP32-**D**.. identifies a dual-core chip, ESP32-**S**.. identifies a single-core chip +* MIFA - Meandered Inverted-F Antenna +* U.FL - U.FL / IPEX antenna connector +* ESP32-WROOM-32x, ESP32-WROVER-B and ESP32-WROVER-IB modules come with 4 MB flash by default but also available with custom flash sizes of 8 MB and 16 MB, see `Espressif Products Ordering Information`_ (PDF) +* `ESP32 Chip Datasheet `__ (PDF) +* Initial release of the ESP32-WROVER module had 4 MB of PSRAM +* *ESP32-WROOM-32* was previously called *ESP-WROOM-32* + + +.. _esp-modules-and-boards-esp32-wroom-32: + +ESP32-WROOM-32 +-------------- + +This is a basic and commonly adopted ESP32 module with the ESP32-D0WDQ6 chip on board. It was the first module of the WROOM / WROVER family released to the market. + +For key characteristics, see the table in Section :ref:`esp-wroom-solo-wrover-modules`, `Espressif Products Ordering Information`_. + + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32-front-back.jpg + :align: center + :alt: ESP32-WROOM-32 module (front and back) + :width: 45% + + ESP32-WROOM-32 module (front and back) + +Documentation +^^^^^^^^^^^^^ + +* `ESP32-WROOM-32 Datasheet `__ (PDF) +* `ESP32-WROOM-32 Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files + + +.. _esp-modules-and-boards-esp32-wroom-32d-and-u: + +ESP32-WROOM-32D / ESP32-WROOM-32U +--------------------------------- + +Both modules integrate the ESP32-D0WD chip which has a smaller footprint than the chip ESP32-D0WDQ6 installed in :ref:`esp-modules-and-boards-esp32-wroom-32`. + +For key characteristics, see the table in Section :ref:`esp-wroom-solo-wrover-modules` and `Espressif Products Ordering Information`_. + +ESP32-WROOM-32U is the smallest representative of the whole WROOM / WROVER family of modules. + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32d-front-back.jpg + :align: center + :alt: ESP32-WROOM-32D module (front and back) + :width: 45% + + ESP32-WROOM-32D module (front and back) + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32u-front-back.jpg + :align: center + :alt: ESP32-WROOM-32U module (front and back) + :width: 45% + + ESP32-WROOM-32U module (front and back) + +Documentation +^^^^^^^^^^^^^ + +* `ESP32-WROOM-32D / ESP32-WROOM-32U Datasheet `__ (PDF) + + +.. _esp-modules-and-boards-esp32-solo-1: + +ESP32-SOLO-1 +------------ + +This is a simplified version of the ESP32-WROOM-32D module. It contains a single-core ESP32 chip that supports a clock frequency of up to 160 MHz. + +For key characteristics, see the table in Section :ref:`esp-wroom-solo-wrover-modules` and `Espressif Products Ordering Information`_. + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-solo-1-front-back.jpg + :align: center + :alt: ESP32-SOLO-1 module (front and back) + :width: 45% + + ESP32-SOLO-1 module (front and back) + + +Documentation +^^^^^^^^^^^^^ + +* `ESP32-SOLO-1 Datasheet `__ (PDF) + + +.. _esp-modules-and-boards-esp32-wrover: + +ESP32-WROVER series +------------------- + +This series consists of a few modifications of ESP32-WROOM-32x modules, which among other upgrades include additional 8 MB SPI PSRAM (pseudo static RAM). + +For details, see the table in Section :ref:`esp-wroom-solo-wrover-modules` and `Espressif Products Ordering Information`_. + +* **ESP32-WROVER (PCB)** and **ESP32-WROVER (IPEX)** have PSRAM that operates at 1.8 V and supports up to 144 MHz clock rate. +* **ESP32-WROVER-B** and **ESP32-WROVER-IB** have PSRAM that operates at 3.3 V and supports up to 133 MHz clock rate. + +The picture below shows an ESP32-WROVER module with a PCB antenna. + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wrover.jpg + :align: center + :alt: ESP32-WROVER module (front and back) + :width: 40% + + ESP32-WROVER module (front and back) + +Documentation +^^^^^^^^^^^^^ + +* `ESP32-WROVER Datasheet `__ (PDF) +* `ESP32-WROVER-B Datasheet `__ (PDF) +* `ESP-PSRAM64 & ESP-PSRAM64H Datasheet `__ (PDF) +* `ESP32-WROVER Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files + + +ESP32-PICO-D4 +------------- + +ESP32-PICO-D4 is a System-in-Package (SiP) module, integrating all peripheral components seamlessly, including the following: + +- 4 MB flash memory +- crystal oscillator +- filter capacitors +- RF matching circuit + +For key characteristics, see `Espressif Products Ordering Information`_. + + +Documentation +^^^^^^^^^^^^^ + +* `ESP32-PICO-D4 Datasheet `__ (PDF) + + +Development Boards +================== + +Depending on the intended functionality, different development boards feature: + +- Access to different ESP32 GPIO pins. +- Different interfaces: USB, JTAG. +- Different peripherals: touchpads, LCD screens, SD card slots, female headers for camera modules, etc. + +.. _esp-modules-and-boards-esp32-pico-kit: + +ESP32-PICO-KIT V4.1 +------------------- + +This is the smallest available ESP32-based development board. It features all the components for direct connection to a computer's USB port as well as pin headers for plugging into a mini breadboard. + +The board is equipped with the `ESP32-PICO-D4`_ module. With such a module, the creation of a fully functional development board required only a few external components that fit on a PCB as small as 20 x 52 mm. The external components include antenna, LDO, USB-UART bridge, and two buttons for reset and activation of Firmware Download mode. + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-pico-kit-v4.1.jpg + :align: center + :alt: ESP32-PICO-KIT V4.1 board + :width: 50% + + ESP32-PICO-KIT V4.1 board + +Comparing to ESP32-PICO-KIT V4, this version features the CP2102N USB-UART bridge that provides faster transfer rates of up to 3 Mbps. + +Documentation +^^^^^^^^^^^^^ + +* :doc:`esp32/get-started-pico-kit` +* `ESP32-PICO-KIT V4.1 Schematic `_ (PDF) +* `ESP32-PICO-KIT Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files +* `ESP32-PICO-D4 Datasheet `_ (PDF) + +Previous Versions +^^^^^^^^^^^^^^^^^ + +* :ref:`esp-modules-and-boards-esp32-pico-kit-v4` +* :ref:`esp-modules-and-boards-esp32-pico-kit-v3` + + +.. _esp-modules-and-boards-esp32-devkitc: + +ESP32 DevKitC V4 +---------------- + +This is a small and convenient development board that features: + +- :ref:`esp-modules-and-boards-esp32-wroom-32` module +- USB-to-serial programming interface that also provides power supply for the board +- pin headers +- pushbuttons for reset and activation of Firmware Download mode +- a few other components + +Comparing to the previous :ref:`esp-modules-and-boards-esp32-devkitc-v2`, this version can integrate :ref:`esp-modules-and-boards-esp32-wrover` module instead of ESP32-WROOM-32 and has the CP2102N chip that supports faster baud rates. + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-devkitc-v4-front.jpg + :align: center + :alt: ESP32 DevKitC V4 board + :width: 50% + + ESP32 DevKitC V4 board + +Documentation +^^^^^^^^^^^^^ + +* :doc:`esp32/get-started-devkitc` +* `ESP32-DevKitC schematic `_ (PDF) +* `ESP32-DevKitC Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files +* `CP210x USB to UART Bridge VCP Drivers `_ + +Previous Versions +^^^^^^^^^^^^^^^^^ + +* :ref:`esp-modules-and-boards-esp32-devkitc-v2` + + +.. _esp-modules-and-boards-esp-wrover-kit: + +ESP-WROVER-KIT V4.1 +------------------- + +This board features: + +- Dual port USB-to-serial converter for programming +- JTAG interface for debugging +- MicroSD card slot +- 3.2” SPI LCD screen +- Female headers for a camera module +- RGB LED for diagnostics +- 32.768 kHz XTAL for internal RTC to operate it in low power modes + +Power can be supplied either via USB or via a standard 5 mm power supply jack. A power source can be selected with a jumper and can be turned on/off with a separate switch. + +This version of the ESP-WROVER-KIT board integrates the ESP-WROVER-B module that has 8 MB PSRAM for flexible extended storage and data processing capabilities. The board can accommodate other versions of ESP modules described in :ref:`esp-wroom-solo-wrover-modules`. + +Comparing to :ref:`esp-modules-and-boards-esp-wrover-kit-v3`, this board has the following design changes: + +- JP8, JP11, and JP13 have been combined into a single JP2. +- USB connector has been changed to DIP type and moved to the lower right corner of the board. +- R61 has been changed to a Zero-ohm resistor. +- Some components have been replaced with functional equivalents based on test results and sourcing options, e.g., the EN and Boot buttons. + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-wrover-kit-v4.1-front.jpg + :align: center + :alt: ESP-WROVER-KIT V4.1 board + :width: 90% + + ESP-WROVER-KIT V4.1 board + +The board in the picture above integrates the ESP32-WROVER-B module. + +Documentation +^^^^^^^^^^^^^ + +* :doc:`esp32/get-started-wrover-kit` +* `ESP-WROVER-KIT V4.1 Schematic `__ (PDF) +* :doc:`../api-guides/jtag-debugging/index` +* `FTDI Virtual COM Port Drivers`_ + +Previous Versions +^^^^^^^^^^^^^^^^^ + +* :ref:`esp-modules-and-boards-esp-wrover-kit-v3` +* :ref:`esp-modules-and-boards-esp-wrover-kit-v2` +* :ref:`esp-modules-and-boards-esp-wrover-kit-v1` + + +.. _FTDI Virtual COM Port Drivers: http://www.ftdichip.com/Drivers/VCP.htm +.. _Espressif Products Ordering Information: https://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_en.pdf \ No newline at end of file diff --git a/docs/en/hw-reference/esp32/inc/modules-and-boards-previous-esp32.rst b/docs/en/hw-reference/esp32/inc/modules-and-boards-previous-esp32.rst new file mode 100644 index 0000000000..8b8e8afac4 --- /dev/null +++ b/docs/en/hw-reference/esp32/inc/modules-and-boards-previous-esp32.rst @@ -0,0 +1,179 @@ +.. _esp-modules-and-boards-previous_esp32: + +Modules (No updated or discontinued modules) +============================================ + +So far, no modules have been updated or discontinued. + + +Development Boards +================== + +To see the latest development boards, please refer to section :ref:`esp-modules-and-boards`. + +.. _esp-modules-and-boards-esp32-pico-kit-v4: + +ESP32-PICO-KIT V4 +----------------- + +The smallest ESP32 development board with all the components required to connect it directly to a PC USB port, and pin headers to plug into a mini breadboard. It is equipped with ESP32-PICO-D4 module that integrates 4 MB flash memory, a crystal oscillator, filter capacitors and RF matching circuit in one single package. As result, the fully functional development board requires only a few external components that can easy fit on a 20 x 52 mm PCB including antenna, LDO, USB-UART bridge and two buttons to reset it and put into download mode. + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-pico-kit-v4.jpeg + :align: center + :alt: ESP32-PICO-KIT V4 board + :width: 50% + + ESP32-PICO-KIT V4 board + +Comparing to ESP32-PICO-KIT V3, this version has revised printout and reduced number of exposed pins. Instead of 20, only 17 header pins are populated, so V4 can fit into a mini breadboard. + +Documentation +^^^^^^^^^^^^^ + +* :doc:`esp32/get-started-pico-kit` +* `ESP32-PICO-KIT V4 Schematic `_ (PDF) +* `ESP32-PICO-D4 Datasheet `_ (PDF) + +.. _esp-modules-and-boards-esp32-pico-kit-v3: + +ESP32-PICO-KIT V3 +----------------- + +The first public release of Espressif's ESP32-PICO-D4 module on a mini development board. The board has a USB port for programming and debugging and two rows of 20 pin headers to plug into a breadboard. The ESP32-PICO-D4 module itself is small and requires only a few external components. Besides two core CPUs it integrates 4MB flash memory, a crystal oscillator and antenna matching components in one single 7 x 7 mm package. As a result the module and all the components making the complete development board fit into 20 x 52 mm PCB. + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-pico-kit-v3.jpeg + :align: center + :alt: ESP32-PICO-KIT V3 board + :width: 50% + + ESP32-PICO-KIT V3 board + +Documentation +^^^^^^^^^^^^^ + +* :doc:`esp32/get-started-pico-kit-v3` +* `ESP32-PICO-KIT V3 Schematic `_ (PDF) +* `ESP32-PICO-D4 Datasheet `_ (PDF) + + +.. _esp-modules-and-boards-esp32-devkitc-v2: + +ESP32 Core Board V2 / ESP32 DevKitC +----------------------------------- + +Small and convenient development board with ESP-WROOM-32 module installed, break out pin headers and minimum additional components. Includes USB to serial programming interface, that also provides power supply for the board. Has pushbuttons to reset the board and put it in upload mode. + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-core-board-v2.png + :align: center + :alt: ESP32 Core Board V2 / ESP32 DevKitC board + :width: 50% + + ESP32 Core Board V2 / ESP32 DevKitC board + +Documentation +^^^^^^^^^^^^^ + +* :doc:`esp32/get-started-devkitc-v2` +* `ESP32 DevKitC V2 Schematic `__ (PDF) +* `CP210x USB to UART Bridge VCP Drivers `_ + +.. _esp-modules-and-boards-esp-wrover-kit-v3: + +ESP-WROVER-KIT V3 +----------------- + +The ESP-WROVER-KIT V3 development board 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. This board has MicroSD card slot, 3.2” SPI LCD screen and dedicated header to connect a camera. It provides RGB diode for diagnostics. Includes 32.768 kHz XTAL for internal RTC to operate it in low power modes. + +As all previous versions of ESP-WROVER-KIT boards, it is ready to accommodate an :ref:`esp-modules-and-boards-esp32-wroom-32` or :ref:`esp-modules-and-boards-esp32-wrover` module. + +This is the first release of ESP-WROVER-KIT shipped with :ref:`esp-modules-and-boards-esp32-wrover` module installed by default. This release also introduced several design changes to conditioning and interlocking of signals to the bootstrapping pins. Also, a zero Ohm resistor (R166) has been added between WROVER/WROOM module and VDD33 net, which can be desoldered, or replaced with a shunt resistor, for current measurement. This is intended to facilitate power consumption analysis in various operation modes of ESP32. Refer to schematic - the changes are enclosed in green border. + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-wrover-kit-v3.jpg + :align: center + :alt: ESP-WROVER-KIT V3 board + :width: 90% + + ESP-WROVER-KIT V3 board + +The camera header has been changed from male back to female. The board soldermask is matte black. The board on picture above has :ref:`esp-modules-and-boards-esp32-wrover` is installed. + +Documentation +^^^^^^^^^^^^^ + +* :doc:`esp32/get-started-wrover-kit-v3` +* `ESP-WROVER-KIT V3 Schematic `__ (PDF) +* :doc:`../api-guides/jtag-debugging/index` +* `FTDI Virtual COM Port Drivers`_ + +.. _esp-modules-and-boards-esp-wrover-kit-v2: + +ESP-WROVER-KIT V2 +----------------- + +This is updated version of ESP32 DevKitJ V1 described above with design improvements identified when DevKitJ was in use, e.g. improved support for SD card. By default board has ESP-WROOM-32 module installed. + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-wrover-kit-v2.jpg + :align: center + :alt: ESP-WROVER-KIT V2 board + :width: 90% + + ESP-WROVER-KIT V2 board + +Comparing to previous version, this board has a shiny black finish and a male camera header. + +Documentation +^^^^^^^^^^^^^ + +* :doc:`esp32/get-started-wrover-kit-v2` +* `ESP-WROVER-KIT V2 Schematic `__ (PDF) +* :doc:`../api-guides/jtag-debugging/index` +* `FTDI Virtual COM Port Drivers`_ + +.. _esp-modules-and-boards-esp-wrover-kit-v1: + +ESP-WROVER-KIT V1 / ESP32 DevKitJ V1 +------------------------------------ + +The first version of ESP-WROVER-KIT development board. Shipped with ESP-WROOM-32 on board. + +ESP-WROVER-KIT 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. The board has MicroSD card slot, 3.2” SPI LCD screen and dedicated header to connect a camera. It provides RGB diode for diagnostics. Includes 32.768 kHz XTAL for internal RTC to operate it in low power modes. + +All versions of ESP-WROVER-KIT are ready to accommodate an ESP-WROOM-32 or ESP32-WROVER module. + + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-devkitj-v1.jpg + :align: center + :alt: ESP-WROVER-KIT V1 / ESP32 DevKitJ V1 board + :width: 90% + + ESP-WROVER-KIT V1 / ESP32 DevKitJ V1 board + +The board has red soldermask. + +Documentation +^^^^^^^^^^^^^ + +* `ESP-WROVER-KIT V1 Schematic `__ (PDF) +* :doc:`../api-guides/jtag-debugging/index` +* `FTDI Virtual COM Port Drivers`_ + +.. _esp-modules-and-boards-esp32-demo-board: + +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. + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-demo-board-v2.jpg + :align: center + :alt: ESP32 Demo Board V2 + + ESP32 Demo Board V2 + +Production of this board is discontinued. + +Documentation +^^^^^^^^^^^^^ + +* `ESP32 Demo Board V2 Schematic `__ (PDF) +* `FTDI Virtual COM Port Drivers`_ diff --git a/docs/en/hw-reference/esp32s2/inc/modules-and-boards-esp32s2.rst b/docs/en/hw-reference/esp32s2/inc/modules-and-boards-esp32s2.rst new file mode 100644 index 0000000000..c5e67936a0 --- /dev/null +++ b/docs/en/hw-reference/esp32s2/inc/modules-and-boards-esp32s2.rst @@ -0,0 +1,21 @@ +.. _esp-s2-modules: + +Modules +======= + +This is a family of ESP32-S2-based modules with some integrated key components, including a crystal oscillator and an antenna matching circuit. The modules constitute ready-made solutions for integration into final products. If combined with a few extra components, such as a programming interface, bootstrapping resistors, and pin headers, these modules can also be used for evaluation of ESP32-S2's functionality. + +The key characteristics of these modules are summarized in the table below. Some additional details are covered in the following sections. + +=================== ============ =========== ========= ==== =============== +Module Chip Flash, MB PSRAM, MB Ant. Dimensions, mm +=================== ============ =========== ========= ==== =============== +ESP32-S2-WROOM-32 ESP32-S2 2 N/A MIFA 16 x 23 x 3 +=================== ============ =========== ========= ==== =============== + +* MIFA - Meandered Inverted-F Antenna +* U.FL - U.FL / IPEX antenna connector + + +.. _FTDI Virtual COM Port Drivers: http://www.ftdichip.com/Drivers/VCP.htm +.. _Espressif Products Ordering Information: https://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_en.pdf \ No newline at end of file diff --git a/docs/en/hw-reference/esp32s2/inc/modules-and-boards-previous-esp32s2.rst b/docs/en/hw-reference/esp32s2/inc/modules-and-boards-previous-esp32s2.rst new file mode 100644 index 0000000000..011a5ce8f7 --- /dev/null +++ b/docs/en/hw-reference/esp32s2/inc/modules-and-boards-previous-esp32s2.rst @@ -0,0 +1,12 @@ +.. _esp-modules-and-boards-previous_esp32s2: + +Modules (No updated or discontinued modules) +============================================ + +So far, no modules have been updated or discontinued. + + +Development Boards +================== + +So far, no development boards have been updated or discontinued. diff --git a/docs/en/hw-reference/index.rst b/docs/en/hw-reference/index.rst index 9978049ee8..7524a02029 100644 --- a/docs/en/hw-reference/index.rst +++ b/docs/en/hw-reference/index.rst @@ -9,7 +9,7 @@ :esp32: Technical Reference Manual (PDF) :esp32s2beta: Technical Reference Manual (PDF) :esp32: Datasheet (PDF) - :esp32s2beta: Datasheet (PDF) + :esp32s2: Datasheet (PDF) :esp32: Hardware Design Guidelines (PDF) :esp32: Silicon Errata (PDF) Modules and Boards diff --git a/docs/en/hw-reference/modules-and-boards-previous.rst b/docs/en/hw-reference/modules-and-boards-previous.rst index 7128bf5c73..ce44b57f4c 100644 --- a/docs/en/hw-reference/modules-and-boards-previous.rst +++ b/docs/en/hw-reference/modules-and-boards-previous.rst @@ -7,186 +7,13 @@ Previous Versions of {IDF_TARGET_NAME} Modules and Boards This sections contains overview and links to documentation of previous version {IDF_TARGET_NAME} Modules and Boards that have been replaced with newer versions or discontinued. It is maintained for convenience of users as previous versions of some modules and boards are still in use and some may still be available for purchase. -Modules (No updated or discontinued modules) -============================================ - -So far, no modules have been updated or discontinued. - - -Development Boards -================== - -To see the latest development boards, please refer to section :ref:`esp-modules-and-boards`. - .. only:: esp32 - .. _esp-modules-and-boards-esp32-pico-kit-v4: + .. include:: esp32/inc/modules-and-boards-previous-esp32.rst - ESP32-PICO-KIT V4 - ----------------- - - The smallest ESP32 development board with all the components required to connect it directly to a PC USB port, and pin headers to plug into a mini breadboard. It is equipped with ESP32-PICO-D4 module that integrates 4 MB flash memory, a crystal oscillator, filter capacitors and RF matching circuit in one single package. As result, the fully functional development board requires only a few external components that can easy fit on a 20 x 52 mm PCB including antenna, LDO, USB-UART bridge and two buttons to reset it and put into download mode. - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-pico-kit-v4.jpeg - :align: center - :alt: ESP32-PICO-KIT V4 board - :width: 50% - - ESP32-PICO-KIT V4 board - - Comparing to ESP32-PICO-KIT V3, this version has revised printout and reduced number of exposed pins. Instead of 20, only 17 header pins are populated, so V4 can fit into a mini breadboard. - - Documentation - ^^^^^^^^^^^^^ - - * :doc:`../hw-reference/get-started-pico-kit` - * `ESP32-PICO-KIT V4 Schematic `_ (PDF) - * `ESP32-PICO-D4 Datasheet `_ (PDF) - - .. _esp-modules-and-boards-esp32-pico-kit-v3: - - ESP32-PICO-KIT V3 - ----------------- - - The first public release of Espressif's ESP32-PICO-D4 module on a mini development board. The board has a USB port for programming and debugging and two rows of 20 pin headers to plug into a breadboard. The ESP32-PICO-D4 module itself is small and requires only a few external components. Besides two core CPUs it integrates 4MB flash memory, a crystal oscillator and antenna matching components in one single 7 x 7 mm package. As a result the module and all the components making the complete development board fit into 20 x 52 mm PCB. - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-pico-kit-v3.jpeg - :align: center - :alt: ESP32-PICO-KIT V3 board - :width: 50% - - ESP32-PICO-KIT V3 board - - Documentation - ^^^^^^^^^^^^^ - - * :doc:`../hw-reference/get-started-pico-kit-v3` - * `ESP32-PICO-KIT V3 Schematic `_ (PDF) - * `ESP32-PICO-D4 Datasheet `_ (PDF) - - - .. _esp-modules-and-boards-esp32-devkitc-v2: - - ESP32 Core Board V2 / ESP32 DevKitC - ----------------------------------- - - Small and convenient development board with ESP-WROOM-32 module installed, break out pin headers and minimum additional components. Includes USB to serial programming interface, that also provides power supply for the board. Has pushbuttons to reset the board and put it in upload mode. - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-core-board-v2.png - :align: center - :alt: ESP32 Core Board V2 / ESP32 DevKitC board - :width: 50% - - ESP32 Core Board V2 / ESP32 DevKitC board - - Documentation - ^^^^^^^^^^^^^ - - * :doc:`../hw-reference/get-started-devkitc-v2` - * `ESP32 DevKitC V2 Schematic `__ (PDF) - * `CP210x USB to UART Bridge VCP Drivers `_ - - .. _esp-modules-and-boards-esp-wrover-kit-v3: - - ESP-WROVER-KIT V3 - ----------------- - - The ESP-WROVER-KIT V3 development board 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. This board has MicroSD card slot, 3.2” SPI LCD screen and dedicated header to connect a camera. It provides RGB diode for diagnostics. Includes 32.768 kHz XTAL for internal RTC to operate it in low power modes. - - As all previous versions of ESP-WROVER-KIT boards, it is ready to accommodate an :ref:`esp-modules-and-boards-esp32-wroom-32` or :ref:`esp-modules-and-boards-esp32-wrover` module. - - This is the first release of ESP-WROVER-KIT shipped with :ref:`esp-modules-and-boards-esp32-wrover` module installed by default. This release also introduced several design changes to conditioning and interlocking of signals to the bootstrapping pins. Also, a zero Ohm resistor (R166) has been added between WROVER/WROOM module and VDD33 net, which can be desoldered, or replaced with a shunt resistor, for current measurement. This is intended to facilitate power consumption analysis in various operation modes of ESP32. Refer to schematic - the changes are enclosed in green border. - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-wrover-kit-v3.jpg - :align: center - :alt: ESP-WROVER-KIT V3 board - :width: 90% - - ESP-WROVER-KIT V3 board - - The camera header has been changed from male back to female. The board soldermask is matte black. The board on picture above has :ref:`esp-modules-and-boards-esp32-wrover` is installed. - - Documentation - ^^^^^^^^^^^^^ - - * :doc:`../hw-reference/get-started-wrover-kit-v3` - * `ESP-WROVER-KIT V3 Schematic `__ (PDF) - * :doc:`../api-guides/jtag-debugging/index` - * `FTDI Virtual COM Port Drivers`_ - - .. _esp-modules-and-boards-esp-wrover-kit-v2: - - ESP-WROVER-KIT V2 - ----------------- - - This is updated version of ESP32 DevKitJ V1 described above with design improvements identified when DevKitJ was in use, e.g. improved support for SD card. By default board has ESP-WROOM-32 module installed. - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-wrover-kit-v2.jpg - :align: center - :alt: ESP-WROVER-KIT V2 board - :width: 90% - - ESP-WROVER-KIT V2 board - - Comparing to previous version, this board has a shiny black finish and a male camera header. - - Documentation - ^^^^^^^^^^^^^ - - * :doc:`../hw-reference/get-started-wrover-kit-v2` - * `ESP-WROVER-KIT V2 Schematic `__ (PDF) - * :doc:`../api-guides/jtag-debugging/index` - * `FTDI Virtual COM Port Drivers`_ - - .. _esp-modules-and-boards-esp-wrover-kit-v1: - - ESP-WROVER-KIT V1 / ESP32 DevKitJ V1 - ------------------------------------ - - The first version of ESP-WROVER-KIT development board. Shipped with ESP-WROOM-32 on board. - - ESP-WROVER-KIT 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. The board has MicroSD card slot, 3.2” SPI LCD screen and dedicated header to connect a camera. It provides RGB diode for diagnostics. Includes 32.768 kHz XTAL for internal RTC to operate it in low power modes. - - All versions of ESP-WROVER-KIT are ready to accommodate an ESP-WROOM-32 or ESP32-WROVER module. - - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-devkitj-v1.jpg - :align: center - :alt: ESP-WROVER-KIT V1 / ESP32 DevKitJ V1 board - :width: 90% - - ESP-WROVER-KIT V1 / ESP32 DevKitJ V1 board - - The board has red soldermask. - - Documentation - ^^^^^^^^^^^^^ - - * `ESP-WROVER-KIT V1 Schematic `__ (PDF) - * :doc:`../api-guides/jtag-debugging/index` - * `FTDI Virtual COM Port Drivers`_ - - .. _esp-modules-and-boards-esp32-demo-board: - - 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. - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-demo-board-v2.jpg - :align: center - :alt: ESP32 Demo Board V2 - - ESP32 Demo Board V2 - - Production of this board is discontinued. - - Documentation - ^^^^^^^^^^^^^ - - * `ESP32 Demo Board V2 Schematic `__ (PDF) - * `FTDI Virtual COM Port Drivers`_ +.. only:: esp32s2 + .. include:: esp32s2/inc/modules-and-boards-previous-esp32s2.rst Related Documents ================= diff --git a/docs/en/hw-reference/modules-and-boards.rst b/docs/en/hw-reference/modules-and-boards.rst index e784f387bd..4e3d000654 100644 --- a/docs/en/hw-reference/modules-and-boards.rst +++ b/docs/en/hw-reference/modules-and-boards.rst @@ -14,300 +14,15 @@ This document provides description of modules and development boards currently a For description of previous versions of modules and development boards as well as for description of discontinued ones, please go to Section :ref:`esp-modules-and-boards-previous`. -.. _esp-wroom-solo-wrover-modules: - -Modules -======= - -This is a family of {IDF_TARGET_NAME}-based modules with some integrated key components, including a crystal oscillator and an antenna matching circuit. The modules constitute ready-made solutions for integration into final products. If combined with a few extra components, such as a programming interface, bootstrapping resistors, and pin headers, these modules can also be used for evaluation of {IDF_TARGET_NAME}'s functionality. - -The key characteristics of these modules are summarized in the table below. Some additional details are covered in the following sections. - .. only:: esp32 - =================== ============ =========== ========= ==== =============== - Module Chip Flash, MB PSRAM, MB Ant. Dimensions, mm - =================== ============ =========== ========= ==== =============== - ESP32-WROOM-32 ESP32-D0WDQ6 4 -- MIFA 18 × 25.5 × 3.1 - ESP32-WROOM-32D ESP32-D0WD 4, 8, or 16 -- MIFA 18 × 25.5 × 3.1 - ESP32-WROOM-32U ESP32-D0WD 4, 8, or 16 -- U.FL 18 × 19.2 × 3.1 - ESP32-SOLO-1 ESP32-S0WD 4 -- MIFA 18 × 25.5 × 3.1 - ESP32-WROVER (PCB) ESP32-D0WDQ6 4 8 MIFA 18 × 31.4 × 3.3 - ESP32-WROVER (IPEX) ESP32-D0WDQ6 4 8 U.FL 18 × 31.4 × 3.3 - ESP32-WROVER-B ESP32-D0WD 4, 8, or 16 8 MIFA 18 × 31.4 × 3.3 - ESP32-WROVER-IB ESP32-D0WD 4, 8, or 16 8 U.FL 18 × 31.4 × 3.3 - =================== ============ =========== ========= ==== =============== + .. include:: esp32/inc/modules-and-boards-esp32.rst - * ESP32-**D**.. identifies a dual-core chip, ESP32-**S**.. identifies a single-core chip - * MIFA - Meandered Inverted-F Antenna - * U.FL - U.FL / IPEX antenna connector - * ESP32-WROOM-32x, ESP32-WROVER-B and ESP32-WROVER-IB modules come with 4 MB flash by default but also available with custom flash sizes of 8 MB and 16 MB, see `Espressif Products Ordering Information`_ (PDF) - * `ESP32 Chip Datasheet `__ (PDF) - * Initial release of the ESP32-WROVER module had 4 MB of PSRAM - * *ESP32-WROOM-32* was previously called *ESP-WROOM-32* - - - .. _esp-modules-and-boards-esp32-wroom-32: - - ESP32-WROOM-32 - -------------- - - This is a basic and commonly adopted ESP32 module with the ESP32-D0WDQ6 chip on board. It was the first module of the WROOM / WROVER family released to the market. - - For key characteristics, see the table in Section :ref:`esp-wroom-solo-wrover-modules`, `Espressif Products Ordering Information`_. - - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32-front-back.jpg - :align: center - :alt: ESP32-WROOM-32 module (front and back) - :width: 45% - - ESP32-WROOM-32 module (front and back) - - Documentation - ^^^^^^^^^^^^^ - - * `ESP32-WROOM-32 Datasheet `__ (PDF) - * `ESP32-WROOM-32 Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files - - - .. _esp-modules-and-boards-esp32-wroom-32d-and-u: - - ESP32-WROOM-32D / ESP32-WROOM-32U - --------------------------------- - - Both modules integrate the ESP32-D0WD chip which has a smaller footprint than the chip ESP32-D0WDQ6 installed in :ref:`esp-modules-and-boards-esp32-wroom-32`. - - For key characteristics, see the table in Section :ref:`esp-wroom-solo-wrover-modules` and `Espressif Products Ordering Information`_. - - ESP32-WROOM-32U is the smallest representative of the whole WROOM / WROVER family of modules. - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32d-front-back.jpg - :align: center - :alt: ESP32-WROOM-32D module (front and back) - :width: 45% - - ESP32-WROOM-32D module (front and back) - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32u-front-back.jpg - :align: center - :alt: ESP32-WROOM-32U module (front and back) - :width: 45% - - ESP32-WROOM-32U module (front and back) - - Documentation - ^^^^^^^^^^^^^ - - * `ESP32-WROOM-32D / ESP32-WROOM-32U Datasheet `__ (PDF) - - - .. _esp-modules-and-boards-esp32-solo-1: - - ESP32-SOLO-1 - ------------ - - This is a simplified version of the ESP32-WROOM-32D module. It contains a single-core ESP32 chip that supports a clock frequency of up to 160 MHz. - - For key characteristics, see the table in Section :ref:`esp-wroom-solo-wrover-modules` and `Espressif Products Ordering Information`_. - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-solo-1-front-back.jpg - :align: center - :alt: ESP32-SOLO-1 module (front and back) - :width: 45% - - ESP32-SOLO-1 module (front and back) - - - Documentation - ^^^^^^^^^^^^^ - - * `ESP32-SOLO-1 Datasheet `__ (PDF) - - - .. _esp-modules-and-boards-esp32-wrover: - - ESP32-WROVER series - ------------------- - - This series consists of a few modifications of ESP32-WROOM-32x modules, which among other upgrades include additional 8 MB SPI PSRAM (pseudo static RAM). - - For details, see the table in Section :ref:`esp-wroom-solo-wrover-modules` and `Espressif Products Ordering Information`_. - - * **ESP32-WROVER (PCB)** and **ESP32-WROVER (IPEX)** have PSRAM that operates at 1.8 V and supports up to 144 MHz clock rate. - * **ESP32-WROVER-B** and **ESP32-WROVER-IB** have PSRAM that operates at 3.3 V and supports up to 133 MHz clock rate. - - The picture below shows an ESP32-WROVER module with a PCB antenna. - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wrover.jpg - :align: center - :alt: ESP32-WROVER module (front and back) - :width: 40% - - ESP32-WROVER module (front and back) - - Documentation - ^^^^^^^^^^^^^ - - * `ESP32-WROVER Datasheet `__ (PDF) - * `ESP32-WROVER-B Datasheet `__ (PDF) - * `ESP-PSRAM64 & ESP-PSRAM64H Datasheet `__ (PDF) - * `ESP32-WROVER Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files - - - ESP32-PICO-D4 - ------------- - - ESP32-PICO-D4 is a System-in-Package (SiP) module, integrating all peripheral components seamlessly, including the following: - - - 4 MB flash memory - - crystal oscillator - - filter capacitors - - RF matching circuit - - For key characteristics, see `Espressif Products Ordering Information`_. - - - Documentation - ^^^^^^^^^^^^^ - - * `ESP32-PICO-D4 Datasheet `__ (PDF) - - - Development Boards - ================== - - Depending on the intended functionality, different development boards feature: - - - Access to different ESP32 GPIO pins. - - Different interfaces: USB, JTAG. - - Different peripherals: touchpads, LCD screens, SD card slots, female headers for camera modules, etc. - - .. _esp-modules-and-boards-esp32-pico-kit: - - ESP32-PICO-KIT V4.1 - ------------------- - - This is the smallest available ESP32-based development board. It features all the components for direct connection to a computer's USB port as well as pin headers for plugging into a mini breadboard. - - The board is equipped with the `ESP32-PICO-D4`_ module. With such a module, the creation of a fully functional development board required only a few external components that fit on a PCB as small as 20 x 52 mm. The external components include antenna, LDO, USB-UART bridge, and two buttons for reset and activation of Firmware Download mode. - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-pico-kit-v4.1.jpg - :align: center - :alt: ESP32-PICO-KIT V4.1 board - :width: 50% - - ESP32-PICO-KIT V4.1 board - - Comparing to ESP32-PICO-KIT V4, this version features the CP2102N USB-UART bridge that provides faster transfer rates of up to 3 Mbps. - - Documentation - ^^^^^^^^^^^^^ - - * :doc:`../hw-reference/get-started-pico-kit` - * `ESP32-PICO-KIT V4.1 Schematic `_ (PDF) - * `ESP32-PICO-KIT Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files - * `ESP32-PICO-D4 Datasheet `_ (PDF) - - Previous Versions - ^^^^^^^^^^^^^^^^^ - - * :ref:`esp-modules-and-boards-esp32-pico-kit-v4` - * :ref:`esp-modules-and-boards-esp32-pico-kit-v3` - - - .. _esp-modules-and-boards-esp32-devkitc: - - ESP32 DevKitC V4 - ---------------- - - This is a small and convenient development board that features: - - - :ref:`esp-modules-and-boards-esp32-wroom-32` module - - USB-to-serial programming interface that also provides power supply for the board - - pin headers - - pushbuttons for reset and activation of Firmware Download mode - - a few other components - - Comparing to the previous :ref:`esp-modules-and-boards-esp32-devkitc-v2`, this version can integrate :ref:`esp-modules-and-boards-esp32-wrover` module instead of ESP32-WROOM-32 and has the CP2102N chip that supports faster baud rates. - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-devkitc-v4-front.jpg - :align: center - :alt: ESP32 DevKitC V4 board - :width: 50% - - ESP32 DevKitC V4 board - - Documentation - ^^^^^^^^^^^^^ - - * :doc:`../hw-reference/get-started-devkitc` - * `ESP32-DevKitC schematic `_ (PDF) - * `ESP32-DevKitC Reference Design `_ containing OrCAD schematic, PCB layout, gerber and BOM files - * `CP210x USB to UART Bridge VCP Drivers `_ - - Previous Versions - ^^^^^^^^^^^^^^^^^ - - * :ref:`esp-modules-and-boards-esp32-devkitc-v2` - - - .. _esp-modules-and-boards-esp-wrover-kit: - - ESP-WROVER-KIT V4.1 - ------------------- - - This board features: - - - Dual port USB-to-serial converter for programming - - JTAG interface for debugging - - MicroSD card slot - - 3.2” SPI LCD screen - - Female headers for a camera module - - RGB LED for diagnostics - - 32.768 kHz XTAL for internal RTC to operate it in low power modes - - Power can be supplied either via USB or via a standard 5 mm power supply jack. A power source can be selected with a jumper and can be turned on/off with a separate switch. - - This version of the ESP-WROVER-KIT board integrates the ESP-WROVER-B module that has 8 MB PSRAM for flexible extended storage and data processing capabilities. The board can accommodate other versions of ESP modules described in :ref:`esp-wroom-solo-wrover-modules`. - - Comparing to :ref:`esp-modules-and-boards-esp-wrover-kit-v3`, this board has the following design changes: - - - JP8, JP11, and JP13 have been combined into a single JP2. - - USB connector has been changed to DIP type and moved to the lower right corner of the board. - - R61 has been changed to a Zero-ohm resistor. - - Some components have been replaced with functional equivalents based on test results and sourcing options, e.g., the EN and Boot buttons. - - .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-wrover-kit-v4.1-front.jpg - :align: center - :alt: ESP-WROVER-KIT V4.1 board - :width: 90% - - ESP-WROVER-KIT V4.1 board - - The board in the picture above integrates the ESP32-WROVER-B module. - - Documentation - ^^^^^^^^^^^^^ - - * :doc:`../hw-reference/get-started-wrover-kit` - * `ESP-WROVER-KIT V4.1 Schematic `__ (PDF) - * :doc:`../api-guides/jtag-debugging/index` - * `FTDI Virtual COM Port Drivers`_ - - Previous Versions - ^^^^^^^^^^^^^^^^^ - - * :ref:`esp-modules-and-boards-esp-wrover-kit-v3` - * :ref:`esp-modules-and-boards-esp-wrover-kit-v2` - * :ref:`esp-modules-and-boards-esp-wrover-kit-v1` +.. only:: esp32s2 + .. include:: esp32s2/inc/modules-and-boards-esp32s2.rst Related Documents ================= * :doc:`modules-and-boards-previous` - - -.. _FTDI Virtual COM Port Drivers: http://www.ftdichip.com/Drivers/VCP.htm -.. _Espressif Products Ordering Information: https://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_en.pdf \ No newline at end of file diff --git a/docs/zh_CN/api-guides/external-ram.rst b/docs/zh_CN/api-guides/external-ram.rst index d6148a0cc0..1e9da62762 100644 --- a/docs/zh_CN/api-guides/external-ram.rst +++ b/docs/zh_CN/api-guides/external-ram.rst @@ -114,7 +114,7 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据 * 片外 RAM 与片外 flash 使用相同的 cache 区域，即频繁在片外 RAM 访问的变量可以像在片上 RAM 中一样快速读取和修改。但访问大块数据时（大于 32 KB），cache 空间可能会不足，访问速度将回落到片外 RAM 访问速度。此外，访问大块数据可以“挤出” flash cache，可能会降低代码执行速度。 - * 片外 RAM 不可用作任务堆栈存储器。因此 :cpp:func:`xTaskCreate` 及类似函数将始终为堆栈和任务 TCB 分配片上储存器，而 :cpp:func:`xTaskCreateStatic` 类型的函数将检查传递的 Buffer 是否属于片上存储器。但对于不以任何方式直接或间接调用 ROM 中代码的任务，menuconfig 选项 :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` 将消除 `xTaskCreateStatic` 中的检查，从而允许任务堆栈存储在外部 RAM 中。但是，不建议使用此方法。 + * 片外 RAM 不可用作任务堆栈存储器。因此 :cpp:func:`xTaskCreate` 及类似函数将始终为堆栈和任务 TCB 分配片上储存器，而 :cpp:func:`xTaskCreateStatic` 类型的函数将检查传递的 Buffer 是否属于片上存储器。 * 默认情况下，片外 RAM 初始化失败将终止 ESP-IDF 启动。如果想禁用此功能，可启用 :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND` 配置选项。如果启用 :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`，:ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND` 选项将不能使用，这是因为在链接时，链接器已经向片外 RAM 分配符号。 diff --git a/docs/zh_CN/api-guides/jtag-debugging/configure-wrover.rst b/docs/zh_CN/api-guides/jtag-debugging/configure-wrover.rst index 7dbc6fdd08..7553bd23a9 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/configure-wrover.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/configure-wrover.rst @@ -8,7 +8,7 @@ 配置硬件 ^^^^^^^^ -1. 根据 :doc:`../../hw-reference/get-started-wrover-kit` 文档中 :ref:`get-started-esp-wrover-kit-v4.1-setup-options` 章节所描述的信息，设置 JP8 便可以启用 JTAG 功能。 +1. 根据 :doc:`../../hw-reference/esp32/get-started-wrover-kit` 文档中 :ref:`get-started-esp-wrover-kit-v4.1-setup-options` 章节所描述的信息，设置 JP8 便可以启用 JTAG 功能。 2. 检查 ESP32 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。 @@ -100,11 +100,11 @@ Linux MacOS """"" -在 macOS 上，同时使用 FT2232 的 JTAG 接口和串口还需另外进行其它操作。当操作系统加载 FTDI 串口驱动的时候，它会对 FT2232 芯片的两个通道做相同的操作。但是，这两个通道中只有一个是被用作串口，而另一个用于 JTAG，如果操作系统已经为用于 JTAG 的通道加载了 FTDI 串口驱动的话，OpenOCD 将无法连接到芯片。有两个方法可以解决这个问题： +在 macOS 上，同时使用 FT2232 的 JTAG 接口和串口还需另外进行其它操作。当操作系统加载 FTDI 串口驱动的时候，它会对 FT2232 芯片的两个通道做相同的操作。但是，这两个通道中只有一个是被用作串口，而另一个用于 JTAG，如果操作系统已经为用于 JTAG 的通道加载了 FTDI 串口驱动的话，OpenOCD 将无法连接到芯片。有两个方法可以解决这个问题： 1. 在启动 OpenOCD 之前手动卸载 FTDI 串口驱动程序，然后启动 OpenOCD，再加载串口驱动程序。 -2. 修改 FTDI 驱动程序的配置，使其不会为 FT2232 芯片的通道 B 进行自我加载，该通道用于 ESP-WROVER-KIT 板上的 JTAG 通道。 +2. 修改 FTDI 驱动程序的配置，使其不会为 FT2232 芯片的通道 B 进行自我加载，该通道用于 ESP-WROVER-KIT 板上的 JTAG 通道。 手动卸载驱动程序 ................ diff --git a/docs/zh_CN/api-guides/jtag-debugging/index.rst b/docs/zh_CN/api-guides/jtag-debugging/index.rst index e6222327aa..3456396939 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/index.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/index.rst @@ -127,7 +127,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G .. toctree:: :maxdepth: 1 - configure-wrover + :esp32: configure-wrover configure-other-jtag @@ -146,7 +146,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G .. note:: - 上述命令中 ``-f`` 选项后跟的配置文件专用于板载 :ref:`ESP-WROOM-32 ` 模组的 ESP-WROVER-KIT 开发板。您可能需要根据具体使用的硬件而选择或修改不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。 + 上述命令中 ``-f`` 选项后跟的配置文件专用于板载 esp32-wroom-32 模组的 ESP-WROVER-KIT 开发板。您可能需要根据具体使用的硬件而选择或修改不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。 .. highlight:: none diff --git a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst index 55fe4c4616..e73ccf83f7 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst @@ -116,7 +116,7 @@ OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRT OpenOCD 需要知道当前使用的 JTAG 适配器的类型，以及其连接的目标板和处理器的类型。为此，请使用位于 OpenOCD 安装目录下 ``share/openocd/scripts/interface`` 和 ``share/openocd/scripts/board`` 文件夹中现有的配置文件。 -例如，如果使用板载 ESP-WROOM-32 模组的 ESP-WROVER-KIT 开发板（详见 :ref:`esp-modules-and-boards-esp-wrover-kit-v1`），请使用以下配置文件： +例如，如果使用板载 ESP-WROOM-32 模组的 ESP-WROVER-KIT 开发板，请使用以下配置文件： * ``board/esp32-wrover-kit-3.3v.cfg`` diff --git a/docs/zh_CN/api-reference/system/power_management.rst b/docs/zh_CN/api-reference/system/power_management.rst index 7e54879826..86a02ca0d8 100644 --- a/docs/zh_CN/api-reference/system/power_management.rst +++ b/docs/zh_CN/api-reference/system/power_management.rst @@ -67,7 +67,7 @@ ESP32 支持下表中所述的三种电源管理锁。 .. only:: esp32 - .. include:: ../../en/inc/power_management_esp32.rst + .. include:: ../../../en/api-reference/system/inc/power_management_esp32.rst 动态调频和外设驱动 ------------------------------------------------ diff --git a/docs/zh_CN/get-started-legacy/index.rst b/docs/zh_CN/get-started-legacy/index.rst index b7c7aa449f..4a474fae61 100644 --- a/docs/zh_CN/get-started-legacy/index.rst +++ b/docs/zh_CN/get-started-legacy/index.rst @@ -57,10 +57,10 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 .. toctree:: :maxdepth: 1 - ESP32-DevKitC <../hw-reference/get-started-devkitc> - ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> - ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> - ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> + ESP32-DevKitC <../hw-reference/esp32/get-started-devkitc> + ESP-WROVER-KIT <../hw-reference/esp32/get-started-wrover-kit> + ESP32-PICO-KIT <../hw-reference/esp32/get-started-pico-kit> + ESP32-Ethernet-Kit <../hw-reference/esp32/get-started-ethernet-kit> .. _get-started-step-by-step-legacy: @@ -399,7 +399,7 @@ Windows 操作系统 用户可以在使用 ``make`` 命令时 **直接设置** 部分环境变量，而无需进入 ``make menuconfig`` 进行重新配置。这些变量包括： -.. list-table:: +.. list-table:: :widths: 25 75 :header-rows: 1 @@ -420,7 +420,7 @@ Windows 操作系统 更新 ESP-IDF ============= -乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或推出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf-legacy` 中的指示，重新完成克隆。 +乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或推出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf-legacy` 中的指示，重新完成克隆。 如果您希望将 ESP-IDF 克隆到新的路径下，请务必 :doc:`重新设置 IDF_PATH `。否则，工具链将无法找到 ESP-IDF。 diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst index 907638154f..c0f55bc17b 100644 --- a/docs/zh_CN/get-started/index.rst +++ b/docs/zh_CN/get-started/index.rst @@ -68,10 +68,10 @@ .. toctree:: :maxdepth: 1 - ESP32-DevKitC <../hw-reference/get-started-devkitc> - ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> - ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> - ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> + ESP32-DevKitC <../hw-reference/esp32/get-started-devkitc> + ESP-WROVER-KIT <../hw-reference/esp32/get-started-wrover-kit> + ESP32-PICO-KIT <../hw-reference/esp32/get-started-pico-kit> + ESP32-Ethernet-Kit <../hw-reference/esp32/get-started-ethernet-kit> .. _get-started-step-by-step: diff --git a/docs/zh_CN/hw-reference/get-started-devkitc-v2.rst b/docs/zh_CN/hw-reference/esp32/get-started-devkitc-v2.rst similarity index 87% rename from docs/zh_CN/hw-reference/get-started-devkitc-v2.rst rename to docs/zh_CN/hw-reference/esp32/get-started-devkitc-v2.rst index 298a2245d8..5978b87100 100644 --- a/docs/zh_CN/hw-reference/get-started-devkitc-v2.rst +++ b/docs/zh_CN/hw-reference/esp32/get-started-devkitc-v2.rst @@ -29,7 +29,7 @@ ESP32-DevKitC V2 开发板的主要组件、接口及控制方式见下。 .. _get-started-esp32-devkitc-v2-board-front: -.. figure:: ../../_static/esp32-devkitc-v2-functional-overview.png +.. figure:: ../../../_static/esp32-devkitc-v2-functional-overview.png :align: center :alt: ESP32-DevKitC V2 开发板 :figclass: align-center @@ -38,7 +38,7 @@ ESP32-DevKitC V2 开发板的主要组件、接口及控制方式见下。 ESP32-DevKitC V2 开发板 -.. list-table:: +.. list-table:: :widths: 25 75 :header-rows: 1 @@ -74,7 +74,7 @@ ESP32-DevKitC V2 开发板 ESP32-DevKitC V2 上电前，请首先确认开发板完好无损。 -现在，请前往 :doc:`index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 +现在，请前往 :doc:`../../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 相关文档 diff --git a/docs/zh_CN/hw-reference/get-started-devkitc.rst b/docs/zh_CN/hw-reference/esp32/get-started-devkitc.rst similarity index 89% rename from docs/zh_CN/hw-reference/get-started-devkitc.rst rename to docs/zh_CN/hw-reference/esp32/get-started-devkitc.rst index 107c55d90c..7ec6a669dc 100644 --- a/docs/zh_CN/hw-reference/get-started-devkitc.rst +++ b/docs/zh_CN/hw-reference/esp32/get-started-devkitc.rst @@ -3,7 +3,7 @@ ESP32-DevKitC V4 入门指南 :link_to_translation:`en: [English]` -本指南介绍了如何开始使用 ESP32-DevKitC V4 开发板。有关 ESP32-DevKitC 其他版本的介绍，请见：:doc:`../hw-reference/index`。 +本指南介绍了如何开始使用 ESP32-DevKitC V4 开发板。有关 ESP32-DevKitC 其他版本的介绍，请见：:doc:`../../hw-reference/index`。 准备工作 @@ -48,7 +48,7 @@ ESP32-DevKitC V4 开发板的主要组件、接口及控制方式见下。 .. _get-started-esp32-devkitc-board-front: -.. figure:: ../../_static/esp32-devkitc-functional-overview.jpg +.. figure:: ../../../_static/esp32-devkitc-functional-overview.jpg :align: center :alt: ESP32-DevKitC V4（板载 ESP32-WROOM-32） :figclass: align-center @@ -56,7 +56,7 @@ ESP32-DevKitC V4 开发板的主要组件、接口及控制方式见下。 ESP32-DevKitC V4（板载 ESP32-WROOM-32） -.. list-table:: +.. list-table:: :widths: 25 75 :header-rows: 1 @@ -79,7 +79,7 @@ ESP32-DevKitC V4（板载 ESP32-WROOM-32） .. note:: - 管脚 D0、D1、D2、D3、CMD 和 CLK 用于 ESP32 芯片与 SPI flash 间的内部通信，集中分布在开发板两侧靠近 USB 端口的位置。通常而言，这些管脚最好不连，否则可能影响 SPI flash / SPI RAM 的工作。 + 管脚 D0、D1、D2、D3、CMD 和 CLK 用于 ESP32 芯片与 SPI flash 间的内部通信，集中分布在开发板两侧靠近 USB 端口的位置。通常而言，这些管脚最好不连，否则可能影响 SPI flash / SPI RAM 的工作。 .. note:: @@ -110,7 +110,7 @@ ESP32-DevKitC V4（板载 ESP32-WROOM-32） 用户如果认为 C15 可能影响开发板的使用，则可以将 C15 完全移除。C15 在开发板上的具体位置见下图黄色部分。 -.. figure:: ../../_static/esp32-devkitc-c15-location.png +.. figure:: ../../../_static/esp32-devkitc-c15-location.png :align: center :alt: C15（黄色）在 ESP32-DevKitC V4 开发板上的位置 :figclass: align-center @@ -124,12 +124,12 @@ C15（黄色）在 ESP32-DevKitC V4 开发板上的位置 ESP32-DevKitC V4 上电前，请首先确认开发板完好无损。 -现在，请前往 :doc:`index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 +现在，请前往 :doc:`../../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 开发板尺寸 ------------- -.. figure:: ../../_static/esp32-devkitc-dimensions-back.jpg +.. figure:: ../../../_static/esp32-devkitc-dimensions-back.jpg :align: center :alt: ESP32-DevKitC 开发板尺寸 -- 仰视图 :figclass: align-center diff --git a/docs/zh_CN/hw-reference/get-started-ethernet-kit-v1.0.rst b/docs/zh_CN/hw-reference/esp32/get-started-ethernet-kit-v1.0.rst similarity index 94% rename from docs/zh_CN/hw-reference/get-started-ethernet-kit-v1.0.rst rename to docs/zh_CN/hw-reference/esp32/get-started-ethernet-kit-v1.0.rst index 3d86e5130f..01731a327e 100644 --- a/docs/zh_CN/hw-reference/get-started-ethernet-kit-v1.0.rst +++ b/docs/zh_CN/hw-reference/esp32/get-started-ethernet-kit-v1.0.rst @@ -24,7 +24,7 @@ ESP32-Ethernet-Kit 是一款来自 `乐鑫 `_ 的开发 .. _get-started-esp32-ethernet-kit-b-v1.0: -.. figure:: ../../_static/esp32-ethernet-kit-v1.0.png +.. figure:: ../../../_static/esp32-ethernet-kit-v1.0.png :align: center :alt: ESP32-Ethernet-Kit V1.0 :figclass: align-center @@ -39,7 +39,7 @@ ESP32-Ethernet-Kit 是一款来自 `乐鑫 `_ 的开发 ESP32-Ethernet-Kit 开发板的主要组件和连接方式见下。 -.. figure:: ../../_static/esp32-ethernet-kit-block-diagram.png +.. figure:: ../../../_static/esp32-ethernet-kit-block-diagram.png :align: center :scale: 50% :alt: ESP32-Ethernet-Kit 功能框图（点击放大） @@ -59,7 +59,7 @@ ESP32-Ethernet-Kit 开发板的主要组件、接口及控制方式见下。 以太网子板（A 板） ^^^^^^^^^^^^^^^^^^ -.. figure:: ../../_static/esp32-ethernet-kit-a-v1.0-layout.png +.. figure:: ../../../_static/esp32-ethernet-kit-a-v1.0-layout.png :align: center :scale: 80% :alt: ESP32-Ethernet-Kit - 以太网子板（A 板）布局 @@ -87,7 +87,7 @@ GPIO Header 3 可连接至 ESP32 的部分 GPIO，根据 `功能选 FT2232H FT2232H 多协议 USB 转串口桥接器。开发人员可通过 USB 接口对 FT2232H 芯片进行控制和编程，与 ESP32 建立连接。FT2232H 芯片可在通道 A 提供 USB-to-JTAG 接口功能，并在通道 B 提供 USB-to-Serial 接口功能，便利开发人员的应用开发与调试。见 `ESP32-Ethernet-Kit V1.0 以太网子板（A 板）原理图`_。 USB 端口 USB 接口。可用作开发板的供电电源，或连接 PC 和开发板的通信接口。 - + 电源开关 电源开关。拨向 **Boot** 按键一侧，开发板上电；拨离 **Boot** 按键一侧，开发板掉电。 5V Input 5V 电源接口建议仅在开发板自动运行（未连接 PC）时使用。仅用于全负荷工作下的后备电源。 @@ -127,7 +127,7 @@ PoE 子板（B 板）具有以下特性： 如需使用 PoE 功能，请用以太网线缆将以太网子板（A 板）上的 **RJ45 端口** 连接至 PoE 的交换机。太网子板（A 板）检测到来自 PoE 子板（B 板）的 5 V 供电后，将从 USB 供电自动切换至 PoE 供电。 -.. figure:: ../../_static/esp32-ethernet-kit-b-v1.0-layout.png +.. figure:: ../../../_static/esp32-ethernet-kit-b-v1.0-layout.png :align: center :scale: 80% :alt: ESP32-Ethernet-Kit - PoE 子板（B 板） @@ -136,7 +136,7 @@ PoE 子板（B 板）具有以下特性： ESP32-Ethernet-Kit - PoE 子板（B 板）布局（点击放大） ========================== ================================================================================================================================= -主要组件 基本介绍 +主要组件 基本介绍 ========================== ================================================================================================================================= A 板连接器 1 个 4 针排母，用于将 B 板连接至 :ref:`以太网子板（A 板）`。 外部电源终端 PoE 子板（B 板）备用电源。 @@ -340,7 +340,7 @@ ESP32-Ethernet-Kit 上电前，请首先确认开发板完好无损。 正式开始开发 ^^^^^^^^^^^^^^^^^^ -现在，请前往 :doc:`../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 +现在，请前往 :doc:`../../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 如需使用较早 GNU Make 编译系统，则请参考 :ref:`get-started-step-by-step` 章节。 @@ -360,8 +360,8 @@ ESP32-Ethernet-Kit 上电前，请首先确认开发板完好无损。 * `ESP32-Ethernet-Kit V1.0 PoE 子板（B 板）原理图`_ (PDF) * `《ESP32 技术规格书》 `_ (PDF) * `《ESP32-WROVER-B 技术规格书》 `_ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* :doc:`../hw-reference/index` +* :doc:`../../api-guides/jtag-debugging/index` +* :doc:`../../hw-reference/index` .. _ESP32-Ethernet-Kit V1.0 以太网子板（A 板）原理图: https://dl.espressif.com/dl/schematics/SCH_ESP32-ETHERNET-KIT_A_V1.0_20190517.pdf .. _ESP32-Ethernet-Kit V1.0 PoE 子板（B 板）原理图: https://dl.espressif.com/dl/schematics/SCH_ESP32-ETHERNET-KIT_B_V1.0_20190517.pdf diff --git a/docs/zh_CN/hw-reference/esp32/get-started-ethernet-kit.rst b/docs/zh_CN/hw-reference/esp32/get-started-ethernet-kit.rst new file mode 100644 index 0000000000..3932cfb3cb --- /dev/null +++ b/docs/zh_CN/hw-reference/esp32/get-started-ethernet-kit.rst @@ -0,0 +1 @@ +.. include:: ../../../en/hw-reference/esp32/get-started-ethernet-kit.rst diff --git a/docs/zh_CN/hw-reference/get-started-pico-kit-v3.rst b/docs/zh_CN/hw-reference/esp32/get-started-pico-kit-v3.rst similarity index 89% rename from docs/zh_CN/hw-reference/get-started-pico-kit-v3.rst rename to docs/zh_CN/hw-reference/esp32/get-started-pico-kit-v3.rst index d662f1bd8b..92b9dd6801 100644 --- a/docs/zh_CN/hw-reference/get-started-pico-kit-v3.rst +++ b/docs/zh_CN/hw-reference/esp32/get-started-pico-kit-v3.rst @@ -2,7 +2,7 @@ ESP32-PICO-KIT V3 入门指南 ======================================= :link_to_translation:`en:[English]` -本指南介绍了如何开始使用 ESP32-PICO-KIT V3 迷你开发板。有关 ESP32-PICO-KIT 其他版本的介绍，请见：:doc:`../hw-reference/index`。 +本指南介绍了如何开始使用 ESP32-PICO-KIT V3 迷你开发板。有关 ESP32-PICO-KIT 其他版本的介绍，请见：:doc:`../../hw-reference/index`。 准备工作 @@ -30,7 +30,7 @@ ESP32-PICO-KIT 集成了 USB 转 UART 桥接电路，允许开发人员直接通 ESP32-PICO-KIT V3 开发板的主要组件、接口及控制方式见下。 -.. figure:: ../../_static/esp32-pico-kit-v3-layout.jpg +.. figure:: ../../../_static/esp32-pico-kit-v3-layout.jpg :align: center :alt: ESP32-PICO-KIT V3 开发板布局 :figclass: align-center @@ -39,10 +39,10 @@ ESP32-PICO-KIT V3 开发板的主要组件、接口及控制方式见下。 ESP32-PICO-KIT 开发板的主要组件描述见下表。 -.. list-table:: +.. list-table:: :widths: 25 75 :header-rows: 1 - + * - 主要组件 - 基本介绍 * - ESP32-PICO-D4 @@ -68,7 +68,7 @@ ESP32-PICO-KIT 开发板的主要组件描述见下表。 ESP32-PICO-KIT V3 上电前，请首先确认开发板完好无损。 -现在，请前往 :doc:`index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 +现在，请前往 :doc:`../../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 相关文档 @@ -76,6 +76,6 @@ ESP32-PICO-KIT V3 上电前，请首先确认开发板完好无损。 * `ESP32-PICO-KIT V3 原理图 `_ (PDF) * `《ESP32-PICO-D4 技术规格书》 `_ (PDF) -* :doc:`../hw-reference/index` +* :doc:`../../hw-reference/index` diff --git a/docs/zh_CN/hw-reference/get-started-pico-kit.rst b/docs/zh_CN/hw-reference/esp32/get-started-pico-kit.rst similarity index 94% rename from docs/zh_CN/hw-reference/get-started-pico-kit.rst rename to docs/zh_CN/hw-reference/esp32/get-started-pico-kit.rst index a7c88cd393..054fc63e36 100644 --- a/docs/zh_CN/hw-reference/get-started-pico-kit.rst +++ b/docs/zh_CN/hw-reference/esp32/get-started-pico-kit.rst @@ -2,7 +2,7 @@ ESP32-PICO-KIT V4/V4.1 入门指南 ======================================================= :link_to_translation:`en:[English]` -本指南介绍了如何开始使用 ESP32-PICO-KIT V4 / V4.1 迷你开发板。有关 ESP32-PICO-KIT 其他版本的介绍，请见：:doc:`../hw-reference/index`。 +本指南介绍了如何开始使用 ESP32-PICO-KIT V4 / V4.1 迷你开发板。有关 ESP32-PICO-KIT 其他版本的介绍，请见：:doc:`../../hw-reference/index`。 本指南仅适用于 ESP32-PICO-KIT V4 和 V4.1。ESP32-PICO-KIT V4.1 与 V4 的最大差别在于桥接器，其中 V4 搭载的 CP2102 USB-to-UART 桥接器最高速率为 1 Mbps，V4.1 搭载的 CP2102N 桥接器最高传输速率 3 Mbps。 @@ -43,7 +43,7 @@ ESP32-PICO-KIT 集成了 USB 转 UART 桥接电路，允许开发人员直接通 ESP32-PICO-KIT 开发板的主要组件和连接方式见下。 -.. figure:: ../../_static/esp32-pico-kit-v4-functional-block-diagram.png +.. figure:: ../../../_static/esp32-pico-kit-v4-functional-block-diagram.png :align: center :alt: ESP32-PICO-KIT 功能框图 :figclass: align-center @@ -58,7 +58,7 @@ ESP32-PICO-KIT 开发板的主要组件、接口及控制方式见下。 .. _get-started-pico-kit-v4-board-front: -.. figure:: ../../_static/esp32-pico-kit-v4.1-f-layout.jpeg +.. figure:: ../../../_static/esp32-pico-kit-v4.1-f-layout.jpeg :align: center :alt: ESP32-PICO-KIT 开发板布局 :figclass: align-center @@ -67,7 +67,7 @@ ESP32-PICO-KIT 开发板的主要组件、接口及控制方式见下。 ESP32-PICO-KIT 开发板的主要组件描述见下表（从左上角起顺时针顺序）。 -.. list-table:: +.. list-table:: :widths: 25 75 :header-rows: 1 @@ -79,7 +79,7 @@ ESP32-PICO-KIT 开发板的主要组件描述见下表（从左上角起顺时 - 5V-to-3.3V 低压差稳压器 * - USB-to-UART 桥接器 - 单芯片 USB-to-UART 桥接器。V4 版本搭载的 CP2102 可提供高达 1 Mbps 的传输速率，V4.1 版本搭载的 CP2102N 可提供高达 3 Mbps 的传输速率。 - * - Micro USB 端口 + * - Micro USB 端口 - USB 接口。可用作开发板的供电电源，或连接 PC 和开发板的通信接口。 * - 5V Power On LED - 开发板通电后，该红色指示灯将亮起。更多信息，请见 `相关文档`_ 中的原理图。 @@ -119,7 +119,7 @@ Header J2 ====== ================= ====== ====================================================== 1 FLASH_SD1 (FSD1) I/O | GPIO8, SD_DATA1, SPID, HS1_DATA1 :ref:`（见说明 1） ` , U2CTS 2 FLASH_SD3 (FSD3) I/O | GPIO7, SD_DATA0, SPIQ, HS1_DATA0 :ref:`（见说明 1） ` , U2RTS -3 FLASH_CLK (FCLK) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`（见说明 1） ` , U1CTS +3 FLASH_CLK (FCLK) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`（见说明 1） ` , U1CTS 4 IO21 I/O | GPIO21, VSPIHD, EMAC_TX_EN 5 IO22 I/O | GPIO22, VSPIWP, U0RTS, EMAC_TXD1 6 IO19 I/O | GPIO19, VSPIQ, U0CTS, EMAC_TXD0 @@ -192,7 +192,7 @@ No. Name Type Function ESP32-PICO-KIT 上电前，请首先确认开发板完好无损。 -现在，请前往 :doc:`index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 +现在，请前往 :doc:`../../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 开发板尺寸 @@ -200,14 +200,14 @@ ESP32-PICO-KIT 上电前，请首先确认开发板完好无损。 ESP32-PICO-KIT 的尺寸为 52 x 20.3 x 10 mm (2.1" x 0.8" x 0.4")。 -.. figure:: ../../_static/esp32-pico-kit-v4.1-dimensions-back.jpg +.. figure:: ../../../_static/esp32-pico-kit-v4.1-dimensions-back.jpg :align: center :alt: ESP32-PICO-KIT 尺寸图 -- 背面 :figclass: align-center ESP32-PICO-KIT 尺寸图 -- 背面 -.. figure:: ../../_static/esp32-pico-kit-v4-dimensions-side.jpg +.. figure:: ../../../_static/esp32-pico-kit-v4-dimensions-side.jpg :align: center :alt: ESP32-PICO-KIT V4 尺寸图 -- 侧面 :figclass: align-center @@ -224,7 +224,7 @@ ESP32-PICO-KIT 的尺寸为 52 x 20.3 x 10 mm (2.1" x 0.8" x 0.4")。 * `ESP32-PICO-KIT V4.1 原理图 `_ (PDF) * `ESP32-PICO-KIT 参考设计 `_ ，内含 OrCAD 原理图、PCB 布局、Gerbers 和 BOM 表。 * `《ESP32-PICO-D4 技术规格书》 `_ (PDF) -* :doc:`../hw-reference/index` +* :doc:`../../hw-reference/index` .. toctree:: diff --git a/docs/zh_CN/hw-reference/get-started-wrover-kit-v2.rst b/docs/zh_CN/hw-reference/esp32/get-started-wrover-kit-v2.rst similarity index 89% rename from docs/zh_CN/hw-reference/get-started-wrover-kit-v2.rst rename to docs/zh_CN/hw-reference/esp32/get-started-wrover-kit-v2.rst index b606dccf90..8793dc9741 100644 --- a/docs/zh_CN/hw-reference/get-started-wrover-kit-v2.rst +++ b/docs/zh_CN/hw-reference/esp32/get-started-wrover-kit-v2.rst @@ -2,7 +2,7 @@ ESP-WROVER-KIT V2 入门指南 =========================================== :link_to_translation:`en:[English]` -本指南介绍了如何开始使用 ESP-WROVER-KIT V2 开发板及其功能和相关配置。有关 ESP-WROVER-KIT 其他版本的介绍，请见：:doc:`../hw-reference/index`。 +本指南介绍了如何开始使用 ESP-WROVER-KIT V2 开发板及其功能和相关配置。有关 ESP-WROVER-KIT 其他版本的介绍，请见：:doc:`../../hw-reference/index`。 准备工作 @@ -39,7 +39,7 @@ ESP-WROVER-KIT 可选贴以下 ESP32 模组： ESP-WROVER-KIT 开发板的主要组件和连接方式如下图所示。 -.. figure:: ../../_static/esp-wrover-kit-block-diagram.png +.. figure:: ../../../_static/esp-wrover-kit-block-diagram.png :align: center :alt: ESP-WROVER-KIT 功能框图 :figclass: align-center @@ -54,7 +54,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 .. _get-started-esp-wrover-kit-v2-board-front: -.. figure:: ../../_static/esp-wrover-kit-v2-layout-front.png +.. figure:: ../../../_static/esp-wrover-kit-v2-layout-front.png :align: center :alt: ESP-WROVER-KIT 开发板布局 -- 俯视图 :figclass: align-center @@ -63,7 +63,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 .. _get-started-esp-wrover-kit-v2-board-back: -.. figure:: ../../_static/esp-wrover-kit-v2-layout-back.png +.. figure:: ../../../_static/esp-wrover-kit-v2-layout-back.png :align: center :alt: ESP-WROVER-KIT 开发板布局 -- 仰视图 :figclass: align-center @@ -73,7 +73,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 下表从图片右上角开始，以顺时针顺序介绍了图 1 中的主要组件，然后以同样的顺序介绍了图 2 中的主要组件。 -.. list-table:: +.. list-table:: :widths: 25 75 :header-rows: 1 @@ -112,7 +112,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 * - RGB LED - 红绿蓝发光二极管，可由 PWM（脉冲宽度调制）控制。 * - I/O - - 板上模组的所有管脚均已引出至开发板的排针。用户可以对 ESP32 进行编程，实现 PWM、ADC、DAC、I2C、I2S、SPI 等多种功能。 + - 板上模组的所有管脚均已引出至开发板的排针。用户可以对 ESP32 进行编程，实现 PWM、ADC、DAC、I2C、I2S、SPI 等多种功能。 * - MicroSD 卡槽 - MicroSD 卡槽，可扩充存储空间：当 ESP32 进入下载模式时，GPIO2 不可处于高电平。然而，为了使能 MicroSD 卡功能，需为 GPIO2 增加一个上拉电阻。默认情况下，GPIO2 和上拉电阻 R153 处于断开状态。为了使能 MicroSD 卡，请按照 `设置选项`_ 章节的要求，连接 JP1 连接器。 * - LCD 显示屏 @@ -169,7 +169,7 @@ USB 供电 使能 UART 通信 正式开始开发 ^^^^^^^^^^^^^^^^^^ -现在，请前往 :doc:`index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 +现在，请前往 :doc:`../../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 相关文档 @@ -179,16 +179,16 @@ USB 供电 使能 UART 通信 * `《ESP32 技术规格书》 `_ (PDF) * `《ESP32-WROVER 技术规格书》 `_ (PDF) * `《ESP32-WROOM-32 技术规格书》 `_ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* :doc:`../hw-reference/index` +* :doc:`../../api-guides/jtag-debugging/index` +* :doc:`../../hw-reference/index` -.. |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-tx-rx| image:: ../../_static/wrover-jp11-tx-rx.png -.. |jp14| image:: ../../_static/wrover-jp14.png +.. |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-tx-rx| image:: ../../../_static/wrover-jp11-tx-rx.png +.. |jp14| image:: ../../../_static/wrover-jp14.png .. _ESP-WROVER-KIT V2 原理图: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf diff --git a/docs/zh_CN/hw-reference/get-started-wrover-kit-v3.rst b/docs/zh_CN/hw-reference/esp32/get-started-wrover-kit-v3.rst similarity index 94% rename from docs/zh_CN/hw-reference/get-started-wrover-kit-v3.rst rename to docs/zh_CN/hw-reference/esp32/get-started-wrover-kit-v3.rst index ab8e8f7530..50f1b7aa94 100644 --- a/docs/zh_CN/hw-reference/get-started-wrover-kit-v3.rst +++ b/docs/zh_CN/hw-reference/esp32/get-started-wrover-kit-v3.rst @@ -2,7 +2,7 @@ ESP-WROVER-KIT V3 入门指南 ======================================= :link_to_translation:`en:[English]` -本指南介绍了如何开始使用 ESP-WROVER-KIT V3 开发板及其功能和相关配置。有关 ESP-WROVER-KIT 其他版本的介绍，请见：:doc:`../hw-reference/index`。 +本指南介绍了如何开始使用 ESP-WROVER-KIT V3 开发板及其功能和相关配置。有关 ESP-WROVER-KIT 其他版本的介绍，请见：:doc:`../../hw-reference/index`。 准备工作 @@ -39,7 +39,7 @@ ESP-WROVER-KIT 可选贴以下 ESP32 模组： ESP-WROVER-KIT 开发板的主要组件和连接方式如下图所示。 -.. figure:: ../../_static/esp-wrover-kit-block-diagram.png +.. figure:: ../../../_static/esp-wrover-kit-block-diagram.png :align: center :alt: ESP-WROVER-KIT 功能框图 :figclass: align-center @@ -54,7 +54,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 .. _get-started-esp-wrover-kit-v3-board-front: -.. figure:: ../../_static/esp-wrover-kit-v3-layout-front.jpg +.. figure:: ../../../_static/esp-wrover-kit-v3-layout-front.jpg :align: center :alt: ESP-WROVER-KIT 开发板布局 -- 俯视图 :figclass: align-center @@ -63,7 +63,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 .. _get-started-esp-wrover-kit-v3-board-back: -.. figure:: ../../_static/esp-wrover-kit-v3-layout-back.jpg +.. figure:: ../../../_static/esp-wrover-kit-v3-layout-back.jpg :align: center :alt: ESP-WROVER-KIT 开发板布局 -- 仰视图 :figclass: align-center @@ -73,7 +73,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 下表从图片右上角开始，以顺时针顺序介绍了图 1 中的主要组件，然后以同样的顺序介绍图 2 中的主要组件。 -.. list-table:: +.. list-table:: :widths: 25 75 :header-rows: 1 @@ -114,7 +114,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 * - RGB LED - 红绿蓝发光二极管，可由 PWM（脉冲宽度调制）控制。 * - I/O - - 板上模组的所有管脚均已引出至开发板的排针。用户可以对 ESP32 进行编程，实现 PWM、ADC、DAC、I2C、I2S、SPI 等多种功能。 + - 板上模组的所有管脚均已引出至开发板的排针。用户可以对 ESP32 进行编程，实现 PWM、ADC、DAC、I2C、I2S、SPI 等多种功能。 * - MicroSD 卡槽 - 适用于需要扩充数据存储空间或进行备份的应用开发场景。 * - LCD 显示屏 @@ -352,7 +352,7 @@ USB 供电 使能 UART 通信 正式开始开发 ^^^^^^^^^^^^^^^^^^ -现在，请前往 :doc:`index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 +现在，请前往 :doc:`../../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 相关文档 ----------------- @@ -361,14 +361,14 @@ USB 供电 使能 UART 通信 * `《ESP32 技术规格书》 `_ (PDF) * `《ESP32-WROVER 技术规格书》 `_ (PDF) * `《ESP32-WROOM-32 技术规格书》 `_ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* :doc:`../hw-reference/index` +* :doc:`../../api-guides/jtag-debugging/index` +* :doc:`../../hw-reference/index` -.. |jp7-ext_5v| image:: ../../_static/esp-wrover-kit-v3-jp7-ext_5v.png -.. |jp7-usb_5v| image:: ../../_static/esp-wrover-kit-v3-jp7-usb_5v.png -.. |jp8| image:: ../../_static/esp-wrover-kit-v3-jp8.png -.. |jp11-tx-rx| image:: ../../_static/esp-wrover-kit-v3-jp11-tx-rx.png -.. |jp14| image:: ../../_static/esp-wrover-kit-v3-jp14.png +.. |jp7-ext_5v| image:: ../../../_static/esp-wrover-kit-v3-jp7-ext_5v.png +.. |jp7-usb_5v| image:: ../../../_static/esp-wrover-kit-v3-jp7-usb_5v.png +.. |jp8| image:: ../../../_static/esp-wrover-kit-v3-jp8.png +.. |jp11-tx-rx| image:: ../../../_static/esp-wrover-kit-v3-jp11-tx-rx.png +.. |jp14| image:: ../../../_static/esp-wrover-kit-v3-jp14.png .. _ESP-WROVER-KIT V3 原理图: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-3.pdf diff --git a/docs/zh_CN/hw-reference/get-started-wrover-kit.rst b/docs/zh_CN/hw-reference/esp32/get-started-wrover-kit.rst similarity index 92% rename from docs/zh_CN/hw-reference/get-started-wrover-kit.rst rename to docs/zh_CN/hw-reference/esp32/get-started-wrover-kit.rst index 9b4785b3b6..0171b676f7 100644 --- a/docs/zh_CN/hw-reference/get-started-wrover-kit.rst +++ b/docs/zh_CN/hw-reference/esp32/get-started-wrover-kit.rst @@ -2,7 +2,7 @@ ESP-WROVER-KIT V4.1 入门指南 ========================================= :link_to_translation:`en:[English]` -本指南介绍了如何开始使用 ESP-WROVER-KIT V4.1 开发板及其功能和相关配置。有关 ESP-WROVER-KIT 其他版本的介绍，请见：:doc:`../hw-reference/index`。 +本指南介绍了如何开始使用 ESP-WROVER-KIT V4.1 开发板及其功能和相关配置。有关 ESP-WROVER-KIT 其他版本的介绍，请见：:doc:`../../hw-reference/index`。 准备工作 @@ -40,7 +40,7 @@ ESP-WROVER-KIT 开发板已集成了如下组件： ESP-WROVER-KIT 开发板的主要组件和连接方式如下图所示。 -.. figure:: ../../_static/esp-wrover-kit-block-diagram.png +.. figure:: ../../../_static/esp-wrover-kit-block-diagram.png :align: center :alt: ESP-WROVER-KIT 功能框图 :figclass: align-center @@ -55,7 +55,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 .. _get-started-esp-wrover-kit-v4.1-board-front: -.. figure:: ../../_static/esp-wrover-kit-v4.1-layout-front.png +.. figure:: ../../../_static/esp-wrover-kit-v4.1-layout-front.png :align: center :alt: ESP-WROVER-KIT 开发板布局 -- 俯视图 :figclass: align-center @@ -64,7 +64,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 .. _get-started-esp-wrover-kit-v4.1-board-back: -.. figure:: ../../_static/esp-wrover-kit-v4.1-layout-back.png +.. figure:: ../../../_static/esp-wrover-kit-v4.1-layout-back.png :align: center :alt: ESP-WROVER-KIT 开发板布局 -- 仰视图 :figclass: align-center @@ -74,7 +74,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 下表将从图片右上角开始，以顺时针顺序介绍图 1 中的主要组件，然后按同样顺序介绍图 2 中的主要组件。 -.. list-table:: +.. list-table:: :widths: 25 75 :header-rows: 1 @@ -90,9 +90,9 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 - 这款 ESP32 模组内置 64-Mbit PSRAM，可提供灵活的额外存储空间和数据处理能力。 * - 诊断 LED 信号灯 - 本开发板 FT2232 芯片的 GPIO 管脚连接了 4 个红色 LED 信号灯，以备后用。 - * - UART + * - UART - 串口。FT2232 和 ESP32 的串行 TX/RX 信号已引出至 JP2 的两端。默认情况下，这两路信号由跳线帽连接。如果仅需使用 ESP32 模组串口，则可移除相关跳线帽，将模组连接至其他外部串口设备。 - * - SPI + * - SPI - 默认情况下，ESP32 使用 SPI 接口访问内置 flash 和 PSRAM。使用这些引脚连接 ESP32 和其他 SPI 设备。这种情况下，需增加额外的片选 (CS) 信号。注意，本接口的工作电压为 3.3 V。 * - CTS/RTS - 串口流控信号。管脚默认不连接至电路。为了使能该功能，必须用跳线帽断路掉 JP14 的相应管脚。 @@ -119,7 +119,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 * - RGB LED - 红绿蓝发光二极管，可由 PMW 控制。 * - I/O 连接器 - - 板上模组的所有管脚均已引出至开发板的排针。用户可以对 ESP32 进行编程，实现 PWM、ADC、DAC、I2C、I2S、SPI 等多种功能。 + - 板上模组的所有管脚均已引出至开发板的排针。用户可以对 ESP32 进行编程，实现 PWM、ADC、DAC、I2C、I2S、SPI 等多种功能。 * - Micro SD 卡槽 - 适用于需要扩充数据存储空间或进行备份的应用开发场景。 * - LCD 显示器 @@ -134,7 +134,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 用户可通过 3 组排针，设置开发板功能，其中常见功能见下表： -.. list-table:: +.. list-table:: :widths: 25 35 40 :header-rows: 1 @@ -145,15 +145,15 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 - |jp7-ext_5v| - 使用外部电源为 ESP-WROVER-KIT 开发板供电 * - JP7 - - |jp7-usb_5v| + - |jp7-usb_5v| - 使用 USB 端口为 ESP-WROVER-KIT 开发板供电 - * - JP2 - - |jp2-jtag| + * - JP2 + - |jp2-jtag| - 使能 JTAG 功能 - * - JP2 + * - JP2 - |jp2-tx-rx| - 使能 UART 通信 - * - JP14 + * - JP14 - |jp14| - 使能 RTS/CTS 串口流控 @@ -163,7 +163,7 @@ ESP32 管脚分配 ESP32 模组的部分管脚/终端已被板上组件占用或用于外部硬件设备。如果某管脚对应的特定硬件未连接，则该管脚可用作他用。比如，摄像头/JP4 排针未连接相应硬件，则这些 GPIO 可用于其他用途。 -部分管脚具备多个功能，可供板上组件或外部硬件设备同时使用，比如 GPIO0 和 GPIO2。由于管脚限制，一些外围设备不可同时使用，比如，由于 JTAG 和 SD 卡槽需共用部分管脚，因此一些使用 SD 卡功能的应用无法同时进行 JTAG 调试。 +部分管脚具备多个功能，可供板上组件或外部硬件设备同时使用，比如 GPIO0 和 GPIO2。由于管脚限制，一些外围设备不可同时使用，比如，由于 JTAG 和 SD 卡槽需共用部分管脚，因此一些使用 SD 卡功能的应用无法同时进行 JTAG 调试。 其他情况下，不同外设可同时使用。比如，LCD 屏幕和 SD 卡仅共用一个 GPIO21 管脚，可以同时使用。该管脚可为 LCD 屏幕提供 D/C（数据/控制）信号，并用于读取来自 SD 卡槽的 CD 信号（卡检测信号）。如无需使用卡检测功能，开发人员还可以通过移除 R167 来禁用该功能。此时，LCD 和 SD 卡槽可同时使用。 @@ -176,7 +176,7 @@ ESP32 模组的部分管脚/终端已被板上组件占用或用于外部硬件 JP1 连接器包括 14 x 2 个排针，具体功能可见下表中间 “I/O” 列的介绍。两侧的“共用”列则介绍了这些管脚在板上的其他用途。 -.. list-table:: +.. list-table:: :widths: 30 20 20 30 :header-rows: 1 @@ -209,7 +209,7 @@ JP1 连接器包括 14 x 2 个排针，具体功能可见下表中间 “I/O” - IO35 - IO34 - 摄像头 - * - 摄像头 + * - 摄像头 - IO39 - IO36 - 摄像头 @@ -236,11 +236,11 @@ JP1 连接器包括 14 x 2 个排针，具体功能可见下表中间 “I/O” * - 摄像头，LED，Boot - IO0 - IO2 - - LED，MicroSD + - LED，MicroSD * - JTAG，MicroSD - IO15 - 5V - - + - 说明： @@ -420,7 +420,7 @@ USB 供电 使能 UART 通信 正式开始开发 ^^^^^^^^^^^^^^^^^^ -现在，请前往 :doc:`index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 +现在，请前往 :doc:`../../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 相关文档 @@ -429,14 +429,14 @@ USB 供电 使能 UART 通信 * `ESP-WROVER-KIT V4.1 原理图`_ (PDF) * `《ESP32 技术规格书》 `_ (PDF) * `《ESP32-WROVER-B 技术规格书》 `_ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* :doc:`../hw-reference/index` +* :doc:`../../api-guides/jtag-debugging/index` +* :doc:`../../hw-reference/index` -.. |jp7-ext_5v| image:: ../../_static/esp-wrover-kit-v4.1-jp7-ext_5v.jpg -.. |jp7-usb_5v| image:: ../../_static/esp-wrover-kit-v4.1-jp7-usb_5v.jpg -.. |jp2-jtag| image:: ../../_static/esp-wrover-kit-v4.1-jp2-jtag.jpg -.. |jp2-tx-rx| image:: ../../_static/esp-wrover-kit-v4.1-jp2-tx-rx.jpg -.. |jp14| image:: ../../_static/esp-wrover-kit-v4.1-jp14.jpg +.. |jp7-ext_5v| image:: ../../../_static/esp-wrover-kit-v4.1-jp7-ext_5v.jpg +.. |jp7-usb_5v| image:: ../../../_static/esp-wrover-kit-v4.1-jp7-usb_5v.jpg +.. |jp2-jtag| image:: ../../../_static/esp-wrover-kit-v4.1-jp2-jtag.jpg +.. |jp2-tx-rx| image:: ../../../_static/esp-wrover-kit-v4.1-jp2-tx-rx.jpg +.. |jp14| image:: ../../../_static/esp-wrover-kit-v4.1-jp14.jpg .. _ESP-WROVER-KIT V4.1 原理图: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_V4_1.pdf diff --git a/docs/zh_CN/hw-reference/esp32/inc/modules-and-boards-esp32.rst b/docs/zh_CN/hw-reference/esp32/inc/modules-and-boards-esp32.rst new file mode 100644 index 0000000000..e5c5b56bbf --- /dev/null +++ b/docs/zh_CN/hw-reference/esp32/inc/modules-and-boards-esp32.rst @@ -0,0 +1,294 @@ +.. _esp-wroom-solo-wrover-modules: + +WROOM、SOLO、WROVER 和 PICO 系列模组 +===================================== + +WROOM、SOLO、WROVER 和 PICO 系列模组内置 ESP32 芯片并集成了晶振、天线匹配电路等重要组件，可直接集成到终端产品中。如果再结合一些其他组件，例如编程接口、Bootstrapping 电阻和排针，您就可以体验 ESP32 的强大功能了。 + +下表总结了上述系列模组的主要特点，详细信息见后续章节。 + ++---------------------+--------------+-------------+-------------+------+-----------------+ +| 模组 | 芯片 | Flash (MB) | PSRAM (MB) | 天线 | 尺寸 (mm) | ++---------------------+--------------+-------------+-------------+------+-----------------+ +| ESP32-WROOM-32 | ESP32-D0WDQ6 | 4 | – | MIFA | 18 × 25.5 × 3.1 | ++---------------------+--------------+-------------+-------------+------+-----------------+ +| ESP32-WROOM-32D | ESP32-D0WD | 4、8 或 16 | – | MIFA | 18 × 25.5 × 3.1 | ++---------------------+--------------+-------------+-------------+------+-----------------+ +| ESP32-WROOM-32U | ESP32-D0WD | 4、8 或 16 | – | U.FL | 18 × 19.2 × 3.1 | ++---------------------+--------------+-------------+-------------+------+-----------------+ +| ESP32-SOLO-1 | ESP32-S0WD | 4 | – | MIFA | 18 × 25.5 × 3.1 | ++---------------------+--------------+-------------+-------------+------+-----------------+ +| ESP32-WROVER (PCB) | ESP32-D0WDQ6 | 4 | 8 | MIFA | 18 × 31.4 × 3.3 | ++---------------------+--------------+-------------+-------------+------+-----------------+ +| ESP32-WROVER (IPEX) | ESP32-D0WDQ6 | 4 | 8 | U.FL | 18 × 31.4 × 3.3 | ++---------------------+--------------+-------------+-------------+------+-----------------+ +| ESP32-WROVER-B | ESP32-D0WD | 4、8 或 16 | 8 | MIFA | 18 × 31.4 × 3.3 | ++---------------------+--------------+-------------+-------------+------+-----------------+ +| ESP32-WROVER-IB | ESP32-D0WD | 4、8 或 16 | 8 | U.FL | 18 × 31.4 × 3.3 | ++---------------------+--------------+-------------+-------------+------+-----------------+ + + +* ESP32-**D**.. 代表双核芯片，ESP32-**S**.. 代表单核芯片； +* MIFA - 蛇形倒 F 天线； +* U.FL - U.FL/IPEX 天线连接器； +* ESP32-WROOM-32x、ESP32-WROVER-B 和 ESP32-WROVER-IB 模组默认内置 4 MB flash，客户可定制 8 MB 和 16 MB flash，详情见 `乐鑫产品订购信息`_ (PDF) 和《`ESP32 技术规格书 `_》(PDF)； +* 最初发布的 ESP32-WROVER 模组内置 4 MB PSRAM； +* *ESP-WROOM-32* 是 *ESP32-WROOM-32* 的曾用名。 + +.. _esp-modules-and-boards-esp32-wroom-32: + +ESP32-WROOM-32 模组 +-------------------- + +ESP32-WROOM-32 模组是 WROOM/WROVER 系列最先发布的模组，内置 ESP32-D0WDQ6 芯片，是一款基础且常用的 ESP32 模组。 + +有关该模组的详细信息，请查看 :ref:`esp-wroom-solo-wrover-modules` 章节中的表格。 + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32-front-back.jpg + :align: center + :alt: ESP32-WROOM-32 module (front and back) + :width: 45% + + ESP32-WROOM-32 模组（正反面图） + +相关文档 +^^^^^^^^^^^^^ + +* 《`ESP32-WROOM-32 技术规格书 `_》(PDF)； +* `ESP32-WROOM-32 参考设计 `_，包括原理图（由 OrCAD Capture 绘制）、PCB 布局（由 Mentor PADS 绘制）、GERBER 文件和 BOM 清单。 + +.. _esp-modules-and-boards-esp32-wroom-32d-and-u: + +ESP32-WROOM-32D/ESP32-WROOM-32U 模组 +-------------------------------------- + +两款模组均集成了 ESP32-D0WD 芯片，与 :ref:`esp-modules-and-boards-esp32-wroom-32` 集成的 ESP32-D0WDQ6 相比，ESP32-D0WD 芯片的封装更小，在 PCB 上占用的面积更小。 + +有关这两款模组的详细信息，请查看 :ref:`esp-wroom-solo-wrover-modules` 中的表格和 `乐鑫产品订购信息`_。 + +ESP32-WROOM-32U 是整个 WROOM/WROVER 模组系列中最小的模组。 + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32d-front-back.jpg + :align: center + :alt: ESP32-WROOM-32D module (front and back) + :width: 45% + + ESP32-WROOM-32D 模组（正反面图） + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32u-front-back.jpg + :align: center + :alt: ESP32-WROOM-32U module (front and back) + :width: 45% + + ESP32-WROOM-32U 模组（正反面图） + +相关文档 +^^^^^^^^^^^^^ + +* 《`ESP32-WROOM-32D/ESP32-WROOM-32U 技术规格书 `_》(PDF) + + +.. _esp-modules-and-boards-esp32-solo-1: + +ESP32-SOLO-1 模组 +----------------- + +ESP32-SOLO-1 模组是 ESP32-WROOM-32D 模组的简化版本，内置一个 ESP32 单核芯片，支持高达 160 MHz 的时钟频率。 + +有关此模组的详细信息，请查看 :ref:`esp-wroom-solo-wrover-modules` 章节中的表格和 `乐鑫产品订购信息`_。 + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-solo-1-front-back.jpg + :align: center + :alt: ESP32-SOLO-1 module (front and back) + :width: 45% + + ESP32-SOLO-1 模组（正反面图） + +相关文档 +^^^^^^^^^^^^^ + +* 《`ESP32-SOLO-1 技术规格书 `__》(PDF) + +.. _esp-modules-and-boards-esp32-wrover: + +ESP32-WROVER 系列模组 +------------------------- + +ESP32-WROVER 系列模组在 ESP32-WROOM-32x 模组的基础上进行了一些修改，其中包含一些功能升级，并新增 8 MB SPI PSRAM（伪静态 RAM）。 + +有关该模组的详细信息，请查看 :ref:`esp-wroom-solo-wrover-modules` 章节中的表格和 `乐鑫产品订购信息`_。 + +* **ESP32-WROVER (PCB)** 模组和 **ESP32-WROVER (IPEX)** 模组内置 1.8 V PSRAM，支持 144 MHz 时钟频率。 +* **ESP32-WROVER-B** 模组和 **ESP32-WROVER-IB** 模组内置 3.3 V PSRAM，支持 133 MHz 时钟频率。 + +下图为配备有 PCB 天线的 ESP32-WROVER 模组： + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wrover.jpg + :align: center + :alt: ESP32-WROVER module (front and back) + :width: 40% + + ESP32-WROVER 模组（正反面图） + +相关文档 +^^^^^^^^^^^^^ + +* 《`ESP32-WROVER 技术规格书 `__》(PDF) +* 《`ESP32-WROVER-B 技术规格书 `__》(PDF) +* 《`ESP-PSRAM64 & ESP-PSRAM64H 技术规格书 `__》(PDF) +* `ESP32-WROVER 参考设计 `_ 包含原理图（由 OrCAD Capture 绘制）、PCB 布局（由 Mentor PADS 绘制）、GERBER 文件和 BOM 清单。 + +ESP32-PICO-D4 模组 +------------------ + +ESP32-PICO-D4 模组是一款 SiP 模组，无缝集成了所有外设，包括： + +- 4 MB flash +- 晶振 +- 滤波电容 +- RF 匹配电路 + +有关该模组的详细信息，请查看 `乐鑫产品订购信息`_。 + +相关文档 +^^^^^^^^^^^^^ + +* 《`ESP32-PICO-D4 技术规格书 `__》(PDF) + +ESP32 开发板 +================== + +ESP32 系列开发板功能各异，具体有以下不同点： + +- 访问的 ESP32 GPIO 管脚不同； +- 接口不同，包括 USB 和 JTAG； +- 外设不同，包括 TouchPad、LCD 显示屏、SD 卡槽和相机模组排母等。 + +.. _esp-modules-and-boards-esp32-pico-kit: + +ESP32-PICO-KIT V4.1 开发板 +--------------------------- +ESP32-PICO-KIT V4.1 开发板是基于 ESP32 的最小开发板，内置连接至电脑 USB 端口所需的所有组件，同时设有排针，可直接将此开发板插接于迷你面包板。 + +ESP32-PICO-KIT V4.1 开发板集成了 `ESP32-PICO-D4 模组`_，只需在 PCB (20 x 52 mm) 上添加少许外部组件即可构成一个功能齐全的开发板。这部分外部组件包括天线、LDO、USB 至 UART 桥接器、一个重置按钮和一个固件下载模式激活按钮。 + + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-pico-kit-v4.1.jpg + :align: center + :alt: ESP32-PICO-KIT V4.1 board + :width: 50% + + ESP32-PICO-KIT V4.1 开发板 + +与 ESP32-PICO-KIT V4 相比，ESP32-PICO-KIT V4.1 开发板支持 CP2102N USB 至 UART 桥接器，可提供高达 3 Mbps 的传输速率。 + +相关文档 +^^^^^^^^^^^^^ + +* :doc:`../../hw-reference/esp32/get-started-pico-kit` +* `ESP32-PICO-KIT V4.1 原理图 `_ (PDF) +* `ESP32-PICO-KIT 参考设计 `_，包含原理图（由 OrCAD Capture 绘制）、PCB 布局（由 Mentor PADS 绘制）、GERBER 文件和 BOM 清单。 +* 《`ESP32-PICO-D4 技术规格书 `_》(PDF) + +较早版本开发板 +^^^^^^^^^^^^^^^^^ + +* :ref:`esp-modules-and-boards-esp32-pico-kit-v4` +* :ref:`esp-modules-and-boards-esp32-pico-kit-v3` + + +.. _esp-modules-and-boards-esp32-devkitc: + +ESP32 DevKitC V4 开发板 +------------------------------ + +ESP32 DevKitC V4 开发板是一款小巧实用的开发板，具备以下特色功能： + +- 集成了 :ref:`esp-modules-and-boards-esp32-wroom-32` +- USB 转串口编程接口同时可为开发板供电 +- 设有排针 +- 设有重置按钮和固件下载模式激活按钮 +- 以及其他组件 + +与较早版本的 :ref:`esp-modules-and-boards-esp32-devkitc-v2` 相比，ESP32 DevKitC V4 开发板集成了 :ref:`esp-modules-and-boards-esp32-wrover` （而非 ESP32-WROOM-32 模组），同时内置 CP2102N 芯片，支持更高波特率。 + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-devkitc-v4-front.jpg + :align: center + :alt: ESP32 DevKitC V4 board + :width: 50% + + ESP32 DevKitC V4 开发板 + +相关文档 +^^^^^^^^^^^^^ + +* :doc:`../../hw-reference/esp32/get-started-devkitc` +* `ESP32-DevKitC 原理图 `_ (PDF) +* `ESP32-DevKitC 参考设计 `_，包含原理图（由 OrCAD Capture 绘制）、PCB 布局（由 Mentor PADS 绘制）、GERBER 文件和 BOM 清单。 +* `CP210x USB 至 UART 桥 VCP 驱动器 `_ + +较早版本开发板 +^^^^^^^^^^^^^^^^^ + +* :ref:`esp-modules-and-boards-esp32-devkitc-v2` + + +.. _esp-modules-and-boards-esp-wrover-kit: + +ESP-WROVER-KIT V4.1 开发板 +------------------------------- + +ESP-WROVER-KIT V4.1 开发板具备以下特色功能： + +- USB 转双串口转换器（用于后续编程） +- JTAG 调试接口 +- MicroSD 卡槽 +- 3.2” SPI LCD 显示屏 +- 相机模组排母 +- RGB 发光二极管 +- 支持 32.768 kHz 晶振输入用于 RTC 及低功耗模式操作 + +ESP-WROVER-KIT V4.1 开发板支持 USB 供电或标准的 5 毫米电源插座供电，可使用跳线选择电源，或使用独立的开关控制电源。 + +ESP-WROVER-KIT V4.1 开发板集成了 ESP-WROVER-B 模组，该模组集成了 8 MB PSRAM，方便用户灵活扩展存储空间，增强数据处理能力。ESP-WROVER-KIT V4.1 开发板还可以集成 :ref:`esp-wroom-solo-wrover-modules` 中所述的 ESP 其他版本模组。 + +与 :ref:`esp-modules-and-boards-esp-wrover-kit-v3` 相比，ESP-WROVER-KIT V4.1 开发板在设计上有以下改动： + +- JP8、JP11 和 JP13 合并成了一个 JP2。 +- USB 连接器的固定脚改为直插式，并移至板子右下角。 +- R61 已变更为零欧姆电阻。 +- 基于测试结果和采购选择，部分组件已由功能对等组件替代，例如 EN 和 Boot 按钮。 + +.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-wrover-kit-v4.1-front.jpg + :align: center + :alt: ESP-WROVER-KIT V4.1 board + :width: 90% + + ESP-WROVER-KIT V4.1 开发板 + +上图所示开发板集成了 ESP32-WROVER-B 模组。 + +相关文档 +^^^^^^^^^^^^^ + +* :doc:`../../hw-reference/esp32/get-started-wrover-kit` +* `ESP-WROVER-KIT V4.1 原理图 `__ (PDF) +* :doc:`../../../api-guides/jtag-debugging/index` +* `FTDI 虚拟 COM 端口驱动`_ + +较早版本开发板 +^^^^^^^^^^^^^^^^^ + +* :ref:`esp-modules-and-boards-esp-wrover-kit-v3` +* :ref:`esp-modules-and-boards-esp-wrover-kit-v2` +* :ref:`esp-modules-and-boards-esp-wrover-kit-v1` + + +相关文档 +================= + +* :doc:`modules-and-boards-previous` + + +.. _FTDI 虚拟 COM 端口驱动: http://www.ftdichip.com/Drivers/VCP.htm +.. _乐鑫产品订购信息: https://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_cn.pdf diff --git a/docs/zh_CN/hw-reference/esp32/inc/modules-and-boards-previous-esp32.rst b/docs/zh_CN/hw-reference/esp32/inc/modules-and-boards-previous-esp32.rst new file mode 100644 index 0000000000..362c2fa3ff --- /dev/null +++ b/docs/zh_CN/hw-reference/esp32/inc/modules-and-boards-previous-esp32.rst @@ -0,0 +1 @@ +.. include:: ../../en/hw-reference/esp32/inc/modules-and-boards-previous-esp32.rst \ No newline at end of file diff --git a/docs/zh_CN/hw-reference/esp32s2/inc/modules-and-boards-esp32s2.rst b/docs/zh_CN/hw-reference/esp32s2/inc/modules-and-boards-esp32s2.rst new file mode 100644 index 0000000000..06ea340f49 --- /dev/null +++ b/docs/zh_CN/hw-reference/esp32s2/inc/modules-and-boards-esp32s2.rst @@ -0,0 +1 @@ +.. include:: ../../en/hw-reference/esp32s2/inc/modules-and-boards-esp32s2.rst \ No newline at end of file diff --git a/docs/zh_CN/hw-reference/esp32s2/inc/modules-and-boards-previous-esp32s2.rst b/docs/zh_CN/hw-reference/esp32s2/inc/modules-and-boards-previous-esp32s2.rst new file mode 100644 index 0000000000..5a84a53e6b --- /dev/null +++ b/docs/zh_CN/hw-reference/esp32s2/inc/modules-and-boards-previous-esp32s2.rst @@ -0,0 +1 @@ +.. include:: ../../en/hw-reference/esp32s2/inc/modules-and-boards-previous-esp32s2.rst diff --git a/docs/zh_CN/hw-reference/get-started-ethernet-kit.rst b/docs/zh_CN/hw-reference/get-started-ethernet-kit.rst deleted file mode 100644 index ab479d4f9e..0000000000 --- a/docs/zh_CN/hw-reference/get-started-ethernet-kit.rst +++ /dev/null @@ -1,409 +0,0 @@ -ESP32-Ethernet-Kit V1.1 入门指南 -================================= - -:link_to_translation:`en:[English]` - -本指南将介绍 ESP32-Ethernet-Kit 开发板的配置以及相关功能的使用。 - -:ref:`ESP32-Ethernet-Kit ` 是一款以太网转 Wi-Fi 开发板，可为以太网设备赋予 Wi-Fi 连接功能。为了提供更灵活的电源选项，ESP32-Ethernet-Kit 同时也支持以太网供电 (PoE)。 - - -准备工作 --------- - -* :ref:`ESP32-Ethernet-Kit V1.1 开发板 ` -* USB 数据线（A 转 Micro-B） -* PC（Windows、Linux 或 Mac OS） - -您可以跳过介绍部分，直接前往 `应用程序开发`_ 章节。 - - -概述 ----- - -ESP32-Ethernet-Kit 是一款来自 `乐鑫 `_ 的开发板。 - -它由 :ref:`以太网母板（A板）` 和 `PoE 子板（B 板）`_ 两部分组成。其中 :ref:`以太网母板（A板）` 集成蓝牙 / Wi-Fi 双模 ESP32-WROVER-B 模组和单端口 10/100 Mbps 快速以太网收发器 (PHY) IP101GRI。`PoE 子板（B 板）`_ 提供以太网供电功能。ESP32-Ethernet-Kit 的 A 板可在不连接 B 板的情况下独立工作。 - -.. _get-started-esp32-ethernet-kit-v1.1: - -.. figure:: ../../_static/esp32-ethernet-kit-v1.1.png - :align: center - :alt: ESP32-Ethernet-Kit V1.1 - :figclass: align-center - - ESP32-Ethernet-Kit V1.1 - -为了实现程序下载和监控，A 板还集成了一款先进多协议 USB 桥接器（FTDI FT2232H 芯片）。FTDI FT2232H 芯片使得开发人员无需额外的 JTAG 适配器，通过 USB 桥接器使用 JTAG 接口便可对 ESP32 直接进行调试。 - - -功能概述 ---------- - -ESP32-Ethernet-Kit 开发板的主要组件和连接方式如下。 - -.. figure:: ../../_static/esp32-ethernet-kit-v1.1-block-diagram.png - :align: center - :scale: 60% - :alt: ESP32-Ethernet-Kit 功能框图（点击放大） - :figclass: align-center - - ESP32-Ethernet-Kit 功能框图（点击放大） - - -功能说明 --------- - -有关 ESP32-Ethernet-Kit 开发板的主要组件、接口及控制方式，请见下方的图片和表格。 - -.. _get-started-esp32-ethernet-kit-a-v1.1-layout: - - -以太网母板（A 板） -^^^^^^^^^^^^^^^^^^^^^ - -.. figure:: ../../_static/esp32-ethernet-kit-a-v1.1-layout.png - :align: center - :scale: 80% - :alt: ESP32-Ethernet-Kit - Ethernet board (A) layout - :figclass: align-center - - ESP32-Ethernet-Kit - 以太网母板（A 板）布局（点击放大）（请更新图片） - -下表将从图片右上角开始，以顺时针顺序介绍图中的主要组件。 - -.. list-table:: 表格1 组件介绍 - :widths: 40 150 - :header-rows: 1 - - * - 主要组件 - - 基本介绍 - * - ESP32-WROVER-B 模组 - - 这款 ESP32 模组内置 64-Mbit PSRAM，可提供灵活的额外存储空间和数据处理能力。 - * - GPIO Header 2 - - 由 5 个未引出通孔组成，可连接至 ESP32 的部分 GPIO。具体介绍，请见 `GPIO Header 2`_。 - * - 功能选择开关 - - 一个 4 位拨码开关，可配置 ESP32 部分 GPIO 的功能。请注意，拨码开关旁边开发板的丝印层上的 GPIO 管脚标记的位置是不正确的。有关详细信息和正确的管脚分配，请见 `功能选择开关`_。 - * - Tx/Rx LEDs - - 2 个 LED，可显示 UART 传输的状态。 - * - FT2232H - - FT2232H 多协议 USB 转串口桥接器。开发人员可通过 USB 接口对 FT2232H 芯片进行控制和编程，与 ESP32 建立连接。FT2232H 芯片可在通道 A 提供 USB-to-JTAG 接口功能，并在通道 B 提供 USB-to-Serial 接口功能，便利开发人员的应用开发与调试。见 `ESP32-Ethernet-Kit V1.1 以太网母板（A 板）原理图`_。 - * - USB 端口 - - USB 接口。可用作开发板的供电电源，或连接 PC 和开发板的通信接口。 - * - 电源开关 - - 电源开关。拨向 **5V0** 按键侧，开发板上电；拨向 **GND** 按键一侧，开发板掉电。 - * - 5V Input - - 5V 电源接口建议仅在开发板自动运行（未连接 PC）时使用。 - * - 5V Power On LED - - 当开发板通电后（USB 或外部 5V 供电），该红色指示灯将亮起。 - * - DC/DC 转换器 - - 直流 5 V 转 3.3 V，输出电流最高可达 2 A。 - * - Board B 连接器 - - 1 对 排针和排母，用于连接 `PoE 子板（B 板）`_。 - * - IP101GRI (PHY) - - 物理层 (PHY) 单端口 10/100 快速以太网收发器 `IP101GRI `_ 芯片，允许开发人员实现与以太网线缆的物理层连接。PHY 与 ESP32 通过简化媒体独立接口 (RMII) 实现连接。RMII 是 `媒体独立接口 (MII) `_ 的标准简化版本。PHY 可在 10/100 Mbps 速率下支持 IEEE 802.3 / 802.3u 标准。 - * - RJ45 端口 - - 以太网数据传输端口。 - * - 网络变压器 - - 网络变压器属于以太网物理层的一部分，可保护电路，使其免受故障和电压瞬变影响，包括防止收发器芯片和线缆之间产生共模信号。同时它也可以在收发器与以太网设备之间提供电流隔绝。 - * - Link/Activity LED - - 2 个 LED（绿色和红色），可分别显示 PHY 处于 “Link” 状态或 “Activity” 状态。 - * - BOOT Button - - 下载按键。按下 **BOOT** 键并保持，同时按一下 **EN** 键（此时不要松开 **BOOT** 键）进入“固件下载”模式，通过串口下载固件。 - * - EN 按键 - - 复位按键。 - * - GPIO Header 1 - - 由 6 个未引出通孔组成，可连接至 ESP32 的备用 GPIO。具体介绍，请见 `GPIO Header 1`_。 - - -PoE 子板（B 板） -^^^^^^^^^^^^^^^^^^^ - -PoE 子板转换以太网电缆传输的电能 (PoE)，为以太网母板（A 板）提供电源。PoE 子板（B 板）的主要组件见 `功能概述`_ 中的功能框图。 - -PoE 子板（B 板）具有以下特性： - -* 支持 IEEE 802.3at 标准 -* 电源输出：5 V，1.4 A - -如需使用 PoE 功能，请用以太网线缆将以太网母板（A 板）上的 **RJ45 Port** 连接至 PoE 的交换机。以太网母板（A 板）检测到来自 PoE 子板（B 板）的 5 V 供电后，将从 USB 供电自动切换至 PoE 供电。 - -.. figure:: ../../_static/esp32-ethernet-kit-b-v1.0-layout.png - :align: center - :scale: 80% - :alt: ESP32-Ethernet-Kit - PoE board (B) - :figclass: align-center - - ESP32-Ethernet-Kit - PoE 子板（B 板）布局（点击放大） - -.. list-table:: 表格2 PoE 子板（B 板） - :widths: 40 150 - :header-rows: 1 - - * - 主要组件 - - 基本介绍 - * - A 板连接器 - - 4 个排针（左侧）和排母（右侧），用于将 PoE 子板（B 板）连接至 :ref:`Ethernet board (A) `。左侧的管脚接受来自 PoE 交换机的电源。右侧的管脚为 以太网母板（A 板）提供 5 V 电源。 - * - 外部电源终端 - - PoE 子板（B 板）可选电源 (26.6 ~ 54 V)。 - -.. _get-started-esp32-ethernet-kit-v1.1-setup-options: - - -设置选项 --------- - -本节介绍用于 ESP32-Ethernet-Kit 开发板的硬件配置选项。 - - -功能选择开关 -^^^^^^^^^^^^^^ - -拨码开关打开时，拨码开关将列出的 GPIO 路由到 FT2232H 以提供JTAG功能。拨码开关关闭时，GPIO 可以用于其他目的。 - -========= ========== -拨码开关 GPIO 管脚 -========= ========== - 1 GPIO13 - 2 GPIO12 - 3 GPIO15 - 4 GPIO14 -========= ========== - -.. note:: - - 拨码开关旁边开发板的丝印层上的 GPIO 管脚标记的位置是不正确的。请以表格中的顺序为准。 - - -RMII 时钟源选择 -^^^^^^^^^^^^^^^^ - -RMII 工作模式下的以太网 MAC 和 PHY 需要一个公共的 50MHz 同步时钟（即 RMII 时钟），它既可以由外部提供，也可以由内部的 ESP32 APLL 产生。 - -.. note:: - - 有关 RMII 时钟源选择的更多信息，请参见 `ESP32-Ethernet-Kit V1.1 以太网母板（A 板）原理图`_，第 2 页的位置 D2。 - - -PHY 侧提供 RMII 时钟 -""""""""""""""""""""""""""""" - -ESP32-Ethernet-Kit 默认配置为 IP101GRI 的 50M_CLKO 信号线提供 RMII 时钟，该时钟信号由 PHY 外侧连接的 25MHz 无源晶振经过倍频产生。详情请参见下图。 - -.. figure:: ../../_static/esp32-ethernet-kit-rmii-clk-from-phy.png - :align: center - :scale: 80% - :alt: RMII Clock from IP101GRI PHY - :figclass: align-center - - PHY 侧提供 RMII 时钟 - -请注意，系统上电时 RESET_N 旁的下拉电阻会将 PHY 置于复位状态，ESP32 需要通过 GPIO5 将 RESET_N 拉高才能启动 PHY，只有这样才能保证系统的正常上电，否则 ESP32 会存在一定几率进入下载模式（当 REF_CLK_50M 时钟信号在 GPIO0 上电采样阶段刚好处于高电平）。 - - -ESP32 APLL 内部提供的 RMII 时钟 -"""""""""""""""""""""""""""""""""""" - -另一种选择是从 ESP32 APLL 内部获取 RMII 时钟，请参见下图。来自 GPIO0 的时钟信号首先被反相，以解决传输线延迟的问题，然后提供给 PHY。 - -.. figure:: ../../_static/esp32-ethernet-kit-rmii-clk-to-phy.png - :align: center - :scale: 80% - :alt: RMII Clock from ESP Internal APLL - :figclass: align-center - - ESP32 APLL 内部提供的 RMII 时钟 - -要实现此选项，用户需要在板子上移除或添加一些阻容元器件。有关详细信息，请参见 `ESP32-Ethernet-Kit V1.1 以太网母板（A 板）原理图`_，第 2 页，位置 D2。请注意，如果 APLL 已经用于其他用途（如 I2S 外设），那么只能使用外部 RMII 时钟。 - - -GPIO 分配 ---------- - -本节介绍了 ESP32-Ethernet-Kit 开发板特定接口或功能的 GPIO 分配情况。 - - -IP101GRI (PHY) 接口 -^^^^^^^^^^^^^^^^^^^^^^^^^ - -下表显示了 ESP32 (MAC) 与 IP101GRI (PHY) 的管脚对应关系。ESP32-Ethernet-Kit 的实现默认设置为简化媒体独立接口。 - -==== ================ =============== -. ESP32 管脚 (MAC) IP101GRI (PHY) -==== ================ =============== -*RMII 接口* ---------------------------------------- - 1 GPIO21 TX_EN - 2 GPIO19 TXD[0] - 3 GPIO22 TXD[1] - 4 GPIO25 RXD[0] - 5 GPIO26 RXD[1] - 6 GPIO27 CRS_DV - 7 GPIO0 REF_CLK ----- ---------------- --------------- -*串行管理接口* ---------------------------------------- - 8 GPIO23 MDC - 9 GPIO18 MDIO ----- ---------------- --------------- -*PHY 复位* ---------------------------------------- -10 GPIO5 Reset_N -==== ================ =============== - -.. Note:: - - 除了 REF_CLK 之外，ESP32 的 *RMII 接口* 下的所有管脚分配都是固定的，不能通过 IOMUX 或 GPIO 矩阵进行更改。 - - -GPIO Header 1 -^^^^^^^^^^^^^ - -本连接器包括 ESP32-Ethernet-Kit 开发板上部分不用做他用的 GPIO。 - -==== ================ -. ESP32 管脚 -==== ================ - 1 GPIO32 - 2 GPIO33 - 3 GPIO34 - 4 GPIO35 - 5 GPIO36 - 6 GPIO39 -==== ================ - - -GPIO Header 2 -^^^^^^^^^^^^^ - -根据“说明"描述的不同情形，本连接器包含可用做他用的 GPIO。 - -==== ========== ==================== -. ESP32 管脚 说明 -==== ========== ==================== - 1 GPIO17 见下方说明 1 - 2 GPIO16 见下方说明 1 - 3 GPIO4 - 4 GPIO2 - 5 GPIO13 见下方说明 2 - 6 GPIO12 见下方说明 2 - 7 GPIO15 见下方说明 2 - 8 GPIO14 见下方说明 2 - 9 GND Ground -10 3V3 3.3 V 电源 -==== ========== ==================== - -.. note:: - - 1. ESP32 芯片的 GPIO16 和 GPIO17 管脚没有引出至 ESP32-WROVER-B 模组的管脚，因此无法使用。如需使用 ESP32 的 GP1016 和 GPIO17 管脚，建议更换其他不含 PSRAM 的模组，比如 ESP32-WROOM-32D 或 ESP32-SOLO-1。 - - - 2. 具体功能取决与 `功能选择开关`_ 的设置。 - - -GPIO 管脚分配总结 -^^^^^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: ESP32-WROVER-B,IP101GRI,UART,JTAG,GPIO,Comments - - S_VP,,,,IO36, - S_VN,,,,IO39, - IO34,,,,IO34, - IO35,,,,IO35, - IO32,,,,IO32, - IO33,,,,IO33, - IO25,RXD[0],,,, - IO26,RXD[1],,,, - IO27,CRS_DV,,,, - IO14,,,TMS,IO14, - IO12,,,TDI,IO12, - IO13,,RTS,TCK,IO13, - IO15,,CTS,TDO,IO15, - IO2,,,,IO2, - IO0,REF_CLK,,,,See note 1 - IO4,,,,IO4, - IO16,,,,IO16 (NC),See note 2 - IO17,,,,IO17 (NC),See note 2 - IO5,Reset_N,,,,See note 1 - IO18,MDIO,,,, - IO19,TXD[0],,,, - IO21,TX_EN,,,, - RXD0,,RXD,,, - TXD0,,TXD,,, - IO22,TXD[1],,,, - IO23,MDC,,,, - -.. note:: - - 1. 为防止 ESP32 侧 GPIO0 的上电状态受 PHY 侧时钟输出的影响，PHY 侧 RESET_N 默认为低，以关闭 PHY 侧时钟输出。上电后，您可通过 GPIO5 控制 RESET_N 以打开该时钟输出。参见 `PHY 侧提供 RMII 时钟`_。对于无法通过 RESET_N 关闭时钟输出的 PHY，PHY 侧建议使用可在外部禁用/使能的有源晶振。与使用 RESET_N 类似，默认情况下晶振模块应禁用，并在上电后由 ESP32 开启。有关参考设计，请参见 `ESP32-Ethernet-Kit V1.1 以太网母板（A 板）原理图`_。 - - - 2. ESP32 芯片的 GPIO16 和 GPIO17 管脚没有引出至 ESP32-WROVER-B 模组的管脚，因此无法使用。如需使用 ESP32 的 GP1016 和 GPIO17 管脚，建议更换其他不含 PSRAM 的模组，比如 ESP32-WROOM-32D 或 ESP32-SOLO-1。 - - -应用程序开发 -------------- - -ESP32-Ethernet-Kit 上电前，请首先确认开发板完好无损。 - - -初始设置 -^^^^^^^^^^ - -1. 首先，请将 :ref:`以太网母板（A 板）` 上的所有开关均拨至 **ON** 状态，使 **功能选择开关** 处于默认状态。 -2. 为了方便应用程序的下载和测试，不要为开发板输入任何信号。 -3. 此时可以连接 `PoE 子板（B 板）`_ ，但不要向 B 板连接任何外部电源。 -4. 使用 USB 数据线将 :ref:`以太网母板（A 板）` 连接至 PC。 -5. 将 **电源开关** 从 GND 拨至 5V0 一侧。此时，**5V Power On LED** 应点亮。 - - -正式开始开发 -^^^^^^^^^^^^^ - -现在，请前往 :doc:`../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 - -请务必在进入下一步前，确保您已完成上述所有步骤。 - - -配置与加载以太网示例 -^^^^^^^^^^^^^^^^^^^^^^^ - -在完成开发环境设置和开发板测试后，您可以配置并烧录 :example:`ethernet/ethernet` 示例。本示例专门用于测试以太网功能，支持不同 PHY，包括 :ref:`get-started-esp32-ethernet-kit-v1.1` 开发板使用的 **IP101GRI** 。 - - -针对 ESP32-Ethernet-Kit V1.0 的主要修改： ------------------------------------------ - -* 原 GPIO0 反相后时钟提供给 PHY 方案改为由 PHY 侧外接无源晶振，提供时钟给 GPIO0。原用于控制有源晶振的 OSC_EN 的 IO2 释放，可用作其他用途。 -* 为防止 ESP32 侧 GPIO0 的上电状态受到 PHY 侧时钟输出的影响，PHY 侧 RESET_N 默认为低，关闭 PHY 侧时钟输出。而后可通过 GPIO5 控制 RESET_N 打开该时钟输出。 -* 移除 FT2232H 芯片的外部 SPI Flash U6。 -* 移除流控的测试排针 J4。 -* 移除 nTRST JTAG信号，相应的 GPIO4 可用作其他用途。 -* GPIO15 线上的上拉电阻 R68 移至 JTAG 的 MTDO 侧。 -* 为了加强 A 板和 B 板连接间的防呆设计（减少反向插入 B 板的机会），将原先 A 板上的 2 排 4 针排针改为 1 排 4 针排母和 1 排 4 针排针。相应的 4 针排针排和排母排则安装在 B 板上。 - -ESP32-Ethernet-Kit 的其他版本 -------------------------------- - -* :doc:`get-started-ethernet-kit-v1.0` - - -相关文档 ----------- - -* `ESP32-Ethernet-Kit V1.1 以太网母板（A 板）原理图`_ (PDF) -* `ESP32-Ethernet-Kit V1.0 PoE 子板（B 板）原理图`_ (PDF) -* `ESP32 技术规格书 `_ (PDF) -* `ESP32-WROVER-B 技术规格书 `_ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* :doc:`../hw-reference/index` - -.. _ESP32-Ethernet-Kit V1.1 以太网母板（A 板）原理图: https://dl.espressif.com/dl/schematics/SCH_ESP32-ETHERNET-KIT_A_V1.1_20190711.pdf -.. _ESP32-Ethernet-Kit V1.0 PoE 子板（B 板）原理图: https://dl.espressif.com/dl/schematics/SCH_ESP32-ETHERNET-KIT_B_V1.0_20190517.pdf -.. _ESP32-Ethernet-Kit V1.0 以太网母板（A 板）原理图: https://dl.espressif.com/dl/schematics/SCH_ESP32-ETHERNET-KIT_A_V1.0_20190517.pdf - -.. toctree:: - :hidden: - - get-started-ethernet-kit-v1.0.rst \ No newline at end of file diff --git a/docs/zh_CN/hw-reference/index.rst b/docs/zh_CN/hw-reference/index.rst index 5aab701a27..4f22477b92 100644 --- a/docs/zh_CN/hw-reference/index.rst +++ b/docs/zh_CN/hw-reference/index.rst @@ -9,7 +9,7 @@ ESP32 H/W 硬件参考 :esp32: ESP32 技术参考手册 (PDF) :esp32s2beta: ESP32-S2 技术参考手册 (PDF) :esp32: ESP32 技术规格书 (PDF) - :esp32s2beta: ESP32-S2 技术规格书 (PDF) + :esp32s2: ESP32-S2 技术规格书 (PDF) :esp32: ESP32 硬件设计指南 (PDF) :esp32: ESP32 勘误表及解决方法 (PDF) 模组与开发板 diff --git a/docs/zh_CN/hw-reference/modules-and-boards-previous.rst b/docs/zh_CN/hw-reference/modules-and-boards-previous.rst index 30e33d94c9..844cdaa9c1 100644 --- a/docs/zh_CN/hw-reference/modules-and-boards-previous.rst +++ b/docs/zh_CN/hw-reference/modules-and-boards-previous.rst @@ -1 +1,24 @@ -.. include:: ../../en/hw-reference/modules-and-boards-previous.rst \ No newline at end of file +.. _esp-modules-and-boards-previous: + +************************************** +{IDF_TARGET_NAME} 模组与开发板（历史版本） +************************************** + +This sections contains overview and links to documentation of previous version {IDF_TARGET_NAME} Modules and Boards that have been replaced with newer versions or discontinued. It is maintained for convenience of users as previous versions of some modules and boards are still in use and some may still be available for purchase. + + +.. only:: esp32 + + .. include:: esp32/inc/modules-and-boards-previous-esp32.rst + +.. only:: esp32s2 + + .. include:: esp32s2/inc/modules-and-boards-previous-esp32s2.rst + +相关文档 +================= + +* :doc:`modules-and-boards` + + +.. _FTDI Virtual COM Port Drivers: http://www.ftdichip.com/Drivers/VCP.htm \ No newline at end of file diff --git a/docs/zh_CN/hw-reference/modules-and-boards.rst b/docs/zh_CN/hw-reference/modules-and-boards.rst index b1843052ee..0e39727776 100644 --- a/docs/zh_CN/hw-reference/modules-and-boards.rst +++ b/docs/zh_CN/hw-reference/modules-and-boards.rst @@ -1,12 +1,12 @@ .. _esp-modules-and-boards: -***************************** -ESP32 系列模组和开发板 -***************************** +******************************** +{IDF_TARGET_NAME} 系列模组和开发板 +******************************** :link_to_translation:`en:[English]` -乐鑫设计并提供多种模组和开发板以供用户体验 ESP32 系列芯片的强大功能。 +乐鑫设计并提供多种模组和开发板以供用户体验 {IDF_TARGET_NAME} 系列芯片的强大功能。 本文档主要介绍了当前乐鑫所提供的各种模组和开发板。 @@ -14,297 +14,16 @@ ESP32 系列模组和开发板 如需了解较早版本或已停产的模组和开发板，请参考 :ref:`esp-modules-and-boards-previous`。 -.. _esp-wroom-solo-wrover-modules: +.. only:: esp32 -WROOM、SOLO、WROVER 和 PICO 系列模组 -===================================== + .. include:: esp32/inc/modules-and-boards-esp32.rst -WROOM、SOLO、WROVER 和 PICO 系列模组内置 ESP32 芯片并集成了晶振、天线匹配电路等重要组件，可直接集成到终端产品中。如果再结合一些其他组件，例如编程接口、Bootstrapping 电阻和排针，您就可以体验 ESP32 的强大功能了。 +.. only:: esp32s2 -下表总结了上述系列模组的主要特点，详细信息见后续章节。 - -+---------------------+--------------+-------------+-------------+------+-----------------+ -| 模组 | 芯片 | Flash (MB) | PSRAM (MB) | 天线 | 尺寸 (mm) | -+---------------------+--------------+-------------+-------------+------+-----------------+ -| ESP32-WROOM-32 | ESP32-D0WDQ6 | 4 | – | MIFA | 18 × 25.5 × 3.1 | -+---------------------+--------------+-------------+-------------+------+-----------------+ -| ESP32-WROOM-32D | ESP32-D0WD | 4、8 或 16 | – | MIFA | 18 × 25.5 × 3.1 | -+---------------------+--------------+-------------+-------------+------+-----------------+ -| ESP32-WROOM-32U | ESP32-D0WD | 4、8 或 16 | – | U.FL | 18 × 19.2 × 3.1 | -+---------------------+--------------+-------------+-------------+------+-----------------+ -| ESP32-SOLO-1 | ESP32-S0WD | 4 | – | MIFA | 18 × 25.5 × 3.1 | -+---------------------+--------------+-------------+-------------+------+-----------------+ -| ESP32-WROVER (PCB) | ESP32-D0WDQ6 | 4 | 8 | MIFA | 18 × 31.4 × 3.3 | -+---------------------+--------------+-------------+-------------+------+-----------------+ -| ESP32-WROVER (IPEX) | ESP32-D0WDQ6 | 4 | 8 | U.FL | 18 × 31.4 × 3.3 | -+---------------------+--------------+-------------+-------------+------+-----------------+ -| ESP32-WROVER-B | ESP32-D0WD | 4、8 或 16 | 8 | MIFA | 18 × 31.4 × 3.3 | -+---------------------+--------------+-------------+-------------+------+-----------------+ -| ESP32-WROVER-IB | ESP32-D0WD | 4、8 或 16 | 8 | U.FL | 18 × 31.4 × 3.3 | -+---------------------+--------------+-------------+-------------+------+-----------------+ - - -* ESP32-**D**.. 代表双核芯片，ESP32-**S**.. 代表单核芯片； -* MIFA - 蛇形倒 F 天线； -* U.FL - U.FL/IPEX 天线连接器； -* ESP32-WROOM-32x、ESP32-WROVER-B 和 ESP32-WROVER-IB 模组默认内置 4 MB flash，客户可定制 8 MB 和 16 MB flash，详情见 `乐鑫产品订购信息`_ (PDF) 和《`ESP32 技术规格书 `_》(PDF)； -* 最初发布的 ESP32-WROVER 模组内置 4 MB PSRAM； -* *ESP-WROOM-32* 是 *ESP32-WROOM-32* 的曾用名。 - -.. _esp-modules-and-boards-esp32-wroom-32: - -ESP32-WROOM-32 模组 --------------------- - -ESP32-WROOM-32 模组是 WROOM/WROVER 系列最先发布的模组，内置 ESP32-D0WDQ6 芯片，是一款基础且常用的 ESP32 模组。 - -有关该模组的详细信息，请查看 :ref:`esp-wroom-solo-wrover-modules` 章节中的表格。 - -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32-front-back.jpg - :align: center - :alt: ESP32-WROOM-32 module (front and back) - :width: 45% - - ESP32-WROOM-32 模组（正反面图） - -相关文档 -^^^^^^^^^^^^^ - -* 《`ESP32-WROOM-32 技术规格书 `_》(PDF)； -* `ESP32-WROOM-32 参考设计 `_，包括原理图（由 OrCAD Capture 绘制）、PCB 布局（由 Mentor PADS 绘制）、GERBER 文件和 BOM 清单。 - -.. _esp-modules-and-boards-esp32-wroom-32d-and-u: - -ESP32-WROOM-32D/ESP32-WROOM-32U 模组 --------------------------------------- - -两款模组均集成了 ESP32-D0WD 芯片，与 :ref:`esp-modules-and-boards-esp32-wroom-32` 集成的 ESP32-D0WDQ6 相比，ESP32-D0WD 芯片的封装更小，在 PCB 上占用的面积更小。 - -有关这两款模组的详细信息，请查看 :ref:`esp-wroom-solo-wrover-modules` 中的表格和 `乐鑫产品订购信息`_。 - -ESP32-WROOM-32U 是整个 WROOM/WROVER 模组系列中最小的模组。 - -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32d-front-back.jpg - :align: center - :alt: ESP32-WROOM-32D module (front and back) - :width: 45% - - ESP32-WROOM-32D 模组（正反面图） - -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wroom-32u-front-back.jpg - :align: center - :alt: ESP32-WROOM-32U module (front and back) - :width: 45% - - ESP32-WROOM-32U 模组（正反面图） - -相关文档 -^^^^^^^^^^^^^ - -* 《`ESP32-WROOM-32D/ESP32-WROOM-32U 技术规格书 `_》(PDF) - - -.. _esp-modules-and-boards-esp32-solo-1: - -ESP32-SOLO-1 模组 ------------------ - -ESP32-SOLO-1 模组是 ESP32-WROOM-32D 模组的简化版本，内置一个 ESP32 单核芯片，支持高达 160 MHz 的时钟频率。 - -有关此模组的详细信息，请查看 :ref:`esp-wroom-solo-wrover-modules` 章节中的表格和 `乐鑫产品订购信息`_。 - -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-solo-1-front-back.jpg - :align: center - :alt: ESP32-SOLO-1 module (front and back) - :width: 45% - - ESP32-SOLO-1 模组（正反面图） - -相关文档 -^^^^^^^^^^^^^ - -* 《`ESP32-SOLO-1 技术规格书 `__》(PDF) - -.. _esp-modules-and-boards-esp32-wrover: - -ESP32-WROVER 系列模组 -------------------------- - -ESP32-WROVER 系列模组在 ESP32-WROOM-32x 模组的基础上进行了一些修改，其中包含一些功能升级，并新增 8 MB SPI PSRAM（伪静态 RAM）。 - -有关该模组的详细信息，请查看 :ref:`esp-wroom-solo-wrover-modules` 章节中的表格和 `乐鑫产品订购信息`_。 - -* **ESP32-WROVER (PCB)** 模组和 **ESP32-WROVER (IPEX)** 模组内置 1.8 V PSRAM，支持 144 MHz 时钟频率。 -* **ESP32-WROVER-B** 模组和 **ESP32-WROVER-IB** 模组内置 3.3 V PSRAM，支持 133 MHz 时钟频率。 - -下图为配备有 PCB 天线的 ESP32-WROVER 模组： - -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-wrover.jpg - :align: center - :alt: ESP32-WROVER module (front and back) - :width: 40% - - ESP32-WROVER 模组（正反面图） - -相关文档 -^^^^^^^^^^^^^ - -* 《`ESP32-WROVER 技术规格书 `__》(PDF) -* 《`ESP32-WROVER-B 技术规格书 `__》(PDF) -* 《`ESP-PSRAM64 & ESP-PSRAM64H 技术规格书 `__》(PDF) -* `ESP32-WROVER 参考设计 `_ 包含原理图（由 OrCAD Capture 绘制）、PCB 布局（由 Mentor PADS 绘制）、GERBER 文件和 BOM 清单。 - -ESP32-PICO-D4 模组 ------------------- - -ESP32-PICO-D4 模组是一款 SiP 模组，无缝集成了所有外设，包括： - -- 4 MB flash -- 晶振 -- 滤波电容 -- RF 匹配电路 - -有关该模组的详细信息，请查看 `乐鑫产品订购信息`_。 - -相关文档 -^^^^^^^^^^^^^ - -* 《`ESP32-PICO-D4 技术规格书 `__》(PDF) - -ESP32 开发板 -================== - -ESP32 系列开发板功能各异，具体有以下不同点： - -- 访问的 ESP32 GPIO 管脚不同； -- 接口不同，包括 USB 和 JTAG； -- 外设不同，包括 TouchPad、LCD 显示屏、SD 卡槽和相机模组排母等。 - -.. _esp-modules-and-boards-esp32-pico-kit: - -ESP32-PICO-KIT V4.1 开发板 ---------------------------- -ESP32-PICO-KIT V4.1 开发板是基于 ESP32 的最小开发板，内置连接至电脑 USB 端口所需的所有组件，同时设有排针，可直接将此开发板插接于迷你面包板。 - -ESP32-PICO-KIT V4.1 开发板集成了 `ESP32-PICO-D4 模组`_，只需在 PCB (20 x 52 mm) 上添加少许外部组件即可构成一个功能齐全的开发板。这部分外部组件包括天线、LDO、USB 至 UART 桥接器、一个重置按钮和一个固件下载模式激活按钮。 - - -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-pico-kit-v4.1.jpg - :align: center - :alt: ESP32-PICO-KIT V4.1 board - :width: 50% - - ESP32-PICO-KIT V4.1 开发板 - -与 ESP32-PICO-KIT V4 相比，ESP32-PICO-KIT V4.1 开发板支持 CP2102N USB 至 UART 桥接器，可提供高达 3 Mbps 的传输速率。 - -相关文档 -^^^^^^^^^^^^^ - -* :doc:`../hw-reference/get-started-pico-kit` -* `ESP32-PICO-KIT V4.1 原理图 `_ (PDF) -* `ESP32-PICO-KIT 参考设计 `_，包含原理图（由 OrCAD Capture 绘制）、PCB 布局（由 Mentor PADS 绘制）、GERBER 文件和 BOM 清单。 -* 《`ESP32-PICO-D4 技术规格书 `_》(PDF) - -较早版本开发板 -^^^^^^^^^^^^^^^^^ - -* :ref:`esp-modules-and-boards-esp32-pico-kit-v4` -* :ref:`esp-modules-and-boards-esp32-pico-kit-v3` - - -.. _esp-modules-and-boards-esp32-devkitc: - -ESP32 DevKitC V4 开发板 ------------------------------- - -ESP32 DevKitC V4 开发板是一款小巧实用的开发板，具备以下特色功能： - -- 集成了 :ref:`esp-modules-and-boards-esp32-wroom-32` -- USB 转串口编程接口同时可为开发板供电 -- 设有排针 -- 设有重置按钮和固件下载模式激活按钮 -- 以及其他组件 - -与较早版本的 :ref:`esp-modules-and-boards-esp32-devkitc-v2` 相比，ESP32 DevKitC V4 开发板集成了 :ref:`esp-modules-and-boards-esp32-wrover` （而非 ESP32-WROOM-32 模组），同时内置 CP2102N 芯片，支持更高波特率。 - -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-devkitc-v4-front.jpg - :align: center - :alt: ESP32 DevKitC V4 board - :width: 50% - - ESP32 DevKitC V4 开发板 - -相关文档 -^^^^^^^^^^^^^ - -* :doc:`../hw-reference/get-started-devkitc` -* `ESP32-DevKitC 原理图 `_ (PDF) -* `ESP32-DevKitC 参考设计 `_，包含原理图（由 OrCAD Capture 绘制）、PCB 布局（由 Mentor PADS 绘制）、GERBER 文件和 BOM 清单。 -* `CP210x USB 至 UART 桥 VCP 驱动器 `_ - -较早版本开发板 -^^^^^^^^^^^^^^^^^ - -* :ref:`esp-modules-and-boards-esp32-devkitc-v2` - - -.. _esp-modules-and-boards-esp-wrover-kit: - -ESP-WROVER-KIT V4.1 开发板 -------------------------------- - -ESP-WROVER-KIT V4.1 开发板具备以下特色功能： - -- USB 转双串口转换器（用于后续编程） -- JTAG 调试接口 -- MicroSD 卡槽 -- 3.2” SPI LCD 显示屏 -- 相机模组排母 -- RGB 发光二极管 -- 支持 32.768 kHz 晶振输入用于 RTC 及低功耗模式操作 - -ESP-WROVER-KIT V4.1 开发板支持 USB 供电或标准的 5 毫米电源插座供电，可使用跳线选择电源，或使用独立的开关控制电源。 - -ESP-WROVER-KIT V4.1 开发板集成了 ESP-WROVER-B 模组，该模组集成了 8 MB PSRAM，方便用户灵活扩展存储空间，增强数据处理能力。ESP-WROVER-KIT V4.1 开发板还可以集成 :ref:`esp-wroom-solo-wrover-modules` 中所述的 ESP 其他版本模组。 - -与 :ref:`esp-modules-and-boards-esp-wrover-kit-v3` 相比，ESP-WROVER-KIT V4.1 开发板在设计上有以下改动： - -- JP8、JP11 和 JP13 合并成了一个 JP2。 -- USB 连接器的固定脚改为直插式，并移至板子右下角。 -- R61 已变更为零欧姆电阻。 -- 基于测试结果和采购选择，部分组件已由功能对等组件替代，例如 EN 和 Boot 按钮。 - -.. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-wrover-kit-v4.1-front.jpg - :align: center - :alt: ESP-WROVER-KIT V4.1 board - :width: 90% - - ESP-WROVER-KIT V4.1 开发板 - -上图所示开发板集成了 ESP32-WROVER-B 模组。 - -相关文档 -^^^^^^^^^^^^^ - -* :doc:`../hw-reference/get-started-wrover-kit` -* `ESP-WROVER-KIT V4.1 原理图 `__ (PDF) -* :doc:`../api-guides/jtag-debugging/index` -* `FTDI 虚拟 COM 端口驱动`_ - -较早版本开发板 -^^^^^^^^^^^^^^^^^ - -* :ref:`esp-modules-and-boards-esp-wrover-kit-v3` -* :ref:`esp-modules-and-boards-esp-wrover-kit-v2` -* :ref:`esp-modules-and-boards-esp-wrover-kit-v1` + .. include:: esp32s2/inc/modules-and-boards-esp32s2.rst 相关文档 ================= * :doc:`modules-and-boards-previous` - - -.. _FTDI 虚拟 COM 端口驱动: http://www.ftdichip.com/Drivers/VCP.htm -.. _乐鑫产品订购信息: https://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_cn.pdf From 83521dbc51d8e26e97c644b4384a43e9b5650af7 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Fri, 13 Dec 2019 10:48:21 +0800 Subject: [PATCH 22/47] doc: Include paths for chip specific headers now depend on target Input for Doxygen now depend on idf_target for some paths, updated path name generated in run_doxygen.py to show the target dependent path. --- docs/Doxyfile | 8 ++++---- docs/idf_extensions/run_doxygen.py | 8 ++++++-- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 6ff8d2f76a..b642f6033c 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -217,7 +217,7 @@ INPUT = \ ## Himem $(IDF_PATH)/components/esp32/include/esp32/himem.h \ ## Interrupt Allocation - $(IDF_PATH)/components/esp32/include/esp_intr_alloc.h \ + $(IDF_PATH)/components/$(IDF_TARGET)/include/esp_intr_alloc.h \ ## Watchdogs ## NOTE: for two lines below header_file.inc is not used $(IDF_PATH)/components/esp_common/include/esp_int_wdt.h \ @@ -233,7 +233,7 @@ INPUT = \ ## ESP HTTPS OTA $(IDF_PATH)/components/esp_https_ota/include/esp_https_ota.h \ ## Sleep - $(IDF_PATH)/components/esp32/include/esp_sleep.h \ + $(IDF_PATH)/components/$(IDF_TARGET)/include/esp_sleep.h \ ## Logging $(IDF_PATH)/components/log/include/esp_log.h \ ## Base MAC address @@ -245,7 +245,7 @@ INPUT = \ ## ULP Coprocessor - API Guides ## ## NOTE: for line below header_file.inc is not used - $(IDF_PATH)/components/ulp/include/esp32/ulp.h \ + $(IDF_PATH)/components/ulp/include/$(IDF_TARGET)/ulp.h \ $(IDF_PATH)/components/ulp/include/ulp_common.h \ ## ## Application Level Tracing - API Reference @@ -254,7 +254,7 @@ INPUT = \ $(IDF_PATH)/components/app_trace/include/esp_sysview_trace.h \ ### Power management $(IDF_PATH)/components/esp_common/include/esp_pm.h \ - $(IDF_PATH)/components/esp32/include/esp32/pm.h \ + $(IDF_PATH)/components/$(IDF_TARGET)/include/$(IDF_TARGET)/pm.h \ ### esp_timer, High Resolution Timer $(IDF_PATH)/components/esp_timer/include/esp_timer.h \ ### esp_event, Event Loop Library diff --git a/docs/idf_extensions/run_doxygen.py b/docs/idf_extensions/run_doxygen.py index b14c5c747d..7c3a6d21a8 100644 --- a/docs/idf_extensions/run_doxygen.py +++ b/docs/idf_extensions/run_doxygen.py @@ -99,7 +99,7 @@ def convert_api_xml_to_inc(app, doxyfile): if not os.path.exists(inc_directory_path): os.makedirs(inc_directory_path) - header_paths = get_doxyfile_input_paths(doxyfile) + header_paths = get_doxyfile_input_paths(app, doxyfile) print("Generating 'api_name.inc' files with Doxygen directives") for header_file_path in header_paths: api_name = get_api_name(header_file_path) @@ -116,7 +116,7 @@ def convert_api_xml_to_inc(app, doxyfile): inc_file.write(rst_output) -def get_doxyfile_input_paths(doxyfile_path): +def get_doxyfile_input_paths(app, doxyfile_path): """Get contents of Doxyfile's INPUT statement. Returns: @@ -148,6 +148,10 @@ def get_doxyfile_input_paths(doxyfile_path): # extract header file path inside components folder m = re.search("components/(.*\.h)", line) # noqa: W605 - regular expression header_file_path = m.group(1) + + # Replace env variable used for multi target header + header_file_path = header_file_path.replace("$(IDF_TARGET)", app.config.idf_target) + doxyfile_INPUT.append(header_file_path) # proceed reading next line From 46dab1b4e8dfa5e063b5d860c4498149f0c67330 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Fri, 13 Dec 2019 11:22:44 +0800 Subject: [PATCH 23/47] doc: removed reference to idf_target in core dump title --- docs/en/api-guides/core_dump.rst | 4 ++-- docs/en/api-guides/index.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/en/api-guides/core_dump.rst b/docs/en/api-guides/core_dump.rst index 8a6c0427e6..0b14acd53a 100644 --- a/docs/en/api-guides/core_dump.rst +++ b/docs/en/api-guides/core_dump.rst @@ -1,5 +1,5 @@ -{IDF_TARGET_NAME} Core Dump -=========================== +Core Dump +========= Overview -------- diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index d71d81ed89..a6f3a495b5 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -15,7 +15,7 @@ API Guides Error Handling :esp32: ESP-BLE-MESH ESP-MESH (Wi-Fi) - {IDF_TARGET_NAME} Core Dump + Core Dump Event Handling External SPI-connected RAM Fatal Errors From 105567d0777ded8f8aec63c5001c851622b8c419 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Fri, 13 Dec 2019 11:49:10 +0800 Subject: [PATCH 24/47] doc: updated peripherals api-reference for s2 --- docs/Doxyfile | 3 +- docs/build_docs.py | 1 - docs/en/api-reference/peripherals/adc.rst | 69 +++++---- docs/en/api-reference/peripherals/can.rst | 26 ++-- docs/en/api-reference/peripherals/dac.rst | 15 +- .../peripherals/esp_slave_protocol.rst | 6 + docs/en/api-reference/peripherals/gpio.rst | 4 +- docs/en/api-reference/peripherals/i2s.rst | 8 +- docs/en/api-reference/peripherals/ledc.rst | 23 ++- docs/en/api-reference/peripherals/mcpwm.rst | 17 +-- docs/en/api-reference/peripherals/pcnt.rst | 13 +- docs/en/api-reference/peripherals/rmt.rst | 22 ++- .../peripherals/sd_pullup_requirements.rst | 131 +++++++++++------- .../api-reference/peripherals/sdio_slave.rst | 22 ++- .../api-reference/peripherals/sdmmc_host.rst | 79 ++++++----- .../api-reference/peripherals/sdspi_host.rst | 4 +- .../api-reference/peripherals/sigmadelta.rst | 4 +- .../api-reference/peripherals/spi_master.rst | 95 +++++++------ .../api-reference/peripherals/spi_slave.rst | 87 +++++++----- .../api-reference/peripherals/temp_sensor.rst | 38 +++-- docs/en/api-reference/peripherals/timer.rst | 11 +- .../api-reference/peripherals/touch_pad.rst | 109 ++++++++++----- docs/en/api-reference/peripherals/uart.rst | 59 +++++--- docs/en/contribute/add-ons-reference.rst | 6 +- 24 files changed, 526 insertions(+), 326 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index b642f6033c..a079a36098 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -103,9 +103,10 @@ INPUT = \ $(IDF_PATH)/components/driver/include/driver/spi_common.h \ $(IDF_PATH)/components/driver/include/driver/spi_master.h \ $(IDF_PATH)/components/driver/include/driver/spi_slave.h \ + $(IDF_PATH)/components/driver/$(IDF_TARGET)/include/touch_sensor.h \ $(IDF_PATH)/components/driver/esp32s2/include/temp_sensor.h \ $(IDF_PATH)/components/driver/include/driver/timer.h \ - $(IDF_PATH)/components/driver/include/driver/touch_pad.h \ + $(IDF_PATH)/components/driver/include/driver/touch_sensor_common.h \ $(IDF_PATH)/components/driver/include/driver/uart.h \ $(IDF_PATH)/components/esp_adc_cal/include/esp_adc_cal.h \ $(IDF_PATH)/components/soc/include/hal/rmt_types.h \ diff --git a/docs/build_docs.py b/docs/build_docs.py index be354fa4c3..014d36b741 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -57,7 +57,6 @@ def main(): build_dir = os.path.realpath(os.path.join(args.build_dir, language, target)) build_docs(language, target, build_dir) - def build_docs(language, target, build_dir): print("Building language:%s target:%s build_dir:%s" % (language, target, build_dir)) try: diff --git a/docs/en/api-reference/peripherals/adc.rst b/docs/en/api-reference/peripherals/adc.rst index 3fc65869b7..b81a6747fd 100644 --- a/docs/en/api-reference/peripherals/adc.rst +++ b/docs/en/api-reference/peripherals/adc.rst @@ -1,14 +1,17 @@ Analog to Digital Converter =========================== +{IDF_TARGET_ADC1_CH0: default="GPIO 0", esp32="GPIO 36"} +{IDF_TARGET_ADC2_CH7: default="GPIO 0", esp32="GPIO 27"} + + Overview -------- -The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register `_) ADCs supporting a total of 18 measurement channels (analog enabled pins). - - .. only:: esp32 + The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register `_) ADCs supporting a total of 18 measurement channels (analog enabled pins). + The ADC driver API supports ADC1 (8 channels, attached to GPIOs 32 - 39), and ADC2 (10 channels, attached to GPIOs 0, 2, 4, 12 - 15 and 25 - 27). However, the usage of ADC2 has some restrictions for the application: 1. ADC2 is used by the Wi-Fi driver. Therefore the application can only use ADC2 when the Wi-Fi driver has not started. @@ -17,6 +20,14 @@ The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Regis - :ref:`ESP32 DevKitC `: GPIO 0 cannot be used due to external auto program circuits. - :ref:`ESP-WROVER-KIT `: GPIO 0, 2, 4 and 15 cannot be used due to external connections for different purposes. +.. only:: esp32s2 + + The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register `_) ADCs supporting a total of 20 measurement channels (analog enabled pins). + + The ADC driver API supports ADC1 (10 channels, attached to GPIOs 1 - 10), and ADC2 (10 channels, attached to GPIOs 11 - 20). However, the usage of ADC2 has some restrictions for the application: + + 1. ADC2 is used by the Wi-Fi driver. Therefore the application can only use ADC2 when the Wi-Fi driver has not started. + Configuration and Reading ADC ----------------------------- @@ -31,7 +42,9 @@ Then it is possible to read ADC conversion result with :cpp:func:`adc1_get_raw` .. note:: Since the ADC2 is shared with the WIFI module, which has higher priority, reading operation of :cpp:func:`adc2_get_raw` will fail between :cpp:func:`esp_wifi_start()` and :cpp:func:`esp_wifi_stop()`. Use the return code to see whether the reading is successful. -It is also possible to read the internal hall effect sensor via ADC1 by calling dedicated function :cpp:func:`hall_sensor_read`. Note that even the hall sensor is internal to ESP32, reading from it uses channels 0 and 3 of ADC1 (GPIO 36 and 39). Do not connect anything else to these pins and do not change their configuration. Otherwise it may affect the measurement of low value signal from the sensor. +.. only:: esp32 + + It is also possible to read the internal hall effect sensor via ADC1 by calling dedicated function :cpp:func:`hall_sensor_read`. Note that even the hall sensor is internal to ESP32, reading from it uses channels 0 and 3 of ADC1 (GPIO 36 and 39). Do not connect anything else to these pins and do not change their configuration. Otherwise it may affect the measurement of low value signal from the sensor. This API provides convenient way to configure ADC1 for reading from :doc:`ULP <../../api-guides/ulp>`. To do so, call function :cpp:func:`adc1_ulp_enable` and then set precision and attenuation as discussed above. @@ -40,7 +53,7 @@ There is another specific function :cpp:func:`adc2_vref_to_gpio` used to route i Application Examples -------------------- -Reading voltage on ADC1 channel 0 (GPIO 36):: +Reading voltage on ADC1 channel 0 ({IDF_TARGET_ADC1_CH0}):: #include @@ -53,7 +66,7 @@ Reading voltage on ADC1 channel 0 (GPIO 36):: The input voltage in above example is from 0 to 1.1V (0 dB attenuation). The input range can be extended by setting higher attenuation, see :cpp:type:`adc_atten_t`. An example using the ADC driver including calibration (discussed below) is available in esp-idf: :example:`peripherals/adc` -Reading voltage on ADC2 channel 7 (GPIO 27):: +Reading voltage on ADC2 channel 7 ({IDF_TARGET_ADC2_CH7}):: #include @@ -72,14 +85,16 @@ Reading voltage on ADC2 channel 7 (GPIO 27):: The reading may fail due to collision with Wi-Fi, should check it. An example using the ADC2 driver to read the output of DAC is available in esp-idf: :example:`peripherals/adc2` -Reading the internal hall effect sensor:: +.. only: esp32 - #include + Reading the internal hall effect sensor:: - ... + #include - adc1_config_width(ADC_WIDTH_BIT_12); - int val = hall_sensor_read(); + ... + + adc1_config_width(ADC_WIDTH_BIT_12); + int val = hall_sensor_read(); @@ -132,32 +147,32 @@ Calibration values are used to generate characteristic curves that account for t ESP32 Chip Surface Marking -If you would like to purchase chips or modules with calibration, double check with distributor or Espressif directly. + If you would like to purchase chips or modules with calibration, double check with distributor or Espressif directly. -.. highlight:: none + .. highlight:: none -If you are unable to check the date code (i.e. the chip may be enclosed inside a canned module, etc.), you can still verify if **eFuse Vref** is present by running `espefuse.py `_ tool with ``adc_info`` parameter :: + If you are unable to check the date code (i.e. the chip may be enclosed inside a canned module, etc.), you can still verify if **eFuse Vref** is present by running `espefuse.py `_ tool with ``adc_info`` parameter :: - $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 adc_info + $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 adc_info -Replace ``/dev/ttyUSB0`` with {IDF_TARGET_NAME} board's port name. + Replace ``/dev/ttyUSB0`` with {IDF_TARGET_NAME} board's port name. -A chip that has specific **eFuse Vref** value programmed (in this case 1093mV) will be reported as follows:: + A chip that has specific **eFuse Vref** value programmed (in this case 1093mV) will be reported as follows:: - ADC VRef calibration: 1093mV + ADC VRef calibration: 1093mV -In another example below the **eFuse Vref** is not programmed:: + In another example below the **eFuse Vref** is not programmed:: - ADC VRef calibration: None (1100mV nominal) + ADC VRef calibration: None (1100mV nominal) -For a chip with two point calibration the message will look similar to:: + For a chip with two point calibration the message will look similar to:: - ADC VRef calibration: 1149mV - ADC readings stored in efuse BLK3: - ADC1 Low reading (150mV): 306 - ADC1 High reading (850mV): 3153 - ADC2 Low reading (150mV): 389 - ADC2 High reading (850mV): 3206 + ADC VRef calibration: 1149mV + ADC readings stored in efuse BLK3: + ADC1 Low reading (150mV): 306 + ADC1 High reading (850mV): 3153 + ADC2 Low reading (150mV): 389 + ADC2 High reading (850mV): 3206 Application Example ^^^^^^^^^^^^^^^^^^^ diff --git a/docs/en/api-reference/peripherals/can.rst b/docs/en/api-reference/peripherals/can.rst index bb63366d91..c371a7d9fb 100644 --- a/docs/en/api-reference/peripherals/can.rst +++ b/docs/en/api-reference/peripherals/can.rst @@ -6,22 +6,30 @@ Controller Area Network (CAN) Overview -------- -The {IDF_TARGET_NAME}'s peripherals contains a CAN Controller that supports Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID) of the CAN2.0B specification. +.. only:: esp32s2 -.. warning:: - The {IDF_TARGET_NAME} CAN controller is not compatible with CAN FD frames and will interpret such frames as errors. + .. note:: -This programming guide is split into the following sections: + The CAN driver is not updated for {IDF_TARGET_NAME} and is temporarily disabled. - 1. :ref:`basic-can-concepts` +.. only:: esp32 - 2. :ref:`signals-lines-and-transceiver` + The {IDF_TARGET_NAME}'s peripherals contains a CAN Controller that supports Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID) of the CAN2.0B specification. - 3. :ref:`configuration` + .. warning:: + The {IDF_TARGET_NAME} CAN controller is not compatible with CAN FD frames and will interpret such frames as errors. - 4. :ref:`driver-operation` + This programming guide is split into the following sections: - 5. :ref:`examples` + 1. :ref:`basic-can-concepts` + + 2. :ref:`signals-lines-and-transceiver` + + 3. :ref:`configuration` + + 4. :ref:`driver-operation` + + 5. :ref:`examples` .. --------------------------- Basic CAN Concepts ------------------------------ diff --git a/docs/en/api-reference/peripherals/dac.rst b/docs/en/api-reference/peripherals/dac.rst index e9496f0ec0..d8fbd55e17 100644 --- a/docs/en/api-reference/peripherals/dac.rst +++ b/docs/en/api-reference/peripherals/dac.rst @@ -1,16 +1,15 @@ Digital To Analog Converter =========================== +{IDF_TARGET_DAC_CH_1: default = "GPIO25", esp32 = "GPIO25", esp32s2 = "GPIO17"} +{IDF_TARGET_DAC_CH_2: default = "GPIO26", esp32 = "GPIO26", esp32s2 = "GPIO18"} + Overview -------- -.. only:: esp32 +{IDF_TARGET_NAME} has two 8-bit DAC (digital to analog converter) channels, connected to {IDF_TARGET_DAC_CH_1} (Channel 1) and {IDF_TARGET_DAC_CH_2} (Channel 2). - {IDF_TARGET_NAME} has two 8-bit DAC (digital to analog converter) channels, connected to GPIO25 (Channel 1) and GPIO26 (Channel 2). -.. only:: esp32s2beta - - {IDF_TARGET_NAME} has two 8-bit DAC (digital to analog converter) channels, connected to GPIO17 (Channel 1) and GPIO18 (Channel 2). The DAC driver allows these channels to be set to arbitrary voltages. @@ -22,7 +21,7 @@ For other analog output options, see the :doc:`Sigma-delta Modulation module @@ -41,7 +40,7 @@ GPIO Lookup Macros Some useful macros can be used to specified the GPIO number of a DAC channel, or vice versa. e.g. -1. ``DAC_CHANNEL_1_GPIO_NUM`` is the GPIO number of channel 1 (25); -2. ``DAC_GPIO26_CHANNEL`` is the channel number of GPIO 26 (channel 2). +1. ``DAC_CHANNEL_1_GPIO_NUM`` is the GPIO number of channel 1 ({IDF_TARGET_DAC_CH_1}); +2. ``DAC_{IDF_TARGET_DAC_CH_2}_CHANNEL`` is the channel number of GPIO 26 (channel 2). .. include-build-file:: inc/dac_channel.inc diff --git a/docs/en/api-reference/peripherals/esp_slave_protocol.rst b/docs/en/api-reference/peripherals/esp_slave_protocol.rst index c0650a9660..2e1b5e615a 100644 --- a/docs/en/api-reference/peripherals/esp_slave_protocol.rst +++ b/docs/en/api-reference/peripherals/esp_slave_protocol.rst @@ -6,6 +6,12 @@ Communication with ESP SDIO Slave ESP SDIO slave initialization ------------------------------ +.. only:: esp32s2 + + .. note:: + + {IDF_TARGET_NAME} does not have a SDIO peripheral. + The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the standard SDIO initialization process (Sector 3.1.2 of `SDIO Simplified Specification `_). In this specification diff --git a/docs/en/api-reference/peripherals/gpio.rst b/docs/en/api-reference/peripherals/gpio.rst index 87a4729752..6281c98c93 100644 --- a/docs/en/api-reference/peripherals/gpio.rst +++ b/docs/en/api-reference/peripherals/gpio.rst @@ -11,10 +11,12 @@ Overview - 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. -.. only:: esp32s2beta +.. only:: esp32s2 The {IDF_TARGET_NAME} chip features 43 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 GPIO26-32 are usually used for SPI flash. + - GPIO46 is fixed to pull-down and is input only 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. diff --git a/docs/en/api-reference/peripherals/i2s.rst b/docs/en/api-reference/peripherals/i2s.rst index 7f4148d7c1..1a96eb7222 100644 --- a/docs/en/api-reference/peripherals/i2s.rst +++ b/docs/en/api-reference/peripherals/i2s.rst @@ -6,7 +6,13 @@ Overview I2S (Inter-IC Sound) is a serial, synchronous communication protocol that is usually used for transmitting audio data between two digital audio devices. -{IDF_TARGET_NAME} integrates two I2S controllers, referred to as I2S0 and I2S1, both of which can be used for streaming audio and video digital data. +.. only:: esp32 + + {IDF_TARGET_NAME} contains two I2S peripherals. These peripherals can be configured to input and output sample data via the I2S driver. + +.. only:: esp32s2 + + {IDF_TARGET_NAME} contains one I2S peripheral. These peripherals can be configured to input and output sample data via the I2S driver. An I2S bus consists of the following lines: diff --git a/docs/en/api-reference/peripherals/ledc.rst b/docs/en/api-reference/peripherals/ledc.rst index 17587e3b4c..492fe21c7d 100644 --- a/docs/en/api-reference/peripherals/ledc.rst +++ b/docs/en/api-reference/peripherals/ledc.rst @@ -6,9 +6,15 @@ LED Control Introduction ------------ -The LED control (LEDC) peripheral is primarily designed to control the intensity of LEDs, although it can also be used to generate PWM signals for other purposes as well. It has 16 channels which can generate independent waveforms that can be used, for example, to drive RGB LED devices. +.. only:: esp32 -A half of LEDC's channels operate in high speed mode. This mode is implemented in hardware and offers automatic and glitch-free changing of the PWM duty cycle. The other half of channels operate in low speed mode, where the moment of change depends on the application software. Each group of channels is also able to use different clock sources. + The LED control (LEDC) peripheral is primarily designed to control the intensity of LEDs, although it can also be used to generate PWM signals for other purposes as well. It has 16 channels which can generate independent waveforms that can be used, for example, to drive RGB LED devices. + + A half of LEDC's channels operate in high speed mode. This mode is implemented in hardware and offers automatic and glitch-free changing of the PWM duty cycle. The other half of channels operate in low speed mode, where the moment of change depends on the application software. Each group of channels is also able to use different clock sources, but this feature is not yet supported in the LEDC driver. + +.. only:: esp32s2 + + A half of LEDC's channels operate in high speed mode. This mode is implemented in hardware and offers automatic and glitch-free changing of the PWM duty cycle. The other half of channels operate in low speed mode, where the moment of change depends on the application software. Each group of channels is also able to use different clock sources. The PWM controller can automatically increase or decrease the duty cycle gradually, allowing for fades without any processor interference. @@ -131,17 +137,20 @@ For registration of a handler to address this interrupt, call :cpp:func:`ledc_is LEDC High and Low Speed Mode ---------------------------- -Of the total 8 timers and 16 channels available in the LED PWM Controller, half of them are dedicated to operation in high speed mode and the other half in low speed mode. Selection of a low or high speed timer or channel is done with the parameter :cpp:type:`ledc_mode_t` that can be found in applicable function calls. +.. only:: esp32 The advantage of high speed mode is glitch-free changeover of the timer settings. This means that if the timer settings are modified, the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the background, e.g., when :cpp:func:`ledc_timer_config` or :cpp:func:`ledc_timer_set` is called. -.. only:: esp32 + The advantage of high speed mode is hardware-supported, glitch-free changeover of the timer settings. This means that if the timer settings are modified, the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the background, e.g., when :cpp:func:`ledc_timer_config` or :cpp:func:`ledc_timer_set` is called. - For additional details regarding speed modes, refer to `ESP32 Technical Reference Manual `_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver. -.. only:: esp32s2beta + For additional details regarding speed modes, refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_URL}>`_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver. - For additional details regarding speed modes, refer to `ESP32-S2 Technical Reference Manual `_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver. +.. only:: esp32s2 + + .. note:: + + All the timers and channels in the {IDF_TARGET_NAME}'s LED PWM Controller only support low speed mode. .. _ledc-api-supported-range-frequency-duty-resolution: diff --git a/docs/en/api-reference/peripherals/mcpwm.rst b/docs/en/api-reference/peripherals/mcpwm.rst index 55743df6c6..7ab6b657bd 100644 --- a/docs/en/api-reference/peripherals/mcpwm.rst +++ b/docs/en/api-reference/peripherals/mcpwm.rst @@ -1,7 +1,9 @@ MCPWM ===== -{IDF_TARGET_NAME} has two MCPWM units which can be used to control different types of motors. Each unit has three pairs of PWM outputs. +.. This peripheral is ESP32 only + +ESP32 has two MCPWM units which can be used to control different types of motors. Each unit has three pairs of PWM outputs. .. figure:: ../../../_static/mcpwm-overview.png :align: center @@ -89,13 +91,8 @@ There are couple of ways to adjust a signal on the outputs and changing how the Synchronization signals are referred to using two different enumerations. First one :cpp:type:`mcpwm_io_signals_t` is used together with function :cpp:func:`mcpwm_gpio_init` when selecting a GPIO as the signal input source. The second one :cpp:type:`mcpwm_sync_signal_t` is used when enabling or disabling synchronization with :cpp:func:`mcpwm_sync_enable` or :cpp:func:`mcpwm_sync_disable`. -.. only:: esp32 - * Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `ESP32 Technical Reference Manual`_. - -.. only:: esp32s2beta - - * Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `ESP32-S2 Technical Reference Manual`_. +* Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `{IDF_TARGET_NAME} Technical Reference Manual`_. Capture ------- @@ -153,7 +150,7 @@ To use the carrier submodule, it should be first initialized by calling :cpp:fun The carrier parameters may be then alerted at a runtime by calling dedicated functions to change individual fields of the :cpp:type:`mcpwm_carrier_config_t` structure, like :cpp:func:`mcpwm_carrier_set_period`, :cpp:func:`mcpwm_carrier_set_duty_cycle`, :cpp:func:`mcpwm_carrier_output_invert`, etc. -This includes enabling and setting duration of the first pulse of the career with :cpp:func:`mcpwm_carrier_oneshot_mode_enable`. For more details please refer to "PWM Carrier Submodule" section of the `ESP32 Technical Reference Manual`_. +This includes enabling and setting duration of the first pulse of the career with :cpp:func:`mcpwm_carrier_oneshot_mode_enable`. For more details please refer to "PWM Carrier Submodule" section of the `{IDF_TARGET_NAME} Technical Reference Manual`_. To disable carrier functionality call :cpp:func:`mcpwm_carrier_disable`. @@ -174,9 +171,7 @@ Examples of using MCPWM for motor control: :example:`peripherals/mcpwm`: * Brushed DC motor control - :example:`peripherals/mcpwm/mcpwm_brushed_dc_control` * Servo motor control - :example:`peripherals/mcpwm/mcpwm_servo_control` -.. _ESP32 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf - -.. _ESP32-S2 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf +.. _{IDF_TARGET_NAME} Technical Reference Manual: {IDF_TARGET_TRM_URL} API Reference diff --git a/docs/en/api-reference/peripherals/pcnt.rst b/docs/en/api-reference/peripherals/pcnt.rst index dab0354a59..55458a48fa 100644 --- a/docs/en/api-reference/peripherals/pcnt.rst +++ b/docs/en/api-reference/peripherals/pcnt.rst @@ -13,17 +13,22 @@ Functionality Overview Description of functionality of this API has been broken down into four sections: * :ref:`pcnt-api-configuration` - describes counter's configuration parameters and how to setup the counter. -* :ref:`pcnt-api-operating-the-counter` - provides information on control functions to pause, measure and clear the counter. +* :ref:`pcnt-api-operating-the-counter` - provides information on control functions to pause, measure and clear the counter. * :ref:`pcnt-api-filtering-pulses` - describes options to filtering pulses and the counter control signals. -* :ref:`pcnt-api-using-interrupts` - presents how to trigger interrupts on specific states of the counter. +* :ref:`pcnt-api-using-interrupts` - presents how to trigger interrupts on specific states of the counter. .. _pcnt-api-configuration: Configuration ------------- +.. only:: esp32 -The PCNT module has eight independent counting "units" numbered from 0 to 7. In the API they are referred to using :cpp:type:`pcnt_unit_t`. Each unit has two independent channels numbered as 0 and 1 and specified with :cpp:type:`pcnt_channel_t`. + The PCNT module has eight independent counting "units" numbered from 0 to 7. In the API they are referred to using :cpp:type:`pcnt_unit_t`. Each unit has two independent channels numbered as 0 and 1 and specified with :cpp:type:`pcnt_channel_t`. + +.. only:: esp32s2 + + The PCNT module has four independent counting "units" numbered from 0 to 3. In the API they are referred to using :cpp:type:`pcnt_unit_t`. Each unit has two independent channels numbered as 0 and 1 and specified with :cpp:type:`pcnt_channel_t`. The configuration is provided separately per unit's channel using :cpp:type:`pcnt_config_t` and covers: @@ -78,7 +83,7 @@ There are five counter state watch events, defined in :cpp:type:`pcnt_evt_type_t * Threshold 0 or Threshold 1 values set using function :cpp:func:`pcnt_set_event_value`. * Pulse count = 0 -To register, enable or disable an interrupt to service the above events, call :cpp:func:`pcnt_isr_register`, :cpp:func:`pcnt_intr_enable`. and :cpp:func:`pcnt_intr_disable`. To enable or disable events on reaching threshold values, you will also need to call functions :cpp:func:`pcnt_event_enable` and :cpp:func:`pcnt_event_disable`. +To register, enable or disable an interrupt to service the above events, call :cpp:func:`pcnt_isr_register`, :cpp:func:`pcnt_intr_enable`. and :cpp:func:`pcnt_intr_disable`. To enable or disable events on reaching threshold values, you will also need to call functions :cpp:func:`pcnt_event_enable` and :cpp:func:`pcnt_event_disable`. In order to check what are the threshold values currently set, use function :cpp:func:`pcnt_get_event_value`. diff --git a/docs/en/api-reference/peripherals/rmt.rst b/docs/en/api-reference/peripherals/rmt.rst index 9c6534cbf8..f1efcef120 100644 --- a/docs/en/api-reference/peripherals/rmt.rst +++ b/docs/en/api-reference/peripherals/rmt.rst @@ -91,7 +91,13 @@ There couple of typical steps to setup and operate the RMT and they are discusse 3. `Change Operation Parameters`_ 4. `Use Interrupts`_ -The RMT has eight channels numbered from zero to seven. Each channel is able to independently transmit or receive data. They are referred to using indexes defined in structure :cpp:type:`rmt_channel_t`. +.. only:: esp32 + + The RMT has eight channels numbered from zero to seven. Each channel is able to independently transmit or receive data. They are referred to using indexes defined in structure :cpp:type:`rmt_channel_t`. + +.. only:: esp32s2 + + The RMT has four channels numbered from zero to three. Each channel is able to independently transmit or receive data. They are referred to using indexes defined in structure :cpp:type:`rmt_channel_t`. Configure Driver @@ -153,7 +159,7 @@ Now, depending on how the channel is configured, we are ready to either `Transmi Transmit Data ------------- -Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized by the RMT controller, later called an 'item', is provided in a structure :cpp:type:`rmt_item32_t`, see :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_caps.h`. Each item consists of two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure of an item is presented below. +Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized by the RMT controller, later called an 'item', is provided in a structure :cpp:type:`rmt_item32_t`, see :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_struct.h`. Each item consists of two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure of an item is presented below. .. packetdiag:: :caption: Structure of RMT items (L - signal level) @@ -186,7 +192,15 @@ Another way to provide data for transmission is by calling :cpp:func:`rmt_fill_t Receive Data ------------ -Before starting the receiver we need some storage for incoming items. The RMT controller has 512 x 32-bits of internal RAM shared between all eight channels. In typical scenarios it is not enough as an ultimate storage for all incoming (and outgoing) items. Therefore this API supports retrieval of incoming items on the fly to save them in a ring buffer of a size defined by the user. The size is provided when calling :cpp:func:`rmt_driver_install` discussed above. To get a handle to this buffer call :cpp:func:`rmt_get_ringbuf_handle`. +.. only:: esp32 + + Before starting the receiver we need some storage for incoming items. The RMT controller has 512 x 32-bits of internal RAM shared between all eight channels. + +.. only:: esp32s2 + + Before starting the receiver we need some storage for incoming items. The RMT controller has 256 x 32-bits of internal RAM shared between all four channels. + +In typical scenarios it is not enough as an ultimate storage for all incoming (and outgoing) items. Therefore this API supports retrieval of incoming items on the fly to save them in a ring buffer of a size defined by the user. The size is provided when calling :cpp:func:`rmt_driver_install` discussed above. To get a handle to this buffer call :cpp:func:`rmt_get_ringbuf_handle`. With the above steps complete we can start the receiver by calling :cpp:func:`rmt_rx_start` and then move to checking what's inside the buffer. To do so, you can use common FreeRTOS functions that interact with the ring buffer. Please see an example how to do it in :example:`peripherals/rmt/ir_protocols`. @@ -242,7 +256,7 @@ The RMT controller triggers interrupts on four specific events describes below. Setting or clearing an interrupt enable mask for specific channels and events may be also done by calling :cpp:func:`rmt_set_intr_enable_mask` or :cpp:func:`rmt_clr_intr_enable_mask`. -When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_struct.h`, where N is the RMT channel number [0, 7] and the ``event_name`` is one of four events described above. +When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_struct.h`, where N is the RMT channel number [0, n] and the ``event_name`` is one of four events described above. If you do not need an ISR anymore, you can deregister it by calling a function :cpp:func:`rmt_isr_deregister`. diff --git a/docs/en/api-reference/peripherals/sd_pullup_requirements.rst b/docs/en/api-reference/peripherals/sd_pullup_requirements.rst index 585862d719..84e72a4427 100644 --- a/docs/en/api-reference/peripherals/sd_pullup_requirements.rst +++ b/docs/en/api-reference/peripherals/sd_pullup_requirements.rst @@ -3,7 +3,7 @@ SD Pull-up Requirements Espressif hardware products are designed for multiple use cases which may require different pull states on pins. For this reason, the pull state of particular pins on certain products will need to be adjusted to provide the pull-ups required in the SD bus. -SD pull-up requirements apply to cases where ESP32 uses the SPI controller to communicate with SD cards. When an SD card is operating in SPI mode or 1-bit SD mode, the CMD and DATA (DAT0 - DAT3) lines of the SD bus must be pulled up by 10 kOhm resistors. Slaves should also have pull-ups on all above-mentioned lines (regardless of whether these lines are connected to the host) in order to prevent SD cards from entering a wrong state. +SD pull-up requirements apply to cases where {IDF_TARGET_NAME} uses the SPI controller to communicate with SD cards. When an SD card is operating in SPI mode or 1-bit SD mode, the CMD and DATA (DAT0 - DAT3) lines of the SD bus must be pulled up by 10 kOhm resistors. Slaves should also have pull-ups on all above-mentioned lines (regardless of whether these lines are connected to the host) in order to prevent SD cards from entering a wrong state. By default, the MTDI bootstrapping pin is incompatible with the DAT2 line pull-up if the flash voltage is 3.3 V. For more information, see :ref:`mtdi_strapping_pin` below. @@ -29,42 +29,67 @@ This section provides an overview of compatibility issues that might occur when Systems on a Chip (SoCs) ^^^^^^^^^^^^^^^^^^^^^^^^ -- ESP32 (except for D2WD versions, see `ESP32 datasheet `_): +.. only:: esp32 - - :ref:`sd_pull-up_no_pull-ups` - - :ref:`strapping_conflicts_dat2` for models with 3.3 V flash chip + - ESP32 (except for D2WD versions, see `ESP32 datasheet `_): -- ESP32-D2WD: + - :ref:`sd_pull-up_no_pull-ups` + - :ref:`strapping_conflicts_dat2` for models with 3.3 V flash chip - - :ref:`sd_pull-up_no_pull-ups` - - :ref:`no_pull-up_on_gpio12` + - ESP32-D2WD: + + - :ref:`sd_pull-up_no_pull-ups` + - :ref:`no_pull-up_on_gpio12` + + .. only:: esp32s2 + + .. note:: + + No chips listed for ESP32-S2 yet. Systems in Packages (SIP) ^^^^^^^^^^^^^^^^^^^^^^^^^ -- ESP32-PICO-D4: +.. only:: esp32 - - :ref:`sd_pull-up_no_pull-ups` - - :ref:`strapping_conflicts_dat2` + - ESP32-PICO-D4: + + - :ref:`sd_pull-up_no_pull-ups` + - :ref:`strapping_conflicts_dat2` + + +.. only:: esp32s2 + + .. note:: + + No chips listed for ESP32-S2 yet. Modules ^^^^^^^ -- ESP32-WROOM-32 Series, including ESP32-WROOM-32, ESP32-WROOM-32D, ESP32-WROOM-32U, and ESP32-SOLO-1 +.. only:: esp32 - - :ref:`sd_pull-up_no_pull-ups` - - :ref:`strapping_conflicts_dat2` + - ESP32-WROOM-32 Series, including ESP32-WROOM-32, ESP32-WROOM-32D, ESP32-WROOM-32U, and ESP32-SOLO-1 -- ESP32-WROVER Series, including ESP32-WROVER and ESP32-WROVER-I + - :ref:`sd_pull-up_no_pull-ups` + - :ref:`strapping_conflicts_dat2` - - :ref:`sd_pull-up_no_pull-ups` + - ESP32-WROVER Series, including ESP32-WROVER and ESP32-WROVER-I -- ESP32-WROVER-B Series, including ESP32-WROVER-B and ESP32-WROVER-IB + - :ref:`sd_pull-up_no_pull-ups` - - :ref:`sd_pull-up_no_pull-ups` - - :ref:`strapping_conflicts_dat2` + - ESP32-WROVER-B Series, including ESP32-WROVER-B and ESP32-WROVER-IB + + - :ref:`sd_pull-up_no_pull-ups` + - :ref:`strapping_conflicts_dat2` + +.. only:: esp32s2 + + .. note:: + + No chips listed for ESP32-S2 yet. .. _sdio_dev_kits: @@ -72,40 +97,48 @@ Modules Development Boards ^^^^^^^^^^^^^^^^^^ -- ESP32-PICO-KIT, including PICO-KIT v4.1, v4.0, and v3 +.. only:: esp32 - - :ref:`sd_pull-up_no_pull-ups` - - :ref:`strapping_conflicts_dat2` - - :ref:`gpio2_strapping_pin` + - ESP32-PICO-KIT, including PICO-KIT v4.1, v4.0, and v3 -- ESP32-DevKitC, including ESP32-DevKitC v4 and v2 + - :ref:`sd_pull-up_no_pull-ups` + - :ref:`strapping_conflicts_dat2` + - :ref:`gpio2_strapping_pin` - - :ref:`sd_pull-up_no_pull-ups` - - :ref:`strapping_conflicts_dat2` - - :ref:`gpio2_strapping_pin` + - ESP32-DevKitC, including ESP32-DevKitC v4 and v2 -- ESP-WROVER-KIT + - :ref:`sd_pull-up_no_pull-ups` + - :ref:`strapping_conflicts_dat2` + - :ref:`gpio2_strapping_pin` - - Required pull-ups are provided - - :ref:`pull-up_conflicts_on_gpio13` (v4.1, v3, v2, and v1) - - :ref:`strapping_conflicts_dat2` (v4.1, v2, and v1) - - :ref:`gpio2_strapping_pin` (v2, v1) + - ESP-WROVER-KIT - You can determine the version of your ESP23-WROVER-KIT by checking which module is mounted on it: + - Required pull-ups are provided + - :ref:`pull-up_conflicts_on_gpio13` (v4.1, v3, v2, and v1) + - :ref:`strapping_conflicts_dat2` (v4.1, v2, and v1) + - :ref:`gpio2_strapping_pin` (v2, v1) - - ESP32-WROVER-B on v4.1 - - ESP32-WROVER on v3 - - ESP32-WROOM-32 on v1 and v2 + You can determine the version of your ESP23-WROVER-KIT by checking which module is mounted on it: -- ESP32-LyraTD-MSC + - ESP32-WROVER-B on v4.1 + - ESP32-WROVER on v3 + - ESP32-WROOM-32 on v1 and v2 - - Required pull-ups are provided - - :ref:`strapping_conflicts_dat2` + - ESP32-LyraTD-MSC -- ESP32-LyraT + - Required pull-ups are provided + - :ref:`strapping_conflicts_dat2` - - Required pull-ups are provided - - :ref:`pull-up_conflicts_on_gpio13` + - ESP32-LyraT + + - Required pull-ups are provided + - :ref:`pull-up_conflicts_on_gpio13` + +.. only:: esp32s2 + + .. note:: + + No chips listed for ESP32-S2 yet. Non-Espressif Hosts @@ -159,7 +192,7 @@ To resolve the conflict, you have the following options: Burning eFuses is irreversible! The issue list above might be out of date, so please make sure that the module you are burning has a 3.3 V flash chip by checking the information on http://www.espressif.com/. If you burn the 3.3 V eFuses on a module with a 1.8 V flash chip, the module will stop functioning. If you are sure that you need to irreversibly burn eFuses, go to your ESP-IDF directory and run the following command: - + .. code-block:: bash components/esptool_py/esptool/espefuse.py set_flash_voltage 3.3V @@ -178,13 +211,13 @@ To resolve the conflict, you have the following options: BURN VDD_SDIO setting complete. - To check the status of the eFuses, run:: + To check the status of the eFuses, run:: ``components/esptool_py/esptool/espefuse.py summary`` If running from an automated flashing script, ``espefuse.py`` has an option ``--do-not-confirm``. - For more details, see the `ESP32 Technical Reference Manual `_ (PDF). + For more details, see the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_URL}>`_ (PDF). 2. **If using 1-bit SD mode or SPI mode**, disconnect the DAT2 pin and make sure it is pulled high. For this, do one the following: @@ -230,7 +263,9 @@ MTDI Strapping Pin MTDI (GPIO12) is used as a bootstrapping pin to select the output voltage of an internal regulator (VDD_SDIO) which powers the flash chip. This pin has an internal pull-down, so, if left unconnected, it will read low at startup, which will lead to selecting the default 3.3 V operation. -All ESP32-WROVER modules, excluding ESP32-WROVER-B, use 1.8 V flash and have internal pull-ups on GPIO12. Other modules that use 3.3 V flash have no pull-ups on the GPIO12 pin, and this pin is slightly pulled down internally. +.. only:: esp32 + + All ESP32-WROVER modules, excluding ESP32-WROVER-B, use 1.8 V flash and have internal pull-ups on GPIO12. Other modules that use 3.3 V flash have no pull-ups on the GPIO12 pin, and this pin is slightly pulled down internally. When adding a pull-up to this pin for SD card operation, consider the following: @@ -263,7 +298,7 @@ The following abbreviations are used in the table: * - **15** - CMD - WPU - - + - * - **2** - DAT0 - WPD @@ -271,7 +306,7 @@ The following abbreviations are used in the table: * - **4** - DAT1 - WPD - - + - * - **12** - DAT2 - PU for 1.8 V flash; WPD for 3.3 V flash @@ -279,4 +314,4 @@ The following abbreviations are used in the table: * - **13** - DAT3 - WPU - - \ No newline at end of file + - \ No newline at end of file diff --git a/docs/en/api-reference/peripherals/sdio_slave.rst b/docs/en/api-reference/peripherals/sdio_slave.rst index f5bd9fe0ee..8c303b1833 100644 --- a/docs/en/api-reference/peripherals/sdio_slave.rst +++ b/docs/en/api-reference/peripherals/sdio_slave.rst @@ -4,14 +4,22 @@ SDIO Card Slave Driver Overview -------- -The ESP32 SDIO Card peripherals (Host, Slave) shares two sets of pins as below table. -The first set is usually occupied by SPI0 bus which is responsible for the SPI flash holding the code to run. -This means SDIO slave driver can only runs on the second set of pins while SDIO host is not using it. +.. only:: esp32s2 -The SDIO slave can run under 3 modes: SPI, 1-bit SD and 4-bit SD modes, which -is detected automatically by the hardware. According to the SDIO -specification, CMD and DAT0-3 lines should be pulled up no matter in 1-bit, -4-bit or SPI mode. + .. note:: + + {IDF_TARGET_NAME} does not have a SDIO peripheral. + +.. only:: esp32 + + The ESP32 SDIO Card peripherals (Host, Slave) shares two sets of pins as below table. + The first set is usually occupied by SPI0 bus which is responsible for the SPI flash holding the code to run. + This means SDIO slave driver can only runs on the second set of pins while SDIO host is not using it. + + The SDIO slave can run under 3 modes: SPI, 1-bit SD and 4-bit SD modes, which + is detected automatically by the hardware. According to the SDIO + specification, CMD and DAT0-3 lines should be pulled up no matter in 1-bit, + 4-bit or SPI mode. Connections ^^^^^^^^^^^ diff --git a/docs/en/api-reference/peripherals/sdmmc_host.rst b/docs/en/api-reference/peripherals/sdmmc_host.rst index 105a92f845..d9157d027b 100644 --- a/docs/en/api-reference/peripherals/sdmmc_host.rst +++ b/docs/en/api-reference/peripherals/sdmmc_host.rst @@ -3,47 +3,54 @@ SDMMC Host Driver Overview -------- +.. only:: esp32s2 -ESP32's SDMMC host peripheral has two slots: + .. note:: -- Slot 0 (:c:macro:`SDMMC_HOST_SLOT_0`) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX. -- Slot 1 (:c:macro:`SDMMC_HOST_SLOT_1`) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX. + {IDF_TARGET_NAME} does not have a SDMMC host peripheral. -Pin mappings of these slots are given in the table below. +.. only:: esp32 - +--------+-------------+-------------+ - | Signal | Slot 0 | Slot 1 | - +========+=============+=============+ - | CMD | GPIO11 | GPIO15 | - +--------+-------------+-------------+ - | CLK | GPIO6 | GPIO14 | - +--------+-------------+-------------+ - | D0 | GPIO7 | GPIO2 | - +--------+-------------+-------------+ - | D1 | GPIO8 | GPIO4 | - +--------+-------------+-------------+ - | D2 | GPIO9 | GPIO12 | - +--------+-------------+-------------+ - | D3 | GPIO10 | GPIO13 | - +--------+-------------+-------------+ - | D4 | GPIO16 | | - +--------+-------------+-------------+ - | D5 | GPIO17 | | - +--------+-------------+-------------+ - | D6 | GPIO5 | | - +--------+-------------+-------------+ - | D7 | GPIO18 | | - +--------+-------------+-------------+ - | CD | any input via GPIO matrix | - +--------+---------------------------+ - | WP | any input via GPIO matrix | - +--------+---------------------------+ + ESP32's SDMMC host peripheral has two slots: -The Card Detect and Write Protect signals can be routed to arbitrary pins using the GPIO matrix. To reserve the pins, set the ``gpio_cd`` and ``gpio_wp`` members of the :cpp:class:`sdmmc_slot_config_t` structure before calling :cpp:func:`sdmmc_host_init_slot`. Please note that it is not advised to specify a Card Detect pin when working with SDIO cards, because the card detect signal in ESP32 can also trigger SDIO slave interrupt. + - Slot 0 (:c:macro:`SDMMC_HOST_SLOT_0`) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX. + - Slot 1 (:c:macro:`SDMMC_HOST_SLOT_1`) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX. -.. warning:: - - Pins used by Slot 0 (``HS1_*``) are also used to connect the SPI flash chip in ESP32-WROOM and ESP32-WROVER modules. These pins cannot be shared between an SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set eFuses accordingly. + Pin mappings of these slots are given in the table below. + + +--------+-------------+-------------+ + | Signal | Slot 0 | Slot 1 | + +========+=============+=============+ + | CMD | GPIO11 | GPIO15 | + +--------+-------------+-------------+ + | CLK | GPIO6 | GPIO14 | + +--------+-------------+-------------+ + | D0 | GPIO7 | GPIO2 | + +--------+-------------+-------------+ + | D1 | GPIO8 | GPIO4 | + +--------+-------------+-------------+ + | D2 | GPIO9 | GPIO12 | + +--------+-------------+-------------+ + | D3 | GPIO10 | GPIO13 | + +--------+-------------+-------------+ + | D4 | GPIO16 | | + +--------+-------------+-------------+ + | D5 | GPIO17 | | + +--------+-------------+-------------+ + | D6 | GPIO5 | | + +--------+-------------+-------------+ + | D7 | GPIO18 | | + +--------+-------------+-------------+ + | CD | any input via GPIO matrix | + +--------+---------------------------+ + | WP | any input via GPIO matrix | + +--------+---------------------------+ + + The Card Detect and Write Protect signals can be routed to arbitrary pins using the GPIO matrix. To reserve the pins, set the ``gpio_cd`` and ``gpio_wp`` members of the :cpp:class:`sdmmc_slot_config_t` structure before calling :cpp:func:`sdmmc_host_init_slot`. Please note that it is not advised to specify a Card Detect pin when working with SDIO cards, because the card detect signal in ESP32 can also trigger SDIO slave interrupt. + + .. warning:: + + Pins used by Slot 0 (``HS1_*``) are also used to connect the SPI flash chip in ESP32-WROOM and ESP32-WROVER modules. These pins cannot be shared between an SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set eFuses accordingly. Supported Speed Modes @@ -74,7 +81,7 @@ Other functions, such as the ones given below, will be called by the SD/MMC prot - :cpp:func:`sdmmc_host_set_bus_width` - :cpp:func:`sdmmc_host_set_card_clk` -- :cpp:func:`sdmmc_host_do_transaction` +- :cpp:func:`sdmmc_host_do_transaction` Configuring Bus Width and Frequency diff --git a/docs/en/api-reference/peripherals/sdspi_host.rst b/docs/en/api-reference/peripherals/sdspi_host.rst index 0d28188c57..c20337b539 100644 --- a/docs/en/api-reference/peripherals/sdspi_host.rst +++ b/docs/en/api-reference/peripherals/sdspi_host.rst @@ -8,7 +8,7 @@ The SD SPI host driver allows using the SPI2 (HSPI) or SPI3 (VSPI) controller fo The SD SPI host driver has the following modes: -- **SPI mode**: offers lower throughput but makes pin selection more flexible. With the help of the GPIO matrix, an SPI peripheral's signals can be routed to any ESP32 pin. +- **SPI mode**: offers lower throughput but makes pin selection more flexible. With the help of the GPIO matrix, an SPI peripheral's signals can be routed to any {IDF_TARGET_NAME} pin. - **1-bit SD mode**: offers higher throughput but requires routing the signals through their dedicated IO_MUX pins only. The SD SPI driver uses software-controlled CS signal. @@ -32,7 +32,7 @@ Only the following driver's API functions are normally used by most applications Other functions are mostly used by the protocol level SD/SDIO/MMC driver via function pointers in the :cpp:type:`sdmmc_host_t` structure. For more details, see :doc:`the SD/SDIO/MMC Driver <../storage/sdmmc>`. .. note:: - + SD over SPI does not support speeds above :c:macro:`SDMMC_FREQ_DEFAULT` due to the limitations of the SPI driver. diff --git a/docs/en/api-reference/peripherals/sigmadelta.rst b/docs/en/api-reference/peripherals/sigmadelta.rst index ccbee0dd0f..55721b3094 100644 --- a/docs/en/api-reference/peripherals/sigmadelta.rst +++ b/docs/en/api-reference/peripherals/sigmadelta.rst @@ -4,9 +4,9 @@ Sigma-delta Modulation Introduction ------------ -ESP32 has a second-order sigma-delta modulation module. This driver configures the channels of the sigma-delta module. +{IDF_TARGET_NAME} has a second-order sigma-delta modulation module. This driver configures the channels of the sigma-delta module. -Functionality Overview +Functionality Overview ---------------------- There are eight independent sigma-delta modulation channels identified with :cpp:type:`sigmadelta_channel_t`. Each channel is capable to output the binary, hardware generated signal with the sigma-delta modulation. diff --git a/docs/en/api-reference/peripherals/spi_master.rst b/docs/en/api-reference/peripherals/spi_master.rst index 4d7d79b695..ddb565401e 100644 --- a/docs/en/api-reference/peripherals/spi_master.rst +++ b/docs/en/api-reference/peripherals/spi_master.rst @@ -1,11 +1,11 @@ SPI Master Driver ================= -SPI Master driver is a program that controls ESP32's SPI peripherals while they function as masters. +SPI Master driver is a program that controls {IDF_TARGET_NAME}'s SPI peripherals while they function as masters. -Overview of ESP32's SPI peripherals ------------------------------------ +Overview of {IDF_TARGET_NAME}'s SPI peripherals +----------------------------------------------- ESP32 integrates four SPI peripherals. @@ -48,7 +48,7 @@ The SPI master driver governs communications of Hosts with Devices. The driver s .. warning:: - The SPI master driver has the concept of multiple Devices connected to a single bus (sharing a single ESP32 SPI peripheral). As long as each Device is accessed by only one task, the driver is thread safe. However, if multiple tasks try to access the same SPI Device, the driver is **not thread-safe**. In this case, it is recommended to either: + The SPI master driver has the concept of multiple Devices connected to a single bus (sharing a single {IDF_TARGET_NAME} SPI peripheral). As long as each Device is accessed by only one task, the driver is thread safe. However, if multiple tasks try to access the same SPI Device, the driver is **not thread-safe**. In this case, it is recommended to either: - Refactor your application so that each SPI peripheral is only accessed by a single task at a time. - Add a mutex lock around the shared Device using :c:macro:`xSemaphoreCreateMutex`. @@ -154,12 +154,12 @@ Driver Usage Organize the Driver Usage into subsections that will reflect the general usage experience of the users, e.g., Configuration - + Add stuff about the configuration API here, and the various options in configuration (e.g., configure for interrupt vs. polling), and optional configuration Transactions - - Describe how to execute a normal transaction (i.e., where data is larger than 32 bits). Describe how to configure between big and little-endian. + + Describe how to execute a normal transaction (i.e., where data is larger than 32 bits). Describe how to configure between big and little-endian. - Add subsub section on how to optimize when transmitting less than 32 bits - Add subsub section on how to transmit mixed transactions to the same device @@ -195,11 +195,11 @@ When the transaction data size is equal to or less than 32 bits, it will be sub- Transactions with Integers Other Than ``uint8_t`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -An SPI Host reads and writes data into memory byte by byte. By default, data is sent with the most significant bit (MSB) first, as LSB first used in rare cases. If a value less than 8 bits needs to be sent, the bits should be written into memory in the MSB first manner. +An SPI Host reads and writes data into memory byte by byte. By default, data is sent with the most significant bit (MSB) first, as LSB first used in rare cases. If a value less than 8 bits needs to be sent, the bits should be written into memory in the MSB first manner. For example, if ``0b00010`` needs to be sent, it should be written into a ``uint8_t`` variable, and the length for reading should be set to 5 bits. The Device will still receive 8 bits with 3 additional "random" bits, so the reading must be performed correctly. -On top of that, ESP32 is a little-endian chip, which means that the least significant byte of ``uint16_t`` and ``uint32_t`` variables is stored at the smallest address. Hence, if ``uint16_t`` is stored in memory, bits [7:0] are sent first, followed by bits [15:8]. +On top of that, {IDF_TARGET_NAME} is a little-endian chip, which means that the least significant byte of ``uint16_t`` and ``uint32_t`` variables is stored at the smallest address. Hence, if ``uint16_t`` is stored in memory, bits [7:0] are sent first, followed by bits [15:8]. For cases when the data to be transmitted has the size differing from ``uint8_t`` arrays, the following macros can be used to transform data to the format that can be sent by the SPI driver directly: @@ -222,42 +222,43 @@ In-flight polling transactions are disturbed by the ISR operation to accommodate To have better control of the calling sequence of functions, send mixed transactions to the same Device only within a single task. +.. only:: esp32 -GPIO Matrix and IO_MUX ----------------------- + GPIO Matrix and IO_MUX + ---------------------- -Most of ESP32's peripheral signals have direct connection to their dedicated IO_MUX pins. However, the signals can also be routed to any other available pins using the less direct GPIO matrix. If at least one signal is routed through the GPIO matrix, then all signals will be routed through it. + Most of ESP32's peripheral signals have direct connection to their dedicated IO_MUX pins. However, the signals can also be routed to any other available pins using the less direct GPIO matrix. If at least one signal is routed through the GPIO matrix, then all signals will be routed through it. -The GPIO matrix introduces flexibility of routing but also brings the following disadvantages: + The GPIO matrix introduces flexibility of routing but also brings the following disadvantages: -- Increases the input delay of the MISO signal, which makes MISO setup time violations more likely. If SPI needs to operate at high speeds, use dedicated IO_MUX pins. -- Allows signals with clock frequencies only up to 40 MHz, as opposed to 80 MHz if IO_MUX pins are used. + - Increases the input delay of the MISO signal, which makes MISO setup time violations more likely. If SPI needs to operate at high speeds, use dedicated IO_MUX pins. + - Allows signals with clock frequencies only up to 40 MHz, as opposed to 80 MHz if IO_MUX pins are used. -.. note:: + .. note:: - For more details about the influence of the MISO input delay on the maximum clock frequency, see :ref:`timing_considerations`. + For more details about the influence of the MISO input delay on the maximum clock frequency, see :ref:`timing_considerations`. -The IO_MUX pins for SPI buses are given below. + The IO_MUX pins for SPI buses are given below. -+----------+------+------+ -| Pin Name | SPI2 | SPI3 | -+ +------+------+ -| | GPIO Number | -+==========+======+======+ -| CS0* | 15 | 5 | -+----------+------+------+ -| SCLK | 14 | 18 | -+----------+------+------+ -| MISO | 12 | 19 | -+----------+------+------+ -| MOSI | 13 | 23 | -+----------+------+------+ -| QUADWP | 2 | 22 | -+----------+------+------+ -| QUADHD | 4 | 21 | -+----------+------+------+ + +----------+------+------+ + | Pin Name | SPI2 | SPI3 | + + +------+------+ + | | GPIO Number | + +==========+======+======+ + | CS0* | 15 | 5 | + +----------+------+------+ + | SCLK | 14 | 18 | + +----------+------+------+ + | MISO | 12 | 19 | + +----------+------+------+ + | MOSI | 13 | 23 | + +----------+------+------+ + | QUADWP | 2 | 22 | + +----------+------+------+ + | QUADHD | 4 | 21 | + +----------+------+------+ -* Only the first Device attached to the bus can use the CS0 pin. + * Only the first Device attached to the bus can use the CS0 pin. .. _speed_considerations: @@ -429,21 +430,23 @@ Corresponding frequency limits for different Devices with different *input delay Known Issues ------------ -1. Half-duplex transactions are not compatible with DMA when both writing and reading phases are used. +.. only:: esp32 - If such transactions are required, you have to use one of the alternative solutions: + 1. Half-duplex transactions are not compatible with DMA when both writing and reading phases are used. - 1. Use full-duplex transactions instead. - 2. Disable DMA by setting the bus initialization function's last parameter to 0 as follows: - ``ret=spi_bus_initialize(VSPI_HOST, &buscfg, 0);`` + If such transactions are required, you have to use one of the alternative solutions: - This can prohibit you from transmitting and receiving data longer than 64 bytes. - 3. Try using the command and address fields to replace the write phase. + 1. Use full-duplex transactions instead. + 2. Disable DMA by setting the bus initialization function's last parameter to 0 as follows: + ``ret=spi_bus_initialize(VSPI_HOST, &buscfg, 0);`` -2. Full-duplex transactions are not compatible with the *dummy bit workaround*, hence the frequency is limited. See :ref:`dummy - bit speed-up workaround `. + This can prohibit you from transmitting and receiving data longer than 64 bytes. + 3. Try using the command and address fields to replace the write phase. -3. ``cs_ena_pretrans`` is not compatible with the command and address phases of full-duplex transactions. + 2. Full-duplex transactions are not compatible with the *dummy bit workaround*, hence the frequency is limited. See :ref:`dummy + bit speed-up workaround `. + + 3. ``cs_ena_pretrans`` is not compatible with the command and address phases of full-duplex transactions. Application Example diff --git a/docs/en/api-reference/peripherals/spi_slave.rst b/docs/en/api-reference/peripherals/spi_slave.rst index 91993f549e..545426b220 100644 --- a/docs/en/api-reference/peripherals/spi_slave.rst +++ b/docs/en/api-reference/peripherals/spi_slave.rst @@ -1,13 +1,13 @@ SPI Slave Driver ================ -SPI Slave driver is a program that controls ESP32's SPI peripherals while they function as slaves. +SPI Slave driver is a program that controls {IDF_TARGET_NAME}'s SPI peripherals while they function as slaves. -Overview of ESP32's SPI peripherals ------------------------------------ +Overview of {IDF_TARGET_NAME}'s SPI peripherals +----------------------------------------------- -ESP32 integrates two general purpose SPI controllers which can be used as slave nodes driven by an off-chip SPI master +{IDF_TARGET_NAME} integrates two general purpose SPI controllers which can be used as slave nodes driven by an off-chip SPI master - SPI2, sometimes referred to as HSPI - SPI3, sometimes referred to as VSPI @@ -23,7 +23,7 @@ The terms used in relation to the SPI slave driver are given in the table below. ================= ========================================================================================= Term Definition ================= ========================================================================================= -**Host** The SPI controller peripheral external to ESP32 that initiates SPI transmissions over the bus, and acts as an SPI Master. +**Host** The SPI controller peripheral external to {IDF_TARGET_NAME} that initiates SPI transmissions over the bus, and acts as an SPI Master. **Device** SPI slave device, in this case the SPI2 and SPI3 controllers. Each Device shares the MOSI, MISO and SCLK signals but is only active on the bus when the Host asserts the Device's individual CS line. **Bus** A signal bus, common to all Devices connected to one Host. In general, a bus includes the following lines: MISO, MOSI, SCLK, one or more CS lines, and, optionally, QUADWP and QUADHD. So Devices are connected to the same lines, with the exception that each Device has its own CS line. Several Devices can also share one CS line if connected in the daisy-chain manner. - **MISO** Master In, Slave Out, a.k.a. Q. Data transmission from a Device to Host. @@ -63,7 +63,15 @@ As not every transaction requires both writing and reading data, you have a choi Driver Usage ------------ -- Initialize an SPI peripheral as a Device by calling the function cpp:func:`spi_slave_initialize`. Make sure to set the correct I/O pins in the struct :cpp:type:`bus_config`. Set the unused signals to ``-1``. If transactions will be longer than 32 bytes, allow a DMA channel 1 or 2 by setting the parameter ``dma_chan`` to ``1`` or ``2`` respectively. Otherwise, set ``dma_chan`` to ``0``. +- Initialize an SPI peripheral as a Device by calling the function cpp:func:`spi_slave_initialize`. Make sure to set the correct I/O pins in the struct :cpp:type:`bus_config`. Set the unused signals to ``-1``. + +.. only:: esp32 + + If transactions will be longer than 32 bytes, allow a DMA channel 1 or 2 by setting the parameter ``dma_chan`` to ``1`` or ``2`` respectively. Otherwise, set ``dma_chan`` to ``0``. + +.. only:: esp32s2 + + If transactions will be longer than 32 bytes, allow a DMA channel by setting the parameter ``dma_chan`` to the host device. Otherwise, set ``dma_chan`` to ``0``. - Before initiating transactions, fill one or more :cpp:type:`spi_slave_transaction_t` structs with the transaction parameters required. Either queue all transactions by calling the function :cpp:func:`spi_slave_queue_trans` and, at a later time, query the result by using the function :cpp:func:`spi_slave_get_trans_result`, or handle all requests individually by feeding them into :cpp:func:`spi_slave_transmit`. The latter two functions will be blocked until the Host has initiated and finished a transaction, causing the queued data to be sent and received. @@ -79,47 +87,54 @@ The amount of data that the driver can read or write to the buffers is limited b If the length of the transmission is greater than the buffer length, only the initial number of bits specified in the :cpp:member:`length` member will be sent and received. In this case, :cpp:member:`trans_len` is set to :cpp:member:`length` instead of the actual transaction length. To meet the actual transaction length requirements, set :cpp:member:`length` to a value greater than the maximum :cpp:member:`trans_len` expected. If the transmission length is shorter than the buffer length, only the data equal to the length of the buffer will be transmitted. -.. Warning:: +.. only:: esp32 - The ESP32 DMA hardware has a limit to the number of bytes sent by a Host and received by a Device. The transaction length must be longer than 8 bytes and a multiple of 4 bytes; otherwise, the SPI hardware might fail to receive the last 1 to 7 bytes. + .. Warning:: + + The ESP32 DMA hardware has a limit to the number of bytes sent by a Host and received by a Device. The transaction length must be longer than 8 bytes and a multiple of 4 bytes; otherwise, the SPI hardware might fail to receive the last 1 to 7 bytes. -GPIO Matrix and IO_MUX ----------------------- +.. only:: esp32 -Most of ESP32's peripheral signals have direct connection to their dedicated IO_MUX pins. However, the signals can also be routed to any other available pins using the less direct GPIO matrix. + GPIO Matrix and IO_MUX + ---------------------- -If at least one signal is routed through the GPIO matrix, then all signals will be routed through it. The GPIO matrix samples all signals at 80 MHz and transmits them between the GPIO and the peripheral. + Most of {IDF_TARGET_NAME}'s peripheral signals have direct connection to their dedicated IO_MUX pins. However, the signals can also be routed to any other available pins using the less direct GPIO matrix. -If the driver is configured so that all SPI signals are either routed to their dedicated IO_MUX pins or are not connected at all, the GPIO matrix will be bypassed. + If at least one signal is routed through the GPIO matrix, then all signals will be routed through it. The GPIO matrix samples all signals at 80 MHz and transmits them between the GPIO and the peripheral. -The GPIO matrix introduces flexibility of routing but also increases the input delay of the MISO signal, which makes MISO setup time violations more likely. If SPI needs to operate at high speeds, use dedicated IO_MUX pins. + If the driver is configured so that all SPI signals are either routed to their dedicated IO_MUX pins or are not connected at all, the GPIO matrix will be bypassed. -.. note:: + The GPIO matrix introduces flexibility of routing but also increases the input delay of the MISO signal, which makes MISO setup time violations more likely. If SPI needs to operate at high speeds, use dedicated IO_MUX pins. - For more details about the influence of the MISO input delay on the maximum clock frequency, see :ref:`timing_considerations`. + .. note:: -The IO_MUX pins for SPI buses are given below. + For more details about the influence of the MISO input delay on the maximum clock frequency, see :ref:`timing_considerations`. -+----------+------+------+ -| Pin Name | SPI2 | SPI3 | -+ +------+------+ -| | GPIO Number | -+==========+======+======+ -| CS0* | 15 | 5 | -+----------+------+------+ -| SCLK | 14 | 18 | -+----------+------+------+ -| MISO | 12 | 19 | -+----------+------+------+ -| MOSI | 13 | 23 | -+----------+------+------+ -| QUADWP | 2 | 22 | -+----------+------+------+ -| QUADHD | 4 | 21 | -+----------+------+------+ + The IO_MUX pins for SPI buses are given below. -* Only the first Device attached to the bus can use the CS0 pin. + .. only:: esp32 + + +----------+------+------+ + | Pin Name | SPI2 | SPI3 | + + +------+------+ + | | GPIO Number | + +==========+======+======+ + | CS0* | 15 | 5 | + +----------+------+------+ + | SCLK | 14 | 18 | + +----------+------+------+ + | MISO | 12 | 19 | + +----------+------+------+ + | MOSI | 13 | 23 | + +----------+------+------+ + | QUADWP | 2 | 22 | + +----------+------+------+ + | QUADHD | 4 | 21 | + +----------+------+------+ + + + * Only the first Device attached to the bus can use the CS0 pin. Speed and Timing Considerations @@ -130,7 +145,7 @@ Speed and Timing Considerations Transaction Interval ^^^^^^^^^^^^^^^^^^^^ -The ESP32 SPI slave peripherals are designed as general purpose Devices controlled by a CPU. As opposed to dedicated slaves, CPU-based SPI Devices have a limited number of pre-defined registers. All transactions must be handled by the CPU, which means that the transfers and responses are not real-time, and there might be noticeable latency. +The {IDF_TARGET_NAME} SPI slave peripherals are designed as general purpose Devices controlled by a CPU. As opposed to dedicated slaves, CPU-based SPI Devices have a limited number of pre-defined registers. All transactions must be handled by the CPU, which means that the transfers and responses are not real-time, and there might be noticeable latency. As a solution, a Device's response rate can be doubled by using the functions :cpp:func:`spi_slave_queue_trans` and then :cpp:func:`spi_slave_get_trans_result` instead of using :cpp:func:`spi_slave_transmit`. diff --git a/docs/en/api-reference/peripherals/temp_sensor.rst b/docs/en/api-reference/peripherals/temp_sensor.rst index 6fc5c86844..9cfe8f819d 100644 --- a/docs/en/api-reference/peripherals/temp_sensor.rst +++ b/docs/en/api-reference/peripherals/temp_sensor.rst @@ -4,22 +4,30 @@ ESP32-S2 Temperature Sensor Overview -------- -The ESP32-S2 has a built-in temperature sensor. The temperature sensor module contains an 8-bit Sigma-Delta ADC and a temperature offset DAC. -The conversion relationship is the first columns of the table below. Among them, offset = 0 is the main measurement option, and other values are extended measurement options. +.. only:: esp32 -+--------+------------------------+------------------------+ -| offset | measure range(Celsius) | measure error(Celsius) | -+========+========================+========================+ -| -2 | 50 ~ 125 | < 3 | -+--------+------------------------+------------------------+ -| -1 | 20 ~ 100 | < 2 | -+--------+------------------------+------------------------+ -| 0 | -10 ~ 80 | < 1 | -+--------+------------------------+------------------------+ -| 1 | -30 ~ 50 | < 2 | -+--------+------------------------+------------------------+ -| 2 | -40 ~ 20 | < 3 | -+--------+------------------------+------------------------+ + .. note:: + + ESP32 does not have a built-in temperature sensor. + +.. only:: esp32s2 + + The ESP32-S2 has a built-in temperature sensor. The temperature sensor module contains an 8-bit Sigma-Delta ADC and a temperature offset DAC. + The conversion relationship is the first columns of the table below. Among them, offset = 0 is the main measurement option, and other values are extended measurement options. + + +--------+------------------------+------------------------+ + | offset | measure range(Celsius) | measure error(Celsius) | + +========+========================+========================+ + | -2 | 50 ~ 125 | < 3 | + +--------+------------------------+------------------------+ + | -1 | 20 ~ 100 | < 2 | + +--------+------------------------+------------------------+ + | 0 | -10 ~ 80 | < 1 | + +--------+------------------------+------------------------+ + | 1 | -30 ~ 50 | < 2 | + +--------+------------------------+------------------------+ + | 2 | -40 ~ 20 | < 3 | + +--------+------------------------+------------------------+ Application Example ------------------- diff --git a/docs/en/api-reference/peripherals/timer.rst b/docs/en/api-reference/peripherals/timer.rst index dbda4106fe..c50701c675 100644 --- a/docs/en/api-reference/peripherals/timer.rst +++ b/docs/en/api-reference/peripherals/timer.rst @@ -2,11 +2,12 @@ Timer ===== :link_to_translation:`zh_CN:[中文]` +{IDF_TARGET_INT_CLR_REG: default="int_clr", esp32="int_clr_timers"} Introduction ------------ -The ESP32 chip contains two hardware timer groups. Each group has two general-purpose hardware timers. They are all 64-bit generic timers based on 16-bit prescalers and 64-bit up / down counters which are capable of being auto-reloaded. +The {IDF_TARGET_NAME} chip contains two hardware timer groups. Each group has two general-purpose hardware timers. They are all 64-bit generic timers based on 16-bit prescalers and 64-bit up / down counters which are capable of being auto-reloaded. Functional Overview @@ -25,7 +26,7 @@ The following sections of this document cover the typical steps to configure and Timer Initialization ^^^^^^^^^^^^^^^^^^^^ -The two ESP32 timer groups, with two timers in each, provide the total of four individual timers for use. An ESP32 timer group should be identified using :cpp:type:`timer_group_t`. An individual timer in a group should be identified with :cpp:type:`timer_idx_t`. +The two {IDF_TARGET_NAME} timer groups, with two timers in each, provide the total of four individual timers for use. An {IDF_TARGET_NAME} timer group should be identified using :cpp:type:`timer_group_t`. An individual timer in a group should be identified with :cpp:type:`timer_idx_t`. First of all, the timer should be initialized by calling the function :cpp:func:`timer_init` and passing a structure :cpp:type:`timer_config_t` to it to define how the timer should operate. In particular, the following timer parameters can be set: @@ -85,14 +86,14 @@ To check the specified alarm value, call :cpp:func:`timer_get_alarm_value`. Interrupts ^^^^^^^^^^ -Registration of the interrupt handler for a specific timer or a timer group can be done by calling :cpp:func:`timer_isr_register`. +Registration of the interrupt handler for a specific timer or a timer group can be done by calling :cpp:func:`timer_isr_register`. To enable interrupts for a timer group, call :cpp:func:`timer_group_intr_enable`, for a specific timer call :cpp:func:`timer_enable_intr`. To disable interrupts for a timer group, call :cpp:func:`timer_group_intr_disable`, for a specified timer, call :cpp:func:`timer_disable_intr`. -When handling an interrupt within an interrupt serivce routine (ISR), the interrupt status bit needs to be explicitly cleared. To do that, set the ``TIMERGN.int_clr_timers.tM`` structure, defined in :component_file:`soc/esp32/include/soc/timer_group_struct.h`. In this structure, ``N`` is the timer group number [0, 1], ``M`` is the timer number [0, 1]. For example, to clear an interrupt status bit for the timer 1 in the timer group 0, call the following:: +When handling an interrupt within an interrupt serivce routine (ISR), the interrupt status bit needs to be explicitly cleared. To do that, set the ``TIMERGN.{IDF_TARGET_INT_CLR_REG}.tM`` structure, defined in :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/timer_group_struct.h`. In this structure, ``N`` is the timer group number [0, 1], ``M`` is the timer number [0, 1]. For example, to clear an interrupt status bit for the timer 1 in the timer group 0, call the following:: - TIMERG0.int_clr_timers.t1 = 1 + TIMERG0.{IDF_TARGET_INT_CLR_REG}.t1 = 1 For more information on how to use interrupts, please see the application example below. diff --git a/docs/en/api-reference/peripherals/touch_pad.rst b/docs/en/api-reference/peripherals/touch_pad.rst index 82545dd711..2fc75c215f 100644 --- a/docs/en/api-reference/peripherals/touch_pad.rst +++ b/docs/en/api-reference/peripherals/touch_pad.rst @@ -8,11 +8,23 @@ Introduction A touch sensor system is built on a substrate which carries electrodes and relevant connections under a protective flat surface. When a user touches the surface, the capacitance variation is used to evaluate if the touch was valid. -ESP32 can handle up to 10 capacitive touch pads / GPIOs. The sensing pads can be arranged in different combinations (e.g., matrix, slider), so that a larger area or more points can be detected. The touch pad sensing process is under the control of a hardware-implemented finite-state machine (FSM) which is initiated by software or a dedicated hardware timer. +.. only:: esp32 -Design, operation, and control registers of a touch sensor are discussed in `ESP32 Technical Reference Manual `_ (PDF). Please refer to this manual for additional details on how this subsystem works. + ESP32 can handle up to 10 capacitive touch pads / GPIOs. -In-depth design details of touch sensors and firmware development guidelines for ESP32 are available in `Touch Sensor Application Note `_. If you want to test touch sensors in various configurations without building them on your own, check the `Guide for ESP32-Sense Development Kit `_. +.. only:: esp32s2 + + {IDF_TARGET_NAME} can handle up to 14 capacitive touch pads / GPIOs. + + The sensing pads can be arranged in different combinations (e.g., matrix, slider), so that a larger area or more points can be detected. The touch pad sensing process is under the control of a hardware-implemented finite-state machine (FSM) which is initiated by software or a dedicated hardware timer. + +Design, operation, and control registers of a touch sensor are discussed in `{IDF_TARGET_NAME} Technical Reference Manual `_ (PDF). Please refer to this manual for additional details on how this subsystem works. + +In-depth design details of touch sensors and firmware development guidelines for {IDF_TARGET_NAME} are available in `Touch Sensor Application Note `_. + +.. only:: esp32 + + If you want to test touch sensors in various configurations without building them on your own, check the `Guide for ESP32-Sense Development Kit `_. Functionality Overview @@ -29,13 +41,13 @@ Description of API is broken down into groups of functions to provide a quick ov - Setting up interrupts to report touch detection - Waking up from Sleep mode on interrupt -For detailed description of a particular function, please go to Section :ref:`touch_pad-api-reference`. Practical implementation of this API is covered in Section :ref:`touch_pad-api-examples`. +For detailed description of a particular function, please go to Section :ref:`touch_pad-api-reference`. Practical implementation of this API is covered in Section :ref:`Application Examples `. Initialization ^^^^^^^^^^^^^^ -Before using a touch pad, you need to initialize the touch pad driver by calling the function :cpp:func:`touch_pad_init`. This function sets several ``.._DEFAULT`` driver parameters listed in :ref:`touch_pad-api-reference` under *Macros*. It also removes the information about which pads have been touched before, if any, and disables interrupts. +Before using a touch pad, you need to initialize the touch pad driver by calling the function :cpp:func:`touch_pad_init`. This function sets several ``.._DEFAULT`` driver parameters listed in :ref:`touch_pad-api-reference` under *Macros*. It also removes the information about which pads have been touched before, if any, and disables interrupts. If the driver is not required anymore, deinitialize it by calling :cpp:func:`touch_pad_deinit`. @@ -43,7 +55,7 @@ If the driver is not required anymore, deinitialize it by calling :cpp:func:`tou Configuration ^^^^^^^^^^^^^ -Enabling the touch sensor functionality for a particular GPIO is done with :cpp:func:`touch_pad_config`. +Enabling the touch sensor functionality for a particular GPIO is done with :cpp:func:`touch_pad_config`. Use the function :cpp:func:`touch_pad_set_fsm_mode` to select if touch pad measurement (operated by FSM) should be started automatically by a hardware timer, or by software. If software mode is selected, use :cpp:func:`touch_pad_sw_start` to start the FSM. @@ -51,18 +63,28 @@ Use the function :cpp:func:`touch_pad_set_fsm_mode` to select if touch pad measu Touch State Measurements ^^^^^^^^^^^^^^^^^^^^^^^^ -The following two functions come in handy to read raw or filtered measurements from the sensor: +.. only:: esp32 -* :cpp:func:`touch_pad_read` -* :cpp:func:`touch_pad_read_filtered` + The following two functions come in handy to read raw or filtered measurements from the sensor: -They can also be used, for example, to evaluate a particular touch pad design by checking the range of sensor readings when a pad is touched or released. This information can be then used to establish a touch threshold. + * :cpp:func:`touch_pad_read_raw_data` + * :cpp:func:`touch_pad_read_filtered` -.. note:: + They can also be used, for example, to evaluate a particular touch pad design by checking the range of sensor readings when a pad is touched or released. This information can be then used to establish a touch threshold. - Before using :cpp:func:`touch_pad_read_filtered`, you need to initialize and configure the filter by calling specific filter functions described in Section `Filtering of Measurements`_. + .. note:: -For the demonstration of how to use both read functions, check the application example :example:`peripherals/touch_pad_read`. + Before using :cpp:func:`touch_pad_read_filtered`, you need to initialize and configure the filter by calling specific filter functions described in Section `Filtering of Measurements`_. + +.. only:: esp32s2 + + The following function come in handy to read raw measurements from the sensor: + + * :cpp:func:`touch_pad_read_raw_data` + + It can also be used, for example, to evaluate a particular touch pad design by checking the range of sensor readings when a pad is touched or released. This information can be then used to establish a touch threshold. + +For the demonstration of how to read the touch pad data, check the application example :example:`peripherals/touch_pad_read`. Optimization of Measurements @@ -81,14 +103,14 @@ The following list summarizes available measurement parameters and corresponding * Measurement time: :cpp:func:`touch_pad_set_meas_time` -Relationship between the voltage range (high / low reference voltages), speed (slope), and measurement time is shown in the figure below. +Relationship between the voltage range (high / low reference voltages), speed (slope), and measurement time is shown in the figure below. .. figure:: ../../../_static/touch_pad-measurement-parameters.jpg :align: center - :alt: Touch Pad - relationship between measurement parameters + :alt: Touch Pad - relationship between measurement parameters :figclass: align-center - Touch pad - relationship between measurement parameters + Touch pad - relationship between measurement parameters The last chart *Output* represents the touch sensor reading, i.e., the count of pulses collected within the measurement time. @@ -98,18 +120,28 @@ All functions are provided in pairs to *set* a specific parameter and to *get* t Filtering of Measurements ^^^^^^^^^^^^^^^^^^^^^^^^^ +.. only:: esp32 -If measurements are noisy, you can filter them with provided API functions. Before using the filter, please start it by calling :cpp:func:`touch_pad_filter_start`. + If measurements are noisy, you can filter them with provided API functions. Before using the filter, please start it by calling :cpp:func:`touch_pad_filter_start`. -The filter type is IIR (infinite impulse response), and it has a configurable period that can be set with the function :cpp:func:`touch_pad_set_filter_period`. + The filter type is IIR (infinite impulse response), and it has a configurable period that can be set with the function :cpp:func:`touch_pad_set_filter_period`. -You can stop the filter with :cpp:func:`touch_pad_filter_stop`. If not required anymore, the filter can be deleted by invoking :cpp:func:`touch_pad_filter_delete`. + You can stop the filter with :cpp:func:`touch_pad_filter_stop`. If not required anymore, the filter can be deleted by invoking :cpp:func:`touch_pad_filter_delete`. + +.. only:: esp32s2 + + If measurements are noisy, you can filter them with provided API functions. The {IDF_TARGET_NAME}'s touch functionality provide two sets of APIs for doing this. + + There is an internal touch channel that is not connected to any external GPIO. The measurements from this denoise pad can be used to filters out interference introduced on all channels, such as noise introduced by the power supply and external EMI. + The denoise paramaters are set with the function :cpp:func:`touch_pad_denoise_set_config` and started by with :cpp:func:`touch_pad_denoise_enable` + + There is also a configurable hardware implemented IIR-filter (infinite impulse response). This IIR-filter is configured with the function :cpp:func:`touch_pad_filter_set_config` and enabled by calling :cpp:func:`touch_pad_filter_enable` Touch Detection ^^^^^^^^^^^^^^^ -Touch detection is implemented in ESP32's hardware based on the user-configured threshold and raw measurements executed by FSM. Use the functions :cpp:func:`touch_pad_get_status` to check which pads have been touched and :cpp:func:`touch_pad_clear_status` to clear the touch status information. +Touch detection is implemented in ESP32's hardware based on the user-configured threshold and raw measurements executed by FSM. Use the functions :cpp:func:`touch_pad_get_status` to check which pads have been touched and :cpp:func:`touch_pad_clear_status` to clear the touch status information. Hardware touch detection can also be wired to interrupts. This is described in the next section. @@ -123,7 +155,9 @@ Before enabling an interrupt on a touch detection, you should establish a touch Once a detection threshold is established, it can be set during initialization with :cpp:func:`touch_pad_config` or at the runtime with :cpp:func:`touch_pad_set_thresh`. -In the next step, configure how interrupts are triggered. They can be triggered below or above the threshold, which is set with the function :cpp:func:`touch_pad_set_trigger_mode`. +.. only:: esp32 + + In the next step, configure how interrupts are triggered. They can be triggered below or above the threshold, which is set with the function :cpp:func:`touch_pad_set_trigger_mode`. Finally, configure and manage interrupt calls using the following functions: @@ -132,26 +166,30 @@ Finally, configure and manage interrupt calls using the following functions: When interrupts are operational, you can obtain the information from which particular pad an interrupt came by invoking :cpp:func:`touch_pad_get_status` and clear the pad status with :cpp:func:`touch_pad_clear_status`. -.. note:: +.. only:: esp32 - Interrupts on touch detection operate on raw / unfiltered measurements checked against user established threshold and are implemented in hardware. Enabling the software filtering API (see :ref:`touch_pad-api-filtering-of-measurements`) does not affect this process. + .. note:: + + Interrupts on touch detection operate on raw / unfiltered measurements checked against user established threshold and are implemented in hardware. Enabling the software filtering API (see :ref:`touch_pad-api-filtering-of-measurements`) does not affect this process. + +.. only:: esp32 + + Wakeup from Sleep Mode + ^^^^^^^^^^^^^^^^^^^^^^ + + If touch pad interrupts are used to wake up the chip from a sleep mode, you can select a certain configuration of pads (SET1 or both SET1 and SET2) that should be touched to trigger the interrupt and cause the subsequent wakeup. To do so, use the function :cpp:func:`touch_pad_set_trigger_source`. + + Configuration of required bit patterns of pads may be managed for each 'SET' with: + + * :cpp:func:`touch_pad_set_group_mask` / :cpp:func:`touch_pad_get_group_mask` + * :cpp:func:`touch_pad_clear_group_mask` -Wakeup from Sleep Mode -^^^^^^^^^^^^^^^^^^^^^^ -If touch pad interrupts are used to wake up the chip from a sleep mode, you can select a certain configuration of pads (SET1 or both SET1 and SET2) that should be touched to trigger the interrupt and cause the subsequent wakeup. To do so, use the function :cpp:func:`touch_pad_set_trigger_source`. - -Configuration of required bit patterns of pads may be managed for each 'SET' with: - -* :cpp:func:`touch_pad_set_group_mask` / :cpp:func:`touch_pad_get_group_mask` -* :cpp:func:`touch_pad_clear_group_mask` - - -.. _touch_pad-api-examples: Application Examples -------------------- +.. _touch_pad-api-examples: - Touch sensor read example: :example:`peripherals/touch_pad_read`. - Touch sensor interrupt example: :example:`peripherals/touch_pad_interrupt`. @@ -162,7 +200,8 @@ Application Examples API Reference ------------- -.. include-build-file:: inc/touch_pad.inc +.. include-build-file:: inc/touch_sensor.inc +.. include-build-file:: inc/touch_sensor_common.inc GPIO Lookup Macros ^^^^^^^^^^^^^^^^^^ diff --git a/docs/en/api-reference/peripherals/uart.rst b/docs/en/api-reference/peripherals/uart.rst index 752d90080b..f56373a8b8 100644 --- a/docs/en/api-reference/peripherals/uart.rst +++ b/docs/en/api-reference/peripherals/uart.rst @@ -1,29 +1,38 @@ UART ==== +{IDF_TARGET_UART_NUM:default = "UART1", esp32 = "UART2", esp32s2 = "UART1"} + Overview -------- A Universal Asynchronous Receiver/Transmitter (UART) is a hardware feature that handles communication (i.e., timing requirements and data framing) using widely-adapted asynchronous serial communication interfaces, such as RS232, RS422, RS485. A UART provides a widely adopted and cheap method to realize full-duplex or half-duplex data exchange among different devices. -The ESP32 chip has three UART controllers (UART0, UART1, and UART2) that feature an identical set of registers for ease of programming and flexibility. Each UART controller is independently configurable with parameters such as baud rate, data bit length, bit ordering, number of stop bits, parity bit etc. All the controllers are compatible with UART-enabled devices from various manufacturers and can also support Infrared Data Association protocols (IrDA). +.. only:: esp32 + The ESP32 chip has three UART controllers (UART0, UART1, and UART2) that feature an identical set of registers for ease of programming and flexibility. + +.. only:: esp32s2 + + The ESP32-S2 chip has two UART controllers (UART0 and UART1) that feature an identical set of registers for ease of programming and flexibility. + +Each UART controller is independently configurable with parameters such as baud rate, data bit length, bit ordering, number of stop bits, parity bit etc. All the controllers are compatible with UART-enabled devices from various manufacturers and can also support Infrared Data Association protocols (IrDA). Functional Overview ------------------- -The following overview describes how to establish communication between an ESP32 and other UART devices using the functions and data types of the UART driver. The overview reflects a typical programming workflow and is broken down into the sections provided below: +The following overview describes how to establish communication between an {IDF_TARGET_NAME} and other UART devices using the functions and data types of the UART driver. The overview reflects a typical programming workflow and is broken down into the sections provided below: 1. :ref:`uart-api-setting-communication-parameters` - Setting baud rate, data bits, stop bits, etc. 2. :ref:`uart-api-setting-communication-pins` - Assigning pins for connection to a device. -3. :ref:`uart-api-driver-installation` - Allocating ESP32's resources for the UART driver. +3. :ref:`uart-api-driver-installation` - Allocating {IDF_TARGET_NAME}'s resources for the UART driver. 4. :ref:`uart-api-running-uart-communication` - Sending / receiving data 5. :ref:`uart-api-using-interrupts` - Triggering interrupts on specific communication events 6. :ref:`uart-api-deleting-driver` - Freeing allocated resources if a UART communication is no longer required Steps 1 to 3 comprise the configuration stage. Step 4 is where the UART starts operating. Steps 5 and 6 are optional. -The UART driver's functions identify each of the three UART controllers using :cpp:type:`uart_port_t`. This identification is needed for all the following function calls. +The UART driver's functions identify each of the UART controllers using :cpp:type:`uart_port_t`. This identification is needed for all the following function calls. .. _uart-api-setting-communication-parameters: @@ -41,7 +50,7 @@ Call the function :cpp:func:`uart_param_config` and pass to it a :cpp:type:`uart .. code-block:: c - const int uart_num = UART_NUM_2; + const int uart_num = {IDF_TARGET_UART_NUM}; uart_config_t uart_config = { .baud_rate = 115200, .data_bits = UART_DATA_8_BITS, @@ -92,8 +101,19 @@ The same macro should be specified for pins that will not be used. .. code-block:: c - // Set UART pins(TX: IO16 (UART2 default), RX: IO17 (UART2 default), RTS: IO18, CTS: IO19) - ESP_ERROR_CHECK(uart_set_pin(UART_NUM_2, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, 18, 19)); +.. only:: esp32 + + :: + + // Set UART pins(TX: IO16 (UART2 default), RX: IO17 (UART2 default), RTS: IO18, CTS: IO19) + ESP_ERROR_CHECK(uart_set_pin(UART_NUM_2, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, 18, 19)); + +.. only:: esp32s2 + + :: + + // Set UART pins(TX: IO17 (UART1 default), RX: IO18 (UART1 default), RTS: IO19, CTS: IO20) + ESP_ERROR_CHECK(uart_set_pin(UART_NUM_1, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE, 19, 20)); .. _uart-api-driver-installation: @@ -108,7 +128,7 @@ Once the communication pins are set, install the driver by calling :cpp:func:`ua - Event queue handle and size - Flags to allocate an interrupt -The function will allocate the required ESP32 resources for the UART driver. +The function will allocate the required internal resources for the UART driver. .. code-block:: c @@ -116,7 +136,7 @@ The function will allocate the required ESP32 resources for the UART driver. const int uart_buffer_size = (1024 * 2); QueueHandle_t uart_queue; // Install UART driver using an event queue here - ESP_ERROR_CHECK(uart_driver_install(UART_NUM_2, uart_buffer_size, \ + ESP_ERROR_CHECK(uart_driver_install({IDF_TARGET_UART_NUM}, uart_buffer_size, \ uart_buffer_size, 10, &uart_queue, 0)); Once this step is complete, you can connect the external UART device and check the communication. @@ -181,7 +201,7 @@ Once the data is received by the UART and saved in the Rx FIFO buffer, it needs .. code-block:: c // Read data from UART. - const int uart_num = UART_NUM_2; + const int uart_num = {IDF_TARGET_UART_NUM}; uint8_t data[128]; int length = 0; ESP_ERROR_CHECK(uart_get_buffered_data_len(uart_num, (size_t*)&length)); @@ -212,7 +232,7 @@ The UART controller supports a number of communication modes. A mode can be sele Using Interrupts ^^^^^^^^^^^^^^^^ -There are many interrupts that can be generated following specific UART states or detected errors. The full list of available interrupts is provided in `ESP32 Technical Reference Manual `_ (PDF). You can enable or disable specific interrupts by calling :cpp:func:`uart_enable_intr_mask` or :cpp:func:`uart_disable_intr_mask` respectively. The mask of all interrupts is available as :c:macro:`UART_INTR_MASK`. +There are many interrupts that can be generated following specific UART states or detected errors. The full list of available interrupts is provided in the SoC Technical Reference Manual. You can enable or disable specific interrupts by calling :cpp:func:`uart_enable_intr_mask` or :cpp:func:`uart_disable_intr_mask` respectively. The mask of all interrupts is available as :c:macro:`UART_INTR_MASK`. By default, the :cpp:func:`uart_driver_install` function installs the driver's internal interrupt handler to manage the Tx and Rx ring buffers and provides high-level API functions like events (see below). It is also possible to register a lower level interrupt handler instead using :cpp:func:`uart_isr_register`, and to free it again using :cpp:func:`uart_isr_free`. Some UART driver functions which use the Tx and Rx ring buffers, events, etc. will not automatically work in this case - it is necessary to handle the interrupts directly in the ISR. Inside the custom handler implementation, clear the interrupt status bits using :cpp:func:`uart_clear_intr_status`. @@ -251,19 +271,19 @@ Overview of RS485 specific communication options .. note:: - The following section will use ``[UART_REGISTER_NAME].[UART_FIELD_BIT]`` to refer to UART register fields/bits. To find more information on a specific option bit, open `Register Summary in the ESP32 Technical Reference Manual `_ (PDF), use the register name to navigate to the register description and then find the field/bit. + The following section will use ``[UART_REGISTER_NAME].[UART_FIELD_BIT]`` to refer to UART register fields/bits. To find more information on a specific option bit, open the Register Summary section of the SoC Technical Reference Manual. Use the register name to navigate to the register description and then find the field/bit. - ``UART_RS485_CONF_REG.UART_RS485_EN``: setting this bit enables RS485 communication mode support. - ``UART_RS485_CONF_REG.UART_RS485TX_RX_EN``: if this bit is set, the transmitter's output signal loops back to the receiver's input signal. - ``UART_RS485_CONF_REG.UART_RS485RXBY_TX_EN``: if this bit is set, the transmitter will still be sending data if the receiver is busy (remove collisions automatically by hardware). -The ESP32's RS485 UART hardware can detect signal collisions during transmission of a datagram and generate the interrupt ``UART_RS485_CLASH_INT`` if this interrupt is enabled. The term collision means that a transmitted datagram is not equal to the one received on the other end. Data collisions are usually associated with the presence of other active devices on the bus or might occur due to bus errors. +The {IDF_TARGET_NAME}'s RS485 UART hardware can detect signal collisions during transmission of a datagram and generate the interrupt ``UART_RS485_CLASH_INT`` if this interrupt is enabled. The term collision means that a transmitted datagram is not equal to the one received on the other end. Data collisions are usually associated with the presence of other active devices on the bus or might occur due to bus errors. The collision detection feature allows handling collisions when their interrupts are activated and triggered. The interrupts ``UART_RS485_FRM_ERR_INT`` and ``UART_RS485_PARITY_ERR_INT`` can be used with the collision detection feature to control frame errors and parity bit errors accordingly in RS485 mode. This functionality is supported in the UART driver and can be used by selecting the :cpp:enumerator:`UART_MODE_RS485_APP_CTRL` mode (see the function :cpp:func:`uart_set_mode`). The collision detection feature can work with circuit A and circuit C (see Section `Interface Connection Options`_). In the case of using circuit A or B, the RTS pin connected to the DE pin of the bus driver should be controlled by the user application. Use the function :cpp:func:`uart_get_collision_flag` to check if the collision detection flag has been raised. -The ESP32's UART controllers themselves do not support half-duplex communication as they cannot provide automatic control of the RTS pin connected to the ~RE/DE input of RS485 bus driver. However, half-duplex communication can be achieved via software control of the RTS pin by the UART driver. This can be enabled by selecting the :cpp:enumerator:`UART_MODE_RS485_HALF_DUPLEX` mode when calling :cpp:func:`uart_set_mode`. +The {IDF_TARGET_NAME} UART controllers themselves do not support half-duplex communication as they cannot provide automatic control of the RTS pin connected to the ~RE/DE input of RS485 bus driver. However, half-duplex communication can be achieved via software control of the RTS pin by the UART driver. This can be enabled by selecting the :cpp:enumerator:`UART_MODE_RS485_HALF_DUPLEX` mode when calling :cpp:func:`uart_set_mode`. Once the host starts writing data to the Tx FIFO buffer, the UART driver automatically asserts the RTS pin (logic 1); once the last bit of the data has been transmitted, the driver de-asserts the RTS pin (logic 0). To use this mode, the software would have to disable the hardware flow control function. This mode works with all the used circuits shown below. @@ -271,7 +291,7 @@ Once the host starts writing data to the Tx FIFO buffer, the UART driver automat Interface Connection Options ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This section provides example schematics to demonstrate the basic aspects of ESP32's RS485 interface connection. +This section provides example schematics to demonstrate the basic aspects of {IDF_TARGET_NAME}'s RS485 interface connection. .. note:: @@ -291,7 +311,7 @@ Circuit A: Collision Detection Circuit RXD <------| R | | B|----------<> B TXD ------>| D ADM483 | - ESP32 | | RS485 bus side + ESP | | RS485 bus side RTS ------>| DE | | A|----------<> A +----| /RE | @@ -299,12 +319,13 @@ Circuit A: Collision Detection Circuit | | GND GND -This circuit is preferable because it allows for collision detection and is quite simple at the same time. The receiver in the line driver is constantly enabled, which allows the UART to monitor the RS485 bus. Echo suppression is performed by the ESP32 hardware when the bit ``UART_RS485_CONF_REG.UART_RS485TX_RX_EN`` is enabled. +This circuit is preferable because it allows for collision detection and is quite simple at the same time. The receiver in the line driver is constantly enabled, which allows the UART to monitor the RS485 bus. Echo suppression is performed by the UART peripheral when the bit ``UART_RS485_CONF_REG.UART_RS485TX_RX_EN`` is enabled. Circuit B: Manual Switching Transmitter/Receiver Without Collision Detection """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + .. code-block:: none VCC ---------------+ @@ -313,7 +334,7 @@ Circuit B: Manual Switching Transmitter/Receiver Without Collision Detection RXD <------| R | | B|-----------<> B TXD ------>| D ADM483 | - ESP32 | | RS485 bus side + ESP | | RS485 bus side RTS --+--->| DE | | | A|-----------<> A +----| /RE | @@ -371,7 +392,7 @@ The table below describes the code examples available in the directory :example: * - :example:`peripherals/uart/uart_select` - Using synchronous I/O multiplexing for UART file descriptors. * - :example:`peripherals/uart/uart_echo_rs485` - - Setting up UART driver to communicate over RS485 interface in half-duplex mode. This example is similar to :example:`peripherals/uart/uart_echo` but allows communication through an RS485 interface chip connected to ESP32 pins. + - Setting up UART driver to communicate over RS485 interface in half-duplex mode. This example is similar to :example:`peripherals/uart/uart_echo` but allows communication through an RS485 interface chip connected to {IDF_TARGET_NAME} pins. * - :example:`peripherals/uart/nmea0183_parser` - Obtaining GPS information by parsing NMEA0183 statements received from GPS via the UART peripheral. diff --git a/docs/en/contribute/add-ons-reference.rst b/docs/en/contribute/add-ons-reference.rst index 2e3a1bcbe4..49d0d6e47f 100644 --- a/docs/en/contribute/add-ons-reference.rst +++ b/docs/en/contribute/add-ons-reference.rst @@ -150,7 +150,11 @@ Other Extensions An extension for replacing generic target related names with the idf_target passed to the Sphinx command line. This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` will, if the backspaces are removed, render as This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`. - This cannot be used inside tables. + Also supports markup for defining local (single .rst-file) substitions with the following syntax: {\IDF_TARGET_TX_PIN:default="IO3",esp32="IO4",esp32s2="IO5"} + + This will define a replacement of the tag {\IDF_TARGET_TX_PIN} in the current rst-file. + + These replacements cannot be used inside markup that rely on allignment of characters, e.g. tables. Related Documents ----------------- From 35db219be26b68fa247abcfe21df5b48f7f920c4 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Wed, 18 Dec 2019 16:32:18 +1100 Subject: [PATCH 25/47] docs: Manage parallel sphinx-build runs with optional parallel jobs within them --- docs/build_docs.py | 116 ++++++++++++++----- docs/idf_extensions/build_system/__init__.py | 1 - 2 files changed, 89 insertions(+), 28 deletions(-) diff --git a/docs/build_docs.py b/docs/build_docs.py index 014d36b741..72029c4d4a 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -8,7 +8,10 @@ # # Specific custom docs functionality should be added in conf_common.py or in a Sphinx extension, not here. # +from __future__ import print_function import argparse +import math +import multiprocessing import os import os.path import subprocess @@ -37,6 +40,10 @@ def main(): required=False) parser.add_argument("--target", "-t", choices=TARGETS, required=False) parser.add_argument("--build-dir", "-b", type=str, default="_build") + parser.add_argument("--sphinx-parallel-builds", "-p", choices=["auto"] + [str(x) for x in range(8)], + help="Parallel Sphinx builds - number of independent Sphinx builds to run", default="auto") + parser.add_argument("--sphinx-parallel-jobs", "-j", choices=["auto"] + [str(x) for x in range(8)], + help="Sphinx parallel jobs argument - number of threads for each Sphinx build to use", default="auto") args = parser.parse_args() @@ -52,39 +59,94 @@ def main(): else: targets = [args.target] - for language in languages: - for target in targets: - build_dir = os.path.realpath(os.path.join(args.build_dir, language, target)) - build_docs(language, target, build_dir) + num_sphinx_builds = len(languages) * len(targets) + num_cpus = multiprocessing.cpu_count() -def build_docs(language, target, build_dir): - print("Building language:%s target:%s build_dir:%s" % (language, target, build_dir)) + if args.sphinx_parallel_builds == "auto": + # at most one sphinx build per CPU, up to the number of CPUs + args.sphinx_parallel_builds = min(num_sphinx_builds, num_cpus) + else: + args.sphinx_parallel_builds = int(args.sphinx_parallel_builds) + + if args.sphinx_parallel_jobs == "auto": + # N CPUs per build job, rounded up - (maybe smarter to round down to avoid contention, idk) + args.sphinx_parallel_jobs = int(math.ceil(num_cpus / args.sphinx_parallel_builds)) + else: + args.sphinx_parallel_jobs = int(args.sphinx_parallel_jobs) + + print("Will use %d parallel builds and %d jobs per build" % (args.sphinx_parallel_builds, args.sphinx_parallel_jobs)) + pool = multiprocessing.Pool(args.sphinx_parallel_builds) + + # make a list of all combinations of build_docs() args as tuples + # + # there's probably a fancy way to do this with itertools but this way is actually readable + entries = [] + for target in targets: + for language in languages: + build_dir = os.path.realpath(os.path.join(args.build_dir, language, target)) + entries.append((language, target, build_dir, args.sphinx_parallel_jobs)) + + print(entries) + failures = pool.map(call_build_docs, entries) + if any(failures): + if len(entries) > 1: + print("The following language/target combinations failed to build:") + for f in failures: + if f is not None: + print("language: %s target: %s" % (f[0], f[1])) + raise SystemExit(2) + + +def call_build_docs(entry): + build_docs(*entry) + + +def build_docs(language, target, build_dir, sphinx_parallel_jobs=1): + # Note: because this runs in a multiprocessing Process, everything which happens here should be isolated to a single process + # (ie it doesn't matter if Sphinx is using global variables, as they're it's own copy of the global variables) + + # wrap stdout & stderr in a way that lets us see which build_docs instance they come from + # + # this doesn't apply to subprocesses, they write to OS stdout & stderr so no prefix appears + prefix = "%s/%s: " % (language, target) + + print("Building in build_dir:%s" % (build_dir)) try: os.makedirs(build_dir) except OSError: pass - try: - environ = {} - environ.update(os.environ) - environ['BUILDDIR'] = build_dir - args = [sys.executable, "-m", "sphinx", - "-j", "auto", # use all the cores! (where possible) - "-b", "html", # TODO: PDFs - "-d", os.path.join(build_dir, "doctrees"), - # TODO: support multiple sphinx-warning.log files, somehow - "-w", "sphinx-warning.log", - "-t", target, - "-D", "idf_target={}".format(target), - os.path.join(os.path.abspath(os.path.dirname(__file__)), language), # srcdir for this language - os.path.join(build_dir, "html") # build directory - ] - cwd = build_dir # also run sphinx in the build directory - print("Running '{}'".format(" ".join(args))) - subprocess.check_call(args, cwd=cwd, env=environ) - except subprocess.CalledProcessError: - print("Sphinx failed for language:%s target:%s" % (language, target)) - raise SystemExit(1) # rest of the details should be in stdout + environ = {} + environ.update(os.environ) + environ['BUILDDIR'] = build_dir + + args = [sys.executable, "-u", "-m", "sphinx.cmd.build", + "-j", str(sphinx_parallel_jobs), + "-b", "html", # TODO: PDFs + "-d", os.path.join(build_dir, "doctrees"), + # TODO: support multiple sphinx-warning.log files, somehow + "-w", "sphinx-warning.log", + "-t", target, + "-D", "idf_target={}".format(target), + os.path.join(os.path.abspath(os.path.dirname(__file__)), language), # srcdir for this language + os.path.join(build_dir, "html") # build directory + ] + cwd = build_dir # also run sphinx in the build directory + + os.chdir(cwd) + print("Running '%s'" % (" ".join(args))) + + try: + # Note: we can't call sphinx.cmd.build.main() here as multiprocessing doesn't est >1 layer deep + # and sphinx.cmd.build() also does a lot of work in the calling thread, especially for j ==1, + # so using a Pyhthon thread for this part is a poor option (GIL) + p = subprocess.Popen(args, stdout=subprocess.PIPE, stderr=subprocess.STDOUT) + for c in iter(lambda: p.stdout.readline(), ''): + sys.stdout.write(prefix) + sys.stdout.write(c) + except KeyboardInterrupt: # this seems to be the only way to get Ctrl-C to kill everything? + p.kill() + return if __name__ == "__main__": diff --git a/docs/idf_extensions/build_system/__init__.py b/docs/idf_extensions/build_system/__init__.py index e990633c5a..11c6ab1be4 100644 --- a/docs/idf_extensions/build_system/__init__.py +++ b/docs/idf_extensions/build_system/__init__.py @@ -39,7 +39,6 @@ def setup(app): except KeyError: idf_path = os.path.realpath(os.path.join(os.path.dirname(__file__), '..')) - app.add_config_value('docs_root', os.path.join(idf_path, "docs"), 'env') app.add_config_value('idf_path', idf_path, 'env') app.add_config_value('build_dir', build_dir, 'env') # not actually an IDF thing From ee03e04947fb8a018b46012e0e71a2bee55c29a1 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 22 Nov 2019 18:58:32 +1100 Subject: [PATCH 26/47] docs: Run build_docs script in ci --- .gitlab-ci.yml | 8 +++-- tools/ci/config/build.yml | 52 +++++++++++++++++++-------------- tools/ci/config/deploy.yml | 42 +++++++++++++++++--------- tools/ci/config/host-test.yml | 25 ---------------- tools/ci/config/post_deploy.yml | 42 ++++++++++++++++++++++++++ tools/ci/config/pre_check.yml | 18 ++++++++++++ 6 files changed, 125 insertions(+), 62 deletions(-) create mode 100644 tools/ci/config/post_deploy.yml diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index d20088dad1..3026757591 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -6,7 +6,7 @@ stages: - target_test - post_check - deploy - - post_check + - post_deploy variables: # System environment @@ -76,6 +76,9 @@ variables: rm -rf "$CUSTOM_TOOLCHAIN_PATH" .setup_tools_unless_target_test: &setup_tools_unless_target_test | + if [[ -n "$IDF_DONT_USE_MIRRORS" ]]; then + export IDF_MIRROR_PREFIX_MAP= + fi if [[ "$SETUP_TOOLS" == "1" || "$CI_JOB_STAGE" != "target_test" ]]; then tools/idf_tools.py --non-interactive install && eval "$(tools/idf_tools.py --non-interactive export)" || exit 1 fi @@ -142,7 +145,7 @@ after_script: tags: - host_test dependencies: [] - extends: .before_script_lesser_nofilter + extends: .before_script_lesser .macos_build_template: stage: build @@ -163,3 +166,4 @@ include: - '/tools/ci/config/target-test.yml' - '/tools/ci/config/post_check.yml' - '/tools/ci/config/deploy.yml' + - '/tools/ci/config/post_deploy.yml' diff --git a/tools/ci/config/build.yml b/tools/ci/config/build.yml index 2edfa6ec8f..b6af246e08 100644 --- a/tools/ci/config/build.yml +++ b/tools/ci/config/build.yml @@ -186,25 +186,16 @@ build_examples_cmake_esp32s2: # If you want to add new build example jobs, please add it into dependencies of `.example_test_template` -build_docs: +.build_docs_template: &build_docs_template stage: build - image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG + image: $CI_DOCKER_REGISTRY/esp-idf-doc-env:esp-docs-20200204-ea18dcbd tags: - build_docs artifacts: when: always paths: - # English version of documentation - - docs/en/doxygen-warning-log.txt - - docs/en/sphinx-warning-log.txt - - docs/en/sphinx-warning-log-sanitized.txt - - docs/en/_build/html - - docs/sphinx-err-* - # Chinese version of documentation - - docs/zh_CN/doxygen-warning-log.txt - - docs/zh_CN/sphinx-warning-log.txt - - docs/zh_CN/sphinx-warning-log-sanitized.txt - - docs/zh_CN/_build/html + - docs/_build/*/*/*.txt + - docs/_build/*/*/html/* expire_in: 4 days only: variables: @@ -212,17 +203,34 @@ build_docs: - $BOT_LABEL_BUILD - $BOT_LABEL_BUILD_DOCS - $BOT_LABEL_REGULAR_TEST + dependencies: [] script: - cd docs - - ./check_lang_folder_sync.sh - - cd en - - make gh-linkcheck - - make html - - ../check_doc_warnings.sh - - cd ../zh_CN - - make gh-linkcheck - - make html - - ../check_doc_warnings.sh + - ./build_docs.py -l $DOCLANG -t $DOCTGT build + +build_docs_en_esp32: + extends: .build_docs_template + variables: + DOCLANG: "en" + DOCTGT: "esp32" + +build_docs_en_esp32s2: + extends: .build_docs_template + variables: + DOCLANG: "en" + DOCTGT: "esp32s2" + +build_docs_zh_CN_esp32: + extends: .build_docs_template + variables: + DOCLANG: "zh_CN" + DOCTGT: "esp32" + +build_docs_zh_CN_esp32s2: + extends: .build_docs_template + variables: + DOCLANG: "zh_CN" + DOCTGT: "esp32s2" test_build_system: extends: .build_template diff --git a/tools/ci/config/deploy.yml b/tools/ci/config/deploy.yml index c7118b7486..acdd0e125d 100644 --- a/tools/ci/config/deploy.yml +++ b/tools/ci/config/deploy.yml @@ -70,6 +70,14 @@ push_to_github: - git remote add github git@github.com:espressif/esp-idf.git - tools/ci/push_to_github.sh +.upload_doc_archive: &upload_doc_archive | + cd docs/_build/$DOCLANG/$DOCTGT + mv html $GIT_VER + tar czf $GIT_VER.tar.gz $GIT_VER + scp $GIT_VER.tar.gz $DOCS_SERVER:$DOCS_PATH/$DOCLANG/$DOCTGT + ssh $DOCS_SERVER -x "cd $DOCS_PATH/$DOCLANG/$DOCTGT && tar xzf $GIT_VER.tar.gz && rm -f latest && ln -s $GIT_VER latest" + cd - + deploy_docs: stage: deploy image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG @@ -86,7 +94,10 @@ deploy_docs: - $BOT_TRIGGER_WITH_LABEL == null - $BOT_LABEL_BUILD_DOCS dependencies: - - build_docs + - build_docs_en_esp32 + - build_docs_en_esp32s2 + - build_docs_zh_CN_esp32 + - build_docs_zh_CN_esp32s2 extends: .before_script_lesser script: - mkdir -p ~/.ssh @@ -96,19 +107,24 @@ deploy_docs: - chmod 600 ~/.ssh/id_rsa - echo -e "Host $DOCS_SERVER\n\tStrictHostKeyChecking no\n\tUser $DOCS_SERVER_USER\n" >> ~/.ssh/config - export GIT_VER=$(git describe --always) - - cd docs/en/_build/ - - mv html $GIT_VER - - tar czvf $GIT_VER.tar.gz $GIT_VER - - scp $GIT_VER.tar.gz $DOCS_SERVER:$DOCS_PATH/en - - ssh $DOCS_SERVER -x "cd $DOCS_PATH/en && tar xzvf $GIT_VER.tar.gz && rm -f latest && ln -s $GIT_VER latest" - - cd ../../zh_CN/_build/ - - mv html $GIT_VER - - tar czvf $GIT_VER.tar.gz $GIT_VER - - scp $GIT_VER.tar.gz $DOCS_SERVER:$DOCS_PATH/zh_CN - - ssh $DOCS_SERVER -x "cd $DOCS_PATH/zh_CN && tar xzvf $GIT_VER.tar.gz && rm -f latest && ln -s $GIT_VER latest" + + - DOCLANG=en; DOCTGT=esp32 + - *upload_doc_archive + + - DOCLANG=en; DOCTGT=esp32s2 + - *upload_doc_archive + + - DOCLANG=zh_CN; DOCTGT=esp32 + - *upload_doc_archive + + - DOCLANG=zh_CN; DOCTGT=esp32s2 + - *upload_doc_archive + # add link to preview doc - - echo "[document preview][en] $CI_DOCKER_REGISTRY/docs/esp-idf/en/${GIT_VER}/index.html" - - echo "[document preview][zh_CN] $CI_DOCKER_REGISTRY/docs/esp-idf/zh_CN/${GIT_VER}/index.html" + - echo "[document preview][en][esp32] https://$CI_DOCKER_REGISTRY/docs/esp-idf/en/esp32/${GIT_VER}/index.html" + - echo "[document preview][en][esp32s2] https://$CI_DOCKER_REGISTRY/docs/esp-idf/en/esp32s2/${GIT_VER}/index.html" + - echo "[document preview][zh_CN][esp32] https://$CI_DOCKER_REGISTRY/docs/esp-idf/zh_CN/esp32/${GIT_VER}/index.html" + - echo "[document preview][zh_CN][esp32s2] https://$CI_DOCKER_REGISTRY/docs/esp-idf/zh_CN/esp32s2/${GIT_VER}/index.html" deploy_test_result: stage: deploy diff --git a/tools/ci/config/host-test.yml b/tools/ci/config/host-test.yml index 928018b899..bc09f262d5 100644 --- a/tools/ci/config/host-test.yml +++ b/tools/ci/config/host-test.yml @@ -290,28 +290,3 @@ test_sysviewtrace_proc: script: - cd ${IDF_PATH}/tools/esp_app_trace/test/sysview - ${IDF_PATH}/tools/ci/multirun_with_pyenv.sh ./test.sh - -check_doc_links: - stage: host_test - image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG - tags: - - check_doc_links - only: - refs: - # can only be triggered - - triggers - variables: - - $BOT_TRIGGER_WITH_LABEL == null - - $BOT_LABEL_BUILD_DOCS - artifacts: - paths: - - docs/_build/linkcheck - expire_in: 1 week - dependencies: [] - script: - # must be triggered with CHECK_LINKS=Yes, otherwise exit without test - - test "$CHECK_LINKS" = "Yes" || exit 0 - # can only run on master branch (otherwise the commit is not on Github yet) - - test "${CI_COMMIT_REF_NAME}" = "master" || exit 0 - - cd docs - - make linkcheck diff --git a/tools/ci/config/post_deploy.yml b/tools/ci/config/post_deploy.yml new file mode 100644 index 0000000000..024b0c5d24 --- /dev/null +++ b/tools/ci/config/post_deploy.yml @@ -0,0 +1,42 @@ +.check_doc_links_template: &check_doc_links_template + stage: post_deploy + image: $CI_DOCKER_REGISTRY/esp-idf-doc-env:esp-docs-20200204-ea18dcbd + tags: [ "build", "amd64", "internet" ] + only: + - master + - /^release\/v/ + - /^v\d+\.\d+(\.\d+)?($|-)/ + artifacts: + when: always + paths: + - docs/_build/*/*/*.txt + expire_in: 1 week + allow_failure: true + dependencies: [] + script: + - cd docs + - ./build_docs.py -l $DOCLANG -t $DOCTGT linkcheck + +check_doc_links_en_esp32: + extends: .check_doc_links_template + variables: + DOCLANG: "en" + DOCTGT: "esp32" + +check_doc_links_en_esp32s2: + extends: .check_doc_links_template + variables: + DOCLANG: "en" + DOCTGT: "esp32s2" + +check_doc_links_zh_CN_esp32: + extends: .check_doc_links_template + variables: + DOCLANG: "zh_CN" + DOCTGT: "esp32" + +check_doc_links_zh_CN_esp32s2: + extends: .check_doc_links_template + variables: + DOCLANG: "zh_CN" + DOCTGT: "esp32s2" diff --git a/tools/ci/config/pre_check.yml b/tools/ci/config/pre_check.yml index 2acb320eff..6e23e0cfc2 100644 --- a/tools/ci/config/pre_check.yml +++ b/tools/ci/config/pre_check.yml @@ -8,6 +8,24 @@ check_permissions: script: - tools/ci/check-executable.sh +check_docs_lang_sync: + extends: .check_job_template + stage: pre_check + variables: + SUBMODULES_TO_FETCH: "none" + script: + - cd docs + - ./check_lang_folder_sync.sh + +check_docs_gh_links: + extends: .build_docs_template + stage: pre_check + variables: + SUBMODULES_TO_FETCH: "none" + script: + - cd docs + - ./build_docs.py gh-linkcheck + check_version: extends: .check_job_template # Don't run this for feature/bugfix branches, so that it is possible to modify From a2516c6188eda8a9bac64513c0975397c578872b Mon Sep 17 00:00:00 2001 From: Anton Maklakov Date: Wed, 4 Dec 2019 01:26:05 +0700 Subject: [PATCH 27/47] doc: Add a link to CN translation for power_management_esp32 --- docs/zh_CN/api-reference/system/inc/power_management_esp32.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/zh_CN/api-reference/system/inc/power_management_esp32.rst diff --git a/docs/zh_CN/api-reference/system/inc/power_management_esp32.rst b/docs/zh_CN/api-reference/system/inc/power_management_esp32.rst new file mode 100644 index 0000000000..25cdae4c4f --- /dev/null +++ b/docs/zh_CN/api-reference/system/inc/power_management_esp32.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/system/inc/power_management_esp32.rst From 50fcdf115d146fed8f608e043cdf97a67cd3d16d Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Wed, 8 Jan 2020 15:23:38 +1100 Subject: [PATCH 28/47] doc builder: Change default to 1 job per Sphinx instance, add a warning --- docs/build_docs.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/build_docs.py b/docs/build_docs.py index 72029c4d4a..956f7783e8 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -43,7 +43,7 @@ def main(): parser.add_argument("--sphinx-parallel-builds", "-p", choices=["auto"] + [str(x) for x in range(8)], help="Parallel Sphinx builds - number of independent Sphinx builds to run", default="auto") parser.add_argument("--sphinx-parallel-jobs", "-j", choices=["auto"] + [str(x) for x in range(8)], - help="Sphinx parallel jobs argument - number of threads for each Sphinx build to use", default="auto") + help="Sphinx parallel jobs argument - number of threads for each Sphinx build to use", default="1") args = parser.parse_args() @@ -77,6 +77,9 @@ def main(): print("Will use %d parallel builds and %d jobs per build" % (args.sphinx_parallel_builds, args.sphinx_parallel_jobs)) pool = multiprocessing.Pool(args.sphinx_parallel_builds) + if args.sphinx_parallel_jobs > 1: + print("WARNING: Sphinx parallel jobs currently produce incorrect docs output with Sphinx 1.8.5") + # make a list of all combinations of build_docs() args as tuples # # there's probably a fancy way to do this with itertools but this way is actually readable From fb3edc9c87e153ad0d96b280fcd36953618ef235 Mon Sep 17 00:00:00 2001 From: Anton Maklakov Date: Fri, 3 Jan 2020 18:00:23 +0700 Subject: [PATCH 29/47] docs: Add features to build_docs.py: check warnings, check links, check GH links The old check_doc_warnings.sh was deleted --- docs/build_docs.py | 244 ++++++++++++++++++++++++++++---- docs/check_doc_warnings.sh | 39 ----- docs/doxygen-known-warnings.txt | 0 docs/sphinx-known-warnings.txt | 2 +- tools/ci/executable-list.txt | 1 - 5 files changed, 219 insertions(+), 67 deletions(-) delete mode 100755 docs/check_doc_warnings.sh create mode 100644 docs/doxygen-known-warnings.txt diff --git a/docs/build_docs.py b/docs/build_docs.py index 956f7783e8..3fa5207d90 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -1,4 +1,5 @@ #!/usr/bin/env python +# coding=utf-8 # # Top-level docs builder # @@ -16,10 +17,28 @@ import os import os.path import subprocess import sys +import re +from collections import namedtuple LANGUAGES = ["en", "zh_CN"] TARGETS = ["esp32", "esp32s2"] +SPHINX_WARN_LOG = "sphinx-warning-log.txt" +SPHINX_SANITIZED_LOG = "sphinx-warning-log-sanitized.txt" +SPHINX_KNOWN_WARNINGS = os.path.join(os.environ["IDF_PATH"], "docs", "sphinx-known-warnings.txt") + +DXG_WARN_LOG = "doxygen-warning-log.txt" +DXG_SANITIZED_LOG = "doxygen-warning-log-sanitized.txt" +DXG_KNOWN_WARNINGS = os.path.join(os.environ["IDF_PATH"], "docs", "doxygen-known-warnings.txt") + +SANITIZE_FILENAME_REGEX = re.compile("[^:]*/([^/:]*)(:.*)") +SANITIZE_LINENUM_REGEX = re.compile("([^:]*)(:[0-9]+:)(.*)") + +LogMessage = namedtuple("LogMessage", "original_text sanitized_text") + +languages = LANGUAGES +targets = TARGETS + def main(): # check Python dependencies for docs @@ -34,10 +53,9 @@ def main(): except subprocess.CalledProcessError: raise SystemExit(2) # stdout will already have these errors - parser = argparse.ArgumentParser(description='build_docs.py: Build IDF docs', - prog='build_docs.py') - parser.add_argument("--language", "-l", choices=LANGUAGES, - required=False) + parser = argparse.ArgumentParser(description='build_docs.py: Build IDF docs', prog='build_docs.py') + + parser.add_argument("--language", "-l", choices=LANGUAGES, required=False) parser.add_argument("--target", "-t", choices=TARGETS, required=False) parser.add_argument("--build-dir", "-b", type=str, default="_build") parser.add_argument("--sphinx-parallel-builds", "-p", choices=["auto"] + [str(x) for x in range(8)], @@ -45,20 +63,42 @@ def main(): parser.add_argument("--sphinx-parallel-jobs", "-j", choices=["auto"] + [str(x) for x in range(8)], help="Sphinx parallel jobs argument - number of threads for each Sphinx build to use", default="1") + action_parsers = parser.add_subparsers(dest='action') + + build_parser = action_parsers.add_parser('build', help='Build documentation') + build_parser.add_argument("--check-warnings-only", "-w", action='store_true') + + action_parsers.add_parser('linkcheck', help='Check links (a current IDF revision should be uploaded to GitHub)') + + action_parsers.add_parser('gh-linkcheck', help='Checking for hardcoded GitHub links') + args = parser.parse_args() + global languages if args.language is None: print("Building all languages") languages = LANGUAGES else: languages = [args.language] + global targets if args.target is None: print("Building all targets") targets = TARGETS else: targets = [args.target] + if args.action == "build" or args.action is None: + sys.exit(action_build(args)) + + if args.action == "linkcheck": + sys.exit(action_linkcheck(args)) + + if args.action == "gh-linkcheck": + sys.exit(action_gh_linkcheck(args)) + + +def parallel_call(args, callback): num_sphinx_builds = len(languages) * len(targets) num_cpus = multiprocessing.cpu_count() @@ -68,6 +108,8 @@ def main(): else: args.sphinx_parallel_builds = int(args.sphinx_parallel_builds) + # Force -j1 because sphinx works incorrectly + args.sphinx_parallel_jobs = 1 if args.sphinx_parallel_jobs == "auto": # N CPUs per build job, rounded up - (maybe smarter to round down to avoid contention, idk) args.sphinx_parallel_jobs = int(math.ceil(num_cpus / args.sphinx_parallel_builds)) @@ -90,21 +132,26 @@ def main(): entries.append((language, target, build_dir, args.sphinx_parallel_jobs)) print(entries) - failures = pool.map(call_build_docs, entries) - if any(failures): - if len(entries) > 1: - print("The following language/target combinations failed to build:") - for f in failures: - if f is not None: - print("language: %s target: %s" % (f[0], f[1])) - raise SystemExit(2) + errcodes = pool.map(callback, entries) + print(errcodes) + + is_error = False + for ret in errcodes: + if ret != 0: + print("\nThe following language/target combinations failed to build:") + is_error = True + break + if is_error: + for ret, entry in zip(errcodes, entries): + if ret != 0: + print("language: %s, target: %s, errcode: %d" % (entry[0], entry[1], ret)) + #Don't re-throw real error code from each parallel process + return 1 + else: + return 0 -def call_build_docs(entry): - build_docs(*entry) - - -def build_docs(language, target, build_dir, sphinx_parallel_jobs=1): +def sphinx_call(language, target, build_dir, sphinx_parallel_jobs, buildername): # Note: because this runs in a multiprocessing Process, everything which happens here should be isolated to a single process # (ie it doesn't matter if Sphinx is using global variables, as they're it's own copy of the global variables) @@ -113,11 +160,12 @@ def build_docs(language, target, build_dir, sphinx_parallel_jobs=1): # this doesn't apply to subprocesses, they write to OS stdout & stderr so no prefix appears prefix = "%s/%s: " % (language, target) - print("Building in build_dir:%s" % (build_dir)) + print("Building in build_dir: %s" % (build_dir)) try: os.makedirs(build_dir) except OSError: - pass + print("Cannot call Sphinx in an existing directory!") + return 1 environ = {} environ.update(os.environ) @@ -125,20 +173,20 @@ def build_docs(language, target, build_dir, sphinx_parallel_jobs=1): args = [sys.executable, "-u", "-m", "sphinx.cmd.build", "-j", str(sphinx_parallel_jobs), - "-b", "html", # TODO: PDFs + "-b", buildername, "-d", os.path.join(build_dir, "doctrees"), - # TODO: support multiple sphinx-warning.log files, somehow - "-w", "sphinx-warning.log", + "-w", SPHINX_WARN_LOG, "-t", target, "-D", "idf_target={}".format(target), os.path.join(os.path.abspath(os.path.dirname(__file__)), language), # srcdir for this language - os.path.join(build_dir, "html") # build directory + os.path.join(build_dir, buildername) # build directory ] - cwd = build_dir # also run sphinx in the build directory - os.chdir(cwd) + saved_cwd = os.getcwd() + os.chdir(build_dir) # also run sphinx in the build directory print("Running '%s'" % (" ".join(args))) + ret = 1 try: # Note: we can't call sphinx.cmd.build.main() here as multiprocessing doesn't est >1 layer deep # and sphinx.cmd.build() also does a lot of work in the calling thread, especially for j ==1, @@ -147,9 +195,153 @@ def build_docs(language, target, build_dir, sphinx_parallel_jobs=1): for c in iter(lambda: p.stdout.readline(), ''): sys.stdout.write(prefix) sys.stdout.write(c) + ret = p.wait() + assert (ret is not None) + sys.stdout.flush() except KeyboardInterrupt: # this seems to be the only way to get Ctrl-C to kill everything? p.kill() - return + os.chdir(saved_cwd) + return 130 #FIXME It doesn't return this errorcode, why? Just prints stacktrace + os.chdir(saved_cwd) + return ret + + +def action_build(args): + if not args.check_warnings_only: + ret = parallel_call(args, call_build_docs) + if ret != 0: + return ret + + # check Doxygen warnings: + ret = 0 + for target in targets: + for language in languages: + build_dir = os.path.realpath(os.path.join(args.build_dir, language, target)) + ret += check_docs(language, target, + log_file=os.path.join(build_dir, DXG_WARN_LOG), + known_warnings_file=DXG_KNOWN_WARNINGS, + out_sanitized_log_file=os.path.join(build_dir, DXG_SANITIZED_LOG)) + if ret != 0: + return ret + + # check Sphinx warnings: + ret = 0 + for target in targets: + for language in languages: + build_dir = os.path.realpath(os.path.join(args.build_dir, language, target)) + ret += check_docs(language, target, + log_file=os.path.join(build_dir, SPHINX_WARN_LOG), + known_warnings_file=SPHINX_KNOWN_WARNINGS, + out_sanitized_log_file=os.path.join(build_dir, SPHINX_SANITIZED_LOG)) + if ret != 0: + return ret + + +def call_build_docs(entry): + return sphinx_call(*entry, buildername="html") + + +def sanitize_line(line): + """ + Clear a log message from insignificant parts + + filter: + - only filename, no path at the beginning + - no line numbers after the filename + """ + + line = re.sub(SANITIZE_FILENAME_REGEX, r'\1\2', line) + line = re.sub(SANITIZE_LINENUM_REGEX, r'\1:line:\3', line) + return line + + +def check_docs(language, target, log_file, known_warnings_file, out_sanitized_log_file): + """ + Check for Documentation warnings in `log_file`: should only contain (fuzzy) matches to `known_warnings_file` + + It prints all unknown messages with `target`/`language` prefix + It leaves `out_sanitized_log_file` file for observe and debug + """ + + # Sanitize all messages + all_messages = list() + with open(log_file) as f, open(out_sanitized_log_file, 'w') as o: + for line in f: + sanitized_line = sanitize_line(line) + all_messages.append(LogMessage(line, sanitized_line)) + o.write(sanitized_line) + + known_messages = list() + with open(known_warnings_file) as k: + for known_line in k: + known_messages.append(known_line) + + # Collect all new messages that are not match with the known messages. + # The order is an important. + new_messages = list() + known_idx = 0 + for msg in all_messages: + try: + known_idx = known_messages.index(msg.sanitized_text, known_idx) + except ValueError: + new_messages.append(msg) + + if new_messages: + print("\n%s/%s: Build failed due to new/different warnings (%s):\n" % (language, target, log_file)) + for msg in new_messages: + print("%s/%s: %s" % (language, target, msg.original_text), end='') + print("\n%s/%s: (Check files %s and %s for full details.)" % (language, target, known_warnings_file, log_file)) + return 1 + + return 0 + + +def action_linkcheck(args): + return parallel_call(args, call_linkcheck) + + +def call_linkcheck(entry): + return sphinx_call(*entry, buildername="linkcheck") + + +GH_LINK_FILTER = ["https://github.com/espressif/esp-idf/tree", + "https://github.com/espressif/esp-idf/blob", + "https://github.com/espressif/esp-idf/raw"] + + +def action_gh_linkcheck(args): + print("Checking for hardcoded GitHub links\n") + + find_args = ['find', + os.path.join(os.path.abspath(os.path.dirname(__file__)), ".."), + '-name', + '*.rst'] + grep_args = ['xargs', + 'grep', + r'\|'.join(GH_LINK_FILTER)] + + p1 = subprocess.Popen(find_args, stdout=subprocess.PIPE) + p2 = subprocess.Popen(grep_args, stdin=p1.stdout, stdout=subprocess.PIPE) + p1.stdout.close() + found_gh_links, _ = p2.communicate() + if found_gh_links: + print(found_gh_links) + print("WARNINIG: Some .rst files contain hardcoded Github links.") + print("Please check above output and replace links with one of the following:") + print("- :idf:`dir` - points to directory inside ESP-IDF") + print("- :idf_file:`file` - points to file inside ESP-IDF") + print("- :idf_raw:`file` - points to raw view of the file inside ESP-IDF") + print("- :component:`dir` - points to directory inside ESP-IDF components dir") + print("- :component_file:`file` - points to file inside ESP-IDF components dir") + print("- :component_raw:`file` - points to raw view of the file inside ESP-IDF components dir") + print("- :example:`dir` - points to directory inside ESP-IDF examples dir") + print("- :example_file:`file` - points to file inside ESP-IDF examples dir") + print("- :example_raw:`file` - points to raw view of the file inside ESP-IDF examples dir") + print("These link types will point to the correct GitHub version automatically") + return 1 + else: + print("No hardcoded links found") + return 0 if __name__ == "__main__": diff --git a/docs/check_doc_warnings.sh b/docs/check_doc_warnings.sh deleted file mode 100755 index 4d22b29037..0000000000 --- a/docs/check_doc_warnings.sh +++ /dev/null @@ -1,39 +0,0 @@ -#!/bin/bash -# -# Check for Documentation warnings: -# doxygen-warning-log.txt should be an empty file -# sphinx-warning-log.txt should only contain (fuzzy) matches to ../sphinx-known-warnings.txt -RESULT=0 -STARS='***************************************************' - -if [ -s doxygen-warning-log.txt ]; then - echo "$STARS" - echo "Build failed due to doxygen warnings:" - cat doxygen-warning-log.txt - echo "$STARS" - RESULT=1 -fi - -# Remove escape characters, file paths, line numbers from -# the Sphinx warning log -# (escape char removal from https://www.commandlinefu.com/commands/view/6141/remove-color-codes-special-characters-with-sed -sed -r 's:\x1B\[[0-9;]*[mK]::g' sphinx-warning-log.txt | \ - sed -E "s/.*\/(.*):[0-9]+:/\1:line:/" > sphinx-warning-log-sanitized.txt - -# diff sanitized warnings, ignoring lines which only appear in ../sphinx-known-warnings.txt - -# format is to display only lines new or changed in second argument -DIFF_FORMAT="--unchanged-line-format= --old-line-format= --new-line-format=%L" - -SPHINX_WARNINGS=$(diff $DIFF_FORMAT ../sphinx-known-warnings.txt sphinx-warning-log-sanitized.txt) -if ! [ -z "$SPHINX_WARNINGS" ]; then - echo "$STARS" - echo "Build failed due to new/different Sphinx warnings:" - echo "$SPHINX_WARNINGS" - echo "$STARS" - RESULT=1 - echo "(Check files ../sphinx-known-warnings.txt and sphinx-warning-log.txt for full details.)" -fi - -exit $RESULT - diff --git a/docs/doxygen-known-warnings.txt b/docs/doxygen-known-warnings.txt new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/sphinx-known-warnings.txt b/docs/sphinx-known-warnings.txt index bb2c611b6c..777b2138f0 100644 --- a/docs/sphinx-known-warnings.txt +++ b/docs/sphinx-known-warnings.txt @@ -2,7 +2,7 @@ # # Build will fail if sphinx-warning-log.txt contains any lines # which are not in this file. Lines are pre-sanitized by -# check_doc_warnings.sh to remove formatting, paths and line numbers. +# `build_docs.py build` to remove formatting, paths and line numbers. # # Warnings in this file must be in the same overall order as the log file. # diff --git a/tools/ci/executable-list.txt b/tools/ci/executable-list.txt index 286b28994e..c4268075b2 100644 --- a/tools/ci/executable-list.txt +++ b/tools/ci/executable-list.txt @@ -14,7 +14,6 @@ components/partition_table/test_gen_esp32part_host/gen_esp32part_tests.py components/spiffs/spiffsgen.py components/ulp/esp32ulp_mapgen.py docs/build_docs.py -docs/check_doc_warnings.sh docs/check_lang_folder_sync.sh docs/idf_extensions/gen_version_specific_includes.py examples/build_system/cmake/idf_as_lib/build-esp32.sh From b9effd8c066fdab4911bd1c8efd7acb2b7069099 Mon Sep 17 00:00:00 2001 From: Anton Maklakov Date: Wed, 8 Jan 2020 13:10:55 +0700 Subject: [PATCH 30/47] fixup build_docs.py, show doxygen and sphinx warnings together --- docs/build_docs.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/build_docs.py b/docs/build_docs.py index 3fa5207d90..9e85334f16 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -221,11 +221,8 @@ def action_build(args): log_file=os.path.join(build_dir, DXG_WARN_LOG), known_warnings_file=DXG_KNOWN_WARNINGS, out_sanitized_log_file=os.path.join(build_dir, DXG_SANITIZED_LOG)) - if ret != 0: - return ret # check Sphinx warnings: - ret = 0 for target in targets: for language in languages: build_dir = os.path.realpath(os.path.join(args.build_dir, language, target)) From 268816649c41a2cbf0abca6b60e5f2d9bdaf80fa Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Thu, 19 Dec 2019 12:16:25 +0800 Subject: [PATCH 31/47] Replace all TRM urls will generic template variable and remove duplicate sections All references to TRM had the section duplicated for both targets using .. only:: , replaced these with a generic template url --- .../jtag-debugging/debugging-examples.rst | 16 +-- docs/en/api-reference/peripherals/i2c.rst | 2 +- docs/en/api-reference/peripherals/ledc.rst | 2 +- docs/en/api-reference/peripherals/mcpwm.rst | 2 +- .../peripherals/sd_pullup_requirements.rst | 2 +- docs/en/api-reference/peripherals/uart.rst | 2 +- docs/en/api-reference/system/efuse.rst | 4 +- docs/en/contribute/documenting-code.rst | 28 +++--- docs/en/hw-reference/index.rst | 3 +- docs/en/security/flash-encryption.rst | 12 +-- docs/idf_extensions/format_idf_target.py | 12 ++- .../jtag-debugging/debugging-examples.rst | 11 +-- .../api-reference/peripherals/touch_pad.rst | 8 +- docs/zh_CN/contribute/documenting-code.rst | 24 ++--- docs/zh_CN/hw-reference/index.rst | 3 +- docs/zh_CN/security/flash-encryption.rst | 98 +++++++++---------- 16 files changed, 103 insertions(+), 126 deletions(-) diff --git a/docs/en/api-guides/jtag-debugging/debugging-examples.rst b/docs/en/api-guides/jtag-debugging/debugging-examples.rst index 8f2954bee7..9448f412d4 100644 --- a/docs/en/api-guides/jtag-debugging/debugging-examples.rst +++ b/docs/en/api-guides/jtag-debugging/debugging-examples.rst @@ -154,13 +154,7 @@ To display or set contents of memory use "Memory" tab at the bottom of "Debug" p With the "Memory" tab, we will read from and write to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's. -.. only:: esp32 - - For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. - -.. only:: esp32s2beta - - For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. +For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`__, chapter IO_MUX and GPIO Matrix. Being in the same ``blink.c`` project as before, set two breakpoints right after ``gpio_set_level`` instruction. Click "Memory" tab and then "Add Memory Monitor" button. Enter ``0x3FF44004`` in provided dialog. @@ -522,13 +516,7 @@ Displaying the contents of memory is done with command ``x``. With additional pa We will demonstrate how ``x`` and ``set`` work by reading from and writing to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's. -.. only:: esp32 - - For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. - -.. only:: esp32s2beta - - For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. +For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`__, chapter IO_MUX and GPIO Matrix. Being in the same ``blink.c`` project as before, set two breakpoints right after ``gpio_set_level`` instruction. Enter two times ``c`` to get to the break point followed by ``x /1wx 0x3FF44004`` to display contents of ``GPIO_OUT_REG`` memory location:: diff --git a/docs/en/api-reference/peripherals/i2c.rst b/docs/en/api-reference/peripherals/i2c.rst index 0a49678715..9d72c333b8 100644 --- a/docs/en/api-reference/peripherals/i2c.rst +++ b/docs/en/api-reference/peripherals/i2c.rst @@ -175,7 +175,7 @@ A code example showing how to use these functions can be found in :example:`peri Interrupt Handling ^^^^^^^^^^^^^^^^^^ -During driver installation, an interrupt handler is installed by default. However, you can register your own interrupt handler instead of the default one by calling the function :cpp:func:`i2c_isr_register`. When implementing your own interrupt handler, refer to the `ESP32 Technical Reference Manual `_ for the description of interrupts triggered by the I2C controller. +During driver installation, an interrupt handler is installed by default. However, you can register your own interrupt handler instead of the default one by calling the function :cpp:func:`i2c_isr_register`. When implementing your own interrupt handler, refer to the `{IDF_TARGET_NAME} Technical Reference Manual (PDF) <{IDF_TARGET_TRM_EN_URL}>`_ for the description of interrupts triggered by the I2C controller. To delete an interrupt handler, call :cpp:func:`i2c_isr_free`. diff --git a/docs/en/api-reference/peripherals/ledc.rst b/docs/en/api-reference/peripherals/ledc.rst index 492fe21c7d..ea0d51e205 100644 --- a/docs/en/api-reference/peripherals/ledc.rst +++ b/docs/en/api-reference/peripherals/ledc.rst @@ -144,7 +144,7 @@ The advantage of high speed mode is glitch-free changeover of the timer settings The advantage of high speed mode is hardware-supported, glitch-free changeover of the timer settings. This means that if the timer settings are modified, the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the background, e.g., when :cpp:func:`ledc_timer_config` or :cpp:func:`ledc_timer_set` is called. - For additional details regarding speed modes, refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_URL}>`_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver. + For additional details regarding speed modes, refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver. .. only:: esp32s2 diff --git a/docs/en/api-reference/peripherals/mcpwm.rst b/docs/en/api-reference/peripherals/mcpwm.rst index 7ab6b657bd..b17d5acdb7 100644 --- a/docs/en/api-reference/peripherals/mcpwm.rst +++ b/docs/en/api-reference/peripherals/mcpwm.rst @@ -171,7 +171,7 @@ Examples of using MCPWM for motor control: :example:`peripherals/mcpwm`: * Brushed DC motor control - :example:`peripherals/mcpwm/mcpwm_brushed_dc_control` * Servo motor control - :example:`peripherals/mcpwm/mcpwm_servo_control` -.. _{IDF_TARGET_NAME} Technical Reference Manual: {IDF_TARGET_TRM_URL} +.. _{IDF_TARGET_NAME} Technical Reference Manual: {IDF_TARGET_TRM_EN_URL} API Reference diff --git a/docs/en/api-reference/peripherals/sd_pullup_requirements.rst b/docs/en/api-reference/peripherals/sd_pullup_requirements.rst index 84e72a4427..3485c8105a 100644 --- a/docs/en/api-reference/peripherals/sd_pullup_requirements.rst +++ b/docs/en/api-reference/peripherals/sd_pullup_requirements.rst @@ -217,7 +217,7 @@ To resolve the conflict, you have the following options: If running from an automated flashing script, ``espefuse.py`` has an option ``--do-not-confirm``. - For more details, see the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_URL}>`_ (PDF). + For more details, see the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ (PDF). 2. **If using 1-bit SD mode or SPI mode**, disconnect the DAT2 pin and make sure it is pulled high. For this, do one the following: diff --git a/docs/en/api-reference/peripherals/uart.rst b/docs/en/api-reference/peripherals/uart.rst index f56373a8b8..45b7953daf 100644 --- a/docs/en/api-reference/peripherals/uart.rst +++ b/docs/en/api-reference/peripherals/uart.rst @@ -232,7 +232,7 @@ The UART controller supports a number of communication modes. A mode can be sele Using Interrupts ^^^^^^^^^^^^^^^^ -There are many interrupts that can be generated following specific UART states or detected errors. The full list of available interrupts is provided in the SoC Technical Reference Manual. You can enable or disable specific interrupts by calling :cpp:func:`uart_enable_intr_mask` or :cpp:func:`uart_disable_intr_mask` respectively. The mask of all interrupts is available as :c:macro:`UART_INTR_MASK`. +There are many interrupts that can be generated following specific UART states or detected errors. The full list of available interrupts is provided `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ (PDF).. You can enable or disable specific interrupts by calling :cpp:func:`uart_enable_intr_mask` or :cpp:func:`uart_disable_intr_mask` respectively. The mask of all interrupts is available as :c:macro:`UART_INTR_MASK`. By default, the :cpp:func:`uart_driver_install` function installs the driver's internal interrupt handler to manage the Tx and Rx ring buffers and provides high-level API functions like events (see below). It is also possible to register a lower level interrupt handler instead using :cpp:func:`uart_isr_register`, and to free it again using :cpp:func:`uart_isr_free`. Some UART driver functions which use the Tx and Rx ring buffers, events, etc. will not automatically work in this case - it is necessary to handle the interrupts directly in the ISR. Inside the custom handler implementation, clear the interrupt status bits using :cpp:func:`uart_clear_intr_status`. diff --git a/docs/en/api-reference/system/efuse.rst b/docs/en/api-reference/system/efuse.rst index f50bda763b..1a4ab011e4 100644 --- a/docs/en/api-reference/system/efuse.rst +++ b/docs/en/api-reference/system/efuse.rst @@ -16,7 +16,7 @@ Some of system parameters are using these eFuse bits directly by hardware module .. only:: esp32 - For more details see `ESP32 Technical Reference Manual `_ in part 20 eFuse controller. Some eFuse bits are available for user applications. + For more details see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ in part 20 eFuse controller. Some eFuse bits are available for user applications. ESP32 has 4 eFuse blocks each of the size of 256 bits (not all bits are available): @@ -27,7 +27,7 @@ Some of system parameters are using these eFuse bits directly by hardware module .. only:: esp32s2 - For more details see `ESP32-S2 Technical Reference Manual `_. Some eFuse bits are available for user applications. + For more details see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_. Some eFuse bits are available for user applications. {IDF_TARGET_NAME} has 11 eFuse blocks each of the size of 256 bits (not all bits are available): diff --git a/docs/en/contribute/documenting-code.rst b/docs/en/contribute/documenting-code.rst index dfd9d76134..57c02cde72 100644 --- a/docs/en/contribute/documenting-code.rst +++ b/docs/en/contribute/documenting-code.rst @@ -3,7 +3,7 @@ Documenting Code :link_to_translation:`zh_CN:[中文]` -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. +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 @@ -22,14 +22,14 @@ Typical comment block, that contains documentation of a function, looks like bel .. 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 rich and very well organized `Doxygen Manual `_. Why we need it? --------------- -The ultimate goal is to ensure that all the code is consistently documented, so we can use tools like `Sphinx `_ and `Breathe `_ to aid preparation and automatic updates of API documentation when the code changes. +The ultimate goal is to ensure that all the code is consistently documented, so we can use tools like `Sphinx `_ and `Breathe `_ to aid preparation and automatic updates of API documentation when the code changes. With these tools the above piece of code renders like below: @@ -58,7 +58,7 @@ When writing code for this repository, please follow guidelines below. .. 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 @@ -75,7 +75,7 @@ When writing code for this repository, please follow guidelines below. * - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist * - other error codes from the underlying storage driver * - + 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``. @@ -118,7 +118,7 @@ There is couple of tips, how you can make your documentation even better and mor */ void first_similar_function (void); void second_similar_function (void); - /**@}*/ + /**@}*/ For practical example see :component_file:`nvs_flash/include/nvs.h`. @@ -127,14 +127,14 @@ There is couple of tips, how you can make your documentation even better and mor 5. Use markdown to make your documentation even more readable. You will add headers, links, tables and more. :: * - * [ESP32 Technical Reference Manual](https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf) + * [{IDF_TARGET_NAME} Technical Reference Manual]({IDF_TARGET_TRM_EN_URL}) * .. 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. -6. 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. +6. 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. .. _link-custom-roles: @@ -199,9 +199,9 @@ The following types of diagrams are supported: * `Activity diagram `_ * `Logical network diagram `_ -With this suite of tools it is possible to generate beautiful diagram images from simple text format (similar to graphviz’s DOT format). The diagram elements are laid out automatically. The diagram code is then converted into ".png" graphics and integrated "behind the scenes" into **Sphinx** documents. +With this suite of tools it is possible to generate beautiful diagram images from simple text format (similar to graphviz’s DOT format). The diagram elements are laid out automatically. The diagram code is then converted into ".png" graphics and integrated "behind the scenes" into **Sphinx** documents. -For the diagram preparation you can use an on-line `interactive shell`_ that instantly shows the rendered image. +For the diagram preparation you can use an on-line `interactive shell`_ that instantly shows the rendered image. Below are couple of diagram examples: @@ -262,10 +262,10 @@ OK, but I am new to Sphinx! 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 `_, `Blockdiag `_ and `Doxygen `_ to build it locally, see chapter below. - + * 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. +4. To preview documentation before building, use `Sublime Text `_ editor together with `OmniMarkupPreviewer `_ plugin. .. _setup-for-building-documentation: @@ -348,13 +348,13 @@ Now you should be ready to build documentation by invoking:: make html -This may take couple of minutes. After completion, documentation will be placed in ``~/esp/esp-idf/docs/en/_build/html`` folder. To see it, open ``index.html`` in a web browser. +This may take couple of minutes. After completion, documentation will be placed in ``~/esp/esp-idf/docs/en/_build/html`` folder. To see it, open ``index.html`` in a web browser. Wrap up ------- -We love good code that is doing cool things. +We love good code that is doing cool things. We love it even better, if it is well documented, so we can quickly make it run and also do the cool things. Go ahead, contribute your code and documentation! diff --git a/docs/en/hw-reference/index.rst b/docs/en/hw-reference/index.rst index 7524a02029..6af93957d6 100644 --- a/docs/en/hw-reference/index.rst +++ b/docs/en/hw-reference/index.rst @@ -6,8 +6,7 @@ .. toctree:: :maxdepth: 3 - :esp32: Technical Reference Manual (PDF) - :esp32s2beta: Technical Reference Manual (PDF) + Technical Reference Manual (PDF) <{IDF_TARGET_TRM_EN_URL}> :esp32: Datasheet (PDF) :esp32s2: Datasheet (PDF) :esp32: Hardware Design Guidelines (PDF) diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index f35ffbd706..e156a6e67c 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -4,17 +4,9 @@ Flash Encryption :link_to_translation:`zh_CN:[中文]` -.. only:: esp32 +This document provides introduction to Flash encryption concept on {IDF_TARGET_NAME} and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `{IDF_TARGET_NAME} Technical reference manual`_. - This document provides introduction to Flash encryption concept on {IDF_TARGET_NAME} and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `ESP32 Technical reference manual`_. - - .. _ESP32 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf - -.. only:: esp32s2beta - - This document provides introduction to Flash encryption concept on {IDF_TARGET_NAME} and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `ESP32-S2 Technical reference manual`_. - - .. _ESP32-S2 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf +.. _{IDF_TARGET_NAME} Technical Reference Manual: {IDF_TARGET_TRM_EN_URL} Introduction diff --git a/docs/idf_extensions/format_idf_target.py b/docs/idf_extensions/format_idf_target.py index 8a2204f444..65c33222bf 100644 --- a/docs/idf_extensions/format_idf_target.py +++ b/docs/idf_extensions/format_idf_target.py @@ -4,9 +4,13 @@ TARGET_NAMES = {'esp32': 'ESP32', 'esp32s2': 'ESP32-S2'} TOOLCHAIN_NAMES = {'esp32': 'esp', 'esp32s2': 'esp32s2'} CONFIG_PREFIX = {'esp32': 'ESP32', 'esp32s2': 'ESP32S2'} -TRM_URL = {'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf', +TRM_EN_URL = {'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf', 'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf'} +TRM_CN_URL = {'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_cn.pdf', + 'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_cn.pdf'} + + class StringSubstituter: """ Allows for string substitution of target related strings before any markup is parsed @@ -16,7 +20,8 @@ class StringSubstituter: {IDF_TARGET_PATH_NAME}, replaced with the path name, e.g. esp32s2 {IDF_TARGET_TOOLCHAIN_NAME}, replaced with the toolchain name, e.g. esp32s2 {IDF_TARGET_CFG_PREFIX}, replaced with the prefix used for config parameters, e.g. ESP32S2 - {IDF_TARGET_TRM_URL}, replaced with the url to the technical reference manual + {IDF_TARGET_TRM_EN_URL}, replaced with the url to the English technical reference manual + {IDF_TARGET_TRM_CH_URL}, replaced with the url to the Chinese technical reference manual Also supports defines of local (single rst file) with the format: {IDF_TARGET_TX_PIN:default="IO3",esp32="IO4",esp32s2="IO5"} @@ -40,7 +45,8 @@ class StringSubstituter: self.add_pair("{IDF_TARGET_PATH_NAME}", config.idf_target) self.add_pair("{IDF_TARGET_TOOLCHAIN_NAME}", TOOLCHAIN_NAMES[config.idf_target]) self.add_pair("{IDF_TARGET_CFG_PREFIX}", CONFIG_PREFIX[config.idf_target]) - self.add_pair("{IDF_TARGET_TRM_URL}", TRM_URL[config.idf_target]) + self.add_pair("{IDF_TARGET_TRM_EN_URL}", TRM_EN_URL[config.idf_target]) + self.add_pair("{IDF_TARGET_TRM_CN_URL}", TRM_CN_URL[config.idf_target]) def add_local_subs(self, matches): diff --git a/docs/zh_CN/api-guides/jtag-debugging/debugging-examples.rst b/docs/zh_CN/api-guides/jtag-debugging/debugging-examples.rst index 2434431b08..411919d1e0 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/debugging-examples.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/debugging-examples.rst @@ -155,14 +155,7 @@ 在 “Memory” 选项卡下，我们将在内存地址 ``0x3FF44004`` 处读取和写入内容。该地址也是 ``GPIO_OUT_REG`` 寄存器的地址，可以用来控制（设置或者清除）某个 GPIO 的电平。 -.. only:: esp32 - - 关于该寄存器的更多详细信息，请参阅 `ESP32 技术参考手册 `_ 中的 IO_MUX 和 GPIO Matrix 章节。 - -.. only:: esp32s2beta - - 关于该寄存器的更多详细信息，请参阅 `ESP32-S2 技术参考手册 `_ 中的 IO_MUX 和 GPIO Matrix 章节。 - +关于该寄存器的更多详细信息，请参阅 `{IDF_TARGET_NAME} 技术参考手册 <{IDF_TARGET_TRM_CN_URL}>`_ 中的 IO_MUX 和 GPIO Matrix 章节。 同样在 ``blink.c`` 项目文件中，在两个 ``gpio_set_level`` 语句的后面各设置一个断点，单击 “Memory” 选项卡，然后单击 “Add Memory Monitor” 按钮，在弹出的对话框中输入 ``0x3FF44004``。 @@ -521,7 +514,7 @@ 使用命令 ``x`` 可以显示内存的内容，配合其余参数还可以调整所显示内存位置的格式和数量。运行 ``help x`` 可以查看更多相关细节。与 ``x`` 命令配合使用的命令是 ``set``，它允许你将值写入内存。 -为了演示 ``x`` 和 ``set`` 的使用，我们将在内存地址 ``0x3FF44004`` 处读取和写入内容。该地址也是 ``GPIO_OUT_REG`` 寄存器的地址，可以用来控制（设置或者清除）某个 GPIO 的电平。关于该寄存器的更多详细信息，请参阅 `ESP32 技术参考手册 `_ 中的 IO_MUX 和 GPIO Matrix章节。 +为了演示 ``x`` 和 ``set`` 的使用，我们将在内存地址 ``0x3FF44004`` 处读取和写入内容。该地址也是 ``GPIO_OUT_REG`` 寄存器的地址，可以用来控制（设置或者清除）某个 GPIO 的电平。关于该寄存器的更多详细信息，请参阅 `{IDF_TARGET_NAME} 技术参考手册 <{IDF_TARGET_TRM_CN_URL}>`_ 中的 IO_MUX 和 GPIO Matrix章节。 同样在 ``blink.c`` 项目文件中，在两个 ``gpio_set_level`` 语句的后面各设置一个断点。输入两次 ``c`` 命令后停止在断点处，然后输入 ``x /1wx 0x3FF44004`` 来显示 ``GPIO_OUT_REG`` 寄存器的值:: diff --git a/docs/zh_CN/api-reference/peripherals/touch_pad.rst b/docs/zh_CN/api-reference/peripherals/touch_pad.rst index c8ba473b63..1c9476fec4 100644 --- a/docs/zh_CN/api-reference/peripherals/touch_pad.rst +++ b/docs/zh_CN/api-reference/peripherals/touch_pad.rst @@ -10,7 +10,7 @@ ESP32 可支持最多 10 个电容式触摸板/GPIO，触摸板可以以矩阵或滑条等方式组合使用，从而覆盖更大触感区域及更多触感点。触摸传感由有限状态机 (FSM) 硬件控制，由软件或专用硬件计时器发起。 -如需了解触摸传感器设计、操作及其控制寄存器等相关信息，请参考《`ESP32 技术参考手册 `_》(PDF)，您也可以在《ESP32 技术参考手册》中查看这一子系统是如何运行的。 +如需了解触摸传感器设计、操作及其控制寄存器等相关信息，请参考《`{IDF_TARGET_NAME} 技术参考手册 <{IDF_TARGET_TRM_CN_URL}>`_》(PDF)，您也可以在《ESP32 技术参考手册》中查看这一子系统是如何运行的。 请参考 `触摸传感器应用方案简介 `_，查看触摸传感器设计详情和固件开发指南。如果不想亲自在多种配置环境下测试触摸传感器，请查看 `ESP32 触摸功能开发套件 `_。 @@ -81,7 +81,7 @@ ESP32 可支持最多 10 个电容式触摸板/GPIO，触摸板可以以矩阵 .. figure:: ../../../_static/touch_pad-measurement-parameters.jpg :align: center - :alt: Touch Pad - relationship between measurement parameters + :alt: Touch Pad - relationship between measurement parameters :figclass: align-center 触摸板 - 测量参数之间的关系 @@ -115,7 +115,7 @@ ESP32 可支持最多 10 个电容式触摸板/GPIO，触摸板可以以矩阵 在对触摸监测启用中断之前，请先设置一个触摸监测阈值。然后使用 `触摸状态测量`_ 中所述的函数读取并显示触摸和释放触摸板时测得的结果。如果测量中存在噪声且相对电容变化较小，请使用滤波器。您也可以根据应用程序和环境条件，测试温度和电源电压变化对测量值的影响。 -确定监测阈值后就可以在初始化时调用 :cpp:func:`touch_pad_config` 设置此阈值，或在运行时调用 :cpp:func:`touch_pad_set_thresh` 设置此阈值。 +确定监测阈值后就可以在初始化时调用 :cpp:func:`touch_pad_config` 设置此阈值，或在运行时调用 :cpp:func:`touch_pad_set_thresh` 设置此阈值。 下一步就是设置如何触发中断。您可以设置在阈值以下或以上触发中断，具体触发模式由函数 :cpp:func:`touch_pad_set_trigger_mode` 设置。 @@ -135,7 +135,7 @@ ESP32 可支持最多 10 个电容式触摸板/GPIO，触摸板可以以矩阵 从睡眠模式唤醒 ^^^^^^^^^^^^^^^^^^^^^^ -如果使用触摸板中断将芯片从睡眠模式唤醒，您可以选择配置一些触摸板，例如 SET1 或 SET1 和 SET2，触摸这些触摸板将触发中断并唤醒芯片。请调用 :cpp:func:`touch_pad_set_trigger_source` 实现上述操作。 +如果使用触摸板中断将芯片从睡眠模式唤醒，您可以选择配置一些触摸板，例如 SET1 或 SET1 和 SET2，触摸这些触摸板将触发中断并唤醒芯片。请调用 :cpp:func:`touch_pad_set_trigger_source` 实现上述操作。 您可以使用以下函数管理 'SET' 中触摸板所需的位模式配置： diff --git a/docs/zh_CN/contribute/documenting-code.rst b/docs/zh_CN/contribute/documenting-code.rst index db4dc11e8e..0da92bad63 100644 --- a/docs/zh_CN/contribute/documenting-code.rst +++ b/docs/zh_CN/contribute/documenting-code.rst @@ -21,14 +21,14 @@ Doxygen 会解析代码，提取命令和后续文本，生成代码文档。 .. image:: ../../_static/doc-code-documentation-inline.png :align: center :alt: 内联代码样本文档 - + Doxygen 支持多种排版风格，对于文档中可以包含的细节非常灵活。请参考数据丰富、条理清晰的 `Doxygen 手册 `_ 熟悉 Doxygen 特性。 为什么需要 Doxygen? -------------------- -使用 Doxygen 的最终目的是确保所有代码编写风格一致，以便在代码变更时使用 `Sphinx `_ 和 `Breathe `_ 等工具协助筹备、自动更新 API 文档。 +使用 Doxygen 的最终目的是确保所有代码编写风格一致，以便在代码变更时使用 `Sphinx `_ 和 `Breathe `_ 等工具协助筹备、自动更新 API 文档。 使用这类工具时，上文代码渲染后呈现效果如下： @@ -57,7 +57,7 @@ Doxygen 支持多种排版风格，对于文档中可以包含的细节非常灵 .. image:: ../../_static/doc-code-void-function.png :align: center :alt: 隐式内联函数样本文档及渲染后的效果 - + 5. 为 ``define``、``struct`` 和 ``enum`` 的成员编写文档时，请在每一项后添加注释，如下所示。 .. image:: ../../_static/doc-code-member.png @@ -74,7 +74,7 @@ Doxygen 支持多种排版风格，对于文档中可以包含的细节非常灵 * - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist * - other error codes from the underlying storage driver * - + 7. 头文件的功能概览和库文件应当存在同一个项目库之下，放入单独的 ``README.rst`` 文件。如果目录下包含不同 API 的头文件，应将文件命名为 ``apiname-readme.rst``。 @@ -117,7 +117,7 @@ Doxygen 支持多种排版风格，对于文档中可以包含的细节非常灵 */ void first_similar_function (void); void second_similar_function (void); - /**@}*/ + /**@}*/ 示例请参照 :component_file:`nvs_flash/include/nvs.h`。 @@ -126,14 +126,14 @@ Doxygen 支持多种排版风格，对于文档中可以包含的细节非常灵 5. 使用 markdown 增强文档可读性，添加页眉、链接、表格及更多内容。 :: * - * [ESP32 技术参考手册](https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_cn.pdf) + * [{IDF_TARGET_NAME} 技术参考手册]({IDF_TARGET_TRM_CN_URL}) * .. note:: 代码片段、注释、链接等内容如没有附在所述对象对应的注释块中，将不会添加到文档中。 -6. 准备一个或更多完整的代码示例和描述，将描述放入单独的 ``README.md`` 文件中，置于 :idf:`examples` 目录的特定文件夹中。 +6. 准备一个或更多完整的代码示例和描述，将描述放入单独的 ``README.md`` 文件中，置于 :idf:`examples` 目录的特定文件夹中。 .. _link-custom-roles: @@ -198,7 +198,7 @@ CI build 脚本中添加了检查功能，查找 RST 文件中的硬编码链接 * `活动图 `_ * `逻辑网络图 `_ -使用该工具包，可以将简单的文本（与 graphviz 的 DOT 格式类似）转换成美观的图片。图中内容自动排版。图标代码之后会转换为 ".png" 图片，在后台添加进 **Sphinx** 文档中。 +使用该工具包，可以将简单的文本（与 graphviz 的 DOT 格式类似）转换成美观的图片。图中内容自动排版。图标代码之后会转换为 ".png" 图片，在后台添加进 **Sphinx** 文档中。 要查看图表的渲染效果，可使用线上的 `interactive shell`_ 即时显示生成的图片。 @@ -262,10 +262,10 @@ Sphinx 新手怎么办 3. 想要查看在上传至 GitHub 前文档如何生成、呈现，有两种方式： * 安装`Sphinx `_、 `Breathe `_、 `Blockdiag `_ 和 `Doxygen `_ 本地生成文档，具体可查看下文。 - + * 在 `Read the Docs `_ 建立账号，在云端生成文档。 Read the Docs 免费提供文档生成和存储，且速度快、质量高。 -4. 在生成文档前预览，可使用 `Sublime Text `_ 编辑器和 `OmniMarkupPreviewer `_ 插件。 +4. 在生成文档前预览，可使用 `Sublime Text `_ 编辑器和 `OmniMarkupPreviewer `_ 插件。 .. _setup-for-building-documentation: @@ -291,7 +291,7 @@ Doxygen 的安装取决于操作系统： **Linux** -:: +:: sudo apt-get install doxygen @@ -348,7 +348,7 @@ Doxygen 的安装取决于操作系统： make html -这一步骤需要几分钟时间。完成后，文档会放置在 ``~/esp/esp-idf/docs/en/_build/html`` 文件夹下。您可以在网页浏览器中打开 ``index.html`` 查看。 +这一步骤需要几分钟时间。完成后，文档会放置在 ``~/esp/esp-idf/docs/en/_build/html`` 文件夹下。您可以在网页浏览器中打开 ``index.html`` 查看。 大功告成 diff --git a/docs/zh_CN/hw-reference/index.rst b/docs/zh_CN/hw-reference/index.rst index 4f22477b92..9d5e73e8aa 100644 --- a/docs/zh_CN/hw-reference/index.rst +++ b/docs/zh_CN/hw-reference/index.rst @@ -6,8 +6,7 @@ ESP32 H/W 硬件参考 .. toctree:: :maxdepth: 2 - :esp32: ESP32 技术参考手册 (PDF) - :esp32s2beta: ESP32-S2 技术参考手册 (PDF) + {IDF_TARGET_NAME} 技术参考手册 (PDF) <{IDF_TARGET_TRM_CN_URL}> :esp32: ESP32 技术规格书 (PDF) :esp32s2: ESP32-S2 技术规格书 (PDF) :esp32: ESP32 硬件设计指南 (PDF) diff --git a/docs/zh_CN/security/flash-encryption.rst b/docs/zh_CN/security/flash-encryption.rst index 5905b823b8..90e749d8fc 100644 --- a/docs/zh_CN/security/flash-encryption.rst +++ b/docs/zh_CN/security/flash-encryption.rst @@ -4,18 +4,18 @@ Flash 加密 :link_to_translation:`en:[English]` -本文档将介绍 ESP32 的 Flash 加密功能，并通过示例展示用户如何在开发及生产过程中使用此功能。本文档旨在引导用户快速入门如何测试及验证 Flash 加密的相关操作。有关 Flash 加密块的详细信息可参见 `ESP32 技术参考手册`_。 +本文档将介绍 {IDF_TARGET_NAME} 的 Flash 加密功能，并通过示例展示用户如何在开发及生产过程中使用此功能。本文档旨在引导用户快速入门如何测试及验证 Flash 加密的相关操作。有关 Flash 加密块的详细信息可参见 `{IDF_TARGET_NAME} 技术参考手册`_。 -.. _ESP32 技术参考手册: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_cn.pdf +.. _{IDF_TARGET_NAME} 技术参考手册: {IDF_TARGET_TRM_CN_URL} 概述 ------ -Flash 加密功能用于加密与 ESP32 搭载使用的 SPI Flash 中的内容。启用 Flash 加密功能后，物理读取 SPI Flash 便无法恢复大部分 Flash 内容。通过明文数据烧录 ESP32 可应用加密功能，（若已启用加密功能）引导加载程序会在首次启动时对数据进行加密。 +Flash 加密功能用于加密与 {IDF_TARGET_NAME} 搭载使用的 SPI Flash 中的内容。启用 Flash 加密功能后，物理读取 SPI Flash 便无法恢复大部分 Flash 内容。通过明文数据烧录 {IDF_TARGET_NAME} 可应用加密功能，（若已启用加密功能）引导加载程序会在首次启动时对数据进行加密。 启用 Flash 加密后，系统将默认加密下列类型的 Flash 数据： - - 引导加载程序 + - 引导加载程序 - 分区表 - 所有 “app” 类型的分区 @@ -24,16 +24,16 @@ Flash 加密功能用于加密与 ESP32 搭载使用的 SPI Flash 中的内容 - 安全启动引导加载程序摘要（如果已启用安全启动） - 分区表中标有“加密”标记的分区 -Flash 加密与 :doc:`安全启动` 功能各自独立，您可以在关闭安全启动的状态下使用 Flash 加密。但是，为了安全的计算机环境，二者应同时使用。在关闭安全启动的状态下，需运行其他配置来确保 Flash 加密的有效性。详细信息可参见 :ref:`flash-encryption-without-secure-boot`。 +Flash 加密与 :doc:`安全启动` 功能各自独立，您可以在关闭安全启动的状态下使用 Flash 加密。但是，为了安全的计算机环境，二者应同时使用。在关闭安全启动的状态下，需运行其他配置来确保 Flash 加密的有效性。详细信息可参见 :ref:`flash-encryption-without-secure-boot`。 .. important:: - 启用 Flash 加密将限制后续 ESP32 更新。请务必阅读本文档（包括 :ref:`flash-encryption-limitations`）了解启用 Flash 加密的影响。 + 启用 Flash 加密将限制后续 {IDF_TARGET_NAME} 更新。请务必阅读本文档（包括 :ref:`flash-encryption-limitations`）了解启用 Flash 加密的影响。 .. _flash-encryption-efuse: Flash 加密过程中使用的 eFuse ------------------------------ -Flash 加密操作由 ESP32 上的多个 eFuse 控制。以下是这些 eFuse 列表及其描述： +Flash 加密操作由 {IDF_TARGET_NAME} 上的多个 eFuse 控制。以下是这些 eFuse 列表及其描述： :: @@ -48,27 +48,27 @@ Flash 加密操作由 ESP32 上的多个 eFuse 控制。以下是这些 eFuse 0: 256 bits 1: 192 bits 2: 128 bits - 最终的 AES 密钥根据 FLASH_CRYPT_CONFIG 的 + 最终的 AES 密钥根据 FLASH_CRYPT_CONFIG 的 值产生。 BLOCK1 存储 AES 密钥的 256 位宽 eFuse 块 是 x - + FLASH_CRYPT_CONFIG 4 位宽 eFuse，控制 AES 加密进程 是 0xF download_dis_encrypt 设置后，在 UART 下载模式运行时关闭 Flash 加 是 0 密操作 - + download_dis_decrypt 设置后，在 UART 下载模式运行时关闭 Flash 解 是 0 密操作 - + FLASH_CRYPT_CNT 7 位 eFuse，在启动时启用/关闭加密功能 是 0 - + 偶数位（0，2，4，6）： 启动时加密 Flash 奇数位（1，3，5，7）： 启动时不加密 Flash -对上述位的读写访问由 ``efuse_wr_disable`` 和 ``efuse_rd_disable`` 寄存器中的相应位控制。有关 ESP32 eFuse 的详细信息可参见 :doc:`eFuse 管理器 <../api-reference/system/efuse>`。 +对上述位的读写访问由 ``efuse_wr_disable`` 和 ``efuse_rd_disable`` 寄存器中的相应位控制。有关 {IDF_TARGET_NAME} eFuse 的详细信息可参见 :doc:`eFuse 管理器 <../api-reference/system/efuse>`。 Flash 的加密过程 ------------------ @@ -84,7 +84,7 @@ Flash 的加密过程 - 在 :ref:`flash_enc_development_mode` 下，第二阶段引导加载程序将仅改写 ``download_dis_decrypt`` 和 ``download_dis_cache`` 的 eFuse 位，从而允许 UART 引导加载程序重新烧录加密的二进制文件。同时将不会写保护 ``FLASH_CRYPT_CNT`` 的 eFuse 位。 - 然后，第二阶段引导加载程序重启设备并开始执行加密映像，同时将透明解密 Flash 的内容并将其加载至 IRAM。 -在开发阶段常需编写不同的明文 Flash 映像，以及测试 Flash 的加密过程。这要求 UART 下载模式能够根据需求不断加载新的明文映像。但是，在量产和生产过程中，出于安全考虑，UART 下载模式不应有权限访问 Flash 内容。因此需要有两种不同的 ESP32 配置：一种用于开发，另一种用于生产。以下章节介绍了 Flash 加密的 :ref:`flash_enc_development_mode` 和 :ref:`flash_enc_release_mode` 及其使用指南。 +在开发阶段常需编写不同的明文 Flash 映像，以及测试 Flash 的加密过程。这要求 UART 下载模式能够根据需求不断加载新的明文映像。但是，在量产和生产过程中，出于安全考虑，UART 下载模式不应有权限访问 Flash 内容。因此需要有两种不同的 {IDF_TARGET_NAME} 配置：一种用于开发，另一种用于生产。以下章节介绍了 Flash 加密的 :ref:`flash_enc_development_mode` 和 :ref:`flash_enc_release_mode` 及其使用指南。 .. important:: 顾名思义，开发模式应 **仅开发过程** 使用，因为该模式可以修改和回读加密的 Flash 内容。 @@ -97,14 +97,14 @@ Flash 的加密过程 开发模式 ^^^^^^^^^^ -可使用 ESP32 内部生成的密钥或外部主机生成的密钥在开发中运行 Flash 加密。 +可使用 {IDF_TARGET_NAME} 内部生成的密钥或外部主机生成的密钥在开发中运行 Flash 加密。 -使用 ESP32 生成的 Flash 加密密钥 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +使用 {IDF_TARGET_NAME} 生成的 Flash 加密密钥 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -正如上文所说，:ref:`flash_enc_development_mode` 允许用户使用 UART 下载模式多次下载明文映像。需完成以下步骤测试 Flash 加密过程： +正如上文所说，:ref:`flash_enc_development_mode` 允许用户使用 UART 下载模式多次下载明文映像。需完成以下步骤测试 Flash 加密过程： -- 确保您的 ESP32 设备有 :ref:`flash-encryption-efuse` 中所示的 Flash 加密 eFuse 的默认设置。 +- 确保您的 {IDF_TARGET_NAME} 设备有 :ref:`flash-encryption-efuse` 中所示的 Flash 加密 eFuse 的默认设置。 - 可在 ``$IDF_PATH/examples/security/flash_encryption`` 文件夹中找到 Flash 加密的示例应用程序。该示例应用程序中有显示 Flash 加密的状态（启用或关闭）以及 ``FLASH_CRYPT_CNT`` eFuse 值。 @@ -117,7 +117,7 @@ Flash 的加密过程 - 在引导加载程序 config 下选择适当详细程度的日志。 - 启用 Flash 加密将增大引导加载程序，因而可能需更新分区表偏移。请参见 :ref:`secure-boot-bootloader-size`。 - + - 保存配置并退出。 构建并烧录完整的映像包括：引导加载程序、分区表和 app。这些分区最初以未加密形式写入 Flash。 @@ -126,7 +126,7 @@ Flash 的加密过程 idf.py flash monitor -一旦烧录完成，设备将重置，在下次启动时，第二阶段引导加载程序将加密 Flash 的 app 分区，然后重置该分区。现在，示例应用程序将在运行时解密并执行命令。以下是首次启用 Flash 加密后 ESP32 启动时的样例输出。 +一旦烧录完成，设备将重置，在下次启动时，第二阶段引导加载程序将加密 Flash 的 app 分区，然后重置该分区。现在，示例应用程序将在运行时解密并执行命令。以下是首次启用 Flash 加密后 {IDF_TARGET_NAME} 启动时的样例输出。 :: @@ -177,20 +177,20 @@ Flash 的加密过程 I (201) flash_encrypt: Disable UART bootloader MMU cache... I (208) flash_encrypt: Disable JTAG... I (212) flash_encrypt: Disable ROM BASIC interpreter fallback... - I (219) esp_image: segment 0: paddr=0x00001020 vaddr=0x3fff0018 size=0x00004 ( 4) - I (227) esp_image: segment 1: paddr=0x0000102c vaddr=0x3fff001c size=0x02104 ( 8452) - I (239) esp_image: segment 2: paddr=0x00003138 vaddr=0x40078000 size=0x03528 ( 13608) - I (249) esp_image: segment 3: paddr=0x00006668 vaddr=0x40080400 size=0x01a08 ( 6664) + I (219) esp_image: segment 0: paddr=0x00001020 vaddr=0x3fff0018 size=0x00004 ( 4) + I (227) esp_image: segment 1: paddr=0x0000102c vaddr=0x3fff001c size=0x02104 ( 8452) + I (239) esp_image: segment 2: paddr=0x00003138 vaddr=0x40078000 size=0x03528 ( 13608) + I (249) esp_image: segment 3: paddr=0x00006668 vaddr=0x40080400 size=0x01a08 ( 6664) I (657) esp_image: segment 0: paddr=0x00020020 vaddr=0x3f400020 size=0x0808c ( 32908) map - I (669) esp_image: segment 1: paddr=0x000280b4 vaddr=0x3ffb0000 size=0x01ea4 ( 7844) - I (672) esp_image: segment 2: paddr=0x00029f60 vaddr=0x40080000 size=0x00400 ( 1024) + I (669) esp_image: segment 1: paddr=0x000280b4 vaddr=0x3ffb0000 size=0x01ea4 ( 7844) + I (672) esp_image: segment 2: paddr=0x00029f60 vaddr=0x40080000 size=0x00400 ( 1024) 0x40080000: _WindowOverflow4 at esp-idf/esp-idf/components/freertos/xtensa_vectors.S:1778 - I (676) esp_image: segment 3: paddr=0x0002a368 vaddr=0x40080400 size=0x05ca8 ( 23720) + I (676) esp_image: segment 3: paddr=0x0002a368 vaddr=0x40080400 size=0x05ca8 ( 23720) I (692) esp_image: segment 4: paddr=0x00030018 vaddr=0x400d0018 size=0x126a8 ( 75432) map 0x400d0018: _flash_cache_start at ??:? - I (719) esp_image: segment 5: paddr=0x000426c8 vaddr=0x400860a8 size=0x01f4c ( 8012) + I (719) esp_image: segment 5: paddr=0x000426c8 vaddr=0x400860a8 size=0x01f4c ( 8012) 0x400860a8: prvAddNewTaskToReadyList at esp-idf/esp-idf/components/freertos/tasks.c:4561 I (722) flash_encrypt: Encrypting partition 2 at offset 0x20000... @@ -248,7 +248,7 @@ Flash 的加密过程 I (211) cpu_start: ELF file SHA256: 8770c886bdf561a7... I (217) cpu_start: ESP-IDF: v4.0-dev-850-gc4447462d-dirty I (224) cpu_start: Starting app cpu, entry point is 0x40080e4c - 0x40080e4c: call_start_cpu1 at esp-idf/esp-idf/components/esp32/cpu_start.c:265 + 0x40080e4c: call_start_cpu1 at esp-idf/esp-idf/components/{IDF_TARGET_PATH_NAME}/cpu_start.c:265 I (0) cpu_start: App cpu up. I (235) heap_init: Initializing. RAM available for dynamic allocation: @@ -262,7 +262,7 @@ Flash 的加密过程 I (0) cpu_start: Starting scheduler on APP CPU. Sample program to check Flash Encryption - This is ESP32 chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash + This is {IDF_TARGET_NAME} chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash Flash encryption feature is enabled Flash encryption mode is DEVELOPMENT Flash in encrypted mode with flash_crypt_cnt = 1 @@ -290,15 +290,15 @@ Flash 的加密过程 使用主机生成的 Flash 加密密钥 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -可在主机中预生成 Flash 加密密钥，并将其烧录到 ESP32 的 eFuse 密钥块中。这样，无需明文 Flash 更新便可以在主机上预加密数据并将其烧录到 ESP32 中。该功能允许在 :ref:`flash_enc_development_mode` 和 :ref:`flash_enc_release_mode` modes 两模式下加密烧录。 +可在主机中预生成 Flash 加密密钥，并将其烧录到 {IDF_TARGET_NAME} 的 eFuse 密钥块中。这样，无需明文 Flash 更新便可以在主机上预加密数据并将其烧录到 {IDF_TARGET_NAME} 中。该功能允许在 :ref:`flash_enc_development_mode` 和 :ref:`flash_enc_release_mode` modes 两模式下加密烧录。 -- 确保您的 ESP32 设备有 :ref:`flash-encryption-efuse` 中所示 Flash 加密 eFuse 的默认设置。 +- 确保您的 {IDF_TARGET_NAME} 设备有 :ref:`flash-encryption-efuse` 中所示 Flash 加密 eFuse 的默认设置。 - 使用 espsecure.py 随机生成一个密钥:: espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin -- 将该密钥烧录到设备上（一次性）。 **该步骤须在第一次加密启动前完成**，否则 ESP32 将随机生成一个软件无权限访问或修改的密钥:: +- 将该密钥烧录到设备上（一次性）。 **该步骤须在第一次加密启动前完成**，否则 {IDF_TARGET_NAME} 将随机生成一个软件无权限访问或修改的密钥:: espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin @@ -313,7 +313,7 @@ Flash 的加密过程 - 启用 Flash 加密将增大引导加载程序，因而可能需要更新分区表偏移。可参见 See :ref:`secure-boot-bootloader-size`。 - 保存配置并退出。 - + 构建并烧录完整的映像包括：引导加载程序、分区表和 app。这些分区最初以未加密形式写入 Flash :: @@ -337,7 +337,7 @@ Flash 的加密过程 在释放模式下，UART 引导加载程序无法执行 Flash 加密操作，**只能** 使用 OTA 方案下载新的明文映像，该方案将在写入 Flash 前加密明文映像。 -- 确保您的 ESP32 设备有 :ref:`flash-encryption-efuse` 中所示 Flash 加密 eFuse 的默认设置。 +- 确保您的 {IDF_TARGET_NAME} 设备有 :ref:`flash-encryption-efuse` 中所示 Flash 加密 eFuse 的默认设置。 - 在第二阶段引导加载程序中启用 Flash 加密支持。请前往 :ref:`project-configuration-menu`，选择 “Security Features”。 @@ -366,7 +366,7 @@ Flash 的加密过程 可能出现的错误 ^^^^^^^^^^^^^^^^ -启用 Flash 加密后，如果 ``FLASH_CRYPT_CNT`` eFuse 值中有奇数位，则所有（标有加密标志的）分区都应包含加密密文。以下为 ESP32 加载明文数据会产生的三种典型错误情况： +启用 Flash 加密后，如果 ``FLASH_CRYPT_CNT`` eFuse 值中有奇数位，则所有（标有加密标志的）分区都应包含加密密文。以下为 {IDF_TARGET_NAME} 加载明文数据会产生的三种典型错误情况： 1. 如果通过明文引导加载程序映像重新更新了引导加载程序分区，则 ROM 加载器将无法加载 引导加载程序，并会显示以下错误类型： @@ -374,27 +374,27 @@ Flash 的加密过程 rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) flash read err, 1000 - ets_main.c 371 + ets_main.c 371 ets Jun 8 2016 00:22:57 rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) flash read err, 1000 - ets_main.c 371 + ets_main.c 371 ets Jun 8 2016 00:22:57 rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) flash read err, 1000 - ets_main.c 371 + ets_main.c 371 ets Jun 8 2016 00:22:57 rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) flash read err, 1000 - ets_main.c 371 + ets_main.c 371 ets Jun 8 2016 00:22:57 rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) flash read err, 1000 - ets_main.c 371 + ets_main.c 371 ets Jun 8 2016 00:22:57 2. 如果引导加载程序已加密，但使用明文分区表映像重新更新了分区表，则引导加载程序将无法读取分区表，并会显示以下错误类型： @@ -459,7 +459,7 @@ Flash 加密的要点 - `flash 加密算法` 采用的是 AES-256，其中密钥随着 Flash 的每个 32 字节块的偏移地址“调整”。这意味着，每个 32 字节块（2 个连续的 16 字节 AES 块）使用从 Flash 加密密钥中产生的一个特殊密钥进行加密。 -- 通过 ESP32 的 Flash 缓存映射功能，Flash 可支持透明访问——读取任何映射到地址空间的 Flash 区域时，都将透明解密该区域。 +- 通过 {IDF_TARGET_NAME} 的 Flash 缓存映射功能，Flash 可支持透明访问——读取任何映射到地址空间的 Flash 区域时，都将透明解密该区域。 为便于访问，某些数据分区最好保持未加密状态，或者也可使用对已加密数据无效的 Flash 友好型更新算法。由于 NVS 库无法与 Flash 加密直接兼容，因此无法加密非易失性存储器的 NVS 分区。详情可参见 :ref:`NVS 加密 `。 @@ -470,14 +470,14 @@ Flash 加密的要点 .. note:: 同时启用安全启动和 Flash 加密后，引导加载程序 app 二进制文件 ``bootloader.bin`` 可能会过大。参见 :ref:`secure-boot-bootloader-size`。 .. important:: - 在首次启动加密过程中，请勿中断 ESP32 的电源。如果电源中断，Flash 的内容将受到破坏，并需要重新烧录未加密数据。而这类重新烧录将不计入烧录限制次数。 + 在首次启动加密过程中，请勿中断 {IDF_TARGET_NAME} 的电源。如果电源中断，Flash 的内容将受到破坏，并需要重新烧录未加密数据。而这类重新烧录将不计入烧录限制次数。 .. _using-encrypted-flash: 使用加密的 Flash ------------------- -ESP32 app 代码可通过调用函数 :cpp:func:`esp_flash_encryption_enabled` 来确认当前是否已启用 Flash 加密。同时，设备可通过调用函数 :cpp:func:`esp_get_flash_encryption_mode` 来识别使用的 Flash 加密模式。 +{IDF_TARGET_NAME} app 代码可通过调用函数 :cpp:func:`esp_flash_encryption_enabled` 来确认当前是否已启用 Flash 加密。同时，设备可通过调用函数 :cpp:func:`esp_get_flash_encryption_mode` 来识别使用的 Flash 加密模式。 启用 Flash 加密后，使用代码访问 Flash 内容时需加注意。 @@ -526,14 +526,14 @@ ROM 函数 ``esp_rom_spiflash_write_encrypted`` 将在 Flash 中写入加密数 OTA 更新 ^^^^^^^^^^ -只要使用了函数 ``esp_partition_write``，则加密分区的 OTA 更新将自动以加密形式写入。 +只要使用了函数 ``esp_partition_write``，则加密分区的 OTA 更新将自动以加密形式写入。 .. _updating-encrypted-flash-serial: 关闭 Flash 加密 ----------------- -若因某些原因意外启用了 Flash 加密，则接下来烧录明文数据时将使 ESP32 软砖（设备不断重启，并报错 ``flash read err, 1000``）。 +若因某些原因意外启用了 Flash 加密，则接下来烧录明文数据时将使 {IDF_TARGET_NAME} 软砖（设备不断重启，并报错 ``flash read err, 1000``）。 可通过写入 ``FLASH_CRYPT_CNT`` eFuse 再次关闭 Flash 加密（仅适用于开发模式下）： @@ -545,7 +545,7 @@ OTA 更新 espefuse.py burn_efuse FLASH_CRYPT_CNT -重置 ESP32，Flash 加密应处于关闭状态，引导加载程序将正常启动。 +重置 {IDF_TARGET_NAME}，Flash 加密应处于关闭状态，引导加载程序将正常启动。 .. _flash-encryption-limitations: @@ -572,7 +572,7 @@ Flash 加密与安全启动 推荐搭配使用 Flash 加密与安全启动。但是，如果已启用安全启动，则重新烧录设备时会受到其他限制： - :ref:`updating-encrypted-flash-ota` 不受限制（如果新的 app 已使用安全启动签名密钥进行正确签名）。 -- 只有当选择 :ref:`可再次烧录 ` 安全启动模式，且安全启动密钥已预生成并烧录至 ESP32（可参见 :ref:`安全启动 `），则 :ref:`明文串行 flash 更新 ` 可实现。在该配置下，``idf.py bootloader`` 将生成简化的引导加载程序和安全启动摘要文件，用于在偏移量 0x0 处进行烧录。当进行明文串行重新烧录步骤时，须在烧录其他明文数据前重新烧录此文件。 +- 只有当选择 :ref:`可再次烧录 ` 安全启动模式，且安全启动密钥已预生成并烧录至 {IDF_TARGET_NAME}（可参见 :ref:`安全启动 `），则 :ref:`明文串行 flash 更新 ` 可实现。在该配置下，``idf.py bootloader`` 将生成简化的引导加载程序和安全启动摘要文件，用于在偏移量 0x0 处进行烧录。当进行明文串行重新烧录步骤时，须在烧录其他明文数据前重新烧录此文件。 - 假设未重新烧录引导加载程序，:ref:`使用预生成的 Flash 加密密钥重新烧录 ` 仍可实现。重新烧录引导加载程序时，需在安全启动配置中启用相同的 :ref:`可重新烧录 ` 选项。 .. _flash-encryption-without-secure-boot: From 11fac8637a3429dcfdf9e10aef6281a21ac96e3c Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Wed, 29 Jan 2020 09:31:14 +1100 Subject: [PATCH 32/47] docs: Resolve doxygen & Sphinx warnings --- .../bt/esp_ble_mesh/api/esp_ble_mesh_defs.h | 12 +- .../bluedroid/api/include/api/esp_a2dp_api.h | 11 +- .../bluedroid/api/include/api/esp_bt_defs.h | 6 +- .../driver/esp32s2/include/touch_sensor.h | 27 ++-- components/driver/include/driver/timer.h | 12 -- components/esp32/include/esp_intr_alloc.h | 12 +- components/esp32s2/include/esp_intr_alloc.h | 12 +- components/esp_event/include/esp_event.h | 1 + .../common/include/esp_modbus_common.h | 2 +- components/soc/include/hal/i2c_types.h | 4 +- .../soc/include/hal/touch_sensor_types.h | 19 ++- components/soc/include/hal/uart_types.h | 2 +- components/vfs/include/esp_vfs.h | 132 +++++++++--------- docs/build_docs.py | 15 +- docs/conf_common.py | 16 ++- docs/doxygen-known-warnings.txt | 1 + docs/en/api-guides/fatal-errors.rst | 4 +- docs/en/api-guides/freertos-smp.rst | 2 +- docs/en/api-guides/lwip.rst | 10 +- docs/en/api-reference/peripherals/adc.rst | 2 +- .../peripherals/esp_slave_protocol.rst | 6 - docs/en/api-reference/peripherals/index.rst | 10 +- .../api-reference/peripherals/sdio_slave.rst | 8 -- .../api-reference/peripherals/sdmmc_host.rst | 75 +++++----- .../api-reference/peripherals/sdspi_host.rst | 6 +- .../api-reference/peripherals/temp_sensor.rst | 37 ++--- docs/en/api-reference/storage/sdmmc.rst | 85 +++++------ docs/en/api-reference/system/system_time.rst | 6 +- docs/sphinx-known-warnings.txt | 6 + docs/zh_CN/api-guides/unit-tests-legacy.rst | 10 +- docs/zh_CN/api-guides/unit-tests.rst | 6 +- docs/zh_CN/api-reference/network/esp_mesh.rst | 2 +- docs/zh_CN/api-reference/network/esp_now.rst | 2 +- .../zh_CN/api-reference/peripherals/index.rst | 8 +- docs/zh_CN/api-reference/peripherals/ledc.rst | 3 +- .../api-reference/peripherals/touch_pad.rst | 3 +- docs/zh_CN/api-reference/protocols/index.rst | 2 +- docs/zh_CN/api-reference/storage/sdmmc.rst | 8 +- 38 files changed, 312 insertions(+), 273 deletions(-) diff --git a/components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h b/components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h index 733c718aa6..486a3a8a82 100644 --- a/components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h +++ b/components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h @@ -439,11 +439,11 @@ typedef struct { struct esp_ble_mesh_model { /** Model ID */ union { - const uint16_t model_id; - struct { - uint16_t company_id; - uint16_t model_id; - } vnd; + const uint16_t model_id; /*!< 16-bit model identifier */ + struct esp_ble_mesh_vnd_struct { + uint16_t company_id; /*!< 16-bit company identifier */ + uint16_t model_id; /*!< 16-bit model identifier */ + } vnd; /*!< Structure encapsulating a model ID with a company ID */ }; /** Internal information, mainly for persistent storage */ @@ -656,7 +656,7 @@ typedef struct { typedef struct { union { struct { - esp_ble_mesh_bd_addr_t addr; /*!< Device address */ + esp_ble_mesh_bd_addr_t addr; /*!< Device address */ esp_ble_mesh_addr_type_t addr_type; /*!< Device address type */ }; uint8_t uuid[16]; /*!< Device UUID */ diff --git a/components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h b/components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h index 3b002a405f..903b17c32b 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h @@ -31,7 +31,8 @@ extern "C" { typedef uint8_t esp_a2d_mct_t; -/// A2DP media codec capabilities union +/** A2DP media codec capabilities union + */ typedef struct { esp_a2d_mct_t type; /*!< A2DP media codec type */ #define ESP_A2D_CIE_LEN_SBC (4) @@ -39,10 +40,10 @@ typedef struct { #define ESP_A2D_CIE_LEN_M24 (6) #define ESP_A2D_CIE_LEN_ATRAC (7) union { - uint8_t sbc[ESP_A2D_CIE_LEN_SBC]; - uint8_t m12[ESP_A2D_CIE_LEN_M12]; - uint8_t m24[ESP_A2D_CIE_LEN_M24]; - uint8_t atrac[ESP_A2D_CIE_LEN_ATRAC]; + uint8_t sbc[ESP_A2D_CIE_LEN_SBC]; /*!< SBC codec capabilities */ + uint8_t m12[ESP_A2D_CIE_LEN_M12]; /*!< MPEG-1,2 audio codec capabilities */ + uint8_t m24[ESP_A2D_CIE_LEN_M24]; /*!< MPEG-2, 4 AAC audio codec capabilities */ + uint8_t atrac[ESP_A2D_CIE_LEN_ATRAC]; /*!< ATRAC family codec capabilities */ } cie; /*!< A2DP codec information element */ } __attribute__((packed)) esp_a2d_mcc_t; diff --git a/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h b/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h index 51044d45c7..906dbd3e78 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h +++ b/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h @@ -86,9 +86,9 @@ typedef struct { #define ESP_UUID_LEN_128 16 uint16_t len; /*!< UUID length, 16bit, 32bit or 128bit */ union { - uint16_t uuid16; - uint32_t uuid32; - uint8_t uuid128[ESP_UUID_LEN_128]; + uint16_t uuid16; /*!< 16bit UUID */ + uint32_t uuid32; /*!< 32bit UUID */ + uint8_t uuid128[ESP_UUID_LEN_128]; /*!< 128bit UUID */ } uuid; /*!< UUID */ } __attribute__((packed)) esp_bt_uuid_t; diff --git a/components/driver/esp32s2/include/touch_sensor.h b/components/driver/esp32s2/include/touch_sensor.h index b677b85e51..d4de6ba3a7 100644 --- a/components/driver/esp32s2/include/touch_sensor.h +++ b/components/driver/esp32s2/include/touch_sensor.h @@ -51,22 +51,22 @@ esp_err_t touch_pad_sw_start(void); * sleep_cycle decide the interval between each measurement. * t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency). * The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function. - * @param meas_timers The times of charge and discharge in each measure process of touch channels. - * The timer frequency is 8Mhz. Range: 0 ~ 0xffff. - * Recommended typical value: Modify this value to make the measurement time around 1ms. + * @param meas_time The time of charge and discharge in each measure process of touch channels. + * The timer frequency is 8Mhz. Range: 0 ~ 0xffff. + * Recommended typical value: Modify this value to make the measurement time around 1ms. * @return * - ESP_OK on success */ -esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times); +esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_time); /** * @brief Get touch sensor times of charge and discharge and sleep time * @param sleep_cycle Pointer to accept sleep cycle number - * @param meas_times Pointer to accept measurement times count. + * @param meas_time Pointer to accept measurement time count. * @return * - ESP_OK on success */ -esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times); +esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_time); /** * @brief Set connection type of touch channel in idle status. @@ -196,7 +196,7 @@ uint32_t touch_pad_read_intr_status_mask(void); /** * @brief Enable touch sensor interrupt by bitmask. - * @param type interrupt type + * @param int_mask Pad mask to enable interrupts * @return * - ESP_OK on success */ @@ -204,7 +204,7 @@ esp_err_t touch_pad_intr_enable(touch_pad_intr_mask_t int_mask); /** * @brief Disable touch sensor interrupt by bitmask. - * @param type interrupt type + * @param int_mask Pad mask to disable interrupts * @return * - ESP_OK on success */ @@ -215,12 +215,13 @@ esp_err_t touch_pad_intr_disable(touch_pad_intr_mask_t int_mask); * The handler will be attached to the same CPU core that this function is running on. * @param fn Pointer to ISR handler * @param arg Parameter for ISR + * @param int_mask Initial pad mask to enable interrupt for * @return * - ESP_OK Success ; * - ESP_ERR_INVALID_ARG GPIO error * - ESP_ERR_NO_MEM No memory */ -esp_err_t touch_pad_isr_register(intr_handler_t fn, void* arg, touch_pad_intr_mask_t intr_mask); +esp_err_t touch_pad_isr_register(intr_handler_t fn, void* arg, touch_pad_intr_mask_t int_mask); /** * @brief get raw data of touch sensor. @@ -239,7 +240,7 @@ esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint32_t *raw_data); * @brief get baseline of touch sensor. * @note After initialization, the baseline value is the maximum during the first measurement period. * @param touch_num touch pad index - * @param touch_value pointer to accept touch sensor value + * @param basedata pointer to accept touch sensor baseline value * @return * - ESP_OK Success * - ESP_ERR_INVALID_ARG Touch channel 0 havent this parameter. @@ -331,7 +332,7 @@ esp_err_t touch_pad_denoise_disable(void); /** * @brief Get denoise measure value (TOUCH_PAD_NUM0). - * @param denoise value of denoise + * @param data Pointer to receive denoise value * @return * - ESP_OK Success */ @@ -405,7 +406,7 @@ esp_err_t touch_pad_proximity_get_config(touch_pad_proximity_t *proximity); * @brief Get measure count of proximity channel. * The proximity sensor measurement is the accumulation of touch channel measurements. * @param touch_num touch pad index - * @param proximity parameter of proximity + * @param cnt Pointer to receive proximity channel measurement count * @return * - ESP_OK Success * - ESP_ERR_INVALID_ARG parameter is NULL @@ -462,4 +463,4 @@ esp_err_t touch_pad_sleep_channel_read_proximity_cnt(uint32_t *proximity_cnt); #ifdef __cplusplus } -#endif \ No newline at end of file +#endif diff --git a/components/driver/include/driver/timer.h b/components/driver/include/driver/timer.h index f99784410f..a4888fb088 100644 --- a/components/driver/include/driver/timer.h +++ b/components/driver/include/driver/timer.h @@ -331,8 +331,6 @@ esp_err_t timer_disable_intr(timer_group_t group_num, timer_idx_t timer_num); * @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1 * @param timer_num Timer index. * - * @return - * - None */ void timer_group_intr_clr_in_isr(timer_group_t group_num, timer_idx_t timer_num) __attribute__((deprecated)); @@ -341,8 +339,6 @@ void timer_group_intr_clr_in_isr(timer_group_t group_num, timer_idx_t timer_num) * @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1 * @param timer_num Timer index. * - * @return - * - None */ void timer_group_clr_intr_status_in_isr(timer_group_t group_num, timer_idx_t timer_num); @@ -351,8 +347,6 @@ void timer_group_clr_intr_status_in_isr(timer_group_t group_num, timer_idx_t tim * @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1 * @param timer_num Timer index. * - * @return - * - None */ void timer_group_enable_alarm_in_isr(timer_group_t group_num, timer_idx_t timer_num); @@ -372,8 +366,6 @@ uint64_t timer_group_get_counter_value_in_isr(timer_group_t group_num, timer_idx * @param timer_num Timer index. * @param alarm_val Alarm threshold. * - * @return - * - None */ void timer_group_set_alarm_value_in_isr(timer_group_t group_num, timer_idx_t timer_num, uint64_t alarm_val); @@ -383,8 +375,6 @@ void timer_group_set_alarm_value_in_isr(timer_group_t group_num, timer_idx_t tim * @param timer_num Timer index. * @param counter_en Enable/disable. * - * @return - * - None */ void timer_group_set_counter_enable_in_isr(timer_group_t group_num, timer_idx_t timer_num, timer_start_t counter_en); @@ -411,8 +401,6 @@ uint32_t timer_group_get_intr_status_in_isr(timer_group_t group_num); * @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1 * @param intr_mask Masked interrupt. * - * @return - * - None */ void timer_group_clr_intr_sta_in_isr(timer_group_t group_num, timer_intr_t intr_mask) __attribute__((deprecated)); diff --git a/components/esp32/include/esp_intr_alloc.h b/components/esp32/include/esp_intr_alloc.h index cafc178bfc..67aca5b779 100644 --- a/components/esp32/include/esp_intr_alloc.h +++ b/components/esp32/include/esp_intr_alloc.h @@ -56,7 +56,6 @@ extern "C" { #define ESP_INTR_FLAG_LEVELMASK (ESP_INTR_FLAG_LEVEL1|ESP_INTR_FLAG_LEVEL2|ESP_INTR_FLAG_LEVEL3| \ ESP_INTR_FLAG_LEVEL4|ESP_INTR_FLAG_LEVEL5|ESP_INTR_FLAG_LEVEL6| \ ESP_INTR_FLAG_NMI) ///< Mask for all level flags -/**@}*/ /** @addtogroup Intr_Alloc_Pseudo_Src @@ -78,16 +77,23 @@ extern "C" { /**@}*/ -// This is used to provide SystemView with positive IRQ IDs, otherwise sheduler events are not shown properly +/** Provides SystemView with positive IRQ IDs, otherwise scheduler events are not shown properly + */ #define ETS_INTERNAL_INTR_SOURCE_OFF (-ETS_INTERNAL_PROFILING_INTR_SOURCE) +/** Enable interrupt by interrupt number */ #define ESP_INTR_ENABLE(inum) xt_ints_on((1<::@NUM not ::name) + RE_ANONYMOUS_FIELD = re.compile(r".+:line: warning: parameters of member [^:\s]+(::[^:\s]+)*(::@\d+)+ are not \(all\) documented") + all_messages = [msg for msg in all_messages if not re.match(RE_ANONYMOUS_FIELD, msg.sanitized_text)] + # Collect all new messages that are not match with the known messages. # The order is an important. new_messages = list() diff --git a/docs/conf_common.py b/docs/conf_common.py index 6d4e94b0ed..cd1d3768e5 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -21,6 +21,7 @@ import os import os.path import re import subprocess +from idf_extensions.util import download_file_if_missing # build_docs on the CI server sometimes fails under Python3. This is a workaround: sys.setrecursionlimit(3500) @@ -132,22 +133,31 @@ def update_exclude_patterns(tags): 'api-guides/esp-ble-mesh/**', 'api-guides/ulp-legacy.rst', 'api-guides/unit-tests-legacy.rst', + 'api-guides/ulp_instruction_set.rst', 'api-guides/jtag-debugging/configure-wrover.rst', 'api-reference/system/himem.rst', 'api-reference/bluetooth/**', + 'api-reference/peripherals/sdio_slave.rst', + 'api-reference/peripherals/esp_slave_protocol.rst', + 'api-reference/peripherals/mcpwm.rst', + 'api-reference/peripherals/sd_pullup_requirements.rst', + 'api-reference/peripherals/sdmmc_host.rst', + 'api-reference/protocols/esp_serial_slave_link.rst', 'api-reference/system/ipc.rst', 'get-started-legacy/**', 'gnu-make-legacy.rst', - 'hw-reference/esp32/**']: + 'hw-reference/esp32/**', + ]: exclude_patterns.append(e) if "esp32s2" not in tags: # Exclude ESP32-only document pages so they aren't found in the initial search for .rst files # note: in toctrees, these also need to be marked with a :esp32: filter - for e in ['hw-reference/esp32s2/**']: + for e in ['hw-reference/esp32s2/**', + 'api-guides/ulps2_instruction_set.rst', + 'api-reference/peripherals/temp_sensor.rst']: exclude_patterns.append(e) - # The reST default role (used for this markup: `text`) to use for all # documents. # default_role = None diff --git a/docs/doxygen-known-warnings.txt b/docs/doxygen-known-warnings.txt index e69de29bb2..a2fd1018ee 100644 --- a/docs/doxygen-known-warnings.txt +++ b/docs/doxygen-known-warnings.txt @@ -0,0 +1 @@ +semphr.h:line: warning: argument 'pxStaticSemaphore' of command @param is not found in the argument list of xSemaphoreCreateCounting(uxMaxCount, uxInitialCount) diff --git a/docs/en/api-guides/fatal-errors.rst b/docs/en/api-guides/fatal-errors.rst index 8dd54b561f..c01a70c780 100644 --- a/docs/en/api-guides/fatal-errors.rst +++ b/docs/en/api-guides/fatal-errors.rst @@ -62,7 +62,9 @@ Behavior of panic handler is affected by two other configuration options. - If :doc:`Core Dump ` feature is enabled, then system state (task stacks and registers) will be dumped either to Flash or UART, for later analysis. -- If :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM` is disabled (disabled by default), the panic handler code is placed in flash memory not IRAM. This means that if ESP-IDF crashes while flash cache is disabled, the panic handler will automatically re-enable flash cache before running GDB Stub or Core Dump. This adds some minor risk, if the flash cache status is also corrupted during the crash. +.. only:: esp32 + + - If :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM` is disabled (disabled by default), the panic handler code is placed in flash memory not IRAM. This means that if ESP-IDF crashes while flash cache is disabled, the panic handler will automatically re-enable flash cache before running GDB Stub or Core Dump. This adds some minor risk, if the flash cache status is also corrupted during the crash. If this option is enabled, the panic handler code is placed in IRAM. This allows the panic handler to run without needing to re-enable cache first. This may be necessary to debug some complex issues with crashes while flash cache is disabled (for example, when writing to SPI flash). diff --git a/docs/en/api-guides/freertos-smp.rst b/docs/en/api-guides/freertos-smp.rst index 1c01774715..e5c2fd62a8 100644 --- a/docs/en/api-guides/freertos-smp.rst +++ b/docs/en/api-guides/freertos-smp.rst @@ -412,7 +412,7 @@ matter. .. _floating-points: Floating Point Arithmetic - ------------------------ + ------------------------- ESP-IDF FreeRTOS implements Lazy Context Switching for FPUs. In other words, the state of a core's FPU registers are not immediately saved when a context diff --git a/docs/en/api-guides/lwip.rst b/docs/en/api-guides/lwip.rst index 66b4381830..a4497afbfa 100644 --- a/docs/en/api-guides/lwip.rst +++ b/docs/en/api-guides/lwip.rst @@ -325,7 +325,15 @@ IP layer features Limitations ^^^^^^^^^^^ -- Calling ``send()`` or ``sendto()`` repeatedly on a UDP socket may eventually fail with ``errno`` equal to ``ENOMEM``. This is a limitation of buffer sizes in the lower layer network interface drivers. If all driver transmit buffers are full then UDP transmission will fail. Applications sending a high volume of UDP datagrams who don't wish for any to be dropped by the sender should check for this error code and re-send the datagram after a short delay. Increasing the number of TX buffers in the :ref:`Wi-Fi ` or :ref:`Ethernet ` project configuration (as applicable) may also help. +- Calling ``send()`` or ``sendto()`` repeatedly on a UDP socket may eventually fail with ``errno`` equal to ``ENOMEM``. This is a limitation of buffer sizes in the lower layer network interface drivers. If all driver transmit buffers are full then UDP transmission will fail. Applications sending a high volume of UDP datagrams who don't wish for any to be dropped by the sender should check for this error code and re-send the datagram after a short delay. + +.. only::esp32 + + Increasing the number of TX buffers in the :ref:`Wi-Fi ` or :ref:`Ethernet ` project configuration (as applicable) may also help. + +.. only::esp32s2 + + Increasing the number of TX buffers in the :ref:`Wi-Fi ` project configuration may also help. Performance Optimization ------------------------ diff --git a/docs/en/api-reference/peripherals/adc.rst b/docs/en/api-reference/peripherals/adc.rst index b81a6747fd..b07bad67c9 100644 --- a/docs/en/api-reference/peripherals/adc.rst +++ b/docs/en/api-reference/peripherals/adc.rst @@ -85,7 +85,7 @@ Reading voltage on ADC2 channel 7 ({IDF_TARGET_ADC2_CH7}):: The reading may fail due to collision with Wi-Fi, should check it. An example using the ADC2 driver to read the output of DAC is available in esp-idf: :example:`peripherals/adc2` -.. only: esp32 +.. only:: esp32 Reading the internal hall effect sensor:: diff --git a/docs/en/api-reference/peripherals/esp_slave_protocol.rst b/docs/en/api-reference/peripherals/esp_slave_protocol.rst index 2e1b5e615a..c0650a9660 100644 --- a/docs/en/api-reference/peripherals/esp_slave_protocol.rst +++ b/docs/en/api-reference/peripherals/esp_slave_protocol.rst @@ -6,12 +6,6 @@ Communication with ESP SDIO Slave ESP SDIO slave initialization ------------------------------ -.. only:: esp32s2 - - .. note:: - - {IDF_TARGET_NAME} does not have a SDIO peripheral. - The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the standard SDIO initialization process (Sector 3.1.2 of `SDIO Simplified Specification `_). In this specification diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst index 23fec20d6a..7a3d5105fe 100644 --- a/docs/en/api-reference/peripherals/index.rst +++ b/docs/en/api-reference/peripherals/index.rst @@ -14,17 +14,17 @@ Peripherals API I2C I2S LED Control - MCPWM + :esp32: MCPWM Pulse Counter Remote Control - SD Pull-up Requirements - SDMMC Host + :esp32: SD Pull-up Requirements + :esp32: SDMMC Host SD SPI Host - SDIO Slave + :esp32: SDIO Slave Sigma-delta Modulation SPI Master SPI Slave - Temp sensor + :esp32s2: Temp sensor Timer Touch Sensor UART diff --git a/docs/en/api-reference/peripherals/sdio_slave.rst b/docs/en/api-reference/peripherals/sdio_slave.rst index 8c303b1833..93d3e241a5 100644 --- a/docs/en/api-reference/peripherals/sdio_slave.rst +++ b/docs/en/api-reference/peripherals/sdio_slave.rst @@ -4,14 +4,6 @@ SDIO Card Slave Driver Overview -------- -.. only:: esp32s2 - - .. note:: - - {IDF_TARGET_NAME} does not have a SDIO peripheral. - -.. only:: esp32 - The ESP32 SDIO Card peripherals (Host, Slave) shares two sets of pins as below table. The first set is usually occupied by SPI0 bus which is responsible for the SPI flash holding the code to run. This means SDIO slave driver can only runs on the second set of pins while SDIO host is not using it. diff --git a/docs/en/api-reference/peripherals/sdmmc_host.rst b/docs/en/api-reference/peripherals/sdmmc_host.rst index d9157d027b..a092c9c070 100644 --- a/docs/en/api-reference/peripherals/sdmmc_host.rst +++ b/docs/en/api-reference/peripherals/sdmmc_host.rst @@ -3,54 +3,47 @@ SDMMC Host Driver Overview -------- -.. only:: esp32s2 - .. note:: +ESP32's SDMMC host peripheral has two slots: - {IDF_TARGET_NAME} does not have a SDMMC host peripheral. +- Slot 0 (:c:macro:`SDMMC_HOST_SLOT_0`) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX. +- Slot 1 (:c:macro:`SDMMC_HOST_SLOT_1`) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX. -.. only:: esp32 +Pin mappings of these slots are given in the table below. - ESP32's SDMMC host peripheral has two slots: ++--------+-------------+-------------+ +| Signal | Slot 0 | Slot 1 | ++========+=============+=============+ +| CMD | GPIO11 | GPIO15 | ++--------+-------------+-------------+ +| CLK | GPIO6 | GPIO14 | ++--------+-------------+-------------+ +| D0 | GPIO7 | GPIO2 | ++--------+-------------+-------------+ +| D1 | GPIO8 | GPIO4 | ++--------+-------------+-------------+ +| D2 | GPIO9 | GPIO12 | ++--------+-------------+-------------+ +| D3 | GPIO10 | GPIO13 | ++--------+-------------+-------------+ +| D4 | GPIO16 | | ++--------+-------------+-------------+ +| D5 | GPIO17 | | ++--------+-------------+-------------+ +| D6 | GPIO5 | | ++--------+-------------+-------------+ +| D7 | GPIO18 | | ++--------+-------------+-------------+ +| CD | any input via GPIO matrix | ++--------+---------------------------+ +| WP | any input via GPIO matrix | ++--------+---------------------------+ - - Slot 0 (:c:macro:`SDMMC_HOST_SLOT_0`) is an 8-bit slot. It uses ``HS1_*`` signals in the PIN MUX. - - Slot 1 (:c:macro:`SDMMC_HOST_SLOT_1`) is a 4-bit slot. It uses ``HS2_*`` signals in the PIN MUX. +The Card Detect and Write Protect signals can be routed to arbitrary pins using the GPIO matrix. To reserve the pins, set the ``gpio_cd`` and ``gpio_wp`` members of the :cpp:class:`sdmmc_slot_config_t` structure before calling :cpp:func:`sdmmc_host_init_slot`. Please note that it is not advised to specify a Card Detect pin when working with SDIO cards, because the card detect signal in ESP32 can also trigger SDIO slave interrupt. - Pin mappings of these slots are given in the table below. +.. warning:: - +--------+-------------+-------------+ - | Signal | Slot 0 | Slot 1 | - +========+=============+=============+ - | CMD | GPIO11 | GPIO15 | - +--------+-------------+-------------+ - | CLK | GPIO6 | GPIO14 | - +--------+-------------+-------------+ - | D0 | GPIO7 | GPIO2 | - +--------+-------------+-------------+ - | D1 | GPIO8 | GPIO4 | - +--------+-------------+-------------+ - | D2 | GPIO9 | GPIO12 | - +--------+-------------+-------------+ - | D3 | GPIO10 | GPIO13 | - +--------+-------------+-------------+ - | D4 | GPIO16 | | - +--------+-------------+-------------+ - | D5 | GPIO17 | | - +--------+-------------+-------------+ - | D6 | GPIO5 | | - +--------+-------------+-------------+ - | D7 | GPIO18 | | - +--------+-------------+-------------+ - | CD | any input via GPIO matrix | - +--------+---------------------------+ - | WP | any input via GPIO matrix | - +--------+---------------------------+ - - The Card Detect and Write Protect signals can be routed to arbitrary pins using the GPIO matrix. To reserve the pins, set the ``gpio_cd`` and ``gpio_wp`` members of the :cpp:class:`sdmmc_slot_config_t` structure before calling :cpp:func:`sdmmc_host_init_slot`. Please note that it is not advised to specify a Card Detect pin when working with SDIO cards, because the card detect signal in ESP32 can also trigger SDIO slave interrupt. - - .. warning:: - - Pins used by Slot 0 (``HS1_*``) are also used to connect the SPI flash chip in ESP32-WROOM and ESP32-WROVER modules. These pins cannot be shared between an SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set eFuses accordingly. + Pins used by Slot 0 (``HS1_*``) are also used to connect the SPI flash chip in ESP32-WROOM and ESP32-WROVER modules. These pins cannot be shared between an SD card and SPI flash. If you need to use Slot 0, connect SPI flash to different pins and set eFuses accordingly. Supported Speed Modes diff --git a/docs/en/api-reference/peripherals/sdspi_host.rst b/docs/en/api-reference/peripherals/sdspi_host.rst index c20337b539..1f89b52849 100644 --- a/docs/en/api-reference/peripherals/sdspi_host.rst +++ b/docs/en/api-reference/peripherals/sdspi_host.rst @@ -4,7 +4,11 @@ SD SPI Host Driver Overview -------- -The SD SPI host driver allows using the SPI2 (HSPI) or SPI3 (VSPI) controller for communication with SD cards. This driver's naming pattern was adopted from the :doc:`SDMMC Host ` driver due to their similarity. Likewise, the APIs of both drivers are also very similar. +The SD SPI host driver allows using the SPI2 (HSPI) or SPI3 (VSPI) controller for communication with SD cards. + +.. only:: esp32 + + This driver's naming pattern was adopted from the :doc:`SDMMC Host ` driver due to their similarity. Likewise, the APIs of both drivers are also very similar. The SD SPI host driver has the following modes: diff --git a/docs/en/api-reference/peripherals/temp_sensor.rst b/docs/en/api-reference/peripherals/temp_sensor.rst index 9cfe8f819d..9fa4a977cf 100644 --- a/docs/en/api-reference/peripherals/temp_sensor.rst +++ b/docs/en/api-reference/peripherals/temp_sensor.rst @@ -4,30 +4,23 @@ ESP32-S2 Temperature Sensor Overview -------- -.. only:: esp32 +The ESP32-S2 has a built-in temperature sensor. The temperature sensor module contains an 8-bit Sigma-Delta ADC and a temperature offset DAC. - .. note:: +The conversion relationship is the first columns of the table below. Among them, offset = 0 is the main measurement option, and other values are extended measurement options. - ESP32 does not have a built-in temperature sensor. - -.. only:: esp32s2 - - The ESP32-S2 has a built-in temperature sensor. The temperature sensor module contains an 8-bit Sigma-Delta ADC and a temperature offset DAC. - The conversion relationship is the first columns of the table below. Among them, offset = 0 is the main measurement option, and other values are extended measurement options. - - +--------+------------------------+------------------------+ - | offset | measure range(Celsius) | measure error(Celsius) | - +========+========================+========================+ - | -2 | 50 ~ 125 | < 3 | - +--------+------------------------+------------------------+ - | -1 | 20 ~ 100 | < 2 | - +--------+------------------------+------------------------+ - | 0 | -10 ~ 80 | < 1 | - +--------+------------------------+------------------------+ - | 1 | -30 ~ 50 | < 2 | - +--------+------------------------+------------------------+ - | 2 | -40 ~ 20 | < 3 | - +--------+------------------------+------------------------+ ++--------+------------------------+------------------------+ +| offset | measure range(Celsius) | measure error(Celsius) | ++========+========================+========================+ +| -2 | 50 ~ 125 | < 3 | ++--------+------------------------+------------------------+ +| -1 | 20 ~ 100 | < 2 | ++--------+------------------------+------------------------+ +| 0 | -10 ~ 80 | < 1 | ++--------+------------------------+------------------------+ +| 1 | -30 ~ 50 | < 2 | ++--------+------------------------+------------------------+ +| 2 | -40 ~ 20 | < 3 | ++--------+------------------------+------------------------+ Application Example ------------------- diff --git a/docs/en/api-reference/storage/sdmmc.rst b/docs/en/api-reference/storage/sdmmc.rst index 4555cfa5cb..86aea71708 100644 --- a/docs/en/api-reference/storage/sdmmc.rst +++ b/docs/en/api-reference/storage/sdmmc.rst @@ -16,74 +16,79 @@ SDMMC and SD SPI host drivers (:component:`driver/include/driver/sdmmc_host.h`) For functions used to initialize and configure: -- SDMMC host, see :doc:`SDMMC Host API <../peripherals/sdmmc_host>` -- SD SPI host, see :doc:`SD SPI Host API <../peripherals/sdspi_host>` +.. only:: esp32 + + - SDMMC host, see :doc:`SDMMC Host API <../peripherals/sdmmc_host>` + + - SD SPI host, see :doc:`SD SPI Host API <../peripherals/sdspi_host>` -The SDMMC protocol layer described in this document handles the specifics of the SD protocol, such as the card initialization and data transfer commands. + The SDMMC protocol layer described in this document handles the specifics of the SD protocol, such as the card initialization and data transfer commands. -The protocol layer works with the host via the :cpp:class:`sdmmc_host_t` structure. This structure contains pointers to various functions of the host. + The protocol layer works with the host via the :cpp:class:`sdmmc_host_t` structure. This structure contains pointers to various functions of the host. -Application Example -------------------- + Application Example + ------------------- -An example which combines the SDMMC driver with the FATFS library is provided in the :example:`storage/sd_card` directory of ESP-IDF examples. This example initializes the card, then writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information. + An example which combines the SDMMC driver with the FATFS library is provided in the :example:`storage/sd_card` directory of ESP-IDF examples. This example initializes the card, then writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information. -Protocol layer API ------------------- + Protocol layer API + ------------------ -The protocol layer is given the :cpp:class:`sdmmc_host_t` structure. This structure describes the SD/MMC host driver, lists its capabilities, and provides pointers to functions of the driver. The protocol layer stores card-specific information in the :cpp:class:`sdmmc_card_t` structure. When sending commands to the SD/MMC host driver, the protocol layer uses the :cpp:class:`sdmmc_command_t` structure to describe the command, arguments, expected return values, and data to transfer if there is any. + The protocol layer is given the :cpp:class:`sdmmc_host_t` structure. This structure describes the SD/MMC host driver, lists its capabilities, and provides pointers to functions of the driver. The protocol layer stores card-specific information in the :cpp:class:`sdmmc_card_t` structure. When sending commands to the SD/MMC host driver, the protocol layer uses the :cpp:class:`sdmmc_command_t` structure to describe the command, arguments, expected return values, and data to transfer if there is any. -Using API with SD memory cards -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Using API with SD memory cards + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. To initialize the host, call the host driver functions, e.g., :cpp:func:`sdmmc_host_init`, :cpp:func:`sdmmc_host_init_slot`. -2. To initialize the card, call :cpp:func:`sdmmc_card_init` and pass to it the parameters ``host`` - the host driver information, and ``card`` - a pointer to the structure :cpp:class:`sdmmc_card_t` which will be filled with information about the card when the function completes. -3. To read and write sectors of the card, use :cpp:func:`sdmmc_read_sectors` and :cpp:func:`sdmmc_write_sectors` respectively and pass to it the parameter ``card`` - a pointer to the card information structure. -4. If the card is not used anymore, call the host driver function - e.g., :cpp:func:`sdmmc_host_deinit` - to disable the host peripheral and free the resources allocated by the driver. + 1. To initialize the host, call the host driver functions, e.g., :cpp:func:`sdmmc_host_init`, :cpp:func:`sdmmc_host_init_slot`. + 2. To initialize the card, call :cpp:func:`sdmmc_card_init` and pass to it the parameters ``host`` - the host driver information, and ``card`` - a pointer to the structure :cpp:class:`sdmmc_card_t` which will be filled with information about the card when the function completes. + 3. To read and write sectors of the card, use :cpp:func:`sdmmc_read_sectors` and :cpp:func:`sdmmc_write_sectors` respectively and pass to it the parameter ``card`` - a pointer to the card information structure. + 4. If the card is not used anymore, call the host driver function - e.g., :cpp:func:`sdmmc_host_deinit` - to disable the host peripheral and free the resources allocated by the driver. -Using API with eMMC chips -^^^^^^^^^^^^^^^^^^^^^^^^^ + Using API with eMMC chips + ^^^^^^^^^^^^^^^^^^^^^^^^^ -From the protocol layer's perspective, eMMC memory chips behave exactly like SD memory cards. Even though eMMCs are chips and do not have a card form factor, the terminology for SD cards can still be applied to eMMC due to the similarity of the protocol (`sdmmc_card_t`, `sdmmc_card_init`). Note that eMMC chips cannot be used over SPI, which makes them incompatible with the SD SPI host driver. + From the protocol layer's perspective, eMMC memory chips behave exactly like SD memory cards. Even though eMMCs are chips and do not have a card form factor, the terminology for SD cards can still be applied to eMMC due to the similarity of the protocol (`sdmmc_card_t`, `sdmmc_card_init`). Note that eMMC chips cannot be used over SPI, which makes them incompatible with the SD SPI host driver. -To initialize eMMC memory and perform read/write operations, follow the steps listed for SD cards in the previous section. + To initialize eMMC memory and perform read/write operations, follow the steps listed for SD cards in the previous section. -Using API with SDIO cards -^^^^^^^^^^^^^^^^^^^^^^^^^ + Using API with SDIO cards + ^^^^^^^^^^^^^^^^^^^^^^^^^ -Initialization and the probing process is the same as with SD memory cards. The only difference is in data transfer commands in SDIO mode. + Initialization and the probing process is the same as with SD memory cards. The only difference is in data transfer commands in SDIO mode. -During the card initialization and probing, performed with :cpp:func:`sdmmc_card_init`, the driver only configures the following registers of the IO card: + During the card initialization and probing, performed with :cpp:func:`sdmmc_card_init`, the driver only configures the following registers of the IO card: -1. The IO portion of the card is reset by setting RES bit in the I/O Abort (0x06) register. -2. If 4-line mode is enabled in host and slot configuration, the driver attempts to set the Bus width field in the Bus Interface Control (0x07) register. If setting the filed is successful, which means that the slave supports 4-line mode, the host is also switched to 4-line mode. -3. If high-speed mode is enabled in the host configuration, the SHS bit is set in the High Speed (0x13) register. + 1. The IO portion of the card is reset by setting RES bit in the I/O Abort (0x06) register. + 2. If 4-line mode is enabled in host and slot configuration, the driver attempts to set the Bus width field in the Bus Interface Control (0x07) register. If setting the filed is successful, which means that the slave supports 4-line mode, the host is also switched to 4-line mode. + 3. If high-speed mode is enabled in the host configuration, the SHS bit is set in the High Speed (0x13) register. -In particular, the driver does not set any bits in (1) I/O Enable and Int Enable registers, (2) I/O block sizes, etc. Applications can set them by calling :cpp:func:`sdmmc_io_write_byte`. + In particular, the driver does not set any bits in (1) I/O Enable and Int Enable registers, (2) I/O block sizes, etc. Applications can set them by calling :cpp:func:`sdmmc_io_write_byte`. -For card configuration and data transfer, choose the pair of functions relevant to your case from the table below. + For card configuration and data transfer, choose the pair of functions relevant to your case from the table below. -========================================================================= ================================= ================================= -Action Read Function Write Function -========================================================================= ================================= ================================= -Read and write a single byte using IO_RW_DIRECT (CMD52) :cpp:func:`sdmmc_io_read_byte` :cpp:func:`sdmmc_io_write_byte` -Read and write multiple bytes using IO_RW_EXTENDED (CMD53) in byte mode :cpp:func:`sdmmc_io_read_bytes` :cpp:func:`sdmmc_io_write_bytes` -Read and write blocks of data using IO_RW_EXTENDED (CMD53) in block mode :cpp:func:`sdmmc_io_read_blocks` :cpp:func:`sdmmc_io_write_blocks` -========================================================================= ================================= ================================= + ========================================================================= ================================= ================================= + Action Read Function Write Function + ========================================================================= ================================= ================================= + Read and write a single byte using IO_RW_DIRECT (CMD52) :cpp:func:`sdmmc_io_read_byte` :cpp:func:`sdmmc_io_write_byte` + Read and write multiple bytes using IO_RW_EXTENDED (CMD53) in byte mode :cpp:func:`sdmmc_io_read_bytes` :cpp:func:`sdmmc_io_write_bytes` + Read and write blocks of data using IO_RW_EXTENDED (CMD53) in block mode :cpp:func:`sdmmc_io_read_blocks` :cpp:func:`sdmmc_io_write_blocks` + ========================================================================= ================================= ================================= -SDIO interrupts can be enabled by the application using the function :cpp:func:`sdmmc_io_enable_int`. When using SDIO in 1-line mode, the D1 line also needs to be connected to use SDIO interrupts. + SDIO interrupts can be enabled by the application using the function :cpp:func:`sdmmc_io_enable_int`. When using SDIO in 1-line mode, the D1 line also needs to be connected to use SDIO interrupts. -If you want the application to wait until the SDIO interrupt occurs, use :cpp:func:`sdmmc_io_wait_int`. + If you want the application to wait until the SDIO interrupt occurs, use :cpp:func:`sdmmc_io_wait_int`. -There is a component ESSL (ESP Serial Slave Link) to use if you are communicating with an ESP32 -SDIO slave. See :doc:`/api-reference/protocols/esp_serial_slave_link` and example :example:`peripherals/sdio/host`. + .. only:: esp32 + + There is a component ESSL (ESP Serial Slave Link) to use if you are communicating with an ESP32 + SDIO slave. See :doc:`/api-reference/protocols/esp_serial_slave_link` and example :example:`peripherals/sdio/host`. Combo (memory + IO) cards ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/en/api-reference/system/system_time.rst b/docs/en/api-reference/system/system_time.rst index d0b94ef0e2..22a52ad39c 100644 --- a/docs/en/api-reference/system/system_time.rst +++ b/docs/en/api-reference/system/system_time.rst @@ -19,7 +19,7 @@ The settings for the system time source are as follows: - High-resolution timer - None -It is recommended to stick to the default setting which provides maximum accuracy. If you want to choose a different timer, configure :ref:`CONFIG_ESP32_TIME_SYSCALL` in project configuration. +It is recommended to stick to the default setting which provides maximum accuracy. If you want to choose a different timer, configure :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_TIME_SYSCALL` in project configuration. RTC Clock Source @@ -35,7 +35,7 @@ The RTC timer has the following clock sources: - ``Internal 8.5MHz oscillator, divided by 256 (~33kHz)``. Provides better frequency stability than the ``internal 150kHz RC oscillator`` at the expense of higher (by 5 uA) deep sleep current consumption. It also does not require external components. -The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set :ref:`CONFIG_ESP32_RTC_CLK_SRC` in project configuration. +The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_RTC_CLK_SRC` in project configuration. More details on wiring requirements for the ``External 32kHz crystal`` and ``External 32kHz oscillator at 32K_XP pin`` sources can be found in Section 2.1.4 *Crystal Oscillator* of `Hardware Design Guidelines `_. @@ -130,4 +130,4 @@ Once these steps are completed, call the standard C library function ``localtime API Reference ------------- -.. include:: /_build/inc/sntp.inc +.. include-build-file:: inc/sntp.inc diff --git a/docs/sphinx-known-warnings.txt b/docs/sphinx-known-warnings.txt index 777b2138f0..89e5f49438 100644 --- a/docs/sphinx-known-warnings.txt +++ b/docs/sphinx-known-warnings.txt @@ -40,6 +40,12 @@ ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point) ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us) README.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point) + + +# This seems like a bug, as the field are ::model_id and ::vnd::model_id +esp_ble_mesh_defs.inc:line: WARNING: Duplicate declaration, uint16_t esp_ble_mesh_model::model_id + + # # Issue present only when building on msys2 / mingw32 START >>> # diff --git a/docs/zh_CN/api-guides/unit-tests-legacy.rst b/docs/zh_CN/api-guides/unit-tests-legacy.rst index 26e6b6c887..81a1a44958 100644 --- a/docs/zh_CN/api-guides/unit-tests-legacy.rst +++ b/docs/zh_CN/api-guides/unit-tests-legacy.rst @@ -92,14 +92,14 @@ GPIO、SPI）需要与其通信的其他设备，因此不能使用常规测试 DUT1（master）终端： -.. code:: bash +.. code:: Waiting for signal: [output high level]! Please press "Enter" key once any board send this signal. DUT2（slave）终端： -.. code:: bash +.. code:: Send signal: [output high level]! @@ -183,7 +183,7 @@ DUT2 终端:: 当单元测试应用程序空闲时，输入回车键，它会打印出测试菜单，其中包含所有的测试项目。 -.. code:: bash +.. code:: Here's the test menu, pick your combo: (1) "esp_ota_begin() verifies arguments" [ota] @@ -230,7 +230,7 @@ DUT2 终端:: 一旦选择了多设备测试用例，它会打印一个子菜单： -.. code:: bash +.. code:: Running gpio master/slave test example... gpio master/slave test example @@ -241,7 +241,7 @@ DUT2 终端:: 与多设备测试用例相似，多阶段测试用例也会打印子菜单： -.. code:: bash +.. code:: Running reset reason check for deepsleep... reset reason check for deepsleep diff --git a/docs/zh_CN/api-guides/unit-tests.rst b/docs/zh_CN/api-guides/unit-tests.rst index fed2fd1303..0145544df3 100644 --- a/docs/zh_CN/api-guides/unit-tests.rst +++ b/docs/zh_CN/api-guides/unit-tests.rst @@ -175,7 +175,7 @@ DUT2（slave）终端： 当单元测试应用程序空闲时，输入回车键，它会打印出测试菜单，其中包含所有的测试项目。 -.. code:: bash +.. code:: Here's the test menu, pick your combo: (1) "esp_ota_begin() verifies arguments" [ota] @@ -222,7 +222,7 @@ DUT2（slave）终端： 一旦选择了多设备测试用例，它会打印一个子菜单： -.. code:: bash +.. code:: Running gpio master/slave test example... gpio master/slave test example @@ -233,7 +233,7 @@ DUT2（slave）终端： 与多设备测试用例相似，多阶段测试用例也会打印子菜单： -.. code:: bash +.. code:: Running reset reason check for deepsleep... reset reason check for deepsleep diff --git a/docs/zh_CN/api-reference/network/esp_mesh.rst b/docs/zh_CN/api-reference/network/esp_mesh.rst index 187a864a1f..a5487ad8ed 100644 --- a/docs/zh_CN/api-reference/network/esp_mesh.rst +++ b/docs/zh_CN/api-reference/network/esp_mesh.rst @@ -332,5 +332,5 @@ ESP-IDF 包含以下 ESP-MESH 示例项目： API 参考 -------------- -.. include:: /_build/inc/esp_mesh.inc +.. include-build-file:: inc/esp_mesh.inc diff --git a/docs/zh_CN/api-reference/network/esp_now.rst b/docs/zh_CN/api-reference/network/esp_now.rst index 7ce944212c..1c58c1efe7 100644 --- a/docs/zh_CN/api-reference/network/esp_now.rst +++ b/docs/zh_CN/api-reference/network/esp_now.rst @@ -84,5 +84,5 @@ ESP-NOW 采用 CCMP 方法保护供应商特定动作帧的安全，具体可参 API 参考 ------------- -.. include:: /_build/inc/esp_now.inc +.. include-build-file:: inc/esp_now.inc diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst index 22d2cd55da..9f4fd1dcb0 100644 --- a/docs/zh_CN/api-reference/peripherals/index.rst +++ b/docs/zh_CN/api-reference/peripherals/index.rst @@ -13,16 +13,16 @@ I2C I2S LED Control - MCPWM + :esp32: MCPWM Pulse Counter Remote Control - SDMMC Host + :esp32: SDMMC Host SD SPI Host - SDIO Slave + :esp32: SDIO Slave Sigma-delta Modulation SPI Master SPI Slave - Temp sensor + :esp32s2: Temp sensor Timer Touch Sensor UART diff --git a/docs/zh_CN/api-reference/peripherals/ledc.rst b/docs/zh_CN/api-reference/peripherals/ledc.rst index 0c50edc45d..5822d9d65e 100644 --- a/docs/zh_CN/api-reference/peripherals/ledc.rst +++ b/docs/zh_CN/api-reference/peripherals/ledc.rst @@ -172,4 +172,5 @@ LED PWM 改变占空比和渐变控制的实例请参照 :example:`peripherals/l API 参考 ------------- -.. include:: /_build/inc/ledc.inc \ No newline at end of file +.. include-build-file:: inc/ledc.inc + diff --git a/docs/zh_CN/api-reference/peripherals/touch_pad.rst b/docs/zh_CN/api-reference/peripherals/touch_pad.rst index 1c9476fec4..57ae303025 100644 --- a/docs/zh_CN/api-reference/peripherals/touch_pad.rst +++ b/docs/zh_CN/api-reference/peripherals/touch_pad.rst @@ -156,7 +156,8 @@ ESP32 可支持最多 10 个电容式触摸板/GPIO，触摸板可以以矩阵 API 参考 ------------- -.. include-build-file:: inc/touch_pad.inc +.. include-build-file:: inc/touch_sensor.inc +.. include-build-file:: inc/touch_sensor_common.inc GPIO 宏查找表 ^^^^^^^^^^^^^^^^^^ diff --git a/docs/zh_CN/api-reference/protocols/index.rst b/docs/zh_CN/api-reference/protocols/index.rst index 66a1b3303c..b77f7eb545 100644 --- a/docs/zh_CN/api-reference/protocols/index.rst +++ b/docs/zh_CN/api-reference/protocols/index.rst @@ -16,7 +16,7 @@ ESP-MQTT Modbus slave Local Control - ESP Serial Slave Link + :esp32: ESP Serial Slave Link 此 API 部分的示例代码在 ESP-IDF 示例工程的 :example:`protocols` 目录下提供。 diff --git a/docs/zh_CN/api-reference/storage/sdmmc.rst b/docs/zh_CN/api-reference/storage/sdmmc.rst index 11ad8cf9ea..e9af6a3d63 100644 --- a/docs/zh_CN/api-reference/storage/sdmmc.rst +++ b/docs/zh_CN/api-reference/storage/sdmmc.rst @@ -16,7 +16,11 @@ SDMMC 主机驱动和 SD SPI 主机驱动（:component:`driver/include/driver/sd 初始化函数及配置函数： -- 如需初始化和配置 SDMMC 主机，请参阅 :doc:`SDMMC 主机 API <../peripherals/sdmmc_host>` +.. only:: esp32 + + - 如需初始化和配置 SDMMC 主机，请参阅 :doc:`SDMMC 主机 API <../peripherals/sdmmc_host>` + + - 如需初始化和配置 SD SPI 主机，请参阅 :doc:`SD SPI 主机 API <../peripherals/sdspi_host>` 本文档中所述的 SDMMC 协议层仅处理 SD 协议相关事项，例如卡初始化和数据传输命令。 @@ -94,4 +98,4 @@ API 参考 .. include-build-file:: inc/sdmmc_cmd.inc -.. include-build-file:: inc/sdmmc_types.inc \ No newline at end of file +.. include-build-file:: inc/sdmmc_types.inc From 844bdd8154b69b3fd24be8155c5fb705311cb491 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Wed, 29 Jan 2020 09:31:25 +1100 Subject: [PATCH 33/47] docs: Allow incremental builds --- docs/build_docs.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/build_docs.py b/docs/build_docs.py index 877179bd33..9dc902f69c 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -161,8 +161,7 @@ def sphinx_call(language, target, build_dir, sphinx_parallel_jobs, buildername): try: os.makedirs(build_dir) except OSError: - print("Cannot call Sphinx in an existing directory!") - return 1 + pass environ = {} environ.update(os.environ) From 740d422134bd1bc12e26e3fb513380826b67d722 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Wed, 29 Jan 2020 09:31:35 +1100 Subject: [PATCH 34/47] docs: Possible fix for blockdiag & seqdiag UnicodeEncodeErrors --- docs/conf_common.py | 29 +++++++++++++++++++++++++++++ docs/en/conf.py | 13 ------------- docs/zh_CN/conf.py | 12 ------------ 3 files changed, 29 insertions(+), 25 deletions(-) diff --git a/docs/conf_common.py b/docs/conf_common.py index cd1d3768e5..1820e0c352 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -26,6 +26,7 @@ from idf_extensions.util import download_file_if_missing # build_docs on the CI server sometimes fails under Python3. This is a workaround: sys.setrecursionlimit(3500) +config_dir = os.path.abspath(os.path.dirname(__file__)) # http://stackoverflow.com/questions/12772927/specifying-an-online-image-in-sphinx-restructuredtext-format # @@ -367,3 +368,31 @@ def setup(app): # note: we generate into xml_in and then copy_if_modified to xml dir app.config.breathe_projects = {"esp32-idf": os.path.join(app.config.build_dir, "xml_in/")} app.config.breathe_default_project = "esp32-idf" + + + setup_diag_font(app) + +def setup_diag_font(app): + # blockdiag and other tools require a font which supports their character set + # the font file is stored on the download server to save repo size + + font_name = { + 'en': 'DejaVuSans.ttf', + 'zh_CN': 'NotoSansSC-Regular.otf', + }[app.config.language] + + font_dir = os.path.join(config_dir, '_static') + assert os.path.exists(font_dir) + + print("Downloading font file %s for %s" % (font_name, app.config.language)) + download_file_if_missing('https://dl.espressif.com/dl/esp-idf/docs/_static/{}'.format(font_name), font_dir) + + font_path = os.path.abspath(os.path.join(font_dir, font_name)) + assert os.path.exists(font_path) + + app.config.blockdiag_fontpath = font_path + app.config.seqdiag_fontpath = font_path + app.config.actdiag_fontpath = font_path + app.config.nwdiag_fontpath = font_path + app.config.rackdiag_fontpath = font_path + app.config.packetdiag_fontpath = font_path diff --git a/docs/en/conf.py b/docs/en/conf.py index ec996f62f2..1bd7f8812f 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -10,7 +10,6 @@ import sys import os sys.path.insert(0, os.path.abspath('..')) from conf_common import * # noqa: F401, F403 - need to make available everything from common -from idf_extensions.util import download_file_if_missing # noqa: E402 - need to import from common folder # General information about the project. project = u'ESP-IDF Programming Guide' @@ -20,16 +19,4 @@ copyright = u'2016 - 2019, Espressif Systems (Shanghai) CO., LTD' # for a list of supported languages. language = 'en' -# Download font file that is stored on a separate server to save on esp-idf repository size. -print("Downloading font file") -download_file_if_missing('https://dl.espressif.com/dl/esp-idf/docs/_static/DejaVuSans.ttf', '../_static') - -# Set up font for blockdiag, nwdiag, rackdiag and packetdiag -blockdiag_fontpath = '../_static/DejaVuSans.ttf' -seqdiag_fontpath = '../_static/DejaVuSans.ttf' -actdiag_fontpath = '../_static/DejaVuSans.ttf' -nwdiag_fontpath = '../_static/DejaVuSans.ttf' -rackdiag_fontpath = '../_static/DejaVuSans.ttf' -packetdiag_fontpath = '../_static/DejaVuSans.ttf' - update_exclude_patterns(tags) # noqa: F405, need to import * from conf_common diff --git a/docs/zh_CN/conf.py b/docs/zh_CN/conf.py index b857bc0d75..70e377de10 100644 --- a/docs/zh_CN/conf.py +++ b/docs/zh_CN/conf.py @@ -20,16 +20,4 @@ copyright = u'2016 - 2019 乐鑫信息科技（上海）股份有限公司' # for a list of supported languages. language = 'zh_CN' -# Download font file that is stored on a separate server to save on esp-idf repository size. -print("Downloading font file") -download_file_if_missing('https://dl.espressif.com/dl/esp-idf/docs/_static/NotoSansSC-Regular.otf', '../_static') - -# Set up font for blockdiag, nwdiag, rackdiag and packetdiag -blockdiag_fontpath = '../_static/NotoSansSC-Regular.otf' -seqdiag_fontpath = '../_static/NotoSansSC-Regular.otf' -actdiag_fontpath = '../_static/NotoSansSC-Regular.otf' -nwdiag_fontpath = '../_static/NotoSansSC-Regular.otf' -rackdiag_fontpath = '../_static/NotoSansSC-Regular.otf' -packetdiag_fontpath = '../_static/NotoSansSC-Regular.otf' - update_exclude_patterns(tags) # noqa: F405, need to import * from conf_common From 50324b505deb3a3d80ca373eb3dfa1efced02143 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Thu, 30 Jan 2020 13:59:12 +1100 Subject: [PATCH 35/47] docs: Note that the idf target formatting filters don't work on "included" documents --- docs/en/api-reference/system/system_time.rst | 19 +++++++++++++++++-- docs/en/contribute/add-ons-reference.rst | 4 +++- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/en/api-reference/system/system_time.rst b/docs/en/api-reference/system/system_time.rst index 22a52ad39c..c1899a368c 100644 --- a/docs/en/api-reference/system/system_time.rst +++ b/docs/en/api-reference/system/system_time.rst @@ -19,7 +19,16 @@ The settings for the system time source are as follows: - High-resolution timer - None -It is recommended to stick to the default setting which provides maximum accuracy. If you want to choose a different timer, configure :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_TIME_SYSCALL` in project configuration. +.. + (Implementation note: Using only blocks in this file not IDF_CONFIG_CFG_PREFIX, until the zh_CN translation for this document is done.) + +.. only:: esp32 + + It is recommended to stick to the default setting which provides maximum accuracy. If you want to choose a different timer, configure :ref:`CONFIG_ESP32_TIME_SYSCALL` in project configuration. + +.. only:: esp32s2 + + It is recommended to stick to the default setting which provides maximum accuracy. If you want to choose a different timer, configure :ref:`CONFIG_ESP32S2_TIME_SYSCALL` in project configuration. RTC Clock Source @@ -35,7 +44,13 @@ The RTC timer has the following clock sources: - ``Internal 8.5MHz oscillator, divided by 256 (~33kHz)``. Provides better frequency stability than the ``internal 150kHz RC oscillator`` at the expense of higher (by 5 uA) deep sleep current consumption. It also does not require external components. -The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_RTC_CLK_SRC` in project configuration. +.. only:: esp32 + + The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set :ref:`CONFIG_ESP32_RTC_CLK_SRC` in project configuration. + +.. only:: esp32s2 + + The choice depends on your requirements for system time accuracy and power consumption in sleep modes. To modify the RTC clock source, set :ref:`CONFIG_ESP32S2_RTC_CLK_SRC` in project configuration. More details on wiring requirements for the ``External 32kHz crystal`` and ``External 32kHz oscillator at 32K_XP pin`` sources can be found in Section 2.1.4 *Crystal Oscillator* of `Hardware Design Guidelines `_. diff --git a/docs/en/contribute/add-ons-reference.rst b/docs/en/contribute/add-ons-reference.rst index 49d0d6e47f..25b70c48f4 100644 --- a/docs/en/contribute/add-ons-reference.rst +++ b/docs/en/contribute/add-ons-reference.rst @@ -154,7 +154,9 @@ Other Extensions This will define a replacement of the tag {\IDF_TARGET_TX_PIN} in the current rst-file. - These replacements cannot be used inside markup that rely on allignment of characters, e.g. tables. + These replacements cannot be used inside markup that rely on alignment of characters, e.g. tables. + + These replacement can't be used in a file which is `::include`-ed from another file. *This includes any English document where the ``zh_CN`` translation includes then ``en`` translation*. Related Documents ----------------- From 775448c792c16a62cd9ba085da7662466cf04552 Mon Sep 17 00:00:00 2001 From: Anton Maklakov Date: Fri, 24 Jan 2020 10:33:28 +0700 Subject: [PATCH 36/47] docs: Make Python 3 compatible --- docs/build_docs.py | 4 ++-- docs/idf_extensions/esp_err_definitions.py | 2 +- docs/idf_extensions/gen_toolchain_links.py | 2 +- docs/idf_extensions/gen_version_specific_includes.py | 2 +- docs/idf_extensions/kconfig_reference.py | 2 +- docs/idf_extensions/run_doxygen.py | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/build_docs.py b/docs/build_docs.py index 9dc902f69c..6d0b6420dc 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -188,9 +188,9 @@ def sphinx_call(language, target, build_dir, sphinx_parallel_jobs, buildername): # and sphinx.cmd.build() also does a lot of work in the calling thread, especially for j ==1, # so using a Pyhthon thread for this part is a poor option (GIL) p = subprocess.Popen(args, stdout=subprocess.PIPE, stderr=subprocess.STDOUT) - for c in iter(lambda: p.stdout.readline(), ''): + for c in iter(lambda: p.stdout.readline(), b''): sys.stdout.write(prefix) - sys.stdout.write(c) + sys.stdout.write(c.decode('utf-8')) ret = p.wait() assert (ret is not None) sys.stdout.flush() diff --git a/docs/idf_extensions/esp_err_definitions.py b/docs/idf_extensions/esp_err_definitions.py index c77ff5bb75..f8a80b2c51 100644 --- a/docs/idf_extensions/esp_err_definitions.py +++ b/docs/idf_extensions/esp_err_definitions.py @@ -1,5 +1,5 @@ # Extension to generate esp_err definition as .rst -from util import copy_if_modified, call_with_python +from .util import copy_if_modified, call_with_python def setup(app): diff --git a/docs/idf_extensions/gen_toolchain_links.py b/docs/idf_extensions/gen_toolchain_links.py index 183e39f81b..64699f9f15 100644 --- a/docs/idf_extensions/gen_toolchain_links.py +++ b/docs/idf_extensions/gen_toolchain_links.py @@ -2,7 +2,7 @@ from __future__ import print_function import os.path from collections import namedtuple -from util import copy_if_modified +from .util import copy_if_modified BASE_URL = 'https://dl.espressif.com/dl/' diff --git a/docs/idf_extensions/gen_version_specific_includes.py b/docs/idf_extensions/gen_version_specific_includes.py index 483f94c84b..fae92512b0 100755 --- a/docs/idf_extensions/gen_version_specific_includes.py +++ b/docs/idf_extensions/gen_version_specific_includes.py @@ -7,7 +7,7 @@ from __future__ import print_function from __future__ import unicode_literals from io import open -from util import copy_if_modified +from .util import copy_if_modified import subprocess import os import re diff --git a/docs/idf_extensions/kconfig_reference.py b/docs/idf_extensions/kconfig_reference.py index 2176683e2f..3ca9c79130 100644 --- a/docs/idf_extensions/kconfig_reference.py +++ b/docs/idf_extensions/kconfig_reference.py @@ -3,7 +3,7 @@ import os.path import sys import subprocess -from util import copy_if_modified +from .util import copy_if_modified def setup(app): diff --git a/docs/idf_extensions/run_doxygen.py b/docs/idf_extensions/run_doxygen.py index 7c3a6d21a8..32856ab664 100644 --- a/docs/idf_extensions/run_doxygen.py +++ b/docs/idf_extensions/run_doxygen.py @@ -7,7 +7,7 @@ import os import os.path import re import subprocess -from util import copy_if_modified +from .util import copy_if_modified ALL_KINDS = [ ("function", "Functions"), From 4bfd004c83d2f9b9b1781f6c0b6393467c077bc6 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 31 Jan 2020 16:18:48 +1100 Subject: [PATCH 37/47] build_docs gh-linkcheck: Use Python, ignore links to master branch SUPPORT_POLICY.md --- docs/build_docs.py | 39 ++++++++++++++++++++++----------------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/docs/build_docs.py b/docs/build_docs.py index 6d0b6420dc..0fa376ecdb 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -309,29 +309,34 @@ def call_linkcheck(entry): return sphinx_call(*entry, buildername="linkcheck") -GH_LINK_FILTER = ["https://github.com/espressif/esp-idf/tree", - "https://github.com/espressif/esp-idf/blob", - "https://github.com/espressif/esp-idf/raw"] +# https://github.com/espressif/esp-idf/tree/ +# https://github.com/espressif/esp-idf/blob/ +# https://github.com/espressif/esp-idf/raw/ +GH_LINK_RE = r"https://github.com/espressif/esp-idf/(?:tree|blob|raw)/[^\s]+" +# we allow this one link, because we always want users to see the latest support policy +GH_LINK_ALLOWED = [ "https://github.com/espressif/esp-idf/blob/master/SUPPORT_POLICY.md" ] def action_gh_linkcheck(args): print("Checking for hardcoded GitHub links\n") - find_args = ['find', - os.path.join(os.path.abspath(os.path.dirname(__file__)), ".."), - '-name', - '*.rst'] - grep_args = ['xargs', - 'grep', - r'\|'.join(GH_LINK_FILTER)] + github_links = [] - p1 = subprocess.Popen(find_args, stdout=subprocess.PIPE) - p2 = subprocess.Popen(grep_args, stdin=p1.stdout, stdout=subprocess.PIPE) - p1.stdout.close() - found_gh_links, _ = p2.communicate() - if found_gh_links: - print(found_gh_links) - print("WARNINIG: Some .rst files contain hardcoded Github links.") + docs_dir = os.path.relpath(os.path.dirname(__file__)) + for root, _, files in os.walk(docs_dir): + if "_build" in root: + continue + files = [ os.path.join(root, f) for f in files if f.endswith(".rst") ] + for path in files: + with open(path, "r") as f: + for link in re.findall(GH_LINK_RE, f.read()): + if link not in GH_LINK_ALLOWED: + github_links.append((path, link)) + + if github_links: + for path, link in github_links: + print("%s: %s" % (path, link)) + print("WARNING: Some .rst files contain hardcoded Github links.") print("Please check above output and replace links with one of the following:") print("- :idf:`dir` - points to directory inside ESP-IDF") print("- :idf_file:`file` - points to file inside ESP-IDF") From eb85cfb9f674b24c58141379227c197d3503d3c2 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 31 Jan 2020 17:16:03 +1100 Subject: [PATCH 38/47] docs: Temporarily mark RF calibration chapter as ESP32 only Can be re-enabled once ESP32-S2 calibration support is added --- components/esp_wifi/Kconfig | 3 ++- docs/conf_common.py | 1 + docs/en/api-guides/index.rst | 2 +- docs/zh_CN/api-guides/index.rst | 2 +- 4 files changed, 5 insertions(+), 3 deletions(-) diff --git a/components/esp_wifi/Kconfig b/components/esp_wifi/Kconfig index 26ec0223d1..b238da7f5b 100644 --- a/components/esp_wifi/Kconfig +++ b/components/esp_wifi/Kconfig @@ -308,7 +308,8 @@ endmenu # Wi-Fi menu "PHY" config ESP32_PHY_CALIBRATION_AND_DATA_STORAGE - # ToDo: remove once NVS and PHY partial calibration are supported + # ToDo: remove target dependency once NVS and PHY partial calibration are supported + # also re-enable the entry in docs/../api-guides/index.rst depends on IDF_TARGET_ESP32 bool "Store phy calibration data in NVS" default y diff --git a/docs/conf_common.py b/docs/conf_common.py index 1820e0c352..2e3c60cf14 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -132,6 +132,7 @@ def update_exclude_patterns(tags): for e in ['api-guides/blufi.rst', 'api-guides/build-system-legacy.rst', 'api-guides/esp-ble-mesh/**', + 'api-guides/RF_calibration.rst', # temporary until support re-added in esp_wifi 'api-guides/ulp-legacy.rst', 'api-guides/unit-tests-legacy.rst', 'api-guides/ulp_instruction_set.rst', diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index a6f3a495b5..fa167406fe 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -27,7 +27,7 @@ API Guides Linker Script Generation lwIP TCP/IP Stack Partition Tables - RF Calibration + :esp32: RF Calibration ROM debug console Secure Boot <../security/secure-boot> Thread Local Storage diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index 9df13bf124..687521c0e8 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -28,7 +28,7 @@ API 指南 应用层跟踪 控制台终端组件 ROM debug console - RF Calibration + :esp32: RF Calibration WiFi Driver :esp32: ESP-BLE-MESH ESP-MESH (Wi-Fi) From ac8e93117935a7b586088bdfe92dd8a3f965f80a Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 31 Jan 2020 18:48:56 +1100 Subject: [PATCH 39/47] confgen: Avoid including invisible (due to target) choice items in kconfig.rst renames --- tools/kconfig_new/confgen.py | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/tools/kconfig_new/confgen.py b/tools/kconfig_new/confgen.py index fd1f6a0df0..77feae5b33 100755 --- a/tools/kconfig_new/confgen.py +++ b/tools/kconfig_new/confgen.py @@ -115,7 +115,16 @@ class DeprecatedOptions(object): def append_doc(self, config, visibility, path_output): def option_was_written(opt): - return any(visibility.visible(node) for node in config.syms[opt].nodes) + # named choices were written if any of the symbols in the choice were visible + if new_opt in config.named_choices: + syms = config.named_choices[new_opt].syms + for s in syms: + if any(visibility.visible(node) for node in s.nodes): + return True + return False + else: + # otherwise if any of the nodes associated with the option was visible + return any(visibility.visible(node) for node in config.syms[opt].nodes) if len(self.r_dic) > 0: with open(path_output, 'a') as f_o: @@ -123,7 +132,7 @@ class DeprecatedOptions(object): f_o.write('.. _configuration-deprecated-options:\n\n{}\n{}\n\n'.format(header, '-' * len(header))) for dep_opt in sorted(self.r_dic): new_opt = self.r_dic[dep_opt] - if new_opt not in config.syms or (config.syms[new_opt].choice is None and option_was_written(new_opt)): + if option_was_written(new_opt) and (new_opt not in config.syms or config.syms[new_opt].choice is None): # everything except config for a choice (no link reference for those in the docs) f_o.write('- {}{} (:ref:`{}{}`)\n'.format(config.config_prefix, dep_opt, config.config_prefix, new_opt)) From d03af45731d78c235a5f1513b397359bee2d9e63 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Mon, 3 Feb 2020 17:38:45 +1100 Subject: [PATCH 40/47] docs: flake8 fixes --- docs/build_docs.py | 15 ++++++++------- docs/conf_common.py | 3 ++- docs/idf_extensions/format_idf_target.py | 4 ++-- docs/idf_extensions/gen_idf_tools_links.py | 1 + docs/zh_CN/conf.py | 1 - 5 files changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/build_docs.py b/docs/build_docs.py index 0fa376ecdb..1c36615ffa 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -142,7 +142,7 @@ def parallel_call(args, callback): for ret, entry in zip(errcodes, entries): if ret != 0: print("language: %s, target: %s, errcode: %d" % (entry[0], entry[1], ret)) - #Don't re-throw real error code from each parallel process + # Don't re-throw real error code from each parallel process return 1 else: return 0 @@ -197,7 +197,7 @@ def sphinx_call(language, target, build_dir, sphinx_parallel_jobs, buildername): except KeyboardInterrupt: # this seems to be the only way to get Ctrl-C to kill everything? p.kill() os.chdir(saved_cwd) - return 130 #FIXME It doesn't return this errorcode, why? Just prints stacktrace + return 130 # FIXME It doesn't return this errorcode, why? Just prints stacktrace os.chdir(saved_cwd) return ret @@ -315,7 +315,8 @@ def call_linkcheck(entry): GH_LINK_RE = r"https://github.com/espressif/esp-idf/(?:tree|blob|raw)/[^\s]+" # we allow this one link, because we always want users to see the latest support policy -GH_LINK_ALLOWED = [ "https://github.com/espressif/esp-idf/blob/master/SUPPORT_POLICY.md" ] +GH_LINK_ALLOWED = ["https://github.com/espressif/esp-idf/blob/master/SUPPORT_POLICY.md"] + def action_gh_linkcheck(args): print("Checking for hardcoded GitHub links\n") @@ -326,12 +327,12 @@ def action_gh_linkcheck(args): for root, _, files in os.walk(docs_dir): if "_build" in root: continue - files = [ os.path.join(root, f) for f in files if f.endswith(".rst") ] + files = [os.path.join(root, f) for f in files if f.endswith(".rst")] for path in files: with open(path, "r") as f: - for link in re.findall(GH_LINK_RE, f.read()): - if link not in GH_LINK_ALLOWED: - github_links.append((path, link)) + for link in re.findall(GH_LINK_RE, f.read()): + if link not in GH_LINK_ALLOWED: + github_links.append((path, link)) if github_links: for path, link in github_links: diff --git a/docs/conf_common.py b/docs/conf_common.py index 2e3c60cf14..36fd57dc30 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -160,6 +160,7 @@ def update_exclude_patterns(tags): 'api-reference/peripherals/temp_sensor.rst']: exclude_patterns.append(e) + # The reST default role (used for this markup: `text`) to use for all # documents. # default_role = None @@ -370,9 +371,9 @@ def setup(app): app.config.breathe_projects = {"esp32-idf": os.path.join(app.config.build_dir, "xml_in/")} app.config.breathe_default_project = "esp32-idf" - setup_diag_font(app) + def setup_diag_font(app): # blockdiag and other tools require a font which supports their character set # the font file is stored on the download server to save repo size diff --git a/docs/idf_extensions/format_idf_target.py b/docs/idf_extensions/format_idf_target.py index 65c33222bf..da342841f5 100644 --- a/docs/idf_extensions/format_idf_target.py +++ b/docs/idf_extensions/format_idf_target.py @@ -5,10 +5,10 @@ TOOLCHAIN_NAMES = {'esp32': 'esp', 'esp32s2': 'esp32s2'} CONFIG_PREFIX = {'esp32': 'ESP32', 'esp32s2': 'ESP32S2'} TRM_EN_URL = {'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf', - 'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf'} + 'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf'} TRM_CN_URL = {'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_cn.pdf', - 'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_cn.pdf'} + 'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_cn.pdf'} class StringSubstituter: diff --git a/docs/idf_extensions/gen_idf_tools_links.py b/docs/idf_extensions/gen_idf_tools_links.py index abba61daa5..4a02b81260 100644 --- a/docs/idf_extensions/gen_idf_tools_links.py +++ b/docs/idf_extensions/gen_idf_tools_links.py @@ -3,6 +3,7 @@ from __future__ import print_function import os.path from util import copy_if_modified, call_with_python + def setup(app): # we don't actually need idf-info, just a convenient event to trigger this on app.connect('idf-info', generate_idf_tools_links) diff --git a/docs/zh_CN/conf.py b/docs/zh_CN/conf.py index 70e377de10..dd4b2cd8c8 100644 --- a/docs/zh_CN/conf.py +++ b/docs/zh_CN/conf.py @@ -10,7 +10,6 @@ import sys import os sys.path.insert(0, os.path.abspath('..')) from conf_common import * # noqa: F401, F403 - need to make available everything from common -from idf_extensions.util import download_file_if_missing # noqa: E402 - need to import from common folder # General information about the project. project = u'ESP-IDF 编程指南' From c7209b110ecb7669e3ee44d695a24aba64b87d01 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Mon, 3 Feb 2020 18:05:53 +1100 Subject: [PATCH 41/47] check_python_dependencies: If overriding requirements.txt path, provide a pip command line Advice about install.sh/install.bat, etc only works for the default requirements.txt --- tools/check_python_dependencies.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/tools/check_python_dependencies.py b/tools/check_python_dependencies.py index 103d98d10f..bb1d15765d 100755 --- a/tools/check_python_dependencies.py +++ b/tools/check_python_dependencies.py @@ -39,10 +39,12 @@ def escape_backslash(path): if __name__ == "__main__": idf_path = os.getenv("IDF_PATH") + default_requirements_path = os.path.join(idf_path, 'requirements.txt') + parser = argparse.ArgumentParser(description='ESP32 Python package dependency checker') parser.add_argument('--requirements', '-r', help='Path to the requrements file', - default=os.path.join(idf_path, 'requirements.txt')) + default=default_requirements_path) args = parser.parse_args() not_satisfied = [] @@ -64,7 +66,10 @@ if __name__ == "__main__": print('The following Python requirements are not satisfied:') for requirement in not_satisfied: print(requirement) - if os.environ.get('IDF_PYTHON_ENV_PATH'): + if os.path.realpath(args.requirements) != os.path.realpath(default_requirements_path): + # we're using this script to check non-default requirements.txt, so tell the user to run pip + print('Please check the documentation for the feature you are using, or run "%s -m pip install -r %s"' % (sys.executable, args.requirements)) + elif os.environ.get('IDF_PYTHON_ENV_PATH'): # We are running inside a private virtual environment under IDF_TOOLS_PATH, # ask the user to run install.bat again. if sys.platform == "win32" and not os.environ.get("MSYSTEM"): From 9f617c787410403621e957e66ff21e759d44079a Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Tue, 14 Jan 2020 12:06:55 +0800 Subject: [PATCH 42/47] docs: Add a short user guide for how to write multi target docs --- docs/en/contribute/documenting-code.rst | 46 ++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/en/contribute/documenting-code.rst b/docs/en/contribute/documenting-code.rst index 57c02cde72..16a60c4713 100644 --- a/docs/en/contribute/documenting-code.rst +++ b/docs/en/contribute/documenting-code.rst @@ -243,7 +243,51 @@ By default, the directives ``.. todo::`` and ``.. todolist::`` are ignored by do Before pushing your changes to origin, please set the value of ``todo_include_todos`` back to ``False``. -For more details about the extension, see `sphinx.ext.todo `_ documenation. +For more details about the extension, see `sphinx.ext.todo `_ documentation. + +Writing generic documentation for multiple chips +------------------------------------------------ + +The documentation for all of Espressif's chips is built from the same files. To faciliate the writing of documents that can be re-used for multiple different chips (called below "targets"), we provide you with the following functionality: + +Exclusion of content based on chip-target +""""""""""""""""""""""""""""""""""""""""" +Occasionally there will be content that is only relevant for one of targets. When this is the case, you can exclude that content by using the ''.. only:: TARGET'' directive, where you replace 'TARGET' with one of the chip names. As of now the following targets are available: + +* esp32 +* esp32s2 + +Example: + +.. code-block:: none + + .. only:: esp32 + + ESP32 specific content. + +This functionality is provided by the `Sphinx selective exclude `_ extension. + +The :TARGET: role is used for excluding content from a table of content tree. For example: + +.. code-block:: none + + .. toctree:: + :maxdepth: 1 + + :esp32: configure-wrover + configure-other-jtag + +When building the documents, Sphinx will use the above mentioned directive and role to include or exclude content based on the target tag it was called with. + +Substitution macros +""""""""""""""""""" +When you need to refer to the chip's name, toolchain name, path or other common names that depend on the target type you can consider using the substitution macros supplied by :idf_file:`docs/idf_extensions/format_idf_target.py`. + +This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` will render as: This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`. + +This extension also supports markup for defining a local (for a single .rst-file) substitutions. You can do this by putting a definition like {\IDF_TARGET_SUFFIX:default="DEFAULT_VALUE",esp32="ESP32_VALUE",esp32s2beta="ESP32S2BETA_VALUE"}, in your rst-file. This will define a target-dependent substitution of the tag {\IDF_TARGET_SUFFIX} in the current rst-file. For example: + +{\IDF_TARGET_TX_PIN:default="IO3",esp32="IO4",esp32s2beta="IO5"} will define a substitution for the tag {\IDF_TARGET_TX_PIN}, which would be replaced by the text IO5 if sphinx was called with the tag esp32s2beta. Put it all together From 4636e8a34c795b33cfcf644ee4bc95abc6012c8a Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Mon, 3 Feb 2020 18:12:47 +1100 Subject: [PATCH 43/47] docs/documenting-code: Add a couple of follow up notes on top of last commit --- docs/en/contribute/documenting-code.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/en/contribute/documenting-code.rst b/docs/en/contribute/documenting-code.rst index 16a60c4713..20d3cea46f 100644 --- a/docs/en/contribute/documenting-code.rst +++ b/docs/en/contribute/documenting-code.rst @@ -279,6 +279,8 @@ The :TARGET: role is used for excluding content from a table of content tree. Fo When building the documents, Sphinx will use the above mentioned directive and role to include or exclude content based on the target tag it was called with. +.. note:: If excluding an entire document from the toctree based on targets, it's necessary to also update the ``exclude_patterns`` list in :idf_file:`docs/conf_common.py` to exclude the file for other targets, or a Sphinx warning "WARNING: document isn't included in any toctree" will be generated.. + Substitution macros """"""""""""""""""" When you need to refer to the chip's name, toolchain name, path or other common names that depend on the target type you can consider using the substitution macros supplied by :idf_file:`docs/idf_extensions/format_idf_target.py`. @@ -289,6 +291,7 @@ This extension also supports markup for defining a local (for a single .rst-file {\IDF_TARGET_TX_PIN:default="IO3",esp32="IO4",esp32s2beta="IO5"} will define a substitution for the tag {\IDF_TARGET_TX_PIN}, which would be replaced by the text IO5 if sphinx was called with the tag esp32s2beta. +.. note:: Due to limitations in Sphinx processing, these substitutions are not applied to any document that is included via the ``.. include::` directive. In these cases it's necessary to use the ``only`` blocks and write per-target sections instead. Unfortunately this includes any document which is not yet translated, as the ``zh_CN`` version will include the ``en`` version. Put it all together ------------------- From 291735c7dd0f63a8d7022bccc6f9525bd9893324 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 4 Feb 2020 17:36:23 +1100 Subject: [PATCH 44/47] docs: Move to Python 3.5+ and Sphinx 2.3 --- docs/README.md | 16 ++++------ docs/build_docs.py | 2 +- docs/conf_common.py | 4 +-- docs/en/contribute/documenting-code.rst | 30 ++++++++++++++----- docs/idf_extensions/format_idf_target.py | 2 +- docs/idf_extensions/gen_idf_tools_links.py | 2 +- .../gen_version_specific_includes.py | 10 +++---- docs/idf_extensions/link_roles.py | 8 ++--- docs/requirements.txt | 17 ++++++----- tools/ci/config/build.yml | 4 +-- tools/ci/config/post_deploy.yml | 4 +-- tools/ci/config/pre_check.yml | 2 +- 12 files changed, 57 insertions(+), 44 deletions(-) diff --git a/docs/README.md b/docs/README.md index 89a0db0a9e..12202ca5b5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,16 +16,12 @@ The above URLs are all for the master branch latest version. Click the drop-down # Building Documentation -* Install `make` and `doxygen` for your platform (`make` may already be installed as an ESP-IDF prerequisite). -* Change to either the docs/en or docs/zh_CN subdirectory and run `make html` -* `make` will probably prompt you to run a python pip install step to get some other Python-related prerequisites. Run the command as shown, then re-run `make html` to build the docs. +* Documentation build requres Python 3 and will not work with Python 2 +* Install dependencies for ESP-IDF as per the Getting Started guide +* Install documentation Python depdendencies, ie `pip install -r $IDF_PATH/docs/requirements.txt` +* Run `./build_docs.py build` to build docs for all supported Language & Target combinations, or `./build_docs.py -t esp32 -l en build` to build docs for a single supported language & target combination only. -## For MSYS2 MINGW32 on Windows +See [Documenting Code](https://docs.espressif.com/projects/esp-idf/en/latest/contribute/documenting-code.rst) for more information. -If using Windows and the MSYS2 MINGW32 terminal, run this command before running "make html" the first time: +Available languages are `en` and `zh_CN`, targets are any target supported by ESP-IDF - for example `esp32` or `esp32s2`. -``` -pacman -S doxygen mingw-w64-i686-python2-pillow -``` - -Note: Currently it is not possible to build docs on Windows without using a Unix-on-Windows layer such as MSYS2 MINGW32. diff --git a/docs/build_docs.py b/docs/build_docs.py index 1c36615ffa..cf6ef6ec31 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -1,4 +1,4 @@ -#!/usr/bin/env python +#!/usr/bin/env python3 # coding=utf-8 # # Top-level docs builder diff --git a/docs/conf_common.py b/docs/conf_common.py index 36fd57dc30..bc9fc63f54 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -107,7 +107,7 @@ master_doc = 'index' # This is supposed to be "the short X.Y version", but it's the only version # visible when you open index.html. # Display full version to make things less confusing. -version = subprocess.check_output(['git', 'describe']).strip() +version = subprocess.check_output(['git', 'describe']).strip().decode('utf-8') # The full version, including alpha/beta/rc tags. # If needed, nearest tag is returned by 'git describe --abbrev=0'. release = version @@ -121,7 +121,7 @@ print('Version: {0} Release: {1}'.format(version, release)) # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['**/inc/**', '_static'] +exclude_patterns = ['**/inc/**', '_static', '**/_build'] # Add target-specific excludes based on tags (for the IDF_TARGET). Haven't found any better way to do this yet diff --git a/docs/en/contribute/documenting-code.rst b/docs/en/contribute/documenting-code.rst index 20d3cea46f..677e507776 100644 --- a/docs/en/contribute/documenting-code.rst +++ b/docs/en/contribute/documenting-code.rst @@ -320,6 +320,9 @@ OK, but I am new to Sphinx! Setup for building documentation locally ---------------------------------------- +Install Dependencies +"""""""""""""""""""" + You can setup environment to build documentation locally on your PC by installing: 1. Doxygen - https://www.stack.nl/~dimitri/doxygen/ @@ -334,6 +337,8 @@ The package "sphinx_rtd_theme" is added to have the same "look and feel" of `ESP Do not worry about being confronted with several packages to install. Besides Doxygen, all remaining packages are written in Python. Therefore installation of all of them is combined into one simple step. +.. important:: Docs building now supports Python 3 only. Python 2 installations will not work. + Installation of Doxygen is OS dependent: **Linux** @@ -356,7 +361,7 @@ Installation of Doxygen is OS dependent: .. note:: - If you are installing on Windows system (Linux and MacOS users should skip this note), **before** going further, execute two extra steps below. These steps are required to install dependencies of "blockdiag" discussed under :ref:`add-illustrations`. + If you are installing on Windows MSYS2 system (Linux and MacOS users should skip this note, Windows users who don't use MSYS2 will need to find other alternatives), **before** going further, execute two extra steps below. These steps are required to install dependencies of "blockdiag" discussed under :ref:`add-illustrations`. 1. Update all the system packages: @@ -370,9 +375,9 @@ Installation of Doxygen is OS dependent: :: - $ pacman -S mingw32/mingw-w64-i686-python2-pillow + $ pacman -S mingw32/mingw-w64-i686-python-pillow - Check the log on the screen that ``mingw-w64-i686-python2-pillow-4.3.0-1`` is installed. Previous versions of *pillow* will not work. + Check the log on the screen that ``mingw-w64-i686-python-pillow-4.3.0-1`` or newer is installed. Previous versions of *pillow* will not work. A downside of Windows installation is that fonts of the `blockdiag pictures ` do not render correctly, you will see some random characters instead. Until this issue is fixed, you can use the `interactive shell`_ to see how the complete picture looks like. @@ -387,15 +392,26 @@ All remaining applications are `Python `_ packages and Installation steps assume that ESP-IDF is placed in ``~/esp/esp-idf`` directory, that is default location of ESP-IDF used in documentation. -Change to directory with files for specific language:: +Building Documentation +"""""""""""""""""""""" - cd en +:: + + cd ~/esp/esp-idf/docs Now you should be ready to build documentation by invoking:: - make html + ./build_docs.py build -This may take couple of minutes. After completion, documentation will be placed in ``~/esp/esp-idf/docs/en/_build/html`` folder. To see it, open ``index.html`` in a web browser. +This will build docs for all supported ESP-IDF languages & targets. This can take some time, although jobs will run in parallel up to the number of CPU cores you have (can modify this with the ``--sphinx-parallel-builds`` option, see ``./build_docs.py --help`` for details). + +To build for a single language and target combination only:: + + ./build_docs.py -l en -t esp32 build + +Choices for language (``-l``) are ``en`` and ``zh_CN``. Choices for target (``-t``) are any supported ESP-IDF build system target (for example ``esp32`` and ``esp32s2``). + +Build documentation will be placed in ``_build///html`` folder. To see it, open the ``index.html`` inside this directory in a web browser. Wrap up diff --git a/docs/idf_extensions/format_idf_target.py b/docs/idf_extensions/format_idf_target.py index da342841f5..15c0db68fa 100644 --- a/docs/idf_extensions/format_idf_target.py +++ b/docs/idf_extensions/format_idf_target.py @@ -75,7 +75,7 @@ class StringSubstituter: # Add any new local tags that matches the reg.ex. sub_defs = re.findall(self.RE_PATTERN, source[0]) - if len(sub_defs) is not 0: + if len(sub_defs) != 0: self.add_local_subs(sub_defs) # Remove the tag defines diff --git a/docs/idf_extensions/gen_idf_tools_links.py b/docs/idf_extensions/gen_idf_tools_links.py index 4a02b81260..126efe63c5 100644 --- a/docs/idf_extensions/gen_idf_tools_links.py +++ b/docs/idf_extensions/gen_idf_tools_links.py @@ -1,7 +1,7 @@ # Generate toolchain download links from toolchain info makefile from __future__ import print_function import os.path -from util import copy_if_modified, call_with_python +from .util import copy_if_modified, call_with_python def setup(app): diff --git a/docs/idf_extensions/gen_version_specific_includes.py b/docs/idf_extensions/gen_version_specific_includes.py index fae92512b0..b93d31e6ab 100755 --- a/docs/idf_extensions/gen_version_specific_includes.py +++ b/docs/idf_extensions/gen_version_specific_includes.py @@ -201,21 +201,21 @@ def get_version(): # Otherwise, use git to look for a tag try: - tag = subprocess.check_output(["git", "describe", "--tags", "--exact-match"]).strip() + tag = subprocess.check_output(["git", "describe", "--tags", "--exact-match"]).strip().decode('utf-8') is_stable = re.match(r"v[0-9\.]+$", tag) is not None return (tag, "tag", is_stable) except subprocess.CalledProcessError: pass # No tag, look for a branch - refs = subprocess.check_output(["git", "for-each-ref", "--points-at", "HEAD", "--format", "%(refname)"]) + refs = subprocess.check_output(["git", "for-each-ref", "--points-at", "HEAD", "--format", "%(refname)"]).decode('utf-8') print("refs:\n%s" % refs) - refs = refs.split(b"\n") + refs = refs.split("\n") # Note: this looks for branches in 'origin' because GitLab CI doesn't check out a local branch - branches = [r.replace(b"refs/remotes/origin/",b"").strip() for r in refs if r.startswith(b"refs/remotes/origin/")] + branches = [r.replace("refs/remotes/origin/","").strip() for r in refs if r.startswith("refs/remotes/origin/")] if len(branches) == 0: # last resort, return the commit (may happen on Gitlab CI sometimes, unclear why) - return (subprocess.check_output(["git", "rev-parse", "--short", "HEAD"]).strip(), "commit", False) + return (subprocess.check_output(["git", "rev-parse", "--short", "HEAD"]).strip().decode('utf-8'), "commit", False) if "master" in branches: return ("master", "branch", False) else: diff --git a/docs/idf_extensions/link_roles.py b/docs/idf_extensions/link_roles.py index ee1a6adc57..5d8728f653 100644 --- a/docs/idf_extensions/link_roles.py +++ b/docs/idf_extensions/link_roles.py @@ -9,9 +9,9 @@ from docutils import nodes def get_github_rev(): - path = subprocess.check_output(['git', 'rev-parse', '--short', 'HEAD']).strip() + path = subprocess.check_output(['git', 'rev-parse', '--short', 'HEAD']).strip().decode('utf-8') try: - tag = subprocess.check_output(['git', 'describe', '--exact-match']).strip() + tag = subprocess.check_output(['git', 'describe', '--exact-match']).strip().decode('utf-8') except subprocess.CalledProcessError: tag = None print('Git commit ID: ', path) @@ -41,11 +41,11 @@ def setup(app): if on_rtd: # provide RTD specific commit identification to be included in the link tag_rev = 'latest' - if (subprocess.check_output(['git','rev-parse', '--short', 'HEAD']).strip() != rev): + if (subprocess.check_output(['git','rev-parse', '--short', 'HEAD']).decode('utf-8').strip() != rev): tag_rev = rev else: # if not on the RTD then provide generic identification - tag_rev = subprocess.check_output(['git', 'describe', '--always']).strip() + tag_rev = subprocess.check_output(['git', 'describe', '--always']).decode('utf-8').strip() app.add_role('link_to_translation', crosslink('%s../../%s/{}/%s.html'.format(tag_rev))) diff --git a/docs/requirements.txt b/docs/requirements.txt index c217a40043..52424f7b8a 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,15 +1,16 @@ # 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.8.4 -breathe==4.11.1 +sphinx==2.3.1 +breathe==4.14.1 sphinx-rtd-theme sphinx-notfound-page -sphinxcontrib-blockdiag>=1.5.5, <2.0.0 -sphinxcontrib-seqdiag>=0.8.5, <2.0.0 -sphinxcontrib-actdiag>=0.8.5, <2.0.0 -sphinxcontrib-nwdiag>=0.9.5, <2.0.0 -nwdiag==1.0.4 +sphinxcontrib-blockdiag==2.0.0 +sphinxcontrib-seqdiag==2.0.0 +sphinxcontrib-actdiag==2.0.0 +sphinxcontrib-nwdiag==2.0.0 +sphinxcontrib-wavedrom==2.0.0 +nwdiag==2.0.0 recommonmark future>=0.16.0 # for ../tools/gen_esp_err_to_name.py -sphinx_selective_exclude>=1.0.3 +sphinx_selective_exclude==1.0.3 diff --git a/tools/ci/config/build.yml b/tools/ci/config/build.yml index b6af246e08..cf682c8a4e 100644 --- a/tools/ci/config/build.yml +++ b/tools/ci/config/build.yml @@ -188,7 +188,7 @@ build_examples_cmake_esp32s2: .build_docs_template: &build_docs_template stage: build - image: $CI_DOCKER_REGISTRY/esp-idf-doc-env:esp-docs-20200204-ea18dcbd + image: $CI_DOCKER_REGISTRY/esp-idf-doc-env:v2-d4034371 tags: - build_docs artifacts: @@ -206,7 +206,7 @@ build_examples_cmake_esp32s2: dependencies: [] script: - cd docs - - ./build_docs.py -l $DOCLANG -t $DOCTGT build + - ${IDF_PATH}/tools/ci/multirun_with_pyenv.sh -p 3.6.10 ./build_docs.py -l $DOCLANG -t $DOCTGT build build_docs_en_esp32: extends: .build_docs_template diff --git a/tools/ci/config/post_deploy.yml b/tools/ci/config/post_deploy.yml index 024b0c5d24..8cc46821a8 100644 --- a/tools/ci/config/post_deploy.yml +++ b/tools/ci/config/post_deploy.yml @@ -1,6 +1,6 @@ .check_doc_links_template: &check_doc_links_template stage: post_deploy - image: $CI_DOCKER_REGISTRY/esp-idf-doc-env:esp-docs-20200204-ea18dcbd + image: $CI_DOCKER_REGISTRY/esp-idf-doc-env:v2-d4034371 tags: [ "build", "amd64", "internet" ] only: - master @@ -15,7 +15,7 @@ dependencies: [] script: - cd docs - - ./build_docs.py -l $DOCLANG -t $DOCTGT linkcheck + - ${IDF_PATH}/tools/ci/multirun_with_pyenv.sh -p 3.6.10 ./build_docs.py -l $DOCLANG -t $DOCTGT linkcheck check_doc_links_en_esp32: extends: .check_doc_links_template diff --git a/tools/ci/config/pre_check.yml b/tools/ci/config/pre_check.yml index 6e23e0cfc2..6439cdda7a 100644 --- a/tools/ci/config/pre_check.yml +++ b/tools/ci/config/pre_check.yml @@ -24,7 +24,7 @@ check_docs_gh_links: SUBMODULES_TO_FETCH: "none" script: - cd docs - - ./build_docs.py gh-linkcheck + - ${IDF_PATH}/tools/ci/multirun_with_pyenv.sh -p 3.6.10 ./build_docs.py gh-linkcheck check_version: extends: .check_job_template From 67bb6f8dc476d0d0781295d8a484d1f984af8522 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Thu, 6 Feb 2020 10:23:52 +1100 Subject: [PATCH 45/47] README: Drop the RTD docs status badge, add a note about docs not updating for a period --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index eeec5708a0..994c89a552 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,6 @@ * [中文版](./README_CN.md) -[![Documentation Status](https://readthedocs.com/projects/espressif-esp-idf/badge/?version=latest)](https://docs.espressif.com/projects/esp-idf/en/latest/?badge=latest) - ESP-IDF is the official development framework for the [ESP32](https://espressif.com/en/products/hardware/esp32/overview) chip. # Developing With ESP-IDF @@ -15,6 +13,8 @@ See setup guides for detailed instructions to set up the ESP-IDF: * [Getting Started Guide for the stable ESP-IDF version](https://docs.espressif.com/projects/esp-idf/en/stable/get-started/) * [Getting Started Guide for the latest (master branch) ESP-IDF version](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/) +*Note: ESP-IDF Programmers Guide is in the process of transitioning to a new documentation host. Master branch ("latest") docs will not be updated from 2020-02-05 for approximately two weeks. This note will be removed once the master branch docs are updating again. Other branch & release docs continue to update as normal.* + ### Non-GitHub forks ESP-IDF uses relative locations as its submodules URLs ([.gitmodules](.gitmodules)). So they link to GitHub. From 54e7cb4d8b6d0955e278fbe6c0bc713d09e1828b Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Thu, 6 Feb 2020 15:52:23 +1100 Subject: [PATCH 46/47] docs: Require UTF-8 as default encoding to build docs Making everything work for both docs & non-docs builds with Py2 is too fiddly otherwise. --- docs/build_docs.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/build_docs.py b/docs/build_docs.py index cf6ef6ec31..8581231257 100755 --- a/docs/build_docs.py +++ b/docs/build_docs.py @@ -11,6 +11,7 @@ # from __future__ import print_function import argparse +import locale import math import multiprocessing import os @@ -50,6 +51,14 @@ def main(): except subprocess.CalledProcessError: raise SystemExit(2) # stdout will already have these errors + # This is not the only way to make sure that all files opened by Python are treated as UTF-8, but the other way is passing encoding='utf-8' to all open() + # functions and this way makes Python 2 compatibility really tough if there is any code that assumes text files contain strings (kconfiglib assumes this). + # The reason for that is that you need to import io.open() to support the encoding argument on Python 2, and this function always uses Py2's unicode + # type not the str type. + if 'UTF-8' not in locale.getlocale(): + raise RuntimeError("build_docs.py requires the default locale's encoding to be UTF-8. " + + "Setting environment variable LC_ALL=C.UTF-8 when running build_docs.py may be enough to fix this.") + parser = argparse.ArgumentParser(description='build_docs.py: Build IDF docs', prog='build_docs.py') parser.add_argument("--language", "-l", choices=LANGUAGES, required=False) From 2c03d2cc4ebed59231a6a32a87b41f95731ff3bc Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Fri, 7 Feb 2020 15:36:14 +1100 Subject: [PATCH 47/47] docs: Re-run the 'set-target' target each time, use a unique sdkconfig file for each lang/target combo Fixes some problems with CMake errors in stale builds, and of sdkconfig file being shared between parallel jobs. --- docs/idf_extensions/build_system/__init__.py | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/idf_extensions/build_system/__init__.py b/docs/idf_extensions/build_system/__init__.py index 11c6ab1be4..8265c30ad2 100644 --- a/docs/idf_extensions/build_system/__init__.py +++ b/docs/idf_extensions/build_system/__init__.py @@ -7,6 +7,7 @@ # Then emits the new 'idf-info' event which has information read from IDF # build system, that other extensions can use to generate relevant data. import os.path +import shutil import sys import subprocess import json @@ -61,15 +62,19 @@ def generate_idf_info(app, config): "-B", cmake_build_dir, "-C", - project_path] - if not os.path.exists(os.path.join(cmake_build_dir, "CMakeCache.txt")): - # if build directory not created yet, run a reconfigure pass over it - print("Starting new dummy IDF project... w") - subprocess.check_call(idf_py + ["set-target", app.config.idf_target]) - else: - print("Re-running CMake on the existing IDF project in {}".format(cmake_build_dir)) + project_path, + "-D", + "SDKCONFIG={}".format(os.path.join(build_dir, "dummy_project_sdkconfig")) + ] + # force a clean idf.py build w/ new sdkconfig each time + # (not much slower than 'reconfigure', avoids any potential config & build versioning problems + shutil.rmtree(cmake_build_dir, ignore_errors=True) + print("Starting new dummy IDF project... ") + subprocess.check_call(idf_py + ["set-target", app.config.idf_target]) + print("Running CMake on dummy project...") subprocess.check_call(idf_py + ["reconfigure"]) + with open(os.path.join(cmake_build_dir, "project_description.json")) as f: project_description = json.load(f) if project_description["target"] != app.config.idf_target: