esp-idf README

The project's README from github.com/espressif/esp-idf. As one markdown file: README.md.

Espressif IoT Development Framework

ESP-IDF is the development framework for Espressif SoCs supported on Windows, Linux and macOS.

ESP-IDF Release Support Schedule

Support Schedule

ESP-IDF Release and SoC Compatibility

Chip support

See Compatibility Between ESP-IDF Releases and Revisions of Espressif SoCs for the details of the compatibility between ESP-IDF and chip revisions.

Espressif SoCs released before 2016 (ESP8266 and ESP8285) are supported by RTOS SDK instead.

Developing With ESP-IDF

Setting Up ESP-IDF

See https://idf.espressif.com/ for links to detailed instructions on how to set up the ESP-IDF depending on chip you use.

Note: Each SoC series and each ESP-IDF release has its own documentation. Please see Section Versions on how to find documentation and how to checkout specific release of ESP-IDF.

Non-GitHub forks

ESP-IDF uses relative locations as its submodules URLs (.gitmodules). So they link to GitHub. If ESP-IDF is forked to a Git repository which is not on GitHub, you will need to run the script tools/set-submodules-to-github.sh after git clone.

The script sets absolute URLs for all submodules, allowing git submodule update --init --recursive to complete. If cloning ESP-IDF from GitHub, this step is not needed.

Finding a Project

As well as the esp-idf-template project mentioned in Getting Started, ESP-IDF comes with some example projects in the examples directory.

Once you've found the project you want to work with, change to its directory and you can configure and build it.

To start your own project based on an example, copy the example project directory outside of the ESP-IDF directory.

Quick Reference

See the Getting Started guide links above for a detailed setup guide. This is a quick reference for common commands when working with ESP-IDF projects:

Setup Build Environment

(See the Getting Started guide listed above for a full list of required steps with more details.)

Configuring the Project

Compiling the Project

idf.py build

... will compile app, bootloader and generate a partition table based on the config.

Flashing the Project

When the build finishes, it will print a command line to use esptool to flash the chip. However you can also do this automatically by running:

idf.py -p PORT flash

Replace PORT with the name of your serial port (like COM3 on Windows, /dev/ttyUSB0 on Linux, or /dev/cu.usbserial-X on MacOS. If the -p option is left out, idf.py flash will try to flash the first available serial port.

This will flash the entire project (app, bootloader and partition table) to a new chip. The settings for serial port flashing can be configured with idf.py menuconfig.

You don't need to run idf.py build before running idf.py flash, idf.py flash will automatically rebuild anything which needs it.

Viewing Serial Output

The idf.py monitor target uses the esp-idf-monitor tool to display serial output from Espressif SoCs. esp-idf-monitor also has a range of features to decode crash output and interact with the device. Check the documentation page for details.

Exit the monitor by typing Ctrl-].

To build, flash and monitor output in one pass, you can run:

idf.py flash monitor

Compiling & Flashing Only the App

After the initial flash, you may just want to build and flash just your app, not the bootloader and partition table:

idf.py app-flash will automatically rebuild the app if any source files have changed.

(In normal development there's no downside to reflashing the bootloader and partition table each time, if they haven't changed.)

Erasing Flash

The idf.py flash target does not erase the entire flash contents. However it is sometimes useful to set the device back to a totally erased state, particularly when making partition table changes or OTA app updates. To erase the entire flash, run idf.py erase-flash.

This can be combined with other targets, ie idf.py -p PORT erase-flash flash will erase everything and then re-flash the new app, bootloader and partition table.

Resources

esp-idf (espressif/esp-idf)

Searching Database…

19.3K ·GitHub
Esp-idf
Что это такое?ESP-IDF — официальный фреймворк для разработки от Espressif, предназначенный для создания прошивок для SoC, пришедших на смену ESP32/ESP8266. Он включает систему сборки, драйверы, сетевые стеки и инструменты.
Это библиотека или полноценный SDK/фреймворк?Это полноценный SDK/фреймворк: в него входят установщик тулчейна, система сборки (idf.py), ОС на базе FreeRTOS, драйверы, сетевые компоненты и примеры проектов, а не одна библиотека.
Как настроить проект и собрать его?Установите системные зависимости, запустите скрипт установки (install.bat/install.sh/install.ps1/install.fish), а затем в каждой оболочке перед использованием выполните source export.sh (или export.bat в Windows). После этого запускайте idf.py set-target, idf.py menuconfig, idf.py build и idf.py -p PORT flash monitor.
Что нужно установить, прежде чем собирать с ESP-IDF?Нужны системные зависимости для сборки, перечисленные в руководстве Getting Started, и плата или SoC от Espressif, подключённые через последовательный порт для прошивки. Также понадобится копия примера проекта или шаблон esp-idf-template, с которого можно начать.
Есть подводные камни при форке или прошивке?Если вы форкаете ESP-IDF на хостинг Git, отличный от GitHub, сабмодули не подтянутся автоматически, поэтому после клонирования нужно выполнить tools/set-submodules-to-github.sh. Кроме того, idf.py flash не стирает существующее содержимое флеш-памяти, поэтому изменения разделов или OTA могут потребовать явного запуска idf.py erase-flash.
Какие чипы поддерживаются?Поддерживаются современные SoC от Espressif, выпущенные начиная с 2016 года. Более старые ESP8266/ESP8285 используют отдельный RTOS SDK, а у каждой серии чипов и каждого релиза есть своя документация.
Можно ли в ESP-IDF смотреть вывод из последовательного порта и логи сбоев?Да, idf.py monitor использует инструмент esp-idf-monitor, чтобы показывать вывод из последовательного порта и расшифровывать дампы сбоев. Можно сразу объединить команды в idf.py flash monitor, чтобы прошить плату и смотреть логи за один шаг.
Как пересобрать только приложение без перепрошивки загрузчика?Используйте idf.py app, чтобы собрать только приложение, и idf.py app-flash, чтобы прошить только его. При изменении исходников сборка выполнится автоматически, а загрузчик и таблица разделов будут пропущены.
What are similar projects?arduino-esp32, tinygo, esp32-c3-adblock, muse-gadget-sdk, Arduino, PixelFonts, oomwoo, voiceshell-muse-bridge
Which topics is it in?arduino, toolchain, driver, esp32, build-tool, firmware, iot, embedded, hardware, c, sdk, networking
Creator
espressif
Size
452 MB
Stars
19.3K
Updated
CommitOct 19Releasev6.1Aug 27
Age
10y
Commits · 90 Days