esp-idf/docs/en/esp32s2.rst
2020-01-22 12:14:38 +08:00

96 lines
4.6 KiB
ReStructuredText

ESP32-S2 Preview Support
========================
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).
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.
Setting up for ESP32-S2
^^^^^^^^^^^^^^^^^^^^^^^
To start with, follow the :doc:`/get-started/index` guide to configure the CMake-based build system for ESP32.
When running ``install.sh`` or ``install.bat`` as part of the Get Started guide, the ESP32-S2 toolchain will be automatically downloaded and added to the IDF Tools directory. If you had already run ``install.sh`` or ``install.bat`` before updating to a version with ESP32-S2 support, you may need to re-run it.
The toolchain tuple is `xtensa-esp32s2-elf-`, for example the GCC compiler for this target is named `xtensa-esp32s2-elf-gcc`.
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 installing the toolchain manually, unpack it somewhere and add the ``bin`` subdirectory to your `PATH`.
Building a project for ESP32-S2
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. important:: Not all ESP-IDF examples support ESP32-S2.
For some examples this is because required hardware is not included in ESP32-S2 so it cannot be supported. For some examples this is because the example has not yet been updated for ESP32-S2.
If building an example, please check the example CMakeLists.txt file for the clause ``SUPPORTED_TARGETS esp32``. If this is present, the example won't work on ESP32-S2.
.. highlight:: bash
Before building an ESP-IDF project, run the following command to switch the target to ESP32-S2::
idf.py set-target esp32s2
.. 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``.
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
Consult the :doc:`/get-started/index` guide for more details on building and flashing an ESP-IDF project.
.. note:: It is possible to set the project target back to ESP32 by running ``idf.py set-target esp32``. This also clears the project configuration.
.. _esp32s2-limitations:
Limitations
^^^^^^^^^^^
ESP32-S2 support is currently a preview and does not support all features. Espressif firmware developers are working hard on the remaining support, so please update the ``master`` branch regularly to receive the latest code.
- 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
- 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.
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.