mirror of
https://github.com/espressif/esp-idf.git
synced 2025-12-07 17:08:49 +00:00
docs: initial update of programming guide for C3
Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
This commit is contained in:
Marius Vikhammer
@@ -2,11 +2,11 @@
|
||||
Get Started
|
||||
***********
|
||||
|
||||
{IDF_TARGET_CORE_NUM:default="2", esp32="2", esp32s2="1"}
|
||||
{IDF_TARGET_CORE_NUM:default="2", esp32="2", esp32s2="1", esp32c3="1"}
|
||||
|
||||
{IDF_TARGET_FEATURES:default="WiFi/BT/BLE, silicon revision 1, 2MB external flash", esp32="WiFi/BT/BLE, silicon revision 1, 2MB external flash", esp32s2="WiFi, silicon revision 0, 2MB external flash"}
|
||||
{IDF_TARGET_FEATURES:default="WiFi/BT/BLE, silicon revision 1, 2MB external flash", esp32="WiFi/BT/BLE, silicon revision 1, 2MB external flash", esp32s2="WiFi, silicon revision 0, 2MB external flash", esp32c3="WiFi/BLE, silicon revision 0, 2MB external flash"}
|
||||
|
||||
{IDF_TARGET_HEAP_SIZE:default="298968", esp32="298968", esp32s2="253900"}
|
||||
{IDF_TARGET_HEAP_SIZE:default="298968", esp32="298968", esp32s2="253900", esp32c3="337332"}
|
||||
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
@@ -28,7 +28,7 @@ Introduction
|
||||
|
||||
* Wi-Fi (2.4 GHz band)
|
||||
* Bluetooth
|
||||
* Dual high performance cores
|
||||
* Dual high performance Xtensa® 32-bit LX6 CPU cores
|
||||
* Ultra Low Power co-processor
|
||||
* Multiple peripherals
|
||||
|
||||
@@ -36,12 +36,20 @@ Introduction
|
||||
.. only:: esp32s2
|
||||
|
||||
* Wi-Fi (2.4 GHz band)
|
||||
* High performance single-core
|
||||
* High performance single core Xtensa® 32-bit LX7 CPU
|
||||
* Ultra Low Power co-processor running either RISC-V or FSM core
|
||||
* Multiple peripherals
|
||||
* Built-in security hardware
|
||||
* USB OTG interface
|
||||
|
||||
.. only:: esp32c3
|
||||
|
||||
* Wi-Fi (2.4 GHz band)
|
||||
* Bluetooth Low Energy
|
||||
* High performance 32-bit RISC-V single-core processor
|
||||
* Multiple peripherals
|
||||
* Built-in security hardware
|
||||
|
||||
Powered by 40 nm technology, {IDF_TARGET_NAME} provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
|
||||
|
||||
Espressif provides basic hardware and software resources to help application developers realize their ideas using the {IDF_TARGET_NAME} series hardware. The software development framework by Espressif is intended for development of Internet-of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features.
|
||||
@@ -99,11 +107,17 @@ If you have one of {IDF_TARGET_NAME} development boards listed below, you can cl
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
|
||||
ESP32-S2-Saola-1 <../hw-reference/esp32s2/user-guide-saola-1-v1.2>
|
||||
ESP32-S2-DevKitM-1(U) <../hw-reference/esp32s2/user-guide-devkitm-1-v1>
|
||||
ESP32-S2-Kaluga-Kit <../hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit>
|
||||
|
||||
.. only:: esp32c3
|
||||
|
||||
.. note::
|
||||
|
||||
No hardware guides for ESP32-C3 published yet.
|
||||
|
||||
.. _get-started-step-by-step:
|
||||
|
||||
Installation Step by Step
|
||||
@@ -486,21 +500,22 @@ For more information on idf.py arguments, see :ref:`idf.py`.
|
||||
|
||||
Encountered Issues While Flashing?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
{IDF_TARGET_STRAP_GPIO:default="GPIO0", esp32="GPIO0", esp32s2="GPIO0", esp32c3="GPIO9"}
|
||||
|
||||
If you run the given command and see errors such as "Failed to connect", there might be several reasons for this. One of the reasons might be issues encountered by ``esptool.py``, the utility that is called by the build system to reset the chip, interact with the ROM bootloader, and flash firmware. One simple solution to try is manual reset described below, and if it does not help you can find more details about possible issues in `Troubleshooting <https://github.com/espressif/esptool#bootloader-wont-respond>`_.
|
||||
|
||||
``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting DTR and RTS control lines of the USB to serial converter chip, i.e., FTDI or CP210x (for more information, see :doc:`establish-serial-connection`). The DTR and RTS control lines are in turn connected to ``GPIO0`` and ``CHIP_PU`` (EN) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of DTR and RTS will boot {IDF_TARGET_NAME} into Firmware Download mode. As an example, check the `schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ for the ESP32 DevKitC development board.
|
||||
``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting DTR and RTS control lines of the USB to serial converter chip, i.e., FTDI or CP210x (for more information, see :doc:`establish-serial-connection`). The DTR and RTS control lines are in turn connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU`` (EN) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of DTR and RTS will boot {IDF_TARGET_NAME} into Firmware Download mode. As an example, check the `schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ for the ESP32 DevKitC development board.
|
||||
|
||||
In general, you should have no problems with the official esp-idf development boards. However, ``esptool.py`` is not able to reset your hardware automatically in the following cases:
|
||||
|
||||
- Your hardware does not have the DTR and RTS lines connected to ``GPIO0`` and ``CIHP_PU``
|
||||
- Your hardware does not have the DTR and RTS lines connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU``
|
||||
- The DTR and RTS lines are configured differently
|
||||
- There are no such serial control lines at all
|
||||
|
||||
Depending on the kind of hardware you have, it may also be possible to manually put your {IDF_TARGET_NAME} board into Firmware Download mode (reset).
|
||||
|
||||
- For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset an esp-idf development board, hold down the **Boot** button (``GPIO0``) and press the **EN** button (``CHIP_PU``).
|
||||
- For other types of hardware, try pulling ``GPIO0`` down.
|
||||
- For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset an esp-idf development board, hold down the **Boot** button (``{IDF_TARGET_STRAP_GPIO}``) and press the **EN** button (``CHIP_PU``).
|
||||
- For other types of hardware, try pulling ``{IDF_TARGET_STRAP_GPIO}`` down.
|
||||
|
||||
|
||||
Normal Operation
|
||||
@@ -588,6 +603,47 @@ When flashing, you will see the output log similar to the following:
|
||||
Hard resetting via RTS pin...
|
||||
Done
|
||||
|
||||
.. only:: esp32c3
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
...
|
||||
esptool.py --chip esp32c3 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 80m --flash_size 2MB 0x8000 partition_table/partition-table.bin 0x0 bootloader/bootloader.bin 0x10000 hello-world.bin
|
||||
esptool.py v3.0
|
||||
Serial port /dev/ttyUSB0
|
||||
Connecting....
|
||||
Chip is ESP32-C3
|
||||
Features: Wi-Fi
|
||||
Crystal is 40MHz
|
||||
MAC: 7c:df:a1:40:02:a4
|
||||
Uploading stub...
|
||||
Running stub...
|
||||
Stub running...
|
||||
Changing baud rate to 460800
|
||||
Changed.
|
||||
Configuring flash size...
|
||||
Compressed 3072 bytes to 103...
|
||||
Writing at 0x00008000... (100 %)
|
||||
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 4238.1 kbit/s)...
|
||||
Hash of data verified.
|
||||
Compressed 18960 bytes to 11311...
|
||||
Writing at 0x00000000... (100 %)
|
||||
Wrote 18960 bytes (11311 compressed) at 0x00000000 in 0.3 seconds (effective 584.9 kbit/s)...
|
||||
Hash of data verified.
|
||||
Compressed 145520 bytes to 71984...
|
||||
Writing at 0x00010000... (20 %)
|
||||
Writing at 0x00014000... (40 %)
|
||||
Writing at 0x00018000... (60 %)
|
||||
Writing at 0x0001c000... (80 %)
|
||||
Writing at 0x00020000... (100 %)
|
||||
Wrote 145520 bytes (71984 compressed) at 0x00010000 in 2.3 seconds (effective 504.4 kbit/s)...
|
||||
Hash of data verified.
|
||||
|
||||
Leaving...
|
||||
Hard resetting via RTS pin...
|
||||
Done
|
||||
|
||||
|
||||
If there are no issues by the end of the flash process, the board will reboot and start up the “hello_world” application.
|
||||
|
||||
If you'd like to use the Eclipse or VS Code IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide <eclipse-setup>`, :doc:`VS Code guide <vscode-setup>`.
|
||||
@@ -625,7 +681,7 @@ After startup and diagnostic logs scroll up, you should see "Hello world!" print
|
||||
Restarting in 9 seconds...
|
||||
Restarting in 8 seconds...
|
||||
Restarting in 7 seconds...
|
||||
|
||||
|
||||
To exit IDF monitor use the shortcut ``Ctrl+]``.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
@@ -68,22 +68,22 @@ Download ``crosstool-NG`` and build it:
|
||||
|
||||
Build the toolchain::
|
||||
|
||||
./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
|
||||
./ct-ng {IDF_TARGET_TOOLCHAIN_PREFIX}
|
||||
./ct-ng build
|
||||
chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
|
||||
chmod -R u+w builds/{IDF_TARGET_TOOLCHAIN_PREFIX}
|
||||
|
||||
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``.
|
||||
Toolchain will be built in ``~/esp/crosstool-NG/builds/{IDF_TARGET_TOOLCHAIN_PREFIX}``.
|
||||
|
||||
Add Toolchain to PATH
|
||||
=====================
|
||||
|
||||
The custom toolchain needs to be copied to a binary directory and added to the ``PATH``.
|
||||
|
||||
Choose a directory, for example ``~/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/``, and copy the build output to this directory.
|
||||
Choose a directory, for example ``~/esp/{IDF_TARGET_TOOLCHAIN_PREFIX}/``, and copy the build output to this directory.
|
||||
|
||||
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
|
||||
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``{IDF_TARGET_TOOLCHAIN_PREFIX}`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
|
||||
|
||||
export PATH="$HOME/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin:$PATH"
|
||||
export PATH="$HOME/esp/{IDF_TARGET_TOOLCHAIN_PREFIX}/bin:$PATH"
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -96,7 +96,7 @@ Log off and log in back to make the ``.profile`` changes effective. Run the foll
|
||||
You are looking for similar result containing toolchain's path at the beginning of displayed string::
|
||||
|
||||
$ printenv PATH
|
||||
/home/user-name/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
|
||||
/home/user-name/esp/{IDF_TARGET_TOOLCHAIN_PREFIX}/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
|
||||
|
||||
Instead of ``/home/user-name`` there should be a home path specific to your installation.
|
||||
|
||||
|
||||
@@ -73,11 +73,11 @@ Download ``crosstool-NG`` and build it:
|
||||
|
||||
Build the toolchain::
|
||||
|
||||
./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
|
||||
./ct-ng {IDF_TARGET_TOOLCHAIN_PREFIX}
|
||||
./ct-ng build
|
||||
chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
|
||||
chmod -R u+w builds/{IDF_TARGET_TOOLCHAIN_PREFIX}
|
||||
|
||||
Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin`` to ``PATH`` environment variable.
|
||||
Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/{IDF_TARGET_TOOLCHAIN_PREFIX}``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/{IDF_TARGET_TOOLCHAIN_PREFIX}/bin`` to ``PATH`` environment variable.
|
||||
|
||||
Python 2 deprecation
|
||||
====================
|
||||
|
||||
@@ -81,12 +81,12 @@ Download the precompiled Windows toolchain:
|
||||
|
||||
|download_link_win32|
|
||||
|
||||
Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``.
|
||||
Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``{IDF_TARGET_TOOLCHAIN_PREFIX}``.
|
||||
|
||||
Next, the ``bin`` subdirectory of this directory must be :ref:`added to your Path <add-directory-windows-path>`. For example, the directory to add may be ``C:\Program Files\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin``.
|
||||
Next, the ``bin`` subdirectory of this directory must be :ref:`added to your Path <add-directory-windows-path>`. For example, the directory to add may be ``C:\Program Files\{IDF_TARGET_TOOLCHAIN_PREFIX}\bin``.
|
||||
|
||||
.. note::
|
||||
If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
|
||||
If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\{IDF_TARGET_TOOLCHAIN_PREFIX}\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
|
||||
|
||||
|
||||
.. _add-directory-windows-path:
|
||||
|
||||
Reference in New Issue
Block a user