docs: update esp32s2 summary page

- Refer to the toolchain links on IDF Tools page
- Update the wording around v4.1/v4.2 releases
- Remove the section about 3 different versions (of S2-beta)
- Add link to the list of features maintained externally

docs/conf_common.py

@@ -154,9 +154,10 @@ def update_exclude_patterns(tags):
             exclude_patterns.append(e)
 
     if "esp32s2" not in tags:
-        # Exclude ESP32-only document pages so they aren't found in the initial search for .rst files
+        # Exclude ESP32-S2-only document pages so they aren't found in the initial search for .rst files
         # note: in toctrees, these also need to be marked with a :esp32: filter
-        for e in ['hw-reference/esp32s2/**',
+        for e in ['esp32s2.rst',
+                  'hw-reference/esp32s2/**',
                   'api-guides/ulps2_instruction_set.rst',
                   'api-reference/peripherals/temp_sensor.rst']:
             exclude_patterns.append(e)

docs/en/api-guides/build-system.rst

@@ -960,7 +960,7 @@ Selecting the Target
 
 ESP-IDF supports multiple targets (chips). The identifiers used for each chip are as follows:
 
-* ``esp32`` — for ESP32-D0WD, ESP32-D2WD, ESP32-S0WD (ESP-SOLO), ESP32-U4WD, ESP32-PICO-D4
+* ``esp32`` — for ESP32-D0WD, ESP32-D2WD, ESP32-S0WD (ESP-SOLO), ESP32-U4WDH, ESP32-PICO-D4
 * ``esp32s2``— for ESP32-S2
 
 To select the target before building the project, use ``idf.py set-target <target>`` command, for example::

docs/en/esp32s2.rst

@@ -1,14 +1,16 @@
 ESP32-S2 Preview Support
 ========================
 
-The current master branch of ESP-IDF (pre-V4.2) contains preview support for ESP32-S2.
+The current master branch of ESP-IDF (pre-v4.2) contains preview support for ESP32-S2.
 
-Software support is still being developed ahead of the final ESP32-S2 release (see :ref:`esp32s2-limitations` and :ref:`esp32s2-roadmap` sections below).
+..note: Support for the ESP32-S2beta chip is included in ESP-IDF v4.1 as a preview only. In ESP-IDF v4.2 (this version) it has been replaced by ESP32-S2 (non-beta) chip support.
+
+Software support and documentation for ESP32-S2 chip is still being developed. See :ref:`esp32s2-limitations` section below.
 
 Documentation
 ^^^^^^^^^^^^^
 
-Except where it specifically mentions ESP32-S2, this version of the ESP-IDF Programming Guide is written for ESP32 only. Most software APIs and components are the same or very similar for ESP32-S2, but differences may not be documented yet.
+You are viewing the version of the ESP-IDF Programming Guide that describes ESP32-S2 support. However, as this version is still under development then there may be some changes from ESP32 that are not yet correctly documented here. If you find documentation that needs updating, please use the "Provide feedback about this document" link at the bottom of the page to tell us about it.
 
 Setting up for ESP32-S2
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -22,12 +24,7 @@ The toolchain tuple is `xtensa-esp32s2-elf-`, for example the GCC compiler for t
 Manual toolchain URLs
 ---------------------
 
-If not using ``install.sh`` or ``install.bat``, you can download the manual toolchain manually from here:
-
-- `Windows <https://dl.espressif.com/dl/xtensa-esp32s2-elf-gcc8_2_0-esp-2019r2-win32.zip>`_
-- `macOS <https://dl.espressif.com/dl/xtensa-esp32s2-elf-gcc8_2_0-esp-2019r2-macos.tar.gz>`_
-- `Linux 64-bit x86 <https://dl.espressif.com/dl/xtensa-esp32s2-elf-gcc8_2_0-esp-2019r2-linux-amd64.tar.gz>`_
-- `Linux 32-bit x86 <https://dl.espressif.com/dl/xtensa-esp32s2-elf-gcc8_2_0-esp-2019r2-linux-i686.tar.gz>`_
+If not using ``install.sh`` or ``install.bat``, you can download the toolchain manually. Download links can be found in the :ref:`idf-tools-list`, under the name ``xtensa-esp32s2-elf``.
 
 If installing the toolchain manually, unpack it somewhere and add the ``bin`` subdirectory to your `PATH`.
 
@@ -48,12 +45,12 @@ Before building an ESP-IDF project, run the following command to switch the targ
 
 .. important:: Running ``set-target`` will clear the project configuration and create a new empty ``sdkconfig`` file for the project. The old configuration will be saved in ``sdkconfig.old``.
 
+See :ref:`selecting-idf-target` for more details about switching between different targets (esp32, esp32s2).
+
 Then configure the project::
 
   idf.py menuconfig
 
-.. important:: There are 3 versions of ESP32-S2 available with different Wi-Fi PHYs. They can be identified by the marking on the chip itself. The project must be configured to match the chip via the project setting "ESP32-S2 chip version" (``CONFIG_ESP32S2_CHIP_VERSION``). This can be found under Component Config -> ESP32S2-specific. If the project setting doesn't match the chip then Wi-Fi performance may be very poor, or the chip may crash when initializing Wi-Fi.
-
 Build and flash the project as usual, for example::
 
   idf.py -p PORT flash monitor
@@ -71,25 +68,15 @@ ESP32-S2 support is currently a preview and does not support all features. Espre
 
 - The integrated USB OTG peripheral is not supported
 - Documentation not updated for ESP32-S2 in most places
-- Peripheral drivers are a work in progress
-- No power saving modes
+- Peripheral drivers and power saving modes are a work in progress
 - No hardware security features or cryptographic accelerator support
 - Time-of-Flight (TOF) measurements with normal Wi-Fi packets is not supported
 
-.. _esp32s2-roadmap:
-
-Roadmap
-^^^^^^^
-
-- ESP-IDF V4.1 will support ESP32-S2beta chip as a preview with some limitations.
-- ESP-IDF V4.2 will support ESP32-S2 (the previous ESP32-S2beta chip can't work on V4.2).
-
-Support for ESP32-S2beta will be removed from ESP-IDF once ESP32-S2 is available.
-
+The up-to-date list of features supported on ESP32-S2 is maintained at `in this forum post <https://esp32.com/viewtopic.php?f=10&p=56361>`_.
 
 Issues
 ^^^^^^
 
 If you find issues which are not mentioned in :ref:`esp32s2-limitations`, please `open an issue on GitHub <https://github.com/espressif/esp-idf/issues>`_.
 
-Please make sure to mention that you are using the ESP32-S2 preview support and give your exact version of ESP-IDF.
+Please make sure to mention that you are using the ESP32-S2 chip and give your exact version of ESP-IDF.

docs/en/index.rst

@@ -47,10 +47,10 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf <htt
 .. toctree::
    :hidden:
 
+   :esp32s2: ESP32-S2 Preview Support <esp32s2>
    Get Started <get-started/index>
    API Reference <api-reference/index>
    H/W Reference <hw-reference/index>
-   ESP32-S2 Preview Support <esp32s2>
    API Guides <api-guides/index>
    Libraries and Frameworks <libraries-and-frameworks/index>
    Contribute <contribute/index>

docs/zh_CN/api-guides/build-system.rst

@@ -791,13 +791,37 @@ Flash 参数
 
 子项目通过 :idf_file:`/components/bootloader/project_include.cmake` 文件作为外部项目插入到项目的顶层，主构建进程会运行子项目的 CMake，包括查找组件（主项目使用的组件的子集），生成引导程序专用的配置文件（从主 ``sdkconfig`` 文件中派生）。
 
-选择硬件目标
-============
+.. _selecting-idf-target:
 
-当前 ESP-IDF 仅支持一个硬件目标，即 ``esp32``，这也是构建系统默认的硬件目标。开发人员可以按照如下方法来添加对新硬件目标的支持::
+Selecting the Target
+====================
 
-    rm sdkconfig
-    idf.py -DIDF_TARGET=new_target reconfigure
+ESP-IDF supports multiple targets (chips). The identifiers used for each chip are as follows:
+
+* ``esp32`` — for ESP32-D0WD, ESP32-D2WD, ESP32-S0WD (ESP-SOLO), ESP32-U4WDH, ESP32-PICO-D4
+* ``esp32s2``— for ESP32-S2
+
+To select the target before building the project, use ``idf.py set-target <target>`` command, for example::
+
+    idf.py set-target esp32s2
+
+.. important::
+
+    ``idf.py set-target`` will clear the build directory and re-generate the ``sdkconfig`` file from scratch. The old ``sdkconfig`` file will be saved as ``sdkconfig.old``.
+
+.. note::
+
+    The behavior of ``idf.py set-target`` command is equivalent to:
+
+    1. clearing the build directory (``idf.py fullclean``)
+    2. removing the sdkconfig file (``mv sdkconfig sdkconfig.old``)
+    3. configuring the project with the new target (``idf.py -DIDF_TARGET=esp32 reconfigure``)
+
+It is also possible to pass the desired ``IDF_TARGET`` as an environement variable (e.g. ``export IDF_TARGET=esp32s2``) or as a CMake variable (e.g. ``-DIDF_TARGET=esp32s2`` argument to CMake or idf.py). Setting the environment variable is a convenient method if you mostly work with one type of the chip.
+
+To specify the _default_ value of ``IDF_TARGET`` for a given project, add ``CONFIG_IDF_TARGET`` value to ``sdkconfig.defaults``. For example, ``CONFIG_IDF_TARGET="esp32s2"``. This value will be used if ``IDF_TARGET`` is not specified by other method: using an environment variable, CMake variable, or ``idf.py set-target`` command.
+
+If the target has not been set by any of these methods, the build system will default to ``esp32`` target.
 
 .. _write-pure-component:
 

docs/zh_CN/get-started/index.rst

@@ -320,6 +320,8 @@ Windows 操作系统
     cd %userprofile%\esp\hello_world
     idf.py menuconfig
 
+Setting the target with ``idf.py set-target {IDF_TARGET}`` should be done once, after opening a new project. If the project contains some existing builds and configuration, they will be cleared and initialized. The target may be saved in environment variable to skip this step at all. See :ref:`selecting-idf-target` for additional information.
+
 如果之前的步骤都正确，则会显示下面的菜单：
 
 .. figure:: ../../_static/project-configuration.png

docs/zh_CN/index.rst

@@ -39,10 +39,10 @@ ESP-IDF 编程指南
 .. toctree::
    :hidden:
 
+   :esp32s2: ESP32-S2 预览 <esp32s2>
    快速入门 <get-started/index>
    API 参考 <api-reference/index>
    H/W 参考 <hw-reference/index>
-   ESP32-S2 预览 <esp32s2>
    API 指南 <api-guides/index>
    Libraries and Frameworks <libraries-and-frameworks/index>
    贡献代码 <contribute/index>