diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 00000000..3306fbc0 --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,251 @@ +# This is Doxygen configuration file +# +# Doxygen provides over 260 configuration statements +# To make this file easier to follow, +# it contains only statements that are non-default +# +# NOTE: +# It is recommended not to change defaults unless specifically required +# Test any changes how they affect generated documentation +# Make sure that correct warnings are generated to flag issues with documented code +# +# For the complete list of configuration statements see: +# https://www.stack.nl/~dimitri/doxygen/manual/config.html + + +PROJECT_NAME = "ESP32 Programming Guide" + +## The 'INPUT' statement below is used as input by script 'gen-df-input.py' +## to automatically generate API reference list files heder_file.inc +## These files are placed in '_inc' directory +## and used to include in API reference documentation + +INPUT = \ + ## + ## Wi-Fi - API Reference + ## + ../../components/esp32/include/esp_wifi.h \ + ../../components/esp32/include/esp_wifi_types.h \ + ../../components/esp32/include/esp_smartconfig.h \ + ../../components/esp32/include/esp_now.h \ + ## Mesh - API Reference + ../../components/esp32/include/esp_mesh.h \ + ## Bluetooth - API Reference + ## Controller && VHCI + ../../components/bt/include/esp_bt.h \ + ## Bluetooth COMMON + ## Issue with __attribute__ + ../../components/bt/bluedroid/api/include/api/esp_bt_defs.h \ + ../../components/bt/bluedroid/api/include/api/esp_bt_main.h \ + ../../components/bt/bluedroid/api/include/api/esp_bt_device.h \ + ## Bluetooth LE + ../../components/bt/bluedroid/api/include/api/esp_gap_ble_api.h \ + ## Issue with __attribute__ + ../../components/bt/bluedroid/api/include/api/esp_gatt_defs.h \ + ../../components/bt/bluedroid/api/include/api/esp_gatts_api.h \ + ../../components/bt/bluedroid/api/include/api/esp_gattc_api.h \ + ../../components/bt/bluedroid/api/include/api/esp_blufi_api.h \ + ## Bluetooth Classic + ../../components/bt/bluedroid/api/include/api/esp_gap_bt_api.h \ + ## Issue with __attribute__ + ../../components/bt/bluedroid/api/include/api/esp_a2dp_api.h \ + ../../components/bt/bluedroid/api/include/api/esp_avrc_api.h \ + ../../components/bt/bluedroid/api/include/api/esp_spp_api.h \ + ../../components/bt/bluedroid/api/include/api/esp_hf_defs.h \ + ../../components/bt/bluedroid/api/include/api/esp_hf_client_api.h \ + ## + ## Ethernet - API Reference + ## + ../../components/ethernet/include/esp_eth.h \ + ../../components/ethernet/include/eth_phy/phy.h \ + ../../components/ethernet/include/eth_phy/phy_tlk110.h \ + ../../components/ethernet/include/eth_phy/phy_lan8720.h \ + ## + ## Peripherals - API Reference + ## + ../../components/driver/include/driver/adc.h \ + ../../components/driver/include/driver/can.h \ + ../../components/driver/include/driver/dac.h \ + ../../components/driver/include/driver/gpio.h \ + ../../components/driver/include/driver/rtc_io.h \ + ../../components/driver/include/driver/i2c.h \ + ../../components/driver/include/driver/i2s.h \ + ../../components/driver/include/driver/ledc.h \ + ../../components/driver/include/driver/mcpwm.h \ + ../../components/driver/include/driver/pcnt.h \ + ../../components/driver/include/driver/rmt.h \ + ../../components/driver/include/driver/sigmadelta.h \ + ../../components/driver/include/driver/spi_common.h \ + ../../components/driver/include/driver/spi_master.h \ + ../../components/driver/include/driver/spi_slave.h \ + ../../components/driver/include/driver/timer.h \ + ../../components/driver/include/driver/touch_pad.h \ + ../../components/driver/include/driver/uart.h \ + ../../components/esp_adc_cal/include/esp_adc_cal.h \ + ../../components/soc/esp32/include/soc/adc_channel.h \ + ../../components/soc/esp32/include/soc/dac_channel.h \ + ../../components/soc/esp32/include/soc/touch_channel.h \ + ../../components/soc/esp32/include/soc/uart_channel.h \ + ../../components/soc/esp32/include/soc/rtc_gpio_channel.h \ + ## + ## Protocols - API Reference + ## + ## ESP-TLS + ../../components/esp-tls/esp_tls.h \ + ## MQTT + ../../components/mqtt/esp-mqtt/include/mqtt_client.h \ + ## mDNS + ../../components/mdns/include/mdns.h \ + ../../components/esp_http_client/include/esp_http_client.h \ + ../../components/esp_http_server/include/esp_http_server.h \ + ## + ## Provisioning - API Reference + ## + ## Protocol Communication + ../../components/protocomm/include/common/protocomm.h \ + ../../components/protocomm/include/security/protocomm_security.h \ + ../../components/protocomm/include/security/protocomm_security0.h \ + ../../components/protocomm/include/security/protocomm_security1.h \ + ../../components/protocomm/include/transports/protocomm_ble.h \ + ../../components/protocomm/include/transports/protocomm_console.h \ + ../../components/protocomm/include/transports/protocomm_httpd.h \ + ## WiFi Provisioning + ../../components/wifi_provisioning/include/wifi_provisioning/wifi_config.h \ + ## + ## Storage - API Reference + ## + ## SPI Flash and Partition APIs + ../../components/spi_flash/include/esp_spi_flash.h \ + ../../components/spi_flash/include/esp_partition.h \ + ../../components/bootloader_support/include/esp_flash_encrypt.h \ + ## SPIFFS + ../../components/spiffs/include/esp_spiffs.h \ + ## SD/MMC Card Host + ../../components/sdmmc/include/sdmmc_cmd.h \ + ../../components/driver/include/driver/sdmmc_host.h \ + ../../components/driver/include/driver/sdmmc_types.h \ + ../../components/driver/include/driver/sdspi_host.h \ + ## SDIO slave + ../../components/driver/include/driver/sdio_slave.h \ + ## Non-Volatile Storage + ../../components/nvs_flash/include/nvs.h \ + ../../components/nvs_flash/include/nvs_flash.h \ + ## Virtual Filesystem + ../../components/vfs/include/esp_vfs.h \ + ../../components/vfs/include/esp_vfs_dev.h \ + ## FAT Filesystem + ## NOTE: for two lines below header_file.inc is not used + ../../components/fatfs/src/esp_vfs_fat.h \ + ../../components/fatfs/src/diskio.h \ + ## Wear Levelling + ../../components/wear_levelling/include/wear_levelling.h \ + ## + ## 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 \ + ## Himem + ../../components/esp32/include/esp_himem.h \ + ## Interrupt Allocation + ../../components/esp32/include/esp_intr_alloc.h \ + ## Watchdogs + ## NOTE: for two lines below header_file.inc is not used + ../../components/esp32/include/esp_int_wdt.h \ + ../../components/esp32/include/esp_task_wdt.h \ + ## Hooks + ../../components/esp32/include/esp_freertos_hooks.h \ + ## Inter-Processor Call + ../../components/esp32/include/esp_ipc.h \ + ## Over The Air Updates (OTA) + ../../components/app_update/include/esp_ota_ops.h \ + ## ESP HTTPS OTA + ../../components/esp_https_ota/include/esp_https_ota.h \ + ## Sleep + ../../components/esp32/include/esp_sleep.h \ + ## Logging + ../../components/log/include/esp_log.h \ + ## Base MAC address + ## NOTE: for line below header_file.inc is not used + ../../components/esp32/include/esp_system.h \ + ## + ## ULP Coprocessor - API Guides + ## + ## NOTE: for line below header_file.inc is not used + ../../components/ulp/include/esp32/ulp.h \ + ## + ## Application Level Tracing - API Reference + ## + ../../components/app_trace/include/esp_app_trace.h \ + ### Power management + ../../components/esp32/include/esp_pm.h \ + ../../components/esp32/include/esp32/pm.h \ + ### esp_timer, High Resolution Timer + ../../components/esp32/include/esp_timer.h \ + ### esp_event, Event Loop Library + ../../components/esp_event/include/esp_event.h \ + ../../components/esp_event/include/esp_event_base.h \ + ### ESP Pthread parameters + ../../components/pthread/include/esp_pthread.h \ + ### + ### FreeRTOS + ### + ../../components/freertos/include/freertos/task.h \ + ../../components/freertos/include/freertos/queue.h \ + ../../components/freertos/include/freertos/semphr.h \ + ../../components/freertos/include/freertos/timers.h \ + ../../components/freertos/include/freertos/event_groups.h \ + ### Ringbuffer + ../../components/esp_ringbuf/include/freertos/ringbuf.h \ + ### Helper functions for error codes + ../../components/esp32/include/esp_err.h \ + ### System APIs + ../../components/esp32/include/esp_system.h \ + ### Modbus controller component header file + ../../components/freemodbus/modbus_controller/mbcontroller.h + +## Get warnings for functions that have no documentation for their parameters or return value +## +WARN_NO_PARAMDOC = YES + +## Enable preprocessing and remove __attribute__(...) expressions from the INPUT files +## +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +PREDEFINED = \ + __attribute__(x)= \ + IRAM_ATTR= \ + configSUPPORT_DYNAMIC_ALLOCATION=1 \ + configSUPPORT_STATIC_ALLOCATION=1 \ + configQUEUE_REGISTRY_SIZE=1 \ + configUSE_RECURSIVE_MUTEXES=1 \ + configTHREAD_LOCAL_STORAGE_DELETE_CALLBACKS=1 \ + configNUM_THREAD_LOCAL_STORAGE_POINTERS=1 \ + configUSE_APPLICATION_TASK_TAG=1 \ + configTASKLIST_INCLUDE_COREID=1 + +## Do not complain about not having dot +## +HAVE_DOT = NO + +## Generate XML that is required for Breathe +## +GENERATE_XML = YES +XML_OUTPUT = xml + +GENERATE_HTML = NO +HAVE_DOT = NO +GENERATE_LATEX = NO +GENERATE_MAN = YES +GENERATE_RTF = NO + +## Skip distracting progress messages +## +QUIET = YES +## Log warnings in a file for further review +## +WARN_LOGFILE = "doxygen-warning-log.txt" + diff --git a/docs/_static/api-guides.gif b/docs/_static/api-guides.gif new file mode 100644 index 00000000..bc9dd36d Binary files /dev/null and b/docs/_static/api-guides.gif differ diff --git a/docs/_static/api-reference.gif b/docs/_static/api-reference.gif new file mode 100644 index 00000000..7fd81755 Binary files /dev/null and b/docs/_static/api-reference.gif differ diff --git a/docs/_static/espressif-logo.svg b/docs/_static/espressif-logo.svg new file mode 100644 index 00000000..5fccc316 --- /dev/null +++ b/docs/_static/espressif-logo.svg @@ -0,0 +1,77 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_static/get-started.gif b/docs/_static/get-started.gif new file mode 100644 index 00000000..7a7a8023 Binary files /dev/null and b/docs/_static/get-started.gif differ diff --git a/docs/_static/linux-logo.png b/docs/_static/linux-logo.png new file mode 100644 index 00000000..1112db65 Binary files /dev/null and b/docs/_static/linux-logo.png differ diff --git a/docs/_static/macos-logo.png b/docs/_static/macos-logo.png new file mode 100644 index 00000000..289d1f60 Binary files /dev/null and b/docs/_static/macos-logo.png differ diff --git a/docs/_static/msys2-terminal-window.png b/docs/_static/msys2-terminal-window.png new file mode 100644 index 00000000..e90a22be Binary files /dev/null and b/docs/_static/msys2-terminal-window.png differ diff --git a/docs/_static/project-configuration.png b/docs/_static/project-configuration.png new file mode 100644 index 00000000..e724556c Binary files /dev/null and b/docs/_static/project-configuration.png differ diff --git a/docs/_static/what-you-need.png b/docs/_static/what-you-need.png new file mode 100644 index 00000000..328c277c Binary files /dev/null and b/docs/_static/what-you-need.png differ diff --git a/docs/_static/windows-logo.png b/docs/_static/windows-logo.png new file mode 100644 index 00000000..122f53a2 Binary files /dev/null and b/docs/_static/windows-logo.png differ diff --git a/docs/conf_common.py b/docs/conf_common.py new file mode 100644 index 00000000..8ffd0b3e --- /dev/null +++ b/docs/conf_common.py @@ -0,0 +1,384 @@ +# -*- coding: utf-8 -*- +# +# Common (non-language-specific) configuration for Read The Docs & Sphinx +# +# Based on a Read the Docs Template documentation build configuration file, +# created by sphinx-quickstart on Tue Aug 26 14:19:49 2014. +# +# This file is imported from a language-specific conf.py (ie en/conf.py or +# zh_CN/conf.py) +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +from __future__ import print_function +from __future__ import unicode_literals +import sys, os +import re +import subprocess +import shlex + +# 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 + +# build_docs on the CI server sometimes fails under Python3. This is a workaround: +sys.setrecursionlimit(3500) + +try: + builddir = os.environ['BUILDDIR'] +except KeyError: + builddir = '_build' + +# 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__), '..')) + +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 '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) +# note: trimming "examples" dir from KConfig/KConfig.projbuild as MQTT submodule +# has its own examples in the submodule. +kconfigs = subprocess.check_output(["find", "../../components", + "-name", "examples", "-prune", + "-o", "-name", "Kconfig", "-print"]).decode() +kconfig_projbuilds = subprocess.check_output(["find", "../../components", + "-name", "examples", "-prune", + "-o", "-name", "Kconfig.projbuild", "-print"]).decode() +confgen_args = [sys.executable, + "../../tools/kconfig_new/confgen.py", + "--kconfig", "../../Kconfig", + "--config", temp_sdkconfig_path, + "--create-config-if-missing", + "--env", "COMPONENT_KCONFIGS={}".format(kconfigs), + "--env", "COMPONENT_KCONFIGS_PROJBUILD={}".format(kconfig_projbuilds), + "--env", "IDF_PATH={}".format(idf_path), + "--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') +copy_if_modified(esp_err_inc_path + '.in', esp_err_inc_path) + +# 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(builddir) + 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/' +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)) + +# http://stackoverflow.com/questions/12772927/specifying-an-online-image-in-sphinx-restructuredtext-format +# +suppress_warnings = ['image.nonlocal_uri'] + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['breathe', + 'link-roles', + 'sphinxcontrib.blockdiag', + 'sphinxcontrib.seqdiag', + 'sphinxcontrib.actdiag', + 'sphinxcontrib.nwdiag', + 'sphinxcontrib.rackdiag', + 'sphinxcontrib.packetdiag' + ] + +# 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' + +# 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": "xml_in/" } +breathe_default_project = "esp32-idf" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = ['.rst', '.md'] + +source_parsers = { + '.md': 'recommonmark.parser.CommonMarkParser', + } + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# + +# Readthedocs largely ignores 'version' and 'release', and displays one of +# 'latest', tag name, or branch name, depending on the build type. +# Still, this is useful for non-RTD builds. +# 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') +# The full version, including alpha/beta/rc tags. +# If needed, nearest tag is returned by 'git describe --abbrev=0'. +release = version +print('Version: {0} Release: {1}'.format(version, release)) + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build','README.md'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = "../_static/espressif-logo.svg" + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['../_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'ReadtheDocsTemplatedoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'ReadtheDocsTemplate.tex', u'Read the Docs Template Documentation', + u'Read the Docs', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'readthedocstemplate', u'Read the Docs Template Documentation', + [u'Read the Docs'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'ReadtheDocsTemplate', u'Read the Docs Template Documentation', + u'Read the Docs', 'ReadtheDocsTemplate', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#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') + generate_version_specific_includes(app) diff --git a/docs/docs_common.mk b/docs/docs_common.mk new file mode 100644 index 00000000..7a77b572 --- /dev/null +++ b/docs/docs_common.mk @@ -0,0 +1,216 @@ +# "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" + @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'\ + ); \ + 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/en/Makefile b/docs/en/Makefile new file mode 100644 index 00000000..281b7201 --- /dev/null +++ b/docs/en/Makefile @@ -0,0 +1,2 @@ +LANGUAGE=en +include ../docs_common.mk diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst new file mode 100644 index 00000000..cf104468 --- /dev/null +++ b/docs/en/api-guides/index.rst @@ -0,0 +1,32 @@ +API Guides +********** + +.. toctree:: + :maxdepth: 1 + + General Notes + Build System + Build System (CMake) + Error Handling + Fatal Errors + Deep Sleep Wake Stubs + ESP32 Core Dump + Flash Encryption <../security/flash-encryption> + FreeRTOS SMP Changes + Thread Local Storage + High Level Interrupts + JTAG Debugging + Bootloader + Partition Tables + Secure Boot <../security/secure-boot> + ULP Coprocessor + ULP Coprocessor (CMake) + Unit Testing + Unit Testing (CMake) + Application Level Tracing + Console Component + ROM debug console + WiFi Driver + ESP-MESH + BluFi + External SPI-connected RAM diff --git a/docs/en/api-reference/index.rst b/docs/en/api-reference/index.rst new file mode 100644 index 00000000..0de5c5ae --- /dev/null +++ b/docs/en/api-reference/index.rst @@ -0,0 +1,19 @@ +************* +API Reference +************* + +.. toctree:: + :maxdepth: 2 + + Wi-Fi + Mesh + Bluetooth + Ethernet + Peripherals + Protocols + Provisioning + Storage + System + Configuration Options + Error Codes Reference + diff --git a/docs/en/api-reference/wifi/esp_smartconfig.rst b/docs/en/api-reference/wifi/esp_smartconfig.rst new file mode 100644 index 00000000..7ad26f5f --- /dev/null +++ b/docs/en/api-reference/wifi/esp_smartconfig.rst @@ -0,0 +1,7 @@ +Smart Config +============ + +API Reference +------------- + +.. include:: /_build/inc/esp_smartconfig.inc diff --git a/docs/en/api-reference/wifi/esp_wifi.rst b/docs/en/api-reference/wifi/esp_wifi.rst new file mode 100644 index 00000000..c8091e00 --- /dev/null +++ b/docs/en/api-reference/wifi/esp_wifi.rst @@ -0,0 +1,33 @@ +Wi-Fi +===== + +Introduction +------------ + +The WiFi libraries provide support for configuring and monitoring the ESP32 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). + +- Various security modes for the above (WPA, WPA2, WEP, etc.) +- Scanning for access points (active & passive scanning). +- Promiscuous mode monitoring of IEEE802.11 WiFi packets. + +Application Examples +-------------------- + +See :example:`wifi` directory of ESP-IDF examples that contains the following applications: + +* Simple application showing how to connect ESP32 module to an Access Point - `esp-idf-template `_. + +* Using power save mode of Wi-Fi - :example:`wifi/power_save`. + + +API Reference +------------- + +.. include:: /_build/inc/esp_wifi.inc +.. include:: /_build/inc/esp_wifi_types.inc + + diff --git a/docs/en/api-reference/wifi/index.rst b/docs/en/api-reference/wifi/index.rst new file mode 100644 index 00000000..1553d359 --- /dev/null +++ b/docs/en/api-reference/wifi/index.rst @@ -0,0 +1,12 @@ +Wi-Fi API +********* + +.. toctree:: + :maxdepth: 1 + + Wi-Fi + Smart Config + ESPNOW + + +Example code for this API section is provided in :example:`wifi` directory of ESP-IDF examples. diff --git a/docs/en/conf.py b/docs/en/conf.py new file mode 100644 index 00000000..a7dde4b1 --- /dev/null +++ b/docs/en/conf.py @@ -0,0 +1,19 @@ +# -*- coding: utf-8 -*- +# +# English Language RTD & Sphinx config file +# +# Uses ../conf_common.py for most non-language-specific settings. + +# Importing conf_common adds all the non-language-specific +# parts to this conf module +import sys, os +sys.path.insert(0, os.path.abspath('..')) +from conf_common import * + +# General information about the project. +project = u'ESP-IDF Programming Guide' +copyright = u'2016 - 2018, Espressif Systems (Shanghai) PTE LTD' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +language = 'en' diff --git a/docs/en/get-started/eclipse-setup-windows.rst b/docs/en/get-started/eclipse-setup-windows.rst new file mode 100644 index 00000000..3e128a09 --- /dev/null +++ b/docs/en/get-started/eclipse-setup-windows.rst @@ -0,0 +1,90 @@ +********************** +Eclipse IDE on Windows +********************** +:link_to_translation:`zh_CN:[中文]` + +Configuring Eclipse on Windows requires some different steps. The full configuration steps for Windows are shown below. + +(For OS X and Linux instructions, see the :doc:`Eclipse IDE page `.) + +Installing Eclipse IDE +====================== + +Follow the steps under :ref:`Installing Eclipse IDE ` for all platforms. + +.. _eclipse-windows-setup: + +Setting up Eclipse on Windows +============================= + +Once your new Eclipse installation launches, follow these steps: + +Import New Project +------------------ + +* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory. + +* Once Eclipse is running, choose File -> Import... + +* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next. + +* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile). + +* On the same page, under "Toolchain for Indexer Settings" uncheck "Show only available toolchains that support this platform". + +* On the extended list that appears, choose "Cygwin GCC". Then click Finish. + +*Note: you may see warnings in the UI that Cygwin GCC Toolchain could not be found. This is OK, we're going to reconfigure Eclipse to find our toolchain.* + +Project Properties +------------------ + +* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu. + +* Click on the "C/C++ Build" properties page (top-level): + + * Uncheck "Use default build command" and enter this for the custom build command: ``python ${IDF_PATH}/tools/windows/eclipse_make.py`` + +* Click on the "Environment" properties page under "C/C++ Build": + + * Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``. + + * Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed. The IDF_PATH directory should be specified using forwards slashes not backslashes, ie *C:/Users/user-name/Development/esp-idf*. + + * Edit the PATH environment variable. Delete the existing value and replace it with ``C:\msys32\usr\bin;C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin`` (If you installed msys32 to a different directory then you'll need to change these paths to match). + +* Click on "C/C++ General" -> "Preprocessor Include Paths, Macros, etc." property page: + + * Click the "Providers" tab + + * In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Change "Command to get compiler specs" to ``xtensa-esp32-elf-gcc ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"``. + + * In the list of providers, click "CDT GCC Build Output Parser" and change the "Compiler command pattern" to ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)`` + +Navigate to "C/C++ General" -> "Indexer" property page: + +* Check "Enable project specific settings" to enable the rest of the settings on this page. + +* Uncheck "Allow heuristic resolution of includes". When this option is enabled Eclipse sometimes fails to find correct header directories. + +Navigate to "C/C++ Build" -> "Behavior" property page: + +* Check "Enable parallel build" to enable multiple build jobs in parallel. + +* Setting the number of jobs slightly higher than the "optimal" may give the absolute fastest builds under Windows, depending on the specific hardware being used. + +Building in Eclipse +------------------- + +Continue from :ref:`Building in Eclipse ` for all platforms. + +Technical Details +================= + +**Of interest to Windows gurus or very curious parties, only.** + +Explanations of the technical reasons for some of these steps. You don't need to know this to use esp-idf with Eclipse on Windows, but it may be helpful background knowledge if you plan to do dig into the Eclipse support: + +* The xtensa-esp32-elf-gcc cross-compiler is *not* a Cygwin toolchain, even though we tell Eclipse that it is one. This is because msys2 uses Cygwin and supports Unix-style paths (of the type ``/c/blah`` instead of ``c:/blah`` or ``c:\\blah``). In particular, xtensa-esp32-elf-gcc reports to the Eclipse "built-in compiler settings" function that its built-in include directories are all under ``/usr/``, which is a Unix/Cygwin-style path that Eclipse otherwise can't resolve. By telling Eclipse the compiler is Cygwin, it resolves these paths internally using the ``cygpath`` utility. + +* The same problem occurs when parsing make output from esp-idf. Eclipse parses this output to find header directories, but it can't resolve include directories of the form ``/c/blah`` without using ``cygpath``. There is a heuristic that Eclipse Build Output Parser uses to determine whether it should call ``cygpath``, but for currently unknown reasons the esp-idf configuration doesn't trigger it. For this reason, the ``eclipse_make.py`` wrapper script is used to call ``make`` and then use ``cygpath`` to process the output for Eclipse. diff --git a/docs/en/get-started/eclipse-setup.rst b/docs/en/get-started/eclipse-setup.rst new file mode 100644 index 00000000..2f02dd4e --- /dev/null +++ b/docs/en/get-started/eclipse-setup.rst @@ -0,0 +1,120 @@ +******************************** +Build and Flash with Eclipse IDE +******************************** +:link_to_translation:`zh_CN:[中文]` + +.. _eclipse-install-steps: + +Installing Eclipse IDE +====================== + +The Eclipse IDE gives you a graphical integrated development environment for writing, compiling and debugging ESP-IDF projects. + +* Start by installing the esp-idf for your platform (see files in this directory with steps for Windows, OS X, Linux). + +* We suggest building a project from the command line first, to get a feel for how that process works. You also need to use the command line to configure your esp-idf project (via ``make menuconfig``), this is not currently supported inside Eclipse. + +* Download the Eclipse Installer for your platform from eclipse.org_. + +* When running the Eclipse Installer, choose "Eclipse for C/C++ Development" (in other places you'll see this referred to as CDT.) + +Windows Users +============= + +Using ESP-IDF with Eclipse on Windows requires different configuration steps. :ref:`See the Eclipse IDE on Windows guide `. + +Setting up Eclipse +================== + +Once your new Eclipse installation launches, follow these steps: + +Import New Project +------------------ + +* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory. + +* Once Eclipse is running, choose File -> Import... + +* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next. + +* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile). + +* On the same page, under "Toolchain for Indexer Settings" choose "Cross GCC". Then click Finish. + + +Project Properties +------------------ + +* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu. + +* Click on the "Environment" properties page under "C/C++ Build". Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``. + +* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed. + +* Edit the ``PATH`` environment variable. Keep the current value, and append the path to the Xtensa toolchain installed as part of IDF setup, if this is not already listed on the PATH. A typical path to the toolchain looks like ``/home/user-name/esp/xtensa-esp32-elf/bin``. Note that you need to add a colon ``:`` before the appended path. + +* On macOS, add a ``PYTHONPATH`` environment variable and set it to ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``. This is so that the system Python, which has pyserial installed as part of the setup steps, overrides any built-in Eclipse Python. + +Navigate to "C/C++ General" -> "Preprocessor Include Paths" property page: + +* Click the "Providers" tab + +* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Change "Command to get compiler specs" to ``xtensa-esp32-elf-gcc ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"``. + +* In the list of providers, click "CDT GCC Build Output Parser" and change the "Compiler command pattern" to ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)`` + +Navigate to "C/C++ General" -> "Indexer" property page: + +* Check "Enable project specific settings" to enable the rest of the settings on this page. + +* Uncheck "Allow heuristic resolution of includes". When this option is enabled Eclipse sometimes fails to find correct header directories. + +Navigate to "C/C++ Build" -> "Behavior" property page: + +* Check "Enable parallel build" to enable multiple build jobs in parallel. + +.. _eclipse-build-project: + +Building in Eclipse +------------------- + +Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the esp-idf build process. These errors and warnings will go away after you build the project. + +* Click OK to close the Properties dialog in Eclipse. + +* Outside Eclipse, open a command line prompt. Navigate to your project directory, and run ``make menuconfig`` to configure your project's esp-idf settings. This step currently has to be run outside Eclipse. + +*If you try to build without running a configuration step first, esp-idf will prompt for configuration on the command line - but Eclipse is not able to deal with this, so the build will hang or fail.* + +* Back in Eclipse, choose Project -> Build to build your project. + +**TIP**: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before choosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths. + +Flash from Eclipse +------------------ + +You can integrate the "make flash" target into your Eclipse project to flash using esptool.py from the Eclipse UI: + +* Right-click your project in Project Explorer (important to make sure you select the project, not a directory in the project, or Eclipse may find the wrong Makefile.) + +* Select Build Targets -> Create... from the context menu. + +* Type "flash" as the target name. Leave the other options as their defaults. + +* Now you can use Project -> Build Target -> Build (Shift+F9) to build the custom flash target, which will compile and flash the project. + +Note that you will need to use "make menuconfig" to set the serial port and other config options for flashing. "make menuconfig" still requires a command line terminal (see the instructions for your platform.) + +Follow the same steps to add ``bootloader`` and ``partition_table`` targets, if necessary. + +Related Documents +----------------- + +.. toctree:: + :maxdepth: 1 + + eclipse-setup-windows + + +.. _eclipse.org: https://www.eclipse.org/ + diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst new file mode 100644 index 00000000..8d027f19 --- /dev/null +++ b/docs/en/get-started/index.rst @@ -0,0 +1,371 @@ +*********** +Get Started +*********** +:link_to_translation:`zh_CN:[中文]` + +This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards. + +.. include:: /_build/inc/version-note.inc + +Introduction +============ + +ESP32 integrates Wi-Fi (2.4 GHz band) and Bluetooth 4.2 solutions on a single chip, along with dual high performance cores, Ultra Low Power co-processor and several peripherals. Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform to meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability. + +Espressif provides the basic hardware and software resources that help application developers to build their ideas around the ESP32 series hardware. The software development framework by Espressif is intended for rapidly developing Internet-of-Things (IoT) applications, with Wi-Fi, Bluetooth, power management and several other system features. + + +What You Need +============= + +To develop applications for ESP32 you need: + +* **PC** loaded with either Windows, Linux or Mac operating system +* **Toolchain** to build the **Application** for ESP32 +* **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain** +* A text editor to write programs (**Projects**) in C, e.g. `Eclipse `_ +* The **ESP32** board itself and a **USB cable** to connect it to the **PC** + +.. figure:: ../../_static/what-you-need.png + :align: center + :alt: Development of applications for ESP32 + :figclass: align-center + + Development of applications for ESP32 + +Preparation of development environment consists of three steps: + +1. Setup of **Toolchain** +2. Getting of **ESP-IDF** from GitHub +3. Installation and configuration of **Eclipse** + +You may skip the last step, if you prefer to use different editor. + +Having environment set up, you are ready to start the most interesting part - the application development. This process may be summarized in four steps: + +1. Configuration of a **Project** and writing the code +2. Compilation of the **Project** and linking it to build an **Application** +3. Flashing (uploading) of the **Application** to **ESP32** +4. Monitoring / debugging of the **Application** + +See instructions below that will walk you through these steps. + + +Guides +====== + +If you have one of ESP32 development boards listed below, click on provided links to get you up and running. + +.. toctree:: + :maxdepth: 1 + + ESP32 DevKitC + ESP-WROVER-KIT + ESP32-PICO-KIT + +If you have different board, move to sections below. + + +.. _get-started-setup-toolchain: + +Setup Toolchain +=============== + +The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions. + +.. toctree:: + :hidden: + + Windows + Linux + MacOS + ++-------------------+-------------------+-------------------+ +| |windows-logo| | |linux-logo| | |macos-logo| | ++-------------------+-------------------+-------------------+ +| `Windows`_ | `Linux`_ | `Mac OS`_ | ++-------------------+-------------------+-------------------+ + +.. |windows-logo| image:: ../../_static/windows-logo.png + :target: ../get-started/windows-setup.html + +.. |linux-logo| image:: ../../_static/linux-logo.png + :target: ../get-started/linux-setup.html + +.. |macos-logo| image:: ../../_static/macos-logo.png + :target: ../get-started/macos-setup.html + +.. _Windows: ../get-started/windows-setup.html +.. _Linux: ../get-started/linux-setup.html +.. _Mac OS: ../get-started/macos-setup.html + +.. note:: + + We are using ``~/esp`` directory to install the prebuilt toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands. + +Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup`. + +Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf`. + + +.. _get-started-get-esp-idf: + +Get ESP-IDF +=========== + +.. highlight:: bash + +Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository `_. + +.. include:: /_build/inc/git-clone.inc + +Consult :doc:`/versions` for information about which version of ESP-IDF to use in a given situation. + +.. note:: + + Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules:: + + cd ~/esp/esp-idf + git submodule update --init --recursive + + +.. _get-started-setup-path: + +Setup Path to ESP-IDF +===================== + +The toolchain programs access ESP-IDF using ``IDF_PATH`` environment variable. This variable should be set up on your PC, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` in user profile. To do so, follow instructions specific to :ref:`Windows ` , :ref:`Linux and MacOS ` in section :doc:`add-idf_path-to-profile`. + +.. _get-started-get-packages: + +Install the Required Python Packages +==================================== + +Python packages required by ESP-IDF are located in the ``$IDF_PATH/requirements.txt`` file. You can install them by running:: + + python -m pip install --user -r $IDF_PATH/requirements.txt + +.. note:: + + Please invoke that version of the Python interpreter which you will be using with ESP-IDF. The version of the + interpreter can be checked by running command ``python --version`` and depending on the result, you might want to + use ``python2``, ``python2.7`` or similar instead of ``python``, e.g.:: + + python2.7 -m pip install --user -r $IDF_PATH/requirements.txt + +.. _get-started-start-project: + +Start a Project +=============== + +Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. + +Copy :example:`get-started/hello_world` to ``~/esp`` directory:: + + cd ~/esp + cp -r $IDF_PATH/examples/get-started/hello_world . + +You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects. + +.. important:: + + The esp-idf build system does not support spaces in paths to esp-idf or to projects. + + +.. _get-started-connect: + +Connect +======= + +You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step. + + +.. _get-started-configure: + +Configure +========= + +Being in terminal window, go to directory of ``hello_world`` application by typing ``cd ~/esp/hello_world``. Then start project configuration utility ``menuconfig``:: + + cd ~/esp/hello_world + make menuconfig + +If previous steps have been done correctly, the following menu will be displayed: + +.. figure:: ../../_static/project-configuration.png + :align: center + :alt: Project configuration - Home window + :figclass: align-center + + Project configuration - Home window + +In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit application by selecting ``< Exit >``. + +.. note:: + + On Windows, serial ports have names like COM1. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``. + (See :doc:`establish-serial-connection` for full details.) + +Here are couple of tips on navigation and use of ``menuconfig``: + +* Use up & down arrow keys to navigate the menu. +* Use Enter key to go into a submenu, Escape key to go out or to exit. +* Type ``?`` to see a help screen. Enter key exits the help screen. +* Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``" +* Pressing ``?`` while highlighting a configuration item displays help about that item. +* Type ``/`` to search the configuration items. + +.. note:: + + If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``. + + +.. attention:: + + When using ESP32-DevKitC board with ESP32-SOLO-1 module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing example applications. + + +.. _get-started-build-flash: + +Build and Flash +=============== + +Now you can build and flash the application. Run:: + + make flash + +This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your ESP32 board. + +.. highlight:: none + +:: + + esptool.py v2.0-beta2 + Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)... + esptool.py v2.0-beta2 + Connecting........___ + Uploading stub... + Running stub... + Stub running... + Changing baud rate to 921600 + Changed. + Attaching SPI flash... + Configuring flash size... + Auto-detected Flash size: 4MB + Flash params set to 0x0220 + Compressed 11616 bytes to 6695... + Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)... + Hash of data verified. + Compressed 408096 bytes to 171625... + Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)... + Hash of data verified. + Compressed 3072 bytes to 82... + Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)... + Hash of data verified. + + Leaving... + Hard resetting... + +If there are no issues, at the end of build process, you should see messages describing progress of loading process. Finally, the end module will be reset and "hello_world" application will start. + +If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide `. + + +.. _get-started-build-monitor: + +Monitor +======= + +To see if "hello_world" application is indeed running, type ``make monitor``. This command is launching :doc:`IDF Monitor ` application:: + + $ make monitor + MONITOR + --- idf_monitor on /dev/ttyUSB0 115200 --- + --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- + ets Jun 8 2016 00:22:57 + + rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) + ets Jun 8 2016 00:22:57 + ... + +Several lines below, after start up and diagnostic log, you should see "Hello world!" printed out by the application. :: + + ... + Hello world! + Restarting in 10 seconds... + I (211) cpu_start: Starting scheduler on APP CPU. + Restarting in 9 seconds... + Restarting in 8 seconds... + Restarting in 7 seconds... + +To exit the monitor use shortcut ``Ctrl+]``. + +.. note:: + + If instead of the messages above, you see a random garbage similar to:: + + e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA + ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp + + or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig `, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash ` the application again. This is found under ``make menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency. + +To execute ``make flash`` and ``make monitor`` in one go, type ``make flash monitor``. Check section :doc:`IDF Monitor ` for handy shortcuts and more details on using this application. + +That's all what you need to get started with ESP32! + +Now you are ready to try some other :idf:`examples`, or go right to developing your own applications. + + +Environment Variables +===================== + +Some environment variables can be specified whilst calling ``make`` allowing users to **override arguments without needing to reconfigure them using** ``make menuconfig``. + ++-----------------+--------------------------------------------------------------+ +| Variables | Description & Usage | ++=================+==============================================================+ +| ``ESPPORT`` | Overrides the serial port used in ``flash`` and ``monitor``. | +| | | +| | Examples: ``make flash ESPPORT=/dev/ttyUSB1``, | +| | ``make monitor ESPPORT=COM1`` | ++-----------------+--------------------------------------------------------------+ +| ``ESPBAUD`` | Overrides the serial baud rate when flashing the ESP32. | +| | | +| | Example: ``make flash ESPBAUD=9600`` | ++-----------------+--------------------------------------------------------------+ +| ``MONITORBAUD`` | Overrides the serial baud rate used when monitoring. | +| | | +| | Example: ``make monitor MONITORBAUD=9600`` | ++-----------------+--------------------------------------------------------------+ + +.. note:: + Users can export environment variables (e.g. ``export ESPPORT=/dev/ttyUSB1``). + All subsequent calls of ``make`` within the same terminal session will use + the exported value given that the variable is not simultaneously overridden. + +Updating ESP-IDF +================ + +After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf`. + +If downloading to a new path, remember to :doc:`add-idf_path-to-profile` so that the toolchain scripts know where to find the ESP-IDF in its release specific location. + +Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using `. + + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + add-idf_path-to-profile + establish-serial-connection + make-project + eclipse-setup + idf-monitor + toolchain-setup-scratch + +.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ +.. _Releases page: https://github.com/espressif/esp-idf/releases + diff --git a/docs/en/get-started/linux-setup.rst b/docs/en/get-started/linux-setup.rst new file mode 100644 index 00000000..c97abda3 --- /dev/null +++ b/docs/en/get-started/linux-setup.rst @@ -0,0 +1,118 @@ +************************************* +Standard Setup of Toolchain for Linux +************************************* +:link_to_translation:`zh_CN:[中文]` + +Install Prerequisites +===================== + +To compile with ESP-IDF you need to get the following packages: + +- CentOS 7:: + + sudo yum install gcc git wget make ncurses-devel flex bison gperf python python2-cryptography + +- Ubuntu and Debian:: + + sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future + +- Arch:: + + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future + +.. note:: + + Some older Linux distributions may be missing some of the Python packages listed above (or may use ``pyserial`` version 2.x which is not supported by ESP-IDF). It is possible to install these packages via ``pip`` instead - as described in section :ref:`get-started-get-packages`. + +Toolchain Setup +=============== + +.. include:: /_build/inc/download-links.inc + +ESP32 toolchain for Linux is available for download from Espressif website: + +- for 64-bit Linux: + + |download_link_linux64| + +- for 32-bit Linux: + + |download_link_linux32| + +1. Download this file, then extract it in ``~/esp`` directory: + + - for 64-bit Linux: + + .. include:: /_build/inc/unpack-code-linux64.inc + + - for 32-bit Linux: + + .. include:: /_build/inc/unpack-code-linux32.inc + +.. _setup-linux-toolchain-add-it-to-path: + +2. The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory. + + To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file:: + + export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH" + + Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file:: + + alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"' + + Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``. + + .. note:: + + If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead. In CentOS, ``alias`` should set in ``.bashrc``. + +3. 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 end of displayed string:: + + $ printenv PATH + /home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/home/user-name/esp/xtensa-esp32-elf/bin + + Instead of ``/home/user-name`` there should be a home path specific to your installation. + + +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`. + + +Arch Linux Users +---------------- + +To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6. + +Backwards compatibility libraries are available in AUR_ for native and lib32 configurations: + +- https://aur.archlinux.org/packages/ncurses5-compat-libs/ +- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/ + +Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above. + +Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. + + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + linux-setup-scratch + + +.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository diff --git a/docs/en/get-started/macos-setup.rst b/docs/en/get-started/macos-setup.rst new file mode 100644 index 00000000..7e1921a6 --- /dev/null +++ b/docs/en/get-started/macos-setup.rst @@ -0,0 +1,57 @@ +************************************** +Standard Setup of Toolchain for Mac OS +************************************** +:link_to_translation:`zh_CN:[中文]` + +Install Prerequisites +===================== + +- install pip:: + + sudo easy_install pip + +.. note:: + + ``pip`` will be used later for installing :ref:`the required Python packages `. + +Toolchain Setup +=============== + +.. include:: /_build/inc/download-links.inc + +ESP32 toolchain for macOS is available for download from Espressif website: + +|download_link_osx| + +Download this file, then extract it in ``~/esp`` directory: + +.. include:: /_build/inc/unpack-code-osx.inc + +.. _setup-macos-toolchain-add-it-to-path: + +The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory. + +To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file:: + + export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH + +Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file:: + + alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH" + +Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. + + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + macos-setup-scratch diff --git a/docs/en/get-started/windows-setup.rst b/docs/en/get-started/windows-setup.rst new file mode 100644 index 00000000..ad7d8210 --- /dev/null +++ b/docs/en/get-started/windows-setup.rst @@ -0,0 +1,70 @@ +*************************************** +Standard Setup of Toolchain for Windows +*************************************** +:link_to_translation:`zh_CN:[中文]` + +Introduction +============ + +Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide this. You don't need to use this environment all the time (you can use :doc:`Eclipse ` or some other front-end), but it runs behind the scenes. + + +Toolchain Setup +=============== + +The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com: + +https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20181001.zip + +Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``C:\``) and it will create an ``msys32`` directory with a pre-prepared environment. + + +Check it Out +============ + +Open a MSYS2 MINGW32 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. Create a directory named ``esp`` that is a default location to develop ESP32 applications. To do so, run the following shell command:: + + mkdir -p ~/esp + +By typing ``cd ~/esp`` you can then move to the newly created directory. If there are no error messages you are done with this step. + +.. figure:: ../../_static/msys2-terminal-window.png + :align: center + :alt: MSYS2 MINGW32 shell window + :figclass: align-center + + MSYS2 MINGW32 shell window + +Use this window in the following steps setting up development environment for ESP32. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. + +Updating The Environment +======================== + +When IDF is updated, sometimes new toolchains are required or new requirements are added to the Windows MSYS2 environment. To move any data from an old version of the precompiled environment to a new one: + +- Take the old MSYS2 environment (ie ``C:\msys32``) and move/rename it to a different directory (ie ``C:\msys32_old``). +- Download the new precompiled environment using the steps above. +- Unzip the new MSYS2 environment to ``C:\msys32`` (or another location). +- Find the old ``C:\msys32_old\home`` directory and move this into ``C:\msys32``. +- You can now delete the ``C:\msys32_old`` directory if you no longer need it. + +You can have independent different MSYS2 environments on your system, as long as they are in different directories. + +There are :ref:`also steps to update the existing environment without downloading a new one `, although this is more complex. + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + windows-setup-scratch + + +.. _MSYS2: https://msys2.github.io/ diff --git a/docs/en/index.rst b/docs/en/index.rst new file mode 100644 index 00000000..b6a85246 --- /dev/null +++ b/docs/en/index.rst @@ -0,0 +1,55 @@ +ESP-IDF Programming Guide +========================= +:link_to_translation:`zh_CN:[中文]` + +This is the documentation for Espressif IoT Development Framework (`esp-idf `_). ESP-IDF is the official development framework for the `ESP32 `_ chip. + +================== ================== ================== +|Get Started|_ |API Reference|_ |H/W Reference|_ +------------------ ------------------ ------------------ +`Get Started`_ `API Reference`_ `H/W Reference`_ +------------------ ------------------ ------------------ +|API Guides|_ |Contribute|_ |Resources|_ +------------------ ------------------ ------------------ +`API Guides`_ `Contribute`_ `Resources`_ +================== ================== ================== + +.. |Get Started| image:: ../_static/get-started.gif +.. _Get Started: get-started/index.html + +.. |API Reference| image:: ../_static/api-reference.gif +.. _API Reference: api-reference/index.html + +.. |H/W Reference| image:: ../_static/hw-reference.gif +.. _H/W Reference: hw-reference/index.html + +.. |API Guides| image:: ../_static/api-guides.gif +.. _API Guides: api-guides/index.html + +.. |Contribute| image:: ../_static/contribute.gif +.. _Contribute: contribute/index.html + +.. |Resources| image:: ../_static/resources.gif +.. _Resources: resources.html + + +.. toctree:: + :hidden: + + Get Started + Get Started (CMake Preview) + API Reference + H/W Reference + API Guides + Contribute + Versions + Resources + Copyrights + About + 语言/Languages + Guide Downloads + +* :ref:`genindex` + + + diff --git a/docs/gen-dxd.py b/docs/gen-dxd.py new file mode 100755 index 00000000..ee2c692c --- /dev/null +++ b/docs/gen-dxd.py @@ -0,0 +1,318 @@ +#!/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. +# + +from __future__ import print_function +from __future__ import unicode_literals +from builtins import range +from io import open +import sys +import os +import re + +# 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 = "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 = [ + ("function", "Functions"), + ("union", "Unions"), + ("struct", "Structures"), + ("define", "Macros"), + ("typedef", "Type Definitions"), + ("enum", "Enumerations") + ] +"""list of items that will be generated for a single API file +""" + + +def get_doxyfile_input(): + """Get contents of Doxyfile's INPUT statement. + + Returns: + Contents of Doxyfile's INPUT. + + """ + if not os.path.isfile(doxyfile_path): + print("Doxyfile '%s' does not exist!" % doxyfile_path) + sys.exit() + + 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 + 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) + header_file_path = m.group(1) + doxyfile_INPUT += header_file_path + "\n" + # proceed reading next line + line = input_file.readline() + + input_file.close() + return doxyfile_INPUT + + +def get_api_name(header_file_path): + """Get name of API from header file path. + + Args: + header_file_path: path to the header file. + + Returns: + The name of API. + + """ + api_name = "" + regex = r".*/(.*)\.h" + m = re.search(regex, header_file_path) + if m: + api_name = m.group(1) + + return api_name + + +def get_rst_header(header_name): + """Get rst formatted code with a header. + + Args: + header_name: name of header. + + Returns: + Formatted rst code with the header. + + """ + + rst_output = "" + rst_output += header_name + "\n" + rst_output += "^" * len(header_name) + "\n" + rst_output += "\n" + + return rst_output + + +def select_unions(innerclass_list): + """Select unions from innerclass list. + + Args: + innerclass_list: raw list with unions and structures + extracted from Dogygen's xml file. + + Returns: + Doxygen directives with unions selected from the list. + + """ + + rst_output = "" + for line in innerclass_list.splitlines(): + # union is denoted by "union" at the beginning of line + if line.find("union") == 0: + union_id, union_name = re.split(r"\t+", line) + rst_output += ".. doxygenunion:: " + rst_output += union_name + rst_output += "\n" + + return rst_output + + +def select_structs(innerclass_list): + """Select structures from innerclass list. + + Args: + innerclass_list: raw list with unions and structures + extracted from Dogygen's xml file. + + Returns: + Doxygen directives with structures selected from the list. + Note: some structures are excluded as described on code below. + + """ + + rst_output = "" + for line in innerclass_list.splitlines(): + # structure is denoted by "struct" at the beginning of line + if line.find("struct") == 0: + # skip structures that are part of union + # they are documented by 'doxygenunion' directive + if line.find("::") > 0: + continue + struct_id, struct_name = re.split(r"\t+", line) + rst_output += ".. doxygenstruct:: " + rst_output += struct_name + rst_output += "\n" + rst_output += " :members:\n" + rst_output += "\n" + + return rst_output + + +def get_directives(tree, kind): + """Get directives for specific 'kind'. + + Args: + tree: the ElementTree 'tree' of XML by Doxygen + kind: name of API "kind" to be generated + + Returns: + Doxygen directives for selected 'kind'. + Note: the header with "kind" name is included. + + """ + + rst_output = "" + if kind in ["union", "struct"]: + innerclass_list = "" + for elem in tree.iterfind('compounddef/innerclass'): + innerclass_list += elem.attrib["refid"] + "\t" + elem.text + "\n" + if kind == "union": + rst_output += select_unions(innerclass_list) + else: + rst_output += select_structs(innerclass_list) + else: + for elem in tree.iterfind( + 'compounddef/sectiondef/memberdef[@kind="%s"]' % kind): + name = elem.find('name') + rst_output += ".. doxygen%s:: " % kind + rst_output += name.text + "\n" + if rst_output: + 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/gen-toolchain-links.py b/docs/gen-toolchain-links.py new file mode 100644 index 00000000..aa824b93 --- /dev/null +++ b/docs/gen-toolchain-links.py @@ -0,0 +1,77 @@ +#!/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 +# + +from __future__ import print_function + +import sys +import os + +def main(): + if len(sys.argv) != 4: + print("Usage: gen-toolchain-links.py ") + sys.exit(1) + + out_dir = sys.argv[3] + if not os.path.exists(out_dir): + print("Creating directory %s" % out_dir) + os.mkdir(out_dir) + + base_url = sys.argv[2] + + versions_file = sys.argv[1] + version_vars = {} + with open(versions_file) as f: + for line in f: + name, var = line.partition("=")[::2] + version_vars[name.strip()] = var.strip() + + gcc_version = version_vars["CURRENT_TOOLCHAIN_GCC_VERSION"] + toolchain_desc = version_vars["CURRENT_TOOLCHAIN_COMMIT_DESC_SHORT"] + + unpack_code_linux_macos = """ +:: + + mkdir -p ~/esp + cd ~/esp + tar -x{}f ~/Downloads/{} +""" + + scratch_build_code_linux_macos = """ +:: + + git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git + cd crosstool-NG + ./bootstrap && ./configure --enable-local && make install +""" + + platform_info = [ ["linux64", "tar.gz", "z", unpack_code_linux_macos], + ["linux32", "tar.gz", "z", unpack_code_linux_macos], + ["osx", "tar.gz", "z", unpack_code_linux_macos], + ["win32", "zip", None, None]] + + with open(os.path.join(out_dir, 'download-links.inc'), "w") as links_file: + for p in platform_info: + platform_name = p[0] + extension = p[1] + unpack_cmd = p[2] + unpack_code = p[3] + + archive_name = 'xtensa-esp32-elf-{}-{}-{}.{}'.format( + platform_name, toolchain_desc, gcc_version, extension) + + print('.. |download_link_{}| replace:: {}{}'.format( + platform_name, base_url, archive_name), file=links_file) + + if unpack_code is not None: + with open(os.path.join(out_dir, 'unpack-code-%s.inc' % platform_name), "w") as f: + print(unpack_code.format(unpack_cmd, archive_name), file=f) + + with open(os.path.join(out_dir, 'scratch-build-code.inc'), "w") as code_file: + print(scratch_build_code_linux_macos, file=code_file) + +if __name__ == "__main__": + main() diff --git a/docs/gen-version-specific-includes.py b/docs/gen-version-specific-includes.py new file mode 100755 index 00000000..fd226407 --- /dev/null +++ b/docs/gen-version-specific-includes.py @@ -0,0 +1,185 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- +# +# Python script 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 +import subprocess +import os +import sys +import re + +TEMPLATES = { + "en" : { + "git-clone" : { + "template" : """ +To obtain a local copy: open terminal, navigate to the directory you want to put ESP-IDF, and clone the repository using ``git clone`` command:: + + cd ~/esp + git clone %(clone_args)s--recursive https://github.com/espressif/esp-idf.git + +ESP-IDF will be downloaded into ``~/esp/esp-idf``. + +.. note:: + + %(extra_note)s + +.. note:: + + %(zipfile_note)s +""" + ,"master" : 'This command will clone the master branch, which has the latest development ("bleeding edge") version of ESP-IDF. It is fully functional and updated on weekly basis with the most recent features and bugfixes.' + ,"branch" : 'The ``git clone`` option ``-b %(clone_arg)s`` tells git to clone the %(ver_type)s in the ESP-IDF repository corresponding to this version of the documentation.' + ,"zipfile" : { + "stable" : 'As a fallback, it is also possible to download a zip file of this stable release from the `Releases page`_. Do not download the "Source code" zip file(s) generated automatically by GitHub, they do not work with ESP-IDF.' + ,"unstable" : 'GitHub\'s "Download zip file" feature does not work with ESP-IDF, a ``git clone`` is required. As a fallback, `Stable version`_ can be installed without Git.' + }, # zipfile + }, # git-clone + "version-note" : { + "master" : """ +.. note:: + This is documentation for the master branch (latest version) of ESP-IDF. This version is under continual development. `Stable version`_ documentation is available, as well as other :doc:`/versions`. +""" + ,"stable" : """ +.. note:: + This is documentation for stable version %s of ESP-IDF. Other :doc:`/versions` are also available. +""" + ,"branch" : """ +.. note:: + This is documentation for %s ``%s`` of ESP-IDF. Other :doc:`/versions` are also available. +""" + }, # version-note + }, # en + "zh_CN" : { + "git-clone" : { + "template" : """ +获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库:: + + cd ~/esp + git clone %(clone_args)s--recursive https://github.com/espressif/esp-idf.git + +ESP-IDF 将会被下载到 ``~/esp/esp-idf`` 目录下。 + +.. note:: + + %(extra_note)s + +.. note:: + + %(zipfile_note)s +""" + ,"master" : '此命令将克隆 master 分支，该分支保存着 ESP-IDF 的最新版本，它功能齐全，每周都会更新一些新功能并修正一些错误。' + ,"branch" : '``git clone`` 命令的 ``-b %(clone_arg)s`` 选项告诉 git 从 ESP-IDF 仓库中克隆与此版本的文档对应的分支。' + ,"zipfile" : { + "stable" : '作为备份，还可以从 `Releases page`_ 下载此稳定版本的 zip 文件。不要下载由 GitHub 自动生成的"源代码"的 zip 文件，它们不适用于 ESP-IDF。' + ,"unstable" : 'GitHub 中"下载 zip 文档"的功能不适用于 ESP-IDF，所以需要使用 ``git clone`` 命令。作为备份，可以在没有安装 Git 的环境中下载 `Stable version`_ 的 zip 归档文件。' + }, # zipfile + }, # git-clone + "version-note" : { + "master" : """ +.. note:: + 这是ESP-IDF master 分支（最新版本）的文档，该版本在持续开发中。还有 `Stable version`_ 的文档，以及其他版本的文档 :doc:`/versions` 供参考。 + This is documentation for the master branch (latest version) of ESP-IDF. This version is under continual development. `Stable version`_ documentation is available, as well as other :doc:`/versions`. +""" + ,"stable" : """ +.. note:: + 这是ESP-IDF 稳定版本 %s 的文档，还有其他版本的文档 :doc:`/versions` 供参考。 +""" + ,"branch" : """ +.. note:: + 这是ESP-IDF %s ``%s`` 版本的文档，还有其他版本的文档 :doc:`/versions` 供参考。 +""" + }, # version-note + }# zh_CN +} + + +def main(): + if len(sys.argv) != 3: + print("Usage: gen-git-clone.py ") + sys.exit(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) + + template = TEMPLATES[language] + + version, ver_type, is_stable = get_version() + + write_git_clone_inc(template["git-clone"], out_dir, version, ver_type, is_stable) + write_version_note(template["version-note"], out_dir, version, ver_type, is_stable) + print("Done") + + +def write_git_clone_inc(template, out_dir, version, ver_type, is_stable): + zipfile = template["zipfile"] + if version == "master": + args = { + "clone_args" : "", + "extra_note" : template["master"], + "zipfile_note" : zipfile["unstable"] + } + else: + args = { + "clone_args" : "-b %s " % version, + "extra_note" : template["branch"] % {"clone_arg" : version, "ver_type" : ver_type}, + "zipfile_note" : zipfile["stable"] if is_stable else zipfile["unstable"] + } + out_file = os.path.join(out_dir, "git-clone.inc") + with open(out_file, "w", encoding='utf-8') as f: + f.write(template["template"] % args) + print("%s written" % out_file) + + +def write_version_note(template, out_dir, version, ver_type, is_stable): + if version == "master": + content = template["master"] + elif ver_type == "tag" and is_stable: + content = template["stable"] % version + else: + content = template["branch"] % (ver_type, version) + out_file = os.path.join(out_dir, "version-note.inc") + with open(out_file, "w", encoding='utf-8') as f: + f.write(content) + print("%s written" % out_file) + + +def get_version(): + """ + Returns a tuple of (name of branch/tag, type branch/tag, is_stable) + """ + # Trust what RTD says our version is, if it is set + version = os.environ.get("READTHEDOCS_VERSION", None) + if version == "latest": + return ("master", "branch", False) + + # Otherwise, use git to look for a tag + try: + tag = subprocess.check_output(["git", "describe", "--tags", "--exact-match"]).strip() + 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)"]) + print("refs:\n%s" % refs) + refs = refs.split(b"\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/") ] + 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) + if "master" in branches: + return ("master", "branch", False) + else: + return (branches[0], "branch", False) # take whatever the first branch is + +if __name__ == "__main__": + main() diff --git a/docs/link-roles.py b/docs/link-roles.py new file mode 100644 index 00000000..c24d2007 --- /dev/null +++ b/docs/link-roles.py @@ -0,0 +1,70 @@ +# based on http://protips.readthedocs.io/link-roles.html + +from __future__ import print_function +from __future__ import unicode_literals +import re +import os +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') + print('Git commit ID: ', path) + if len(tag): + print('Git tag: ', tag) + path = tag + return path + +def setup(app): + rev = get_github_rev() + + # links to files or folders on the GitHub + baseurl = 'https://github.com/espressif/esp-idf' + app.add_role('idf', autolink('{}/tree/{}/%s'.format(baseurl, rev))) + app.add_role('idf_file', autolink('{}/blob/{}/%s'.format(baseurl, rev))) + app.add_role('idf_raw', autolink('{}/raw/{}/%s'.format(baseurl, rev))) + app.add_role('component', autolink('{}/tree/{}/components/%s'.format(baseurl, rev))) + app.add_role('component_file', autolink('{}/blob/{}/components/%s'.format(baseurl, rev))) + app.add_role('component_raw', autolink('{}/raw/{}/components/%s'.format(baseurl, rev))) + app.add_role('example', autolink('{}/tree/{}/examples/%s'.format(baseurl, rev))) + app.add_role('example_file', autolink('{}/blob/{}/examples/%s'.format(baseurl, rev))) + app.add_role('example_raw', autolink('{}/raw/{}/examples/%s'.format(baseurl, rev))) + + # link to the current documentation file in specific language version + on_rtd = os.environ.get('READTHEDOCS', None) == 'True' + 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): + tag_rev = rev + else: + # if not on the RTD then provide generic identification + tag_rev = run_cmd_get_output('git describe --always') + + app.add_role('link_to_translation', crosslink('%s../../%s/{}/%s.html'.format(tag_rev))) + +def autolink(pattern): + def role(name, rawtext, text, lineno, inliner, options={}, content=[]): + m = re.search('(.*)\s*<(.*)>', text) + if m: + link_text = m.group(1) + link = m.group(2) + else: + link_text = text + link = text + url = pattern % (link,) + node = nodes.reference(rawtext, link_text, refuri=url, **options) + return [node], [] + return role + +def crosslink(pattern): + def role(name, rawtext, text, lineno, inliner, options={}, content=[]): + (language, link_text) = text.split(':') + docname = inliner.document.settings.env.docname + doc_path = inliner.document.settings.env.doc2path(docname, None, None) + return_path = '../' * doc_path.count('/') + url = pattern % (return_path, language, docname) + node = nodes.reference(rawtext, link_text, refuri=url, **options) + return [node], [] + return role diff --git a/docs/local_util.py b/docs/local_util.py new file mode 100644 index 00000000..38b324bd --- /dev/null +++ b/docs/local_util.py @@ -0,0 +1,55 @@ +# Utility functions used in conf.py +# +# Copyright 2017 Espressif Systems (Shanghai) PTE LTD +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http:#www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import unicode_literals +from io import open +import re +import os +import shutil + +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 + file_1_contents = '' + with open(path_1, "r", encoding='utf-8') as f_1: + file_1_contents = f_1.read() + file_2_contents = '' + with open(path_2, "r", encoding='utf-8') as f_2: + file_2_contents = f_2.read() + return file_1_contents == file_2_contents + +def copy_file_if_modified(src_file_path, dst_file_path): + if not files_equal(src_file_path, dst_file_path): + dst_dir_name = os.path.dirname(dst_file_path) + if not os.path.isdir(dst_dir_name): + os.makedirs(dst_dir_name) + shutil.copy(src_file_path, dst_file_path) + +def copy_if_modified(src_path, dst_path): + if os.path.isfile(src_path): + copy_file_if_modified(src_path, dst_path) + return + + src_path_len = len(src_path) + for root, dirs, files in os.walk(src_path): + for src_file_name in files: + src_file_path = os.path.join(root, src_file_name) + dst_file_path = os.path.join(dst_path + root[src_path_len:], src_file_name) + copy_file_if_modified(src_file_path, dst_file_path) + diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..6a4de8f3 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,12 @@ +# This is a list of python packages used to generate documentation. This file is used with pip: +# pip install --user -r requirements.txt +# +sphinx==1.6.5 +sphinx-rtd-theme +breathe==4.7.3 +sphinxcontrib-blockdiag==1.5.3 +sphinxcontrib-seqdiag==0.8.5 +sphinxcontrib-actdiag==0.8.5 +sphinxcontrib-nwdiag==0.9.5 +recommonmark +future>=0.16.0 # for ../tools/gen_esp_err_to_name.py diff --git a/tools/check_python_dependencies.py b/tools/check_python_dependencies.py new file mode 100755 index 00000000..d8767004 --- /dev/null +++ b/tools/check_python_dependencies.py @@ -0,0 +1,76 @@ +#!/usr/bin/env python +# +# Copyright 2018 Espressif Systems (Shanghai) PTE LTD +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os +import sys +import argparse +try: + import pkg_resources +except: + print('pkg_resources cannot be imported probably because the pip package is not installed and/or using a ' + 'legacy Python interpreter. Please refer to the Get Started section of the ESP-IDF Programming Guide for ' + 'setting up the required packages.') + sys.exit(1) + +if __name__ == "__main__": + idf_path = os.getenv("IDF_PATH") + + parser = argparse.ArgumentParser(description='ESP32 Python package dependency checker') + parser.add_argument('--requirements', '-r', + help='Path to the requrements file', + default=idf_path + '/requirements.txt') + args = parser.parse_args() + + # Special case for MINGW32 Python, needs some packages + # via MSYS2 not via pip or system breaks... + if sys.platform == "win32" and \ + os.environ.get("MSYSTEM", None) == "MINGW32" and \ + "/mingw32/bin/python" in sys.executable: + failed = False + try: + import cryptography + except ImportError: + print("Please run the following command to install MSYS2's MINGW Python cryptography package:") + print("pacman -S mingw-w64-i686-python%d-cryptography" % (sys.version_info[0],)) + failed = True + try: + import setuptools + except ImportError: + print("Please run the following command to install MSYS2's MINGW Python setuptools package:") + print("pacman -S mingw-w64-i686-python%d-setuptools" % (sys.version_info[0],)) + failed = True + if failed: + sys.exit(1) + + not_satisfied = [] + with open(args.requirements) as f: + for line in f: + line = line.strip() + try: + pkg_resources.require(line) + except: + not_satisfied.append(line) + + if len(not_satisfied) > 0: + print('The following Python requirements are not satisfied:') + for requirement in not_satisfied: + print(requirement) + print('Please refer to the Get Started section of the ESP-IDF Programming Guide for setting up the required ' + 'packages. Alternatively, you can run "{} -m pip install --user -r {}" for resolving the issue.' + ''.format(sys.executable, args.requirements)) + sys.exit(1) + + print('Python requirements from {} are satisfied.'.format(args.requirements)) diff --git a/tools/gen_esp_err_to_name.py b/tools/gen_esp_err_to_name.py new file mode 100755 index 00000000..2beb5ac9 --- /dev/null +++ b/tools/gen_esp_err_to_name.py @@ -0,0 +1,352 @@ +#!/usr/bin/env python +# +# Copyright 2018 Espressif Systems (Shanghai) PTE LTD +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import print_function +from __future__ import unicode_literals +import sys +try: + from builtins import str + from builtins import range + from builtins import object +except ImportError: + # This should not happen because the Python packages are checked before invoking this script. However, here is + # some output which should help if we missed something. + print('Import has failed probably because of the missing "future" package. Please install all the packages for ' + 'interpreter {} from the requirements.txt file.'.format(sys.executable)) + # The path to requirements.txt is not provided because this script could be invoked from an IDF project (then the + # requirements.txt from the IDF_PATH should be used) or from the documentation project (then the requirements.txt + # for the documentation directory should be used). + sys.exit(1) +from io import open +import os +import argparse +import re +import fnmatch +import collections +import textwrap +import functools + +# list files here which should not be parsed +ignore_files = [ 'components/mdns/test_afl_fuzz_host/esp32_compat.h' ] + +# add directories here which should not be parsed +ignore_dirs = ( 'examples' ) + +# macros from here have higher priorities in case of collisions +priority_headers = [ 'components/esp32/include/esp_err.h' ] + +err_dict = collections.defaultdict(list) #identified errors are stored here; mapped by the error code +rev_err_dict = dict() #map of error string to error code +unproc_list = list() #errors with unknown codes which depend on other errors + +class ErrItem(object): + """ + Contains information about the error: + - name - error string + - file - relative path inside the IDF project to the file which defines this error + - include_as - (optional) overwrites the include determined from file + - comment - (optional) comment for the error + - rel_str - (optional) error string which is a base for the error + - rel_off - (optional) offset in relation to the base error + """ + def __init__(self, name, file, include_as = None, comment = "", rel_str = "", rel_off = 0): + self.name = name + self.file = file + self.include_as = include_as + self.comment = comment + self.rel_str = rel_str + self.rel_off = rel_off + def __str__(self): + ret = self.name + " from " + self.file + if (self.rel_str != ""): + ret += " is (" + self.rel_str + " + " + str(self.rel_off) + ")" + if self.comment != "": + ret += " // " + self.comment + return ret + def __cmp__(self, other): + if self.file in priority_headers and other.file not in priority_headers: + return -1 + elif self.file not in priority_headers and other.file in priority_headers: + return 1 + + base = "_BASE" + + if self.file == other.file: + if self.name.endswith(base) and not(other.name.endswith(base)): + return 1 + elif not(self.name.endswith(base)) and other.name.endswith(base): + return -1 + + self_key = self.file + self.name + other_key = other.file + other.name + if self_key < other_key: + return -1 + elif self_key > other_key: + return 1 + else: + return 0 + +class InputError(RuntimeError): + """ + Represents and error on the input + """ + def __init__(self, p, e): + super(InputError, self).__init__(p + ": " + e) + +def process(line, idf_path, include_as): + """ + Process a line of text from file idf_path (relative to IDF project). + Fills the global list unproc_list and dictionaries err_dict, rev_err_dict + """ + if idf_path.endswith(".c"): + # We would not try to include a C file + raise InputError(idf_path, "This line should be in a header file: %s" % line) + + words = re.split(r' +', line, 2) + # words[1] is the error name + # words[2] is the rest of the line (value, base + value, comment) + if len(words) < 3: + raise InputError(idf_path, "Error at line %s" % line) + + line = "" + todo_str = words[2] + + comment = "" + # identify possible comment + m = re.search(r'/\*!<(.+?(?=\*/))', todo_str) + if m: + comment = m.group(1).strip() + todo_str = todo_str[:m.start()].strip() # keep just the part before the comment + + # identify possible parentheses () + m = re.search(r'\((.+)\)', todo_str) + if m: + todo_str = m.group(1) #keep what is inside the parentheses + + # identify BASE error code, e.g. from the form BASE + 0x01 + m = re.search(r'\s*(\w+)\s*\+(.+)', todo_str) + if m: + related = m.group(1) # BASE + todo_str = m.group(2) # keep and process only what is after "BASE +" + + # try to match a hexadecimal number + m = re.search(r'0x([0-9A-Fa-f]+)', todo_str) + if m: + num = int(m.group(1), 16) + else: + # Try to match a decimal number. Negative value is possible for some numbers, e.g. ESP_FAIL + m = re.search(r'(-?[0-9]+)', todo_str) + if m: + num = int(m.group(1), 10) + elif re.match(r'\w+', todo_str): + # It is possible that there is no number, e.g. #define ERROR BASE + related = todo_str # BASE error + num = 0 # (BASE + 0) + else: + raise InputError(idf_path, "Cannot parse line %s" % line) + + try: + related + except NameError: + # The value of the error is known at this moment because it do not depends on some other BASE error code + err_dict[num].append(ErrItem(words[1], idf_path, include_as, comment)) + rev_err_dict[words[1]] = num + else: + # Store the information available now and compute the error code later + unproc_list.append(ErrItem(words[1], idf_path, include_as, comment, related, num)) + +def process_remaining_errors(): + """ + Create errors which could not be processed before because the error code + for the BASE error code wasn't known. + This works for sure only if there is no multiple-time dependency, e.g.: + #define BASE1 0 + #define BASE2 (BASE1 + 10) + #define ERROR (BASE2 + 10) - ERROR will be processed successfully only if it processed later than BASE2 + """ + for item in unproc_list: + if item.rel_str in rev_err_dict: + base_num = rev_err_dict[item.rel_str] + base = err_dict[base_num][0] + num = base_num + item.rel_off + err_dict[num].append(ErrItem(item.name, item.file, item.include_as, item.comment)) + rev_err_dict[item.name] = num + else: + print(item.rel_str + " referenced by " + item.name + " in " + item.file + " is unknown") + + del unproc_list[:] + +def path_to_include(path): + """ + Process the path (relative to the IDF project) in a form which can be used + to include in a C file. Using just the filename does not work all the + time because some files are deeper in the tree. This approach tries to + find an 'include' parent directory an include its subdirectories, e.g. + "components/XY/include/esp32/file.h" will be transported into "esp32/file.h" + So this solution works only works when the subdirectory or subdirectories + are inside the "include" directory. Other special cases need to be handled + here when the compiler gives an unknown header file error message. + """ + spl_path = path.split(os.sep) + try: + i = spl_path.index('include') + except ValueError: + # no include in the path -> use just the filename + return os.path.basename(path) + else: + return os.sep.join(spl_path[i+1:]) # subdirectories and filename in "include" + +def print_warning(error_list, error_code): + """ + Print warning about errors with the same error code + """ + print("[WARNING] The following errors have the same code (%d):" % error_code) + for e in error_list: + print(" " + str(e)) + +def max_string_width(): + max = 0 + for k in err_dict: + for e in err_dict[k]: + x = len(e.name) + if x > max: + max = x + return max + +def generate_c_output(fin, fout): + """ + Writes the output to fout based on th error dictionary err_dict and + template file fin. + """ + # make includes unique by using a set + includes = set() + for k in err_dict: + for e in err_dict[k]: + if e.include_as: + includes.add(e.include_as) + else: + includes.add(path_to_include(e.file)) + + # The order in a set in non-deterministic therefore it could happen that the + # include order will be different in other machines and false difference + # in the output file could be reported. In order to avoid this, the items + # are sorted in a list. + include_list = list(includes) + include_list.sort() + + max_width = max_string_width() + 17 + 1 # length of " ERR_TBL_IT()," with spaces is 17 + max_decdig = max(len(str(k)) for k in err_dict) + + for line in fin: + if re.match(r'@COMMENT@', line): + fout.write("//Do not edit this file because it is autogenerated by " + os.path.basename(__file__) + "\n") + + elif re.match(r'@HEADERS@', line): + for i in include_list: + fout.write("#if __has_include(\"" + i + "\")\n#include \"" + i + "\"\n#endif\n") + elif re.match(r'@ERROR_ITEMS@', line): + last_file = "" + for k in sorted(err_dict.keys()): + if len(err_dict[k]) > 1: + err_dict[k].sort(key=functools.cmp_to_key(ErrItem.__cmp__)) + print_warning(err_dict[k], k) + for e in err_dict[k]: + if e.file != last_file: + last_file = e.file + fout.write(" // %s\n" % last_file) + table_line = (" ERR_TBL_IT(" + e.name + "), ").ljust(max_width) + "/* " + str(k).rjust(max_decdig) + fout.write("# ifdef %s\n" % e.name) + fout.write(table_line) + hexnum_length = 0 + if k > 0: # negative number and zero should be only ESP_FAIL and ESP_OK + hexnum = " 0x%x" % k + hexnum_length = len(hexnum) + fout.write(hexnum) + if e.comment != "": + if len(e.comment) < 50: + fout.write(" %s" % e.comment) + else: + indent = " " * (len(table_line) + hexnum_length + 1) + w = textwrap.wrap(e.comment, width=120, initial_indent = indent, subsequent_indent = indent) + # this couldn't be done with initial_indent because there is no initial_width option + fout.write(" %s" % w[0].strip()) + for i in range(1, len(w)): + fout.write("\n%s" % w[i]) + fout.write(" */\n# endif\n") + else: + fout.write(line) + +def generate_rst_output(fout): + for k in sorted(err_dict.keys()): + v = err_dict[k][0] + fout.write(':c:macro:`{}` '.format(v.name)) + if k > 0: + fout.write('**(0x{:x})**'.format(k)) + else: + fout.write('({:d})'.format(k)) + if len(v.comment) > 0: + fout.write(': {}'.format(v.comment)) + fout.write('\n\n') + +def main(): + if 'IDF_PATH' in os.environ: + idf_path = os.environ['IDF_PATH'] + else: + idf_path = os.path.realpath(os.path.join(os.path.dirname(os.path.abspath(__file__)), '..')) + + parser = argparse.ArgumentParser(description='ESP32 esp_err_to_name lookup generator for esp_err_t') + parser.add_argument('--c_input', help='Path to the esp_err_to_name.c.in template input.', default=idf_path + '/components/esp32/esp_err_to_name.c.in') + parser.add_argument('--c_output', help='Path to the esp_err_to_name.c output.', default=idf_path + '/components/esp32/esp_err_to_name.c') + parser.add_argument('--rst_output', help='Generate .rst output and save it into this file') + args = parser.parse_args() + + include_as_pattern = re.compile(r'\s*//\s*{}: [^"]* "([^"]+)"'.format(os.path.basename(__file__))) + define_pattern = re.compile(r'\s*#define\s+(ESP_ERR_|ESP_OK|ESP_FAIL)') + + for root, dirnames, filenames in os.walk(idf_path): + for filename in fnmatch.filter(filenames, '*.[ch]'): + full_path = os.path.join(root, filename) + path_in_idf = os.path.relpath(full_path, idf_path) + if path_in_idf in ignore_files or path_in_idf.startswith(ignore_dirs): + continue + with open(full_path, encoding='utf-8') as f: + try: + include_as = None + for line in f: + line = line.strip() + m = include_as_pattern.search(line) + if m: + include_as = m.group(1) + # match also ESP_OK and ESP_FAIL because some of ESP_ERRs are referencing them + elif define_pattern.match(line): + try: + process(line, path_in_idf, include_as) + except InputError as e: + print(e) + except UnicodeDecodeError: + raise ValueError("The encoding of {} is not Unicode.".format(path_in_idf)) + + process_remaining_errors() + + if args.rst_output is not None: + with open(args.rst_output, 'w', encoding='utf-8') as fout: + generate_rst_output(fout) + else: + with open(args.c_input, 'r', encoding='utf-8') as fin, open(args.c_output, 'w', encoding='utf-8') as fout: + generate_c_output(fin, fout) + +if __name__ == "__main__": + main() diff --git a/tools/toolchain_versions.mk b/tools/toolchain_versions.mk new file mode 100644 index 00000000..cf74ef5e --- /dev/null +++ b/tools/toolchain_versions.mk @@ -0,0 +1,6 @@ +SUPPORTED_TOOLCHAIN_COMMIT_DESC = crosstool-ng-1.22.0-80-g6c4433a +SUPPORTED_TOOLCHAIN_GCC_VERSIONS = 5.2.0 + +CURRENT_TOOLCHAIN_COMMIT_DESC = crosstool-ng-1.22.0-80-g6c4433a +CURRENT_TOOLCHAIN_COMMIT_DESC_SHORT = 1.22.0-80-g6c4433a +CURRENT_TOOLCHAIN_GCC_VERSION = 5.2.0